FFMPEG学习【libavutil】：数据结构（二）

一、AVFrame

AVFrame是引用计数的原始多媒体数据的抽象。

一）、模块

描述其他帧属性的标志。

#define AV_FRAME_FLAG_CORRUPT   (1 << 0)帧数据可能被破坏，例如，

由于解码错误。

#define AV_FRAME_FLAG_DISCARD   (1 << 2)标记需要解码的帧的标志，但不应该被输出。

二）、数据结构

AVFrameSideData

结构以保存AVFrame的边数据。

sizeof（AVFrameSideData）不是公共ABI的一部分，所以新的字段可能会添加到最后一个小的凹凸。

struct  AVFrameSideData{
enum AVFrameSideDataType type；
uint8_t * data；
int size；
AVDictionary * metadata；
AVBufferRef * buf；
}

AVFrame

该结构描述了解码（原始）音频或视频数据。

AVFrame必须使用av_frame_alloc（）分配。 请注意，这只会分配AVFrame本身，数据的缓冲区必须通过其他方式进行管理（见下文）。 AVFrame必须与av_frame_free（）一起释放。

AVFrame通常被分配一次，然后重复使用多次以保存不同的数据（例如，单个AVFrame来保存从解码器接收的帧）。 在这种情况下，av_frame_unref（）将释放框架中的任何引用，并将其重新设置为原始的清洁状态，然后再次重新使用。

AVFrame描述的数据通常通过AVBuffer API进行引用。 基础缓冲区引用存储在AVFrame.buf / AVFrame.extended_buf中。 如果设置了至少一个引用，则AVFrame被认为是引用计数，即如果AVFrame.buf [0]！= NULL。 在这种情况下，每个单个数据平面必须包含在AVFrame.buf或AVFrame.extended_buf中的缓冲区之一中。 所有数据可能有一个缓冲区，或者每个平面有一个单独的缓冲区，或两者之间的任何内容。

sizeof（AVFrame）不是公共ABI的一部分，所以新的字段可能会被添加到最后一个小的碰撞。

可以通过AVOptions访问字段，使用的名称字符串与通过AVOptions可访问的字段的C结构字段名称相匹配。 用于AVFrame的AVClass可以从avcodec_get_frame_class（）获取，

struct  AVFrame{
uint8_t * data [AV_NUM_DATA_POINTERS]； // 指向图片/频道平面的指针。
int linesize [AV_NUM_DATA_POINTERS] // 对于视频，每个图片行的字节大小。
uint8_t ** extended_data; //指向数据平面/通道的指针。
int nb_samples; // 此框描述的音频样本数（每个通道）
int format; // 帧的格式，-1如果未知或未设置值对应于视频帧的枚举AVPixelFormat，枚举AVSampleFormat为音频）
int key_frame; // 1 - >关键帧，0->非关键帧
enum AVPictureType pict_type;//帧的图片类型。
AVRational sample_aspect_ratio； //视频帧的采样宽高比，如果未知/未指定，则为0/1。
int64_t pts; // 以time_base为单位表示时间戳（应向用户显示帧的时间）。
attribute_deprecated int64_t pkt_pts; //从AVPacket复制的PTS被解码以产生此帧。
int64_t pkt_dts; // 从AVPacket复制的DTS触发返回此帧。
int coded_picture_number; //图片编号以比特比顺序
int display_picture_number; // 图片编号显示顺序
int quality; // 质量（1（好）和FF_LAMBDA_MAX（差））
void * opaque; //为用户的一些私人数据
attribute_deprecated uint64_t error [AV_NUM_DATA_POINTERS];
int repeat_pict; // 当解码时，这表示图片必须延迟多少。
int interlaced_frame; // 图片的内容是交错的。
int top_field_first; // 如果内容是隔行扫描，则首先显示顶部字段。
int palette_has_changed; //告诉用户应用程序调色板已从前一帧更改。
int64_t reordered_opaque; //重新排序的不透明64位（通常是整数或双精度浮点PTS，但可以是任何东西）。
int sample_rate; //音频数据的采样率。
uint64_t channel_layout; // 音频数据的通道布局。
AVBufferRef * buf [AV_NUM_DATA_POINTERS]; // AVBuffer引用支持此框架的数据。
AVBufferRef ** extended_buf; // 对于需要超过AV_NUM_DATA_POINTERS AVBufferRef指针的平面音频，此数组将保存所有不能适合AVFrame.buf的引用。
int nb_extended_buf; // extended_buf中的元素数。
AVFrameSideData ** side_data;
int nb_side_data;
int flags; //帧标志，AV_FRAME_FLAGS的组合。
enum AVColorRange color_range;// MPEG与JPEG YUV范围。
enum AVColorPrimaries color_primaries;
enum AVColorTransferCharacteristic color_trc;
enum AVColorSpace colorspace;//YUV颜色空间类型。
enum AVChromaLocation chroma_location;
int64_t best_effort_timestamp; // 帧时间戳使用各种启发式估计，在流时基
int64_t pkt_pos; // 从已经输入到解码器的最后一个AVPacket重新排序pos
int64_t pkt_duration; // 相应分组的持续时间，以AVStream-> time_base单位表示，如果未知，则为0。
AVDictionary * metadata;//元数据
int decode_error_flags； //解码帧的错误标志，如果解码器产生帧，则将其设置为FF_DECODE_ERROR_xxx标志的组合，但在解码期间存在错误。
int channels; // 音频通道数，仅用于音频。
int pkt_size; //包含压缩帧的相应分组的大小。
attribute_deprecated int8_t * qscale_table;// QP表。
attribute_deprecated int qstride;// QP店步伐。
attribute_deprecated int qscale_type;
AVBufferRef * qp_table_buf;
AVBufferRef * hw_frames_ctx; //对于hwaccel格式的帧，这应该是对描述帧的AVHWFramesContext的引用。
AVBufferRef * opaque_ref; // AVBufferRef由API用户免费使用。
}视频尺寸

视频帧。

视频帧的编码维度（以像素为单位），即包含一些明确定义值的矩形的大小。

注意：用于显示/呈现的框架部分进一步受到“裁剪”矩形的限制。

int widthint height

裁剪

视频帧。 从帧的顶部/底部/左/右边界丢弃的像素数，以获得用于呈现的帧的子矩形。

size_t crop_topsize_t crop_bottomsize_t crop_leftsize_t crop_right

三）、枚举

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, 
  AV_FRAME_DATA_MOTION_VECTORS, 
AV_FRAME_DATA_SKIP_SAMPLES, 
AV_FRAME_DATA_AUDIO_SERVICE_TYPE, 
AV_FRAME_DATA_MASTERING_DISPLAY_METADATA, 
  AV_FRAME_DATA_GOP_TIMECODE, 
AV_FRAME_DATA_SPHERICAL, 
AV_FRAME_DATA_CONTENT_LIGHT_LEVEL 
}

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 
}

四）、函数

int64_t av_frame_get_best_effort_timestamp (const AVFrame *frame)某些AVFrame字段的访问器。

void av_frame_set_best_effort_timestamp (AVFrame *frame, int64_t val)

int64_t av_frame_get_pkt_duration (const AVFrame *frame)

void av_frame_set_pkt_duration (AVFrame *frame, int64_t val)

int64_t av_frame_get_pkt_pos (const AVFrame *frame)

void av_frame_set_pkt_pos (AVFrame *frame, int64_t val)

int64_t av_frame_get_channel_layout (const AVFrame *frame)

void av_frame_set_channel_layout (AVFrame *frame, int64_t val)

int av_frame_get_channels (const AVFrame *frame)

void av_frame_set_channels (AVFrame *frame, int val) 

int av_frame_get_sample_rate (const AVFrame *frame)

void av_frame_set_sample_rate (AVFrame *frame, int val)

AVDictionary * av_frame_get_metadata (const AVFrame *frame)

void av_frame_set_metadata (AVFrame *frame, AVDictionary *val)

int av_frame_get_decode_error_flags (const AVFrame *frame)

void av_frame_set_decode_error_flags (AVFrame *frame, int val)

int av_frame_get_pkt_size (const AVFrame *frame)

void av_frame_set_pkt_size (AVFrame *frame, int val)

AVDictionary ** avpriv_frame_get_metadatap (AVFrame *frame)

int8_t * av_frame_get_qp_table (AVFrame *f, int *stride, int *type)

int av_frame_set_qp_table (AVFrame *f, AVBufferRef *buf, int stride, int type) 

enum AVColorSpace av_frame_get_colorspace (const AVFrame *frame)

void av_frame_set_colorspace (AVFrame *frame, enum AVColorSpace val)

enum AVColorRange av_frame_get_color_range (const AVFrame *frame)

void av_frame_set_color_range (AVFrame *frame, enum AVColorRange val)

const char * av_get_colorspace_name (enum AVColorSpace val)获取颜色空间的名称。

返回：标识颜色空间的静态字符串; 可以为NULL。

AVFrame * av_frame_alloc (void)分配AVFrame并将其字段设置为默认值。

结果必须使用av_frame_free（）被释放。

返回：AVFrame充满默认值或失败时为NULL。

注意：这只分配AVFrame本身，而不是数据缓冲区。 那些必须通过其他方式分配，例如 使用av_frame_get_buffer（）或手动。

void av_frame_free (AVFrame **frame)释放帧和其中任何动态分配的对象，例如

extended_data。 如果框架被引用计数，则首先将其未引用。

参数：frame：框架被释放。 指针将设置为NULL。

int av_frame_ref (AVFrame *dst, const AVFrame *src)设置对源帧描述的数据的新引用。

将框架属性从src复制到dst，并从src为每个AVBufferRef创建一个新的引用。

如果src未引用计数，则会分配新的缓冲区并复制数据。

警告：在调用此函数之前，dst必须已经被av_frame_unref（dst）未被引用或新分配了av_frame_alloc（），否则将会发生未定义的行为。

返回：0成功，否定AVERROR出错

AVFrame * av_frame_clone (const AVFrame *src)创建引用与src相同的数据的新框架。

这是av_frame_alloc（）+ av_frame_ref（）的快捷方式。

返回：新创建的AVFrame成功，NULL出错。

void av_frame_unref (AVFrame *frame)取消引用帧引用的所有缓冲区，并重置框架域。

void av_frame_move_ref (AVFrame *dst, AVFrame *src)将src中包含的所有内容移动到dst并重置src。

警告：dst不是未引用的，而是直接覆盖而不读取或取消分配其内容。 在调用此函数之前，请手动调用av_frame_unref（dst），以确保没有内存泄漏。

int av_frame_get_buffer (AVFrame *frame, int align)为音频或视频数据分配新的缓冲区。

在调用此函数之前，必须在框架上设置以下字段：

1、格式（视频的像素格式，音频采样格式）

2、视频的宽度和高度

3、音频的nb_samples和channel_layout

此函数将填充AVFrame.data和AVFrame.buf数组，并在必要时分配并填充AVFrame.extended_data和AVFrame.extended_buf。 对于平面格式，将为每个平面分配一个缓冲区。

警告：如果帧已经被分配，调用此函数将泄漏内存。 此外，在某些情况下可能会发生未定义的行为。

参数：frame：在其中存储新缓冲区的帧。

   align：所需缓冲区大小对齐

返回：0成功，否定AVERROR出错。

int av_frame_is_writable (AVFrame *frame)检查帧数据是否可写。

返回：如果帧数据是可写的，则为正值（如果且仅当每个底层缓冲区只有一个引用，即存储在此帧中的引用）时，则该值为真。 否则返回0。
如果返回1，答案是有效的，直到av_buffer_ref（）被调用到任何一个底层的AVBufferRefs（例如通过av_frame_ref（）或直接）。

int av_frame_make_writable (AVFrame *frame)确保帧数据是可写的，如果可能，避免数据复制。

如果帧是可写的，则不执行任何操作，如果不是，则分配新的缓冲区并复制数据。

返回：0成功，否定AVERROR出错。

int av_frame_copy (AVFrame *dst, const AVFrame *src)将帧数据从src复制到dst。

此函数不分配任何东西，dst必须已经初始化并分配与src相同的参数。

该功能仅复制帧数据（即数据/扩展数据数组的内容），而不是任何其他属性。

返回：> = 0成功，错误的AVERROR为负。

int av_frame_copy_props (AVFrame *dst, const AVFrame *src)仅将src中的“元数据”字段复制到dst。

用于此功能的元数据是不影响缓冲区中数据布局的那些字段。 例如。 pts，采样率（音频）或采样宽高比（视频），但不是宽/高或通道布局。 侧面数据也被复制。

AVBufferRef * av_frame_get_plane_buffer (AVFrame *frame, int plane)获取存储给定数据平面的缓冲区引用。

参数：plane：在frame-> extended_data中感兴趣的数据平面的索引。

返回：包含平面的缓冲区引用，如果输入框无效则为NULL。

AVFrameSideData * av_frame_new_side_data (AVFrame *frame, enum AVFrameSideDataType type, int size)将一个新的边数据添加到一个框架。

参数：frame：应该添加侧面数据的框架

   type：添加侧数据的类型

   size：边数据的大小

返回：新添加的侧面数据成功，NULL出错

AVFrameSideData * av_frame_get_side_data (const AVFrame *frame, enum AVFrameSideDataType type)返回：指向成功的给定类型的边数据的指针，如果在该帧中没有这种类型的边数据，则为NULL。

void av_frame_remove_side_data (AVFrame *frame, enum AVFrameSideDataType type)如果提供的类型的边数据存在于帧中，则将其从帧中取出并将其移除。

const char * av_frame_side_data_name (enum AVFrameSideDataType type)返回：一个标识边数据类型的字符串