Struct AVFrame

#[repr(C)]
pub struct AVFrame {

    pub data: [*mut u8; 8],
    pub linesize: [c_int; 8],
    pub extended_data: *mut *mut u8,
    pub width: c_int,
    pub height: c_int,
    pub nb_samples: c_int,
    pub format: c_int,
    pub key_frame: c_int,
    pub pict_type: AVPictureType,
    pub sample_aspect_ratio: AVRational,
    pub pts: i64,
    pub pkt_dts: i64,
    pub time_base: AVRational,
    pub coded_picture_number: c_int,
    pub display_picture_number: c_int,
    pub quality: c_int,
    pub opaque: *mut c_void,
    pub repeat_pict: c_int,
    pub interlaced_frame: c_int,
    pub top_field_first: c_int,
    pub palette_has_changed: c_int,
    pub reordered_opaque: i64,
    pub sample_rate: c_int,
    pub channel_layout: u64,
    pub buf: [*mut AVBufferRef; 8],
    pub extended_buf: *mut *mut AVBufferRef,
    pub nb_extended_buf: c_int,
    pub side_data: *mut *mut AVFrameSideData,
    pub nb_side_data: c_int,
    pub flags: c_int,
    pub color_range: AVColorRange,
    pub color_primaries: AVColorPrimaries,
    pub color_trc: AVColorTransferCharacteristic,
    pub colorspace: AVColorSpace,
    pub chroma_location: AVChromaLocation,
    pub best_effort_timestamp: i64,
    pub pkt_pos: i64,
    pub pkt_duration: i64,
    pub metadata: *mut AVDictionary,
    pub decode_error_flags: c_int,
    pub channels: c_int,
    pub pkt_size: c_int,
    pub hw_frames_ctx: *mut AVBufferRef,
    pub opaque_ref: *mut AVBufferRef,
    pub crop_top: usize,
    pub crop_bottom: usize,
    pub crop_left: usize,
    pub crop_right: usize,
    pub private_ref: *mut AVBufferRef,
    pub ch_layout: AVChannelLayout,
    pub duration: i64,
}

This structure describes decoded (raw) audio or video data.

AVFrame must be allocated using av_frame_alloc(). Note that this only allocates the AVFrame itself, the buffers for the data must be managed through other means (see below). AVFrame must be freed with av_frame_free().

AVFrame is typically allocated once and then reused multiple times to hold different data (e.g. a single AVFrame to hold frames received from a decoder). In such a case, av_frame_unref() will free any references held by the frame and reset it to its original clean state before it is reused again.

The data described by an AVFrame is usually reference counted through the AVBuffer API. The underlying buffer references are stored in AVFrame.buf / AVFrame.extended_buf. An AVFrame is considered to be reference counted if at least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case, every single data plane must be contained in one of the buffers in AVFrame.buf or AVFrame.extended_buf. There may be a single buffer for all the data, or one separate buffer for each plane, or anything in between.

sizeof(AVFrame) is not a part of the public ABI, so new fields may be added to the end with a minor bump.

Fields can be accessed through AVOptions, the name string used, matches the C structure field name for fields accessible through AVOptions. The AVClass for AVFrame can be obtained from avcodec_get_frame_class()

Fields

data: [*mut u8; 8]

pointer to the picture/channel planes. This might be different from the first allocated byte. For video, it could even point to the end of the image data.

All pointers in data and extended_data must point into one of the AVBufferRef in buf or extended_buf.

Some decoders access areas outside 0,0 - width,height, please see avcodec_align_dimensions2(). Some filters and swscale can read up to 16 bytes beyond the planes, if these filters are to be used, then 16 extra bytes must be allocated.

NOTE: Pointers not needed by the format MUST be set to NULL.

@attention In case of video, the data[] pointers can point to the end of image data in order to reverse line order, when used in combination with negative values in the linesize[] array.

linesize: [c_int; 8]

For video, a positive or negative value, which is typically indicating the size in bytes of each picture line, but it can also be:

• the negative byte size of lines for vertical flipping (with data[n] pointing to the end of the data
• a positive or negative multiple of the byte size as for accessing even and odd fields of a frame (possibly flipped)

For audio, only linesize[0] may be set. For planar audio, each channel plane must be the same size.

For video the linesizes should be multiples of the CPUs alignment preference, this is 16 or 32 for modern desktop CPUs. Some code requires such alignment other code can be slower without correct alignment, for yet other it makes no difference.

@note The linesize may be larger than the size of usable data – there may be extra padding present for performance reasons.

@attention In case of video, line size values can be negative to achieve a vertically inverted iteration over image lines.

extended_data: *mut *mut u8

pointers to the data planes/channels.

For video, this should simply point to data[].

For planar audio, each channel has a separate data pointer, and linesize[0] contains the size of each channel buffer. For packed audio, there is just one data pointer, and linesize[0] contains the total size of the buffer for all channels.

Note: Both data and extended_data should always be set in a valid frame, but for planar audio with more channels that can fit in data, extended_data must be used in order to access all channels.

width: c_int

@name Video dimensions Video frames only. The coded dimensions (in pixels) of the video frame, i.e. the size of the rectangle that contains some well-defined values.

@note The part of the frame intended for display/presentation is further restricted by the @ref cropping “Cropping rectangle”. @{

height: c_int

@name Video dimensions Video frames only. The coded dimensions (in pixels) of the video frame, i.e. the size of the rectangle that contains some well-defined values.

@note The part of the frame intended for display/presentation is further restricted by the @ref cropping “Cropping rectangle”. @{

nb_samples: c_int

number of audio samples (per channel) described by this frame

format: c_int

format of the frame, -1 if unknown or unset Values correspond to enum AVPixelFormat for video frames, enum AVSampleFormat for audio)

key_frame: c_int

1 -> keyframe, 0-> not

@deprecated Use AV_FRAME_FLAG_KEY instead

pict_type: AVPictureType

Picture type of the frame.

sample_aspect_ratio: AVRational

Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.

pts: i64

Presentation timestamp in time_base units (time when frame should be shown to user).

pkt_dts: i64

DTS copied from the AVPacket that triggered returning this frame. (if frame threading isn’t used) This is also the Presentation time of this AVFrame calculated from only AVPacket.dts values without pts values.

time_base: AVRational

Time base for the timestamps in this frame. In the future, this field may be set on frames output by decoders or filters, but its value will be by default ignored on input to encoders or filters.

coded_picture_number: c_int

picture number in bitstream order

display_picture_number: c_int

picture number in display order

quality: c_int

quality (between 1 (good) and FF_LAMBDA_MAX (bad))

opaque: *mut c_void

Frame owner’s private data.

This field may be set by the code that allocates/owns the frame data. It is then not touched by any library functions, except:

• it is copied to other references by av_frame_copy_props() (and hence by av_frame_ref());
• it is set to NULL when the frame is cleared by av_frame_unref()
• on the caller’s explicit request. E.g. libavcodec encoders/decoders will copy this field to/from @ref AVPacket “AVPackets” if the caller sets @ref AV_CODEC_FLAG_COPY_OPAQUE.

@see opaque_ref the reference-counted analogue

repeat_pict: c_int

Number of fields in this frame which should be repeated, i.e. the total duration of this frame should be repeat_pict + 2 normal field durations.

For interlaced frames this field may be set to 1, which signals that this frame should be presented as 3 fields: beginning with the first field (as determined by AV_FRAME_FLAG_TOP_FIELD_FIRST being set or not), followed by the second field, and then the first field again.

For progressive frames this field may be set to a multiple of 2, which signals that this frame’s duration should be (repeat_pict + 2) / 2 normal frame durations.

@note This field is computed from MPEG2 repeat_first_field flag and its associated flags, H.264 pic_struct from picture timing SEI, and their analogues in other codecs. Typically it should only be used when higher-layer timing information is not available.

interlaced_frame: c_int

The content of the picture is interlaced.

@deprecated Use AV_FRAME_FLAG_INTERLACED instead

top_field_first: c_int

If the content is interlaced, is top field displayed first.

@deprecated Use AV_FRAME_FLAG_TOP_FIELD_FIRST instead

palette_has_changed: c_int

Tell user application that palette has changed from previous frame.

reordered_opaque: i64

reordered opaque 64 bits (generally an integer or a double precision float PTS but can be anything). The user sets AVCodecContext.reordered_opaque to represent the input at that time, the decoder reorders values as needed and sets AVFrame.reordered_opaque to exactly one of the values provided by the user through AVCodecContext.reordered_opaque

@deprecated Use AV_CODEC_FLAG_COPY_OPAQUE instead

sample_rate: c_int

Sample rate of the audio data.

channel_layout: u64

Channel layout of the audio data. @deprecated use ch_layout instead

buf: [*mut AVBufferRef; 8]

AVBuffer references backing the data for this frame. All the pointers in data and extended_data must point inside one of the buffers in buf or extended_buf. This array must be filled contiguously – if buf[i] is non-NULL then buf[j] must also be non-NULL for all j < i.

There may be at most one AVBuffer per data plane, so for video this array always contains all the references. For planar audio with more than AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in this array. Then the extra AVBufferRef pointers are stored in the extended_buf array.

extended_buf: *mut *mut AVBufferRef

For planar audio which requires more than AV_NUM_DATA_POINTERS AVBufferRef pointers, this array will hold all the references which cannot fit into AVFrame.buf.

Note that this is different from AVFrame.extended_data, which always contains all the pointers. This array only contains the extra pointers, which cannot fit into AVFrame.buf.

This array is always allocated using av_malloc() by whoever constructs the frame. It is freed in av_frame_unref().

nb_extended_buf: c_int

Number of elements in extended_buf.

side_data: *mut *mut AVFrameSideData

nb_side_data: c_int

flags: c_int

Frame flags, a combination of @ref lavu_frame_flags

color_range: AVColorRange

MPEG vs JPEG YUV range.

• encoding: Set by user
• decoding: Set by libavcodec

color_primaries: AVColorPrimaries

color_trc: AVColorTransferCharacteristic

colorspace: AVColorSpace

YUV colorspace type.

• encoding: Set by user
• decoding: Set by libavcodec

chroma_location: AVChromaLocation

best_effort_timestamp: i64

frame timestamp estimated using various heuristics, in stream time base

• encoding: unused
• decoding: set by libavcodec, read by user.

pkt_pos: i64

reordered pos from the last AVPacket that has been input into the decoder

• encoding: unused
• decoding: Read by user. @deprecated use AV_CODEC_FLAG_COPY_OPAQUE to pass through arbitrary user data from packets to frames

pkt_duration: i64

duration of the corresponding packet, expressed in AVStream->time_base units, 0 if unknown.

• encoding: unused
• decoding: Read by user.

@deprecated use duration instead

metadata: *mut AVDictionary

metadata.

• encoding: Set by user.
• decoding: Set by libavcodec.

decode_error_flags: c_int

decode error flags of the frame, set to a combination of FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there were errors during the decoding.

• encoding: unused
• decoding: set by libavcodec, read by user.

channels: c_int

number of audio channels, only used for audio.

• encoding: unused
• decoding: Read by user. @deprecated use ch_layout instead

pkt_size: c_int

size of the corresponding packet containing the compressed frame. It is set to a negative value if unknown.

• encoding: unused
• decoding: set by libavcodec, read by user. @deprecated use AV_CODEC_FLAG_COPY_OPAQUE to pass through arbitrary user data from packets to frames

hw_frames_ctx: *mut AVBufferRef

For hwaccel-format frames, this should be a reference to the AVHWFramesContext describing the frame.

opaque_ref: *mut AVBufferRef

Frame owner’s private data.

This field may be set by the code that allocates/owns the frame data. It is then not touched by any library functions, except:

• a new reference to the underlying buffer is propagated by av_frame_copy_props() (and hence by av_frame_ref());
• it is unreferenced in av_frame_unref();
• on the caller’s explicit request. E.g. libavcodec encoders/decoders will propagate a new reference to/from @ref AVPacket “AVPackets” if the caller sets @ref AV_CODEC_FLAG_COPY_OPAQUE.

@see opaque the plain pointer analogue

crop_top: usize

@anchor cropping @name Cropping Video frames only. The number of pixels to discard from the the top/bottom/left/right border of the frame to obtain the sub-rectangle of the frame intended for presentation. @{

crop_bottom: usize

crop_left: usize

crop_right: usize

private_ref: *mut AVBufferRef

AVBufferRef for internal use by a single libav* library. Must not be used to transfer data between libraries. Has to be NULL when ownership of the frame leaves the respective library.

Code outside the FFmpeg libs should never check or change the contents of the buffer ref.

FFmpeg calls av_buffer_unref() on it when the frame is unreferenced. av_frame_copy_props() calls create a new reference with av_buffer_ref() for the target frame’s private_ref field.

ch_layout: AVChannelLayout

Channel layout of the audio data.

duration: i64

Duration of the frame, in the same units as pts. 0 if unknown.