FFmpeg
Enumerations | Functions
Image related

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void av_image_copy (uint8_t *dst_data[4], int dst_linesizes[4], const uint8_t *src_data[4], const int src_linesizes[4], enum AVPixelFormat pix_fmt, int width, int height)
 Copy image in src_data to dst_data. More...
 
void av_image_copy_uc_from (uint8_t *dst_data[4], const ptrdiff_t dst_linesizes[4], const uint8_t *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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
int av_image_fill_black (uint8_t *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. More...
 

Detailed Description

AVPicture types, pixel formats and basic image planes manipulation.

Enumeration Type Documentation

◆ 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 272 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_typethe picture type
Returns
a single character representing the picture type, '?' if pict_type is unknown

Definition at line 83 of file utils.c.

Referenced by do_video_stats(), dump_sidedata(), ff_er_frame_end(), ff_flv_decode_picture_header(), ff_h263_show_pict_info(), ff_h264_decode_mb_cavlc(), ff_print_debug_info2(), ff_rate_estimate_qscale(), filter_frame(), func_pict_type(), h264_slice_init(), queue_picture(), select_frame(), show_frame(), svq3_decode_frame(), tlog_ref(), and vc1_decode_frame().

◆ 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_pixstepsan 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_compsan array which is filled with the component for each plane which has the max pixel step. May be NULL.

Definition at line 35 of file imgutils.c.

Referenced by av_image_fill_linesizes(), av_image_get_linesize(), config_input(), config_input_main(), config_input_overlay(), config_output(), config_props(), and config_props_output().

◆ 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

Definition at line 76 of file imgutils.c.

Referenced by av_image_check_size2(), av_image_fill_black(), config_input(), copy_frame(), copy_uv_planes(), dds_decode(), ff_proc_from_dnn_to_frame(), ff_proc_from_frame_to_dnn(), filter_frame(), handle_p_frame_png(), image_copy(), msrle_decode_frame(), and qsv_fill_border().

◆ 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
linesizesarray to be filled with the linesize for each plane
Returns
>= 0 in case of success, a negative error code otherwise

Definition at line 89 of file imgutils.c.

Referenced by av_image_alloc(), av_image_copy_to_buffer(), av_image_fill_arrays(), av_image_get_buffer_size(), config_input(), config_output(), config_props(), config_props_output(), doTest(), ff_frame_pool_video_init(), ff_frame_to_dnn_classify(), ff_frame_to_dnn_detect(), get_video_buffer(), main(), update_frame_pool(), and video_frame_cksum().

◆ 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
sizethe array to be filled with the size of each image plane
linesizesthe 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().

Definition at line 111 of file imgutils.c.

Referenced by av_image_alloc(), av_image_fill_pointers(), av_image_get_buffer_size(), get_video_buffer(), main(), read_in_data(), and update_frame_pool().

◆ 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
datapointers array to be filled with the pointer for each image plane
ptrthe pointer to a buffer which will contain the image
linesizesthe 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

Definition at line 145 of file imgutils.c.

Referenced by av_image_alloc(), av_image_fill_arrays(), dxva2_map_frame(), fill_texture_ptrs(), get_video_buffer(), main(), and nvenc_copy_frame().

◆ 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
alignthe 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

Definition at line 218 of file imgutils.c.

Referenced by config_input(), config_out_props(), config_props(), ff_load_image(), ff_scale_image(), main(), sws_init_context(), and sws_setColorspaceDetails().

◆ 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_linesizelinesize for the image plane in dst
src_linesizelinesize for the image plane in src

Definition at line 374 of file imgutils.c.

Referenced by amplify_frame(), apply_delogo(), bilateralo_planes(), blur_image(), blur_planes(), cas_slice16(), cas_slice8(), copy_field(), copy_fields(), copy_frame(), copy_picture_field(), copy_uv_planes(), dds_decode(), decode_frame(), do_alphamerge(), do_morpho(), encode_plane(), ff_h274_apply_film_grain(), ff_mpegvideoencdsp_init(), ff_proc_from_dnn_to_frame(), ff_proc_from_frame_to_dnn(), filter(), filter_frame(), filter_slice(), limitdiff_slice(), load_mask(), maskedclamp_slice(), maskedminmax_slice(), median_frames16(), median_frames8(), noise(), paf_video_decode(), pix_decode_frame(), premultiply_slice(), process_frame(), process_slice(), rscc_decode_frame(), screenpresso_decode_frame(), tdsc_decode_tiles(), threshold_slice(), and weave_slice().

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

Definition at line 359 of file imgutils.c.

Referenced by av_image_copy_uc_from().

◆ av_image_copy()

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

◆ av_image_copy_uc_from()

void av_image_copy_uc_from ( uint8_t *  dst_data[4],
const ptrdiff_t  dst_linesizes[4],
const uint8_t *  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.

Definition at line 438 of file imgutils.c.

Referenced by dxva2_transfer_data_from().

◆ 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_datadata pointers to be filled in
dst_linesizelinesizes for the image in dst_data to be filled in
srcbuffer which will contain or contains the actual image data, can be NULL
pix_fmtthe pixel format of the image
widththe width of the image in pixels
heightthe height of the image in pixels
alignthe value used in src for linesize alignment
Returns
the size in bytes required for src, a negative error code in case of failure

Definition at line 446 of file imgutils.c.

Referenced by bitpacked_decode_uyvy422(), copy_frame(), cuda_get_buffer(), ffmal_copy_frame(), libdav1d_picture_allocator(), omx_encode_frame(), raw_decode(), sdl2_write_packet(), and xv_write_packet().

◆ 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_fmtthe pixel format of the image
widththe width of the image in pixels
heightthe height of the image in pixels
alignthe assumed linesize alignment
Returns
the buffer size in bytes, a negative error code in case of failure

Definition at line 466 of file imgutils.c.

Referenced by av_image_copy_to_buffer(), compute_crc_of_packets(), cuda_frames_init(), dc1394_read_common(), decode_write(), encode_frame(), frm_read_packet(), image_available(), lavfi_read_packet(), libdav1d_picture_allocator(), mf_v_avframe_to_sample(), msp_read_header(), omx_encode_frame(), pnm_encode_frame(), pnm_parse(), qsv_decode_init_context(), raw_decode(), raw_encode(), rawvideo_read_header(), ser_read_header(), targa_encode_frame(), v4l2_read_header(), vble_decode_init(), video_decode(), video_decode_example(), write_header(), and yuv4_read_header().

◆ 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
dsta buffer into which picture data will be copied
dst_sizethe size in bytes of dst
src_datapointers containing the source image data
src_linesizelinesizes for the image in src_data
pix_fmtthe pixel format of the source image
widththe width of the source image in pixels
heightthe height of the source image in pixels
alignthe assumed linesize alignment for dst
Returns
the number of bytes written to dst, or a negative value (error code) on error

Definition at line 501 of file imgutils.c.

Referenced by compute_crc_of_packets(), copy_cvpixelbuffer(), decode_write(), encode_frame(), image_available(), lavfi_read_packet(), mf_v_avframe_to_sample(), raw_encode(), video_decode(), and video_decode_example().

◆ 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
wthe width of the picture
hthe height of the picture
log_offsetthe offset to sum to the log level for logging with log_ctx
log_ctxthe parent logging context, it may be NULL
Returns
>= 0 if valid, a negative error code otherwise

Definition at line 318 of file imgutils.c.

Referenced by apng_probe(), apng_read_header(), av_hwframe_ctx_init(), av_image_alloc(), av_image_fill_arrays(), av_image_get_buffer_size(), cmv_decode_frame(), config_output(), config_props(), decode_frame(), decode_frame_headers(), decode_ihdr_chunk(), decode_init(), dfa_decode_init(), dxv_init(), encode_dvd_subtitles(), encode_init(), ff_flv_decode_picture_header(), ff_h263_decode_picture_header(), ff_h264_decode_seq_parameter_set(), ff_hevc_parse_sps(), ff_jpeg2000_init_component(), ff_mjpeg_decode_sof(), ff_mpv_common_frame_size_change(), ff_mpv_common_init(), ff_msmpeg4_decode_init(), ff_pnm_decode_header(), ff_rv34_decode_frame(), flashsv2_encode_init(), get_video_buffer(), hap_init(), hnm_decode_init(), hqx_decode_frame(), idcin_read_header(), init(), LLVMFuzzerTestOneInput(), main(), nuv_header(), qtrle_encode_init(), raw_decode(), rawvideo_read_header(), read_header(), rscc_init(), rv10_decode_init(), rv20_decode_picture_header(), rv40_parse_slice_header(), scan_file(), screenpresso_init(), source_config_props(), swf_read_packet(), v210_read_header(), v4l2_read_header(), vid_read_header(), webp_decode_frame(), xwd_decode_frame(), and yop_decode_init().

◆ 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
wthe width of the picture
hthe height of the picture
max_pixelsthe maximum number of pixels the user wants to accept
pix_fmtthe pixel format, can be AV_PIX_FMT_NONE if unknown.
log_offsetthe offset to sum to the log level for logging with log_ctx
log_ctxthe parent logging context, it may be NULL
Returns
>= 0 if valid, a negative error code otherwise

Definition at line 289 of file imgutils.c.

Referenced by av_image_check_size(), avcodec_open2(), decode_pic_hdr(), dvbsub_parse_region_segment(), encode_receive_packet_internal(), ff_frame_pool_video_init(), ff_get_buffer(), ff_ivi_init_planes(), ff_mpeg_framesize_alloc(), ff_set_dimensions(), g2m_decode_frame(), get_siz(), graph_check_links(), and paf_video_init().

◆ 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
wwidth of the image
hheight of the image
sarsample aspect ratio of the image
Returns
0 if valid, a negative AVERROR code otherwise

Definition at line 323 of file imgutils.c.

Referenced by avcodec_open2(), decode_slice_header(), dirac_header(), ff_decode_frame_props(), ff_set_sar(), and mpeg_decode_postinit().

◆ av_image_fill_black()

int av_image_fill_black ( uint8_t *  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_datadata pointers to destination image
dst_linesizelinesizes for the destination image
pix_fmtthe pixel format of the image
rangethe color range of the image (important for colorspaces such as YUV)
widththe width of the image in pixels
heightthe height of the image in pixels
Returns
0 if the image data was cleared, a negative AVERROR code otherwise

Definition at line 582 of file imgutils.c.

Referenced by decode_frame().