Libav
Files | Data Structures | Enumerations | Functions

AVFrame is an abstraction for reference-counted raw multimedia data. More...

Files

file  frame.h
 reference-counted frame API
 

Data Structures

struct  AVFrameSideData
 
struct  AVFrame
 This structure describes decoded (raw) audio or video data. More...
 

Enumerations

enum  AVFrameSideDataType {
  AV_FRAME_DATA_PANSCAN, AV_FRAME_DATA_A53_CC, AV_FRAME_DATA_STEREO3D, AV_FRAME_DATA_MATRIXENCODING,
  AV_FRAME_DATA_DOWNMIX_INFO, AV_FRAME_DATA_REPLAYGAIN, AV_FRAME_DATA_DISPLAYMATRIX, AV_FRAME_DATA_AFD
}
 
enum  AVActiveFormatDescription {
  AV_AFD_SAME = 8, AV_AFD_4_3 = 9, AV_AFD_16_9 = 10, AV_AFD_14_9 = 11,
  AV_AFD_4_3_SP_14_9 = 13, AV_AFD_16_9_SP_14_9 = 14, AV_AFD_SP_4_3 = 15
}
 

Functions

AVFrameav_frame_alloc (void)
 Allocate an AVFrame and set its fields to default values. More...
 
void av_frame_free (AVFrame **frame)
 Free the frame and any dynamically allocated objects in it, e.g. More...
 
int av_frame_ref (AVFrame *dst, const AVFrame *src)
 Set up a new reference to the data described by the source frame. More...
 
AVFrameav_frame_clone (const AVFrame *src)
 Create a new frame that references the same data as src. More...
 
void av_frame_unref (AVFrame *frame)
 Unreference all the buffers referenced by frame and reset the frame fields. More...
 
void av_frame_move_ref (AVFrame *dst, AVFrame *src)
 Move everythnig contained in src to dst and reset src. More...
 
int av_frame_get_buffer (AVFrame *frame, int align)
 Allocate new buffer(s) for audio or video data. More...
 
int av_frame_is_writable (AVFrame *frame)
 Check if the frame data is writable. More...
 
int av_frame_make_writable (AVFrame *frame)
 Ensure that the frame data is writable, avoiding data copy if possible. More...
 
int av_frame_copy (AVFrame *dst, const AVFrame *src)
 Copy the frame data from src to dst. More...
 
int av_frame_copy_props (AVFrame *dst, const AVFrame *src)
 Copy only "metadata" fields from src to dst. More...
 
AVBufferRefav_frame_get_plane_buffer (AVFrame *frame, int plane)
 Get the buffer reference a given data plane is stored in. More...
 
AVFrameSideDataav_frame_new_side_data (AVFrame *frame, enum AVFrameSideDataType type, int size)
 Add a new side data to a frame. More...
 
AVFrameSideDataav_frame_get_side_data (const AVFrame *frame, enum AVFrameSideDataType type)
 
void av_frame_remove_side_data (AVFrame *frame, enum AVFrameSideDataType type)
 If side data of the supplied type exists in the frame, free it and remove it from the frame. More...
 

Detailed Description

AVFrame is an abstraction for reference-counted raw multimedia data.

Enumeration Type Documentation

Enumerator
AV_FRAME_DATA_PANSCAN 

The data is the AVPanScan struct defined in libavcodec.

AV_FRAME_DATA_A53_CC 

ATSC A53 Part 4 Closed Captions.

A53 CC bitstream is stored as uint8_t in AVFrameSideData.data. The number of bytes of CC data is AVFrameSideData.size.

AV_FRAME_DATA_STEREO3D 

Stereoscopic 3d metadata.

The data is the AVStereo3D struct defined in libavutil/stereo3d.h.

AV_FRAME_DATA_MATRIXENCODING 

The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h.

AV_FRAME_DATA_DOWNMIX_INFO 

Metadata relevant to a downmix procedure.

The data is the AVDownmixInfo struct defined in libavutil/downmix_info.h.

AV_FRAME_DATA_REPLAYGAIN 

ReplayGain information in the form of the AVReplayGain struct.

AV_FRAME_DATA_DISPLAYMATRIX 

This side data contains a 3x3 transformation matrix describing an affine transformation that needs to be applied to the frame for correct presentation.

See libavutil/display.h for a detailed description of the data.

AV_FRAME_DATA_AFD 

Active Format Description data consisting of a single byte as specified in ETSI TS 101 154 using enum AVActiveFormatDescription.

Definition at line 48 of file frame.h.

Enumerator
AV_AFD_SAME 
AV_AFD_4_3 
AV_AFD_16_9 
AV_AFD_14_9 
AV_AFD_4_3_SP_14_9 
AV_AFD_16_9_SP_14_9 
AV_AFD_SP_4_3 

Definition at line 92 of file frame.h.

Function Documentation

AVFrame* av_frame_alloc ( void  )

Allocate an AVFrame and set its fields to default values.

The resulting struct must be freed using av_frame_free().

Returns
An AVFrame filled with default values or NULL on failure.
Note
this only allocates the AVFrame itself, not the data buffers. Those must be allocated through other means, e.g. with av_frame_get_buffer() or manually.

Definition at line 57 of file frame.c.

Referenced by a64multi_encode_init(), aasc_decode_init(), alac_encode_init(), alloc_audio_frame(), alloc_picture(), audio_decode_example(), audio_decode_frame(), audio_encode_example(), av_buffersrc_add_frame(), av_buffersrc_buffer(), av_buffersrc_write_frame(), av_frame_clone(), avcodec_open2(), avs_decode_init(), bethsoftvid_decode_init(), bmp_encode_init(), cdg_decode_init(), cinepak_decode_init(), cinvideo_decode_init(), cmv_decode_init(), compat_read(), config_output(), decode_audio(), decode_entropy_coded_image(), decode_init(), decode_video(), dnxhd_encode_init(), dvvideo_encode_init(), dxva2_alloc(), encode_init(), encode_init_ls(), escape124_decode_init(), ff_cavs_init(), ff_default_get_audio_buffer(), ff_default_get_video_buffer(), ff_frame_thread_init(), ff_mjpeg_decode_init(), ff_mpv_common_init(), ff_mpv_encode_init(), ff_reget_buffer(), ff_vp56_init(), ffv1_decode_init(), ffv1_encode_init(), fic_decode_init(), flashsv_decode_init(), flashsv_encode_init(), flic_decode_init(), gif_encode_init(), hevc_init_context(), init_frames(), init_input_frame(), init_output_frame(), ipvideo_decode_init(), ir2_decode_init(), join_request_frame(), libopenjpeg_encode_init(), libschroedinger_encode_init(), libwebp_encode_frame(), libx265_encode_init(), ljpeg_encode_init(), main(), mimic_decode_init(), mimic_init_thread_copy(), mm_decode_init(), movie_get_frame(), mp_decode_init(), msrle_decode_init(), mss1_decode_init(), mss2_decode_init(), mss3_decode_init(), mss4_decode_init(), msvideo1_decode_init(), mvc_decode_init(), mxpeg_decode_init(), pad_last_frame(), paf_video_init(), pam_encode_init(), pcm_encode_init(), pcx_encode_init(), png_dec_init(), png_enc_init(), pnm_encode_init(), poll_filter(), qtrle_decode_init(), qtrle_encode_init(), roq_decode_init(), roq_encode_init(), rpza_decode_init(), seqvideo_decode_init(), sgirle_decode_init(), smc_decode_init(), sunrast_encode_init(), svq1_decode_init(), svq1_encode_init(), targa_encode_init(), tgv_decode_init(), truemotion1_decode_init(), try_decode_frame(), tscc2_decode_init(), ulti_decode_init(), utvideo_encode_init(), v410_encode_init(), vc1_decode_init(), vda_init(), vdpau_alloc(), video_decode_example(), video_encode_example(), video_thread(), vmdvideo_decode_init(), vp8_init_frames(), vp8_lossy_decode_alpha(), vp9_decode_init(), vpx_init(), X264_init(), xan_decode_init(), XAVS_init(), xbm_encode_init(), xvid_encode_init(), xwd_encode_init(), and zerocodec_decode_init().

void av_frame_free ( AVFrame **  frame)

Free the frame and any dynamically allocated objects in it, e.g.

extended_data. If the frame is reference counted, it will be unreferenced first.

Parameters
frameframe to be freed. The pointer will be set to NULL.

Definition at line 69 of file frame.c.

Referenced by a64multi_close_encoder(), aasc_decode_end(), add_to_queue(), asv_encode_close(), audio_decode_example(), audio_encode_example(), av_buffersink_get_frame(), av_buffersink_get_samples(), av_buffersrc_add_frame(), av_buffersrc_buffer(), av_buffersrc_write_frame(), av_frame_clone(), avcodec_close(), avcodec_encode_audio2(), avcodec_open2(), avconv_cleanup(), avs_decode_end(), bethsoftvid_decode_end(), bmp_encode_close(), cdg_decode_end(), channelmap_filter_frame(), cinepak_decode_end(), cinvideo_decode_end(), close_stream(), cmv_decode_end(), cmv_decode_init(), compand_delay(), compand_nodelay(), compat_free_buffer(), compat_read(), decode_close(), decode_end(), dnxhd_encode_end(), dvvideo_encode_close(), dxva2_uninit(), encode_close(), encode_end(), escape124_decode_close(), ff_cavs_end(), ff_default_get_audio_buffer(), ff_default_get_video_buffer(), ff_filter_frame(), ff_frame_thread_free(), ff_ivi_decode_close(), ff_mjpeg_decode_end(), ff_mpv_common_end(), ff_mpv_encode_end(), ff_reget_buffer(), ff_vc1_decode_end(), ff_vp56_free(), ff_vp8_decode_free(), ffv1_decode_close(), ffv1_encode_close(), fic_decode_close(), fic_decode_frame(), filter_frame(), flashsv_decode_end(), flashsv_encode_end(), flic_decode_end(), flush_fifo(), framepack_uninit(), gif_encode_close(), hevc_decode_free(), image_ctx_free(), init_frames(), init_output_frame(), ipvideo_decode_end(), ipvideo_decode_init(), ir2_decode_end(), join_request_frame(), join_uninit(), libschroedinger_encode_close(), libwebp_encode_frame(), libx265_encode_close(), ljpeg_encode_close(), load_encode_and_write(), main(), mimic_decode_end(), mm_decode_end(), mp_decode_end(), msrle_decode_end(), mss1_decode_end(), mss2_decode_end(), mss3_decode_end(), mss4_decode_end(), msvideo1_decode_end(), mvc_decode_end(), mxpeg_decode_end(), null_filter_frame(), output_frame(), pad_last_frame(), paf_video_close(), pam_encode_close(), pcx_encode_close(), png_dec_end(), png_enc_close(), pnm_encode_close(), qtrle_decode_end(), qtrle_encode_end(), read_decode_convert_and_store(), read_from_fifo(), request_frame(), return_audio_frame(), roq_decode_end(), roq_decode_init(), roq_encode_end(), rpza_decode_end(), seqvideo_decode_end(), sgirle_decode_end(), shuffleplanes_filter_frame(), smc_decode_end(), stream_component_close(), sunrast_encode_close(), svq1_decode_end(), svq1_encode_end(), targa_encode_close(), tgv_decode_end(), truemotion1_decode_end(), try_decode_frame(), tscc2_decode_end(), ulti_decode_end(), uninit(), vda_uninit(), vdpau_uninit(), video_decode_example(), video_encode_example(), video_thread(), vmdvideo_decode_end(), vp3_decode_end(), vp8_lossy_decode_alpha(), vp9_decode_free(), write_to_fifo(), X264_close(), xan_decode_end(), XAVS_close(), xbm_encode_close(), and zerocodec_decode_close().

int av_frame_ref ( AVFrame dst,
const AVFrame src 
)

Set up a new reference to the data described by the source frame.

Copy frame properties from src to dst and create a new reference for each AVBufferRef from src.

If src is not reference counted, new buffers are allocated and the data is copied.

Returns
0 on success, a negative AVERROR on error

Definition at line 188 of file frame.c.

Referenced by aasc_decode_frame(), av_buffersrc_add_frame(), av_buffersrc_write_frame(), av_frame_clone(), avs_decode_frame(), bethsoftvid_decode_frame(), cavs_decode_frame(), cdg_decode_frame(), cinepak_decode_frame(), cinvideo_decode_frame(), cmv_decode_frame(), decode_audio(), decode_frame(), decode_frame_byterun1(), decode_frame_ilbm(), decode_video(), escape124_decode_frame(), ff_h263_decode_frame(), ff_hevc_output_frame(), ff_mjpeg_decode_frame(), ff_rv34_decode_frame(), ff_thread_ref_frame(), ff_vp56_decode_frame(), ffv1_decode_frame(), fic_decode_frame(), finish_frame(), flashsv_decode_frame(), flic_decode_frame_15_16BPP(), flic_decode_frame_8BPP(), h261_decode_frame(), ipvideo_decode_frame(), ir2_decode_frame(), load_input_picture(), mimic_decode_frame(), mjpegb_decode_frame(), mm_decode_frame(), mp_decode_frame(), mpeg_decode_frame(), msrle_decode_frame(), mss1_decode_frame(), mss2_decode_frame(), mss3_decode_frame(), mss4_decode_frame(), msvideo1_decode_frame(), mvc_decode_frame(), mxpeg_decode_frame(), output_frame(), paf_video_decode(), qtrle_decode_frame(), roq_decode_frame(), rpza_decode_frame(), rv10_decode_frame(), seqvideo_decode_frame(), sgirle_decode_frame(), slice_end(), smc_decode_frame(), svq1_decode_frame(), svq3_decode_frame(), tgv_decode_frame(), truemotion1_decode_frame(), tscc2_decode_frame(), ulti_decode_frame(), vc1_decode_frame(), vmdvideo_decode_frame(), vp78_decode_frame(), vp9_decode_frame(), xan_decode_frame(), and zerocodec_decode_frame().

AVFrame* av_frame_clone ( const AVFrame src)

Create a new frame that references the same data as src.

This is a shortcut for av_frame_alloc()+av_frame_ref().

Returns
newly created AVFrame on success, NULL on error.

Definition at line 270 of file frame.c.

Referenced by fic_decode_frame(), filter_frame(), request_frame(), and return_audio_frame().

void av_frame_unref ( AVFrame frame)
void av_frame_move_ref ( AVFrame dst,
AVFrame src 
)
int av_frame_get_buffer ( AVFrame frame,
int  align 
)

Allocate new buffer(s) for audio or video data.

The following fields must be set on frame before calling this function:

  • format (pixel format for video, sample format for audio)
  • width and height for video
  • nb_samples and channel_layout for audio

This function will fill AVFrame.data and AVFrame.buf arrays and, if necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf. For planar formats, one buffer will be allocated for each plane.

Parameters
frameframe in which to store the new buffers.
alignrequired buffer size alignment
Returns
0 on success, a negative AVERROR on error.

Definition at line 175 of file frame.c.

Referenced by alloc_audio_frame(), alloc_picture(), av_frame_make_writable(), av_frame_ref(), avresample_convert_frame(), config_output(), decode_entropy_coded_image(), dxva2_retrieve_data(), ff_default_get_audio_buffer(), ff_default_get_video_buffer(), ff_mpv_encode_init(), get_input(), init_output_frame(), libwebp_encode_frame(), pad_last_frame(), vda_retrieve_data(), and vdpau_retrieve_data().

int av_frame_is_writable ( AVFrame frame)

Check if the frame data is writable.

Returns
A positive value if the frame data is writable (which is true if and only if each of the underlying buffers has only one reference, namely the one stored in this frame). Return 0 otherwise.

If 1 is returned the answer is valid until av_buffer_ref() is called on any of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly).

See also
av_frame_make_writable(), av_buffer_is_writable()

Definition at line 309 of file frame.c.

Referenced by av_frame_make_writable(), compand_nodelay(), ff_filter_frame(), ff_reget_buffer(), filter_frame(), and frame_needs_copy().

int av_frame_make_writable ( AVFrame frame)

Ensure that the frame data is writable, avoiding data copy if possible.

Do nothing if the frame is writable, allocate new buffers and copy the data if it is not.

Returns
0 on success, a negative AVERROR on error.
See also
av_frame_is_writable(), av_buffer_is_writable(), av_buffer_make_writable()

Definition at line 325 of file frame.c.

Referenced by fill_yuv_image(), and process_audio_stream().

int av_frame_copy ( AVFrame dst,
const AVFrame src 
)

Copy the frame data from src to dst.

This function does not allocate anything, dst must be already initialized and allocated with the same parameters as src.

This function only copies the frame data (i.e. the contents of the data / extended data arrays), not any other properties.

Returns
>= 0 on success, a negative AVERROR on error.

Definition at line 532 of file frame.c.

Referenced by av_frame_make_writable(), av_frame_ref(), ff_reget_buffer(), filter_frame(), libwebp_encode_frame(), and shuffleplanes_filter_frame().

int av_frame_copy_props ( AVFrame dst,
const AVFrame src 
)

Copy only "metadata" fields from src to dst.

Metadata for the purpose of this function are those fields that do not affect the data layout in the buffers. E.g. pts, sample rate (for audio) or sample aspect ratio (for video), but not width/height or channel layout. Side data is also copied.

Definition at line 367 of file frame.c.

Referenced by av_frame_make_writable(), av_frame_ref(), compand_delay(), compand_nodelay(), dxva2_retrieve_data(), ff_filter_frame(), filter_frame(), load_input_picture(), pad_last_frame(), request_frame(), return_frame(), select_input_picture(), shuffleplanes_filter_frame(), unrefcount_frame(), vda_retrieve_data(), and vdpau_retrieve_data().

AVBufferRef* av_frame_get_plane_buffer ( AVFrame frame,
int  plane 
)

Get the buffer reference a given data plane is stored in.

Parameters
planeindex of the data plane of interest in frame->extended_data.
Returns
the buffer reference that contains the plane or NULL if the input frame is not valid.

Definition at line 414 of file frame.c.

Referenced by buffer_needs_copy(), and join_request_frame().

AVFrameSideData* av_frame_new_side_data ( AVFrame frame,
enum AVFrameSideDataType  type,
int  size 
)

Add a new side data to a frame.

Parameters
framea frame to which the side data should be added
typetype of the added side data
sizesize of the side data
Returns
newly added side data on success, NULL on error

Definition at line 444 of file frame.c.

Referenced by av_downmix_info_update_side_data(), av_frame_copy_props(), av_stereo3d_create_side_data(), decode_postinit(), ff_decode_frame_props(), ff_side_data_update_matrix_encoding(), mpeg_field_start(), and set_side_data().

AVFrameSideData* av_frame_get_side_data ( const AVFrame frame,
enum AVFrameSideDataType  type 
)
Returns
a pointer to the side data of a given type on success, NULL if there is no side data with such type in this frame.

Definition at line 477 of file frame.c.

Referenced by av_downmix_info_update_side_data(), ff_mpeg1_encode_picture_header(), ff_side_data_update_matrix_encoding(), filter_frame(), and X264_frame().

void av_frame_remove_side_data ( AVFrame frame,
enum AVFrameSideDataType  type 
)

If side data of the supplied type exists in the frame, free it and remove it from the frame.

Definition at line 545 of file frame.c.

Referenced by filter_frame().