upipe/ubuf_pic.h header reference

Upipe buffer handling for picture managers More

• upipe/ubuf.h

• struct ubuf * ubuf_pic_alloc(struct ubuf_mgr *mgr, int hsize, int vsize)
• int ubuf_pic_blit(struct ubuf *dest, struct ubuf *src, int dest_hoffset, int dest_voffset, int src_hoffset, int src_voffset, int extract_hsize, int extract_vsize, const uint8_t alpha, const uint8_t threshold)
• int ubuf_pic_blit_alpha(struct ubuf *dest, struct ubuf *src, int dest_hoffset, int dest_voffset, int src_hoffset, int src_voffset, int extract_hsize, int extract_vsize, const uint8_t *alpha_plane, int alpha_stride, const uint8_t alpha, const uint8_t threshold)
• int ubuf_pic_clear(struct ubuf *ubuf, int hoffset, int voffset, int hsize, int vsize, int fullrange)
• struct ubuf * ubuf_pic_copy(struct ubuf_mgr *mgr, struct ubuf *ubuf, int hskip, int vskip, int new_hsize, int new_vsize)
• int ubuf_pic_plane_clear(struct ubuf *ubuf, const char *chroma, int hoffset, int voffset, int hsize, int vsize, int fullrange)
• int ubuf_pic_plane_iterate(struct ubuf *ubuf, const char **chroma_p)
• int ubuf_pic_plane_read(struct ubuf *ubuf, const char *chroma, int hoffset, int voffset, int hsize, int vsize, const uint8_t **buffer_p)
• int ubuf_pic_plane_size(struct ubuf *ubuf, const char *chroma, size_t *stride_p, uint8_t *hsub_p, uint8_t *vsub_p, uint8_t *macropixel_size_p)
• int ubuf_pic_plane_unmap(struct ubuf *ubuf, const char *chroma, int hoffset, int voffset, int hsize, int vsize)
• int ubuf_pic_plane_write(struct ubuf *ubuf, const char *chroma, int hoffset, int voffset, int hsize, int vsize, uint8_t **buffer_p)
• int ubuf_pic_replace(struct ubuf_mgr *mgr, struct ubuf **ubuf_p, int hskip, int vskip, int new_hsize, int new_vsize)
• int ubuf_pic_resize(struct ubuf *ubuf, int hskip, int vskip, int new_hsize, int new_vsize)
• int ubuf_pic_size(struct ubuf *ubuf, size_t *hsize_p, size_t *vsize_p, uint8_t *mpixel_p)

• UBUF_ALLOC_PICTURE

This file defines the picture-specific API to access buffers.

This macro is declared in upipe/ubuf_pic.h source file, line 44.

This macro is a simple signature to make sure the ubuf_alloc internal API is used properly.

This macro is declared in upipe/ubuf_pic.h source file, line 32.

This function is declared in upipe/ubuf_pic.h source file, line 56.

This function returns a new ubuf from a picture allocator.

Parameter list:

• mgr: management structure for this ubuf type
• hsize: horizontal size in pixels
• vsize: vertical size in lines

The return value is pointer to ubuf or NULL in case of failure

This function is declared in upipe/ubuf_pic.h source file, line 475.

This function blits a picture ubuf to another ubuf.

Parameter list:

• dest: destination ubuf
• src: source ubuf
• dest_hoffset: number of pixels to seek at the beginning of each line of dest
• dest_voffset: number of lines to seek at the beginning of dest
• src_hoffset: number of pixels to skip at the beginning of each line of src
• src_voffset: number of lines to skip at the beginning of src
• extract_hsize: horizontal size to copy
• extract_vsize: vertical size to copy
• alpha: alpha multiplier
• threshold: threshold parameter for alpha

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 355.

This function blits a picture ubuf to another ubuf.

Parameter list:

• dest: destination ubuf
• src: source ubuf
• dest_hoffset: number of pixels to seek at the beginning of each line of dest
• dest_voffset: number of lines to seek at the beginning of dest
• src_hoffset: number of pixels to skip at the beginning of each line of src
• src_voffset: number of lines to skip at the beginning of src
• extract_hsize: horizontal size to copy
• extract_vsize: vertical size to copy
• alpha_plane: pointer to alpha plane buffer, if any
• alpha_stride: horizontal stride of the alpha plane buffer
• alpha: alpha multiplier
• threshold: alpha blending method 0 means ignore alpha 255 means blends src and dest together using alpha levels (slow) Any value in between means using the src pixels if and only if their alpha value is more than this value

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 635.

This function clears (part of) the specified picture, depending on plane type and size (set U/V chroma to 0x80 instead of 0 for instance)

Parameter list:

• ubuf: pointer to ubuf
• hoffset: horizontal offset of the picture area wanted in the whole picture, negative values start from the end of lines, in pixels (before dividing by macropixel and hsub)
• voffset: vertical offset of the picture area wanted in the whole picture, negative values start from the last line, in lines (before dividing by vsub)
• hsize: number of pixels wanted per line, or -1 for until the end of the line
• vsize: number of lines wanted in the picture area, or -1 for until the last line
• fullrange: whether the input is full-range

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 519.

This function copies a picture ubuf to a newly allocated ubuf, and doesn't deal with the old ubuf or a dictionary.

Parameter list:

• mgr: management structure for this ubuf type
• ubuf: pointer to ubuf to copy
• hskip: number of pixels to skip at the beginning of each line (if < 0, extend the picture leftwards)
• vskip: number of lines to skip at the beginning of the picture (if < 0, extend the picture upwards)
• new_hsize: final horizontal size of the buffer, in pixels (if set to -1, keep same line ends)
• new_vsize: final vertical size of the buffer, in lines (if set to -1, keep same last line)

The return value is pointer to newly allocated ubuf or NULL in case of error

This function is declared in upipe/ubuf_pic.h source file, line 615.

This function clears (part of) the specified plane, depending on plane type and size (set U/V chroma to 0x80 instead of 0 for instance)

Parameter list:

• ubuf: pointer to ubuf
• chroma: chroma type (see chroma reference)
• hoffset: horizontal offset of the picture area wanted in the whole picture, negative values start from the end of lines, in pixels (before dividing by macropixel and hsub)
• voffset: vertical offset of the picture area wanted in the whole picture, negative values start from the last line, in lines (before dividing by vsub)
• hsize: number of pixels wanted per line, or -1 for until the end of the line
• vsize: number of lines wanted in the picture area, or -1 for until the last line

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 89.

This function iterates on picture planes chroma types. Start by initializing *chroma_p to NULL. If *chroma_p is NULL after running this function, there are no more planes in this picture. Otherwise the string pointed to by *chroma_p remains valid until the ubuf picture manager is deallocated.

Parameter list:

• ubuf: pointer to ubuf
• chroma_p: reference written with chroma type of the next plane

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 184.

This function returns a read-only pointer to the buffer space. You must call ubuf_pic_plane_unmap when you're done with the pointer.

Parameter list:

• ubuf: pointer to ubuf
• chroma: chroma type (see chroma reference)
• hoffset: horizontal offset of the picture area wanted in the whole picture, negative values start from the end of lines, in pixels (before dividing by macropixel and hsub)
• voffset: vertical offset of the picture area wanted in the whole picture, negative values start from the last line, in lines (before dividing by vsub)
• hsize: number of pixels wanted per line, or -1 for until the end of the line (before dividing by macropixel and hsub)
• vsize: number of lines wanted in the picture area, or -1 for until the last line (before deviding by vsub)
• buffer_p: reference written with a pointer to buffer space if not NULL

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 111.

This function returns the sizes of a plane of the picture ubuf.

Parameter list:

• ubuf: pointer to ubuf
• chroma: chroma type (see chroma reference)
• stride_p: reference written with the offset between lines, in octets, if not NULL
• hsub_p: reference written with the horizontal subsamping for this plane if not NULL
• vsub_p: reference written with the vertical subsamping for this plane if not NULL
• macropixel_size_p: reference written with the size of a macropixel in octets for this plane if not NULL

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 240.

This function marks the buffer space as being currently unused, and the pointer will be invalid until the next time the ubuf is mapped.

Parameter list:

• ubuf: pointer to ubuf
• chroma: chroma type (see chroma reference)
• hoffset: horizontal offset of the picture area wanted in the whole picture, negative values start from the end of lines, in pixels (before dividing by macropixel and hsub)
• voffset: vertical offset of the picture area wanted in the whole picture, negative values start from the last line, in lines (before dividing by vsub)
• hsize: number of pixels wanted per line, or -1 for until the end of the line
• vsize: number of lines wanted in the picture area, or -1 for until the last line

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 213.

This function returns a writable pointer to the buffer space, if the ubuf is not shared. You must call ubuf_pic_plane_unmap when you're done with the pointer.

Parameter list:

• ubuf: pointer to ubuf
• chroma: chroma type (see chroma reference)
• hoffset: horizontal offset of the picture area wanted in the whole picture, negative values start from the end of lines, in pixels (before dividing by macropixel and hsub)
• voffset: vertical offset of the picture area wanted in the whole picture, negative values start from the last line, in lines (before dividing by vsub)
• hsize: number of pixels wanted per line, or -1 for until the end of the line
• vsize: number of lines wanted in the picture area, or -1 for until the last line
• buffer_p: reference written with a pointer to buffer space if not NULL

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 585.

This function copies part of a ubuf to a newly allocated ubuf, and replaces the old ubuf with the new ubuf.

Parameter list:

• mgr: management structure for this ubuf type
• ubuf_p: reference to a pointer to ubuf to replace with a new picture ubuf
• hskip: number of pixels to skip at the beginning of each line (if < 0, extend the picture leftwards)
• vskip: number of lines to skip at the beginning of the picture (if < 0, extend the picture upwards)
• new_hsize: final horizontal size of the buffer, in pixels (if set to -1, keep same line ends)
• new_vsize: final vertical size of the buffer, in lines (if set to -1, keep same last line)

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 319.

This function resizes a picture ubuf, if possible. This will only work if:

• the ubuf is only shrunk in one or both directions, or

• the relevant low-level buffer is not shared with another ubuf and the picture manager allows to grow the buffer (ie. prepend/append have been correctly specified at allocation, or reallocation is allowed)

Should this fail, ubuf_pic_replace may be used to achieve the same goal with an extra buffer copy.

Parameter list:

• ubuf: pointer to ubuf
• hskip: number of pixels to skip at the beginning of each line (if < 0, extend the picture leftwards)
• vskip: number of lines to skip at the beginning of the picture (if < 0, extend the picture upwards)
• new_hsize: final horizontal size of the buffer, in pixels (if set to -1, keep same line ends)
• new_vsize: final vertical size of the buffer, in lines (if set to -1, keep same last line)

The return value is an error code

This function is declared in upipe/ubuf_pic.h source file, line 74.

This function returns the sizes of the picture ubuf.

Parameter list:

• ubuf: pointer to ubuf
• hsize_p: reference written with the horizontal size of the picture if not NULL
• vsize_p: reference written with the vertical size of the picture if not NULL
• mpixel_p: reference written with the number of pixels in a macropixel if not NULL

The return value is an error code

This function is for internal use only.

This function is declared in upipe/ubuf_pic.h source file, line 270.

This function checks the skip and new_size parameters of a lot of resizing functions, and transforms them.

Parameter list:

• ubuf: pointer to ubuf
• hskip_p: reference to number of pixels to skip at the beginning of each line (if < 0, extend the picture leftwards)
• vskip_p: reference to number of lines to skip at the beginning of the picture (if < 0, extend the picture upwards)
• new_hsize_p: reference to final horizontal size of the buffer, in pixels (if set to -1, keep same line ends)
• new_vsize_p: reference to final vertical size of the buffer, in lines (if set to -1, keep same last line)
• ubuf_hsize_p: filled in with the total horizontal size of the ubuf (may be NULL)
• ubuf_vsize_p: filled in with the total vertical size of the ubuf (may be NULL)
• macropixel_p: filled in with the number of pixels in a macropixel (may be NULL)

The return value is an error code

This function is for internal use only.

This function is declared in upipe/ubuf_pic.h source file, line 136.

This function checks the offset and size parameters of a lot of functions, and transforms them into absolute offset and size.

Parameter list:

• ubuf: pointer to ubuf
• chroma: chroma type (see chroma reference)
• hoffset_p: reference to horizontal offset of the picture area wanted in the whole picture, negative values start from the end of lines, in pixels (before dividing by macropixel and hsub)
• voffset_p: reference to vertical offset of the picture area wanted in the whole picture, negative values start from the last line, in lines (before dividing by vsub)
• hsize_p: reference to number of pixels wanted per line, or -1 for until the end of the line
• vsize_p: reference to number of lines wanted in the picture area, or -1 for until the last line (may be NULL)

The return value is UBASE_ERR_INVALID when the parameters are invalid