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_clear(struct ubuf *ubuf, int hoffset, int voffset, int hsize, int vsize)
• 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 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.

Parameters 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 517.

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)

Parameters 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

The return value is an error code

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

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

Parameters 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 498.

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)

Parameters 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.

Parameters 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.

Parameters 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.

Parameters 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.

Parameters 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.

Parameters 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 469.

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

Parameters 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 shrinked 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.

Parameters 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.

Parameters 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.

Parameters 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.

Parameters 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