Loading...
Searching...
No Matches
Image related
libavutil » Other

AVPicture types, pixel formats and basic image planes manipulation. More...

## Enumerations

enum | AVPictureType { AV_PICTURE_TYPE_NONE = 0 , AV_PICTURE_TYPE_I , AV_PICTURE_TYPE_P , AV_PICTURE_TYPE_B , AV_PICTURE_TYPE_S , AV_PICTURE_TYPE_SI , AV_PICTURE_TYPE_SP , AV_PICTURE_TYPE_BI }

## Functions

char | av_get_picture_type_char (enum AVPictureType pict_type)
| Return a single letter to describe the given picture type pict_type.
void | av_image_fill_max_pixsteps (int max_pixsteps[4], int max_pixstep_comps[4], const AVPixFmtDescriptor *pixdesc)
| Compute the max pixel step for each plane of an image with a format described by pixdesc.
int | av_image_get_linesize (enum AVPixelFormat pix_fmt, int width, int plane)
| Compute the size of an image line with format pix_fmt and width width for the plane plane.
int | av_image_fill_linesizes (int linesizes[4], enum AVPixelFormat pix_fmt, int width)
| Fill plane linesizes for an image with pixel format pix_fmt and width width.
int | av_image_fill_plane_sizes (size_t size[4], enum AVPixelFormat pix_fmt, int height, const ptrdiff_t linesizes[4])
| Fill plane sizes for an image with pixel format pix_fmt and height height.
int | av_image_fill_pointers (uint8_t *data[4], enum AVPixelFormat pix_fmt, int height, uint8_t *ptr, const int linesizes[4])
| Fill plane data pointers for an image with pixel format pix_fmt and height height.
int | av_image_alloc (uint8_t *pointers[4], int linesizes[4], int w, int h, enum AVPixelFormat pix_fmt, int align)
| Allocate an image with size w and h and pixel format pix_fmt, and fill pointers and linesizes accordingly.
void | av_image_copy_plane (uint8_t *dst, int dst_linesize, const uint8_t *src, int src_linesize, int bytewidth, int height)
| Copy image plane from src to dst.
void | av_image_copy_plane_uc_from (uint8_t *dst, ptrdiff_t dst_linesize, const uint8_t *src, ptrdiff_t src_linesize, ptrdiff_t bytewidth, int height)
| Copy image data located in uncacheable (e.g.
void | av_image_copy (uint8_t *const dst_data[4], const int dst_linesizes[4], const uint8_t *const src_data[4], const int src_linesizes[4], enum AVPixelFormat pix_fmt, int width, int height)
| Copy image in src_data to dst_data.
static void | av_image_copy2 (uint8_t *const dst_data[4], const int dst_linesizes[4], uint8_t *const src_data[4], const int src_linesizes[4], enum AVPixelFormat pix_fmt, int width, int height)
| Wrapper around av_image_copy() to workaround the limitation that the conversion from uint8_t * const * to const uint8_t * const * is not performed automatically in C.
void | av_image_copy_uc_from (uint8_t *const dst_data[4], const ptrdiff_t dst_linesizes[4], const uint8_t *const src_data[4], const ptrdiff_t src_linesizes[4], enum AVPixelFormat pix_fmt, int width, int height)
| Copy image data located in uncacheable (e.g.
int | av_image_fill_arrays (uint8_t *dst_data[4], int dst_linesize[4], const uint8_t *src, enum AVPixelFormat pix_fmt, int width, int height, int align)
| Setup the data pointers and linesizes based on the specified image parameters and the provided array.
int | av_image_get_buffer_size (enum AVPixelFormat pix_fmt, int width, int height, int align)
| Return the size in bytes of the amount of data required to store an image with the given parameters.
int | av_image_copy_to_buffer (uint8_t *dst, int dst_size, const uint8_t *const src_data[4], const int src_linesize[4], enum AVPixelFormat pix_fmt, int width, int height, int align)
| Copy image data from an image into a buffer.
int | av_image_check_size (unsigned int w, unsigned int h, int log_offset, void *log_ctx)
| Check if the given dimension of an image is valid, meaning that all bytes of the image can be addressed with a signed int.
int | av_image_check_size2 (unsigned int w, unsigned int h, int64_t max_pixels, enum AVPixelFormat pix_fmt, int log_offset, void *log_ctx)
| Check if the given dimension of an image is valid, meaning that all bytes of a plane of an image with the specified pix_fmt can be addressed with a signed int.
int | av_image_check_sar (unsigned int w, unsigned int h, AVRational sar)
| Check if the given sample aspect ratio of an image is valid.
int | av_image_fill_black (uint8_t *const dst_data[4], const ptrdiff_t dst_linesize[4], enum AVPixelFormat pix_fmt, enum AVColorRange range, int width, int height)
| Overwrite the image data with black.
int | av_image_fill_color (uint8_t *const dst_data[4], const ptrdiff_t dst_linesize[4], enum AVPixelFormat pix_fmt, const uint32_t color[4], int width, int height, int flags)
| Overwrite the image data with a color.

## Detailed Description

AVPicture types, pixel formats and basic image planes manipulation.

## Enumeration Type Documentation

## AVPictureType

enum AVPictureType

Enumerator
AV_PICTURE_TYPE_NONE | Undefined.
AV_PICTURE_TYPE_I | Intra.
AV_PICTURE_TYPE_P | Predicted.
AV_PICTURE_TYPE_B | Bi-dir predicted.
AV_PICTURE_TYPE_S | S(GMC)-VOP MPEG-4.
AV_PICTURE_TYPE_SI | Switching Intra.
AV_PICTURE_TYPE_SP | Switching Predicted.
AV_PICTURE_TYPE_BI | BI type.

Definition at line 277 of file avutil.h.

## Function Documentation

## av_get_picture_type_char()

char av_get_picture_type_char | ( | enum AVPictureType | pict_type | ) |

Return a single letter to describe the given picture type pict_type.

Parameters

  [in] | pict_type | the picture type

Returns
  a single character representing the picture type, '?' if pict_type is unknown

## av_image_fill_max_pixsteps()

void av_image_fill_max_pixsteps | ( | int | max_pixsteps[4],
|  | int | max_pixstep_comps[4],
|  | const AVPixFmtDescriptor * | pixdesc
| ) |  |

Compute the max pixel step for each plane of an image with a format described by pixdesc.

The pixel step is the distance in bytes between the first byte of the group of bytes which describe a pixel component and the first byte of the successive group in the same plane for the same component.

Parameters

  max_pixsteps | an array which is filled with the max pixel step for each plane. Since a plane may contain different pixel components, the computed max_pixsteps[plane] is relative to the component in the plane with the max pixel step.
  max_pixstep_comps | an array which is filled with the component for each plane which has the max pixel step. May be NULL.
  pixdesc | the AVPixFmtDescriptor for the image, describing its format

## av_image_get_linesize()

int av_image_get_linesize | ( | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | plane
| ) |  |

Compute the size of an image line with format pix_fmt and width width for the plane plane.

Returns
  the computed size in bytes

## av_image_fill_linesizes()

int av_image_fill_linesizes | ( | int | linesizes[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | width
| ) |  |

Fill plane linesizes for an image with pixel format pix_fmt and width width.

Parameters

  linesizes | array to be filled with the linesize for each plane
  pix_fmt | the AVPixelFormat of the image
  width | width of the image in pixels

Returns
  >= 0 in case of success, a negative error code otherwise

## av_image_fill_plane_sizes()

int av_image_fill_plane_sizes | ( | size_t | size[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | height,
|  | const ptrdiff_t | linesizes[4]
| ) |  |

Fill plane sizes for an image with pixel format pix_fmt and height height.

Parameters

  size | the array to be filled with the size of each image plane
  pix_fmt | the AVPixelFormat of the image
  height | height of the image in pixels
  linesizes | the array containing the linesize for each plane, should be filled by av_image_fill_linesizes()

Returns
  >= 0 in case of success, a negative error code otherwise

Note
  The linesize parameters have the type ptrdiff_t here, while they are int for av_image_fill_linesizes().

## av_image_fill_pointers()

int av_image_fill_pointers | ( | uint8_t * | data[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | height,
|  | uint8_t * | ptr,
|  | const int | linesizes[4]
| ) |  |

Fill plane data pointers for an image with pixel format pix_fmt and height height.

Parameters

  data | pointers array to be filled with the pointer for each image plane
  pix_fmt | the AVPixelFormat of the image
  height | height of the image in pixels
  ptr | the pointer to a buffer which will contain the image
  linesizes | the array containing the linesize for each plane, should be filled by av_image_fill_linesizes()

Returns
  the size in bytes required for the image buffer, a negative error code in case of failure

## av_image_alloc()

int av_image_alloc | ( | uint8_t * | pointers[4],
|  | int | linesizes[4],
|  | int | w,
|  | int | h,
|  | enum AVPixelFormat | pix_fmt,
|  | int | align
| ) |  |

Allocate an image with size w and h and pixel format pix_fmt, and fill pointers and linesizes accordingly.

The allocated image buffer has to be freed by using av_freep(&pointers[0]).

Parameters

  pointers | array to be filled with the pointer for each image plane
  linesizes | the array filled with the linesize for each plane
  w | width of the image in pixels
  h | height of the image in pixels
  pix_fmt | the AVPixelFormat of the image
  align | the value to use for buffer size alignment

Returns
  the size in bytes required for the image buffer, a negative error code in case of failure

Examples
  demux_decode.c, and scale_video.c.

Referenced by main().

## av_image_copy_plane()

void av_image_copy_plane | ( | uint8_t * | dst,
|  | int | dst_linesize,
|  | const uint8_t * | src,
|  | int | src_linesize,
|  | int | bytewidth,
|  | int | height
| ) |  |

Copy image plane from src to dst.

That is, copy "height" number of lines of "bytewidth" bytes each. The first byte of each successive line is separated by *_linesize bytes.

bytewidth must be contained by both absolute values of dst_linesize and src_linesize, otherwise the function behavior is undefined.

Parameters

  dst | destination plane to copy to
  dst_linesize | linesize for the image plane in dst
  src | source plane to copy from
  src_linesize | linesize for the image plane in src
  height | height (number of lines) of the plane

## av_image_copy_plane_uc_from()

void av_image_copy_plane_uc_from | ( | uint8_t * | dst,
|  | ptrdiff_t | dst_linesize,
|  | const uint8_t * | src,
|  | ptrdiff_t | src_linesize,
|  | ptrdiff_t | bytewidth,
|  | int | height
| ) |  |

Copy image data located in uncacheable (e.g.

GPU mapped) memory. Where available, this function will use special functionality for reading from such memory, which may result in greatly improved performance compared to plain av_image_copy_plane().

bytewidth must be contained by both absolute values of dst_linesize and src_linesize, otherwise the function behavior is undefined.

Note
  The linesize parameters have the type ptrdiff_t here, while they are int for av_image_copy_plane().
  On x86, the linesizes currently need to be aligned to the cacheline size (i.e. 64) to get improved performance.

## av_image_copy()

void av_image_copy | ( | uint8_t *const | dst_data[4],
|  | const int | dst_linesizes[4],
|  | const uint8_t *const | src_data[4],
|  | const int | src_linesizes[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | height
| ) |  |

Copy image in src_data to dst_data.

Parameters

  dst_data | destination image data buffer to copy to
  dst_linesizes | linesizes for the image in dst_data
  src_data | source image data buffer to copy from
  src_linesizes | linesizes for the image in src_data
  pix_fmt | the AVPixelFormat of the image
  width | width of the image in pixels
  height | height of the image in pixels

Referenced by av_image_copy2().

## av_image_copy2()

static void av_image_copy2 | ( | uint8_t *const | dst_data[4],
|  | const int | dst_linesizes[4],
|  | uint8_t *const | src_data[4],
|  | const int | src_linesizes[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | height
| ) |  |

inline static

Wrapper around av_image_copy() to workaround the limitation that the conversion from uint8_t * const * to const uint8_t * const * is not performed automatically in C.

See also
  av_image_copy()

Examples
  demux_decode.c.

Definition at line 184 of file imgutils.h.

Referenced by output_video_frame().

## av_image_copy_uc_from()

void av_image_copy_uc_from | ( | uint8_t *const | dst_data[4],
|  | const ptrdiff_t | dst_linesizes[4],
|  | const uint8_t *const | src_data[4],
|  | const ptrdiff_t | src_linesizes[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | height
| ) |  |

Copy image data located in uncacheable (e.g.

GPU mapped) memory. Where available, this function will use special functionality for reading from such memory, which may result in greatly improved performance compared to plain av_image_copy().

The data pointers and the linesizes must be aligned to the maximum required by the CPU architecture.

Note
  The linesize parameters have the type ptrdiff_t here, while they are int for av_image_copy().
  On x86, the linesizes currently need to be aligned to the cacheline size (i.e. 64) to get improved performance.

## av_image_fill_arrays()

int av_image_fill_arrays | ( | uint8_t * | dst_data[4],
|  | int | dst_linesize[4],
|  | const uint8_t * | src,
|  | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | height,
|  | int | align
| ) |  |

Setup the data pointers and linesizes based on the specified image parameters and the provided array.

The fields of the given image are filled in by using the src address which points to the image data buffer. Depending on the specified pixel format, one or multiple image data pointers and line sizes will be set. If a planar format is specified, several pointers will be set pointing to the different picture planes and the line sizes of the different planes will be stored in the lines_sizes array. Call with src == NULL to get the required size for the src buffer.

To allocate the buffer and fill in the dst_data and dst_linesize in one call, use av_image_alloc().

Parameters

  dst_data | data pointers to be filled in
  dst_linesize | linesizes for the image in dst_data to be filled in
  src | buffer which will contain or contains the actual image data, can be NULL
  pix_fmt | the pixel format of the image
  width | the width of the image in pixels
  height | the height of the image in pixels
  align | the value used in src for linesize alignment

Returns
  the size in bytes required for src, a negative error code in case of failure

## av_image_get_buffer_size()

int av_image_get_buffer_size | ( | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | height,
|  | int | align
| ) |  |

Return the size in bytes of the amount of data required to store an image with the given parameters.

Parameters

  pix_fmt | the pixel format of the image
  width | the width of the image in pixels
  height | the height of the image in pixels
  align | the assumed linesize alignment

Returns
  the buffer size in bytes, a negative error code in case of failure

Examples
  hw_decode.c.

Referenced by decode_write().

## av_image_copy_to_buffer()

int av_image_copy_to_buffer | ( | uint8_t * | dst,
|  | int | dst_size,
|  | const uint8_t *const | src_data[4],
|  | const int | src_linesize[4],
|  | enum AVPixelFormat | pix_fmt,
|  | int | width,
|  | int | height,
|  | int | align
| ) |  |

Copy image data from an image into a buffer.

av_image_get_buffer_size() can be used to compute the required size for the buffer to fill.

Parameters

  dst | a buffer into which picture data will be copied
  dst_size | the size in bytes of dst
  src_data | pointers containing the source image data
  src_linesize | linesizes for the image in src_data
  pix_fmt | the pixel format of the source image
  width | the width of the source image in pixels
  height | the height of the source image in pixels
  align | the assumed linesize alignment for dst

Returns
  the number of bytes written to dst, or a negative value (error code) on error

Examples
  hw_decode.c.

Referenced by decode_write().

## av_image_check_size()

int av_image_check_size | ( | unsigned int | w,
|  | unsigned int | h,
|  | int | log_offset,
|  | void * | log_ctx
| ) |  |

Check if the given dimension of an image is valid, meaning that all bytes of the image can be addressed with a signed int.

Parameters

  w | the width of the picture
  h | the height of the picture
  log_offset | the offset to sum to the log level for logging with log_ctx
  log_ctx | the parent logging context, it may be NULL

Returns
  >= 0 if valid, a negative error code otherwise

## av_image_check_size2()

int av_image_check_size2 | ( | unsigned int | w,
|  | unsigned int | h,
|  | int64_t | max_pixels,
|  | enum AVPixelFormat | pix_fmt,
|  | int | log_offset,
|  | void * | log_ctx
| ) |  |

Check if the given dimension of an image is valid, meaning that all bytes of a plane of an image with the specified pix_fmt can be addressed with a signed int.

Parameters

  w | the width of the picture
  h | the height of the picture
  max_pixels | the maximum number of pixels the user wants to accept
  pix_fmt | the pixel format, can be AV_PIX_FMT_NONE if unknown.
  log_offset | the offset to sum to the log level for logging with log_ctx
  log_ctx | the parent logging context, it may be NULL

Returns
  >= 0 if valid, a negative error code otherwise

## av_image_check_sar()

int av_image_check_sar | ( | unsigned int | w,
|  | unsigned int | h,
|  | AVRational | sar
| ) |  |

Check if the given sample aspect ratio of an image is valid.

It is considered invalid if the denominator is 0 or if applying the ratio to the image size would make the smaller dimension less than 1. If the sar numerator is 0, it is considered unknown and will return as valid.

Parameters

  w | width of the image
  h | height of the image
  sar | sample aspect ratio of the image

Returns
  0 if valid, a negative AVERROR code otherwise

## av_image_fill_black()

int av_image_fill_black | ( | uint8_t *const | dst_data[4],
|  | const ptrdiff_t | dst_linesize[4],
|  | enum AVPixelFormat | pix_fmt,
|  | enum AVColorRange | range,
|  | int | width,
|  | int | height
| ) |  |

Overwrite the image data with black.

This is suitable for filling a sub-rectangle of an image, meaning the padding between the right most pixel and the left most pixel on the next line will not be overwritten. For some formats, the image size might be rounded up due to inherent alignment.

If the pixel format has alpha, the alpha is cleared to opaque.

This can return an error if the pixel format is not supported. Normally, all non-hwaccel pixel formats should be supported.

Passing NULL for dst_data is allowed. Then the function returns whether the operation would have succeeded. (It can return an error if the pix_fmt is not supported.)

Parameters

  dst_data | data pointers to destination image
  dst_linesize | linesizes for the destination image
  pix_fmt | the pixel format of the image
  range | the color range of the image (important for colorspaces such as YUV)
  width | the width of the image in pixels
  height | the height of the image in pixels

Returns
  0 if the image data was cleared, a negative AVERROR code otherwise

## av_image_fill_color()

int av_image_fill_color | ( | uint8_t *const | dst_data[4],
|  | const ptrdiff_t | dst_linesize[4],
|  | enum AVPixelFormat | pix_fmt,
|  | const uint32_t | color[4],
|  | int | width,
|  | int | height,
|  | int | flags
| ) |  |

Overwrite the image data with a color.

This is suitable for filling a sub-rectangle of an image, meaning the padding between the right most pixel and the left most pixel on the next line will not be overwritten. For some formats, the image size might be rounded up due to inherent alignment.

If the pixel format has alpha, it is also replaced. Color component values are interpreted as native integers (or intfloats) regardless of actual pixel format endianness.

This can return an error if the pixel format is not supported. Normally, all non-hwaccel pixel formats should be supported.

Passing NULL for dst_data is allowed. Then the function returns whether the operation would have succeeded. (It can return an error if the pix_fmt is not supported.)

Parameters

  dst_data | data pointers to destination image
  dst_linesize | linesizes for the destination image
  pix_fmt | the pixel format of the image
  color | the color components to be used for the fill
  width | the width of the image in pixels
  height | the height of the image in pixels
  flags | currently unused

Returns
  0 if the image data was filled, a negative AVERROR code otherwise