FFmpeg5.0源码阅读之AVClass和AVOption

  摘要：本文通过阅读FFmpeg源码来理解FFmpeg中AVOption的实现原理和具体的使用方式。
  关键字：AVClss,AVOption,AVOptionRange
  版本：FFmpeg5.0

1 AVOption结构

  AVOption是FFmpeg中设置参数的一个基本抽象结构。因为FFmpeg是一个支持多种封装解封装器，编解码器的框架，而不同的外部库需要的参数各不相同，因此利用AVOption来封装一个基本的key-value结构来获取和设置对应模块的参数。AVOption本身就是一个key-value项，可以理解为C++中map中的项pair，而其中name就是key，default_val就是value。而在实际使用中所有的参数是存储在AVClass中的AVOption数组中，而需要设置参数的模块会在Context结构体开头设置一个AVClass的指针来表示当前模块的参数，FFmpeg通过搜索该数组来获取和设置对应模块的参数。另外，并不是所有的参数都会存储在AVOption中，有些参数对应的Context本身就有对应的成员，因此AVOption只需要指定该成员相对应该Context首部地址的偏移即可进行设置和读取，也就是说通过AVOption设置和直接用Context->param = value的形式是一致的。

typedef struct AVOption {
    
    
    const char *name;           //参数名称
    const char *help;           //简短的帮助信息，因为是char因此无法支持中文等语言
    int offset;                 //选项相对于结构体首部的偏移量
    enum AVOptionType type;     //选项的类型
    union {
    
    
        int64_t i64;
        double dbl;
        const char *str;
        AVRational q;
    } default_val;              //选项的默认值
    double min;                 //选项可允许的最小值
    double max;                 //选项可允许的最大值
    int flags;                  //标志符
    const char *unit;           //当前选项所属的逻辑单元，可以为NULL
} AVOption;

• default_value：当前选项的值是一个64bit的union，这基本能够表示所有的数值参数和字符串参数；

• type：当前选项的类型，如下面的AVOptionType的定义，不仅仅输数据类型也涵盖了一些FFmpeg中用到的选项类型；

  enum AVOptionType{
        
        
    AV_OPT_TYPE_FLAGS,
    AV_OPT_TYPE_INT,
    AV_OPT_TYPE_INT64,
    AV_OPT_TYPE_DOUBLE,
    AV_OPT_TYPE_FLOAT,
    AV_OPT_TYPE_STRING,
    AV_OPT_TYPE_RATIONAL,
    AV_OPT_TYPE_BINARY,  ///< offset must point to a pointer immediately followed by an int for the length
    AV_OPT_TYPE_DICT,
    AV_OPT_TYPE_UINT64,
    AV_OPT_TYPE_CONST,
    AV_OPT_TYPE_IMAGE_SIZE, ///< offset must point to two consecutive integers
    AV_OPT_TYPE_PIXEL_FMT,
    AV_OPT_TYPE_SAMPLE_FMT,
    AV_OPT_TYPE_VIDEO_RATE, ///< offset must point to AVRational
    AV_OPT_TYPE_DURATION,
    AV_OPT_TYPE_COLOR,
    AV_OPT_TYPE_CHANNEL_LAYOUT,
    AV_OPT_TYPE_BOOL,
  };
  

• offset：如上面描述，这个offset是相对于包含AVClass的Context的首地址的偏移；

• min,max：选项取值范围，需要注意的是这里声明的是double；

• flags：flag描述当前选项的用处，如下定义；

  #define AV_OPT_FLAG_ENCODING_PARAM  1   ///< a generic parameter which can be set by the user for muxing or encoding
  #define AV_OPT_FLAG_DECODING_PARAM  2   ///< a generic parameter which can be set by the user for demuxing or decoding
  #define AV_OPT_FLAG_AUDIO_PARAM     8
  #define AV_OPT_FLAG_VIDEO_PARAM     16
  #define AV_OPT_FLAG_SUBTITLE_PARAM  32
  //The option is intended for exporting values to the caller.
  #define AV_OPT_FLAG_EXPORT          64
  //The option may not be set through the AVOptions API, only read. This flag only makes sense when AV_OPT_FLAG_EXPORT is also set.
  #define AV_OPT_FLAG_READONLY        128
  #define AV_OPT_FLAG_BSF_PARAM       (1<<8) ///< a generic parameter which can be set by the user for bit stream filtering
  #define AV_OPT_FLAG_RUNTIME_PARAM   (1<<15) ///< a generic parameter which can be set by the user at runtime
  #define AV_OPT_FLAG_FILTERING_PARAM (1<<16) ///< a generic parameter which can be set by the user for filtering
  #define AV_OPT_FLAG_DEPRECATED      (1<<17) ///< set if option is deprecated, users should refer to AVOption.help text for more information
  #define AV_OPT_FLAG_CHILD_CONSTS    (1<<18) ///< set if option constants can also reside in child objects
  

2 AVClass结构

  由于设置AVOption都是通过AVClass进行的，因此有必要了解下AVClass的结构。AVClass是FFmpeg中描述一个Context的抽象，FFmpeg中的Context的第一个成员就是一个AVClass的指针来描述当前Context的基本信息和相关的参数，设置参数也是通过这个指针进行的。比如AVFormatContext：

typedef struct AVFormatContext {
    
    
    //A class for logging and @ref avoptions. Set by avformat_alloc_context(). Exports (de)muxer private options if they exist.
    const AVClass *av_class;
    //省略大部分代码
}AVFormatContext;

typedef struct AVClass {
    
    
    const char* class_name;                            //AVClass所属类的名称
    const char* (*item_name)(void* ctx);               //获取AVClass所属类名称的函数指针，有些实现会直接返回AVClass->class_name
    const struct AVOption *option;                     //当前类的参数，没有就置为NULL
    int version;                                       //当前字段创建的版本，可用于版本控制，This is used to allow fields to be added without requiring major version bumps everywhere.
    int log_level_offset_offset;                       //AVClass所属结构体中log_level_offset相对于其首地址的偏移，0表示没有该成员
    int parent_log_context_offset;                     //当前Context中存储parent context的偏移量
    void* (*child_next)(void *obj, void *prev);        //AVOptions中下一个可用的参数
    AVClassCategory category;                          //当前类的类别
    AVClassCategory (*get_category)(void* ctx);        //获取当前Context类别的函数指针      
    //查询对应选项的范围，虽然定义了但是FFmpeg源码中好像没有API用到
    int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags);
    /**
     * Iterate over the AVClasses corresponding to potential AVOptions-enabled children.
     * @param iter pointer to opaque iteration state. The caller must initialize *iter to NULL before the first call.
     * @return AVClass for the next AVOptions-enabled child or NULL if there are no more such children.
     * @note The difference between child_next and this is that child_next iterates over _already existing_ objects, while child_class_iterate iterates over _all possible_ children.
    const struct AVClass* (*child_class_iterate)(void **iter);
} AVClass;

  AVClassCategory定义如下：

typedef enum {
    
    
    AV_CLASS_CATEGORY_NA = 0,
    AV_CLASS_CATEGORY_INPUT,
    AV_CLASS_CATEGORY_OUTPUT,
    AV_CLASS_CATEGORY_MUXER,
    AV_CLASS_CATEGORY_DEMUXER,
    AV_CLASS_CATEGORY_ENCODER,
    AV_CLASS_CATEGORY_DECODER,
    AV_CLASS_CATEGORY_FILTER,
    AV_CLASS_CATEGORY_BITSTREAM_FILTER,
    AV_CLASS_CATEGORY_SWSCALER,
    AV_CLASS_CATEGORY_SWRESAMPLER,
    AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT = 40,
    AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT,
    AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT,
    AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT,
    AV_CLASS_CATEGORY_DEVICE_OUTPUT,
    AV_CLASS_CATEGORY_DEVICE_INPUT,
    AV_CLASS_CATEGORY_NB  ///< not part of ABI/API
}AVClassCategory;

  FFmpeg源码在libavutil/tests/opt.c中有示例程序TestContext，下面只截取其中一部分。从下面可以看到TestContext第一个成员便是AVClass的指针，然后下面定义了所有选项的数组并将该数组传递给AVClass的option成员。而其中选项不同类型初始化方式也不同有些是直接写值，有些是通过偏移写TestContext的成员变量的值：

typedef struct TestContext {
    
    
    const AVClass *class;
    int num;
    int flags;
    AVRational rational;
    enum AVPixelFormat pix_fmt;
    char *escape;
} TestContext;

#define OFFSET(x) offsetof(TestContext, x)

#define TEST_FLAG_COOL 01
#define TEST_FLAG_LAME 02
#define TEST_FLAG_MU   04

static const AVOption test_options[]= {
    
    
    {
    
    "num",        "set num",            OFFSET(num),            AV_OPT_TYPE_INT,            {
    
     .i64 = 0 },                      0,       100, 1 },
    {
    
    "rational",   "set rational",       OFFSET(rational),       AV_OPT_TYPE_RATIONAL,       {
    
     .dbl = 1 },                      0,        10, 1 },
    {
    
    "escape",     "set escape str",     OFFSET(escape),         AV_OPT_TYPE_STRING,         {
    
     .str = "\\=," },          CHAR_MIN,  CHAR_MAX, 1 },
    {
    
    "flags",      "set flags",          OFFSET(flags),          AV_OPT_TYPE_FLAGS,          {
    
     .i64 = 1 },                      0,   INT_MAX, 1, "flags" },
    {
    
    "cool",       "set cool flag",      0,                      AV_OPT_TYPE_CONST,          {
    
     .i64 = TEST_FLAG_COOL },   INT_MIN,   INT_MAX, 1, "flags" },
    {
    
    "pix_fmt",    "set pixfmt",         OFFSET(pix_fmt),        AV_OPT_TYPE_PIXEL_FMT,      {
    
     .i64 = AV_PIX_FMT_0BGR },       -1,   INT_MAX, 1 },
};

static const char *test_get_name(void *ctx)
{
    
    
    return "test";
}

static const AVClass test_class = {
    
    
    .class_name = "TestContext",
    .item_name  = test_get_name,
    .option     = test_options,
};

3 AVOptionRange及相关的API

AVOption结构

扫描二维码关注公众号，回复： 14571599 查看本文章

typedef struct AVOptionRange {
    
    
    const char *str;						//字符串描述
    double value_min, value_max;			//对于字符串表示最大最小长度。对于尺寸，这表示多组件情况下的最小/最大像素数或宽度/高度。
    double component_min, component_max;	//对于字符串，这表示字符的 unicode 范围，0-127 限制为 ASCII。
    int is_range;							//是不是一个范围，0的话就是一个单纯的数值
} AVOptionRange;

//List of AVOptionRange structs.
typedef struct AVOptionRanges {
    
    
    AVOptionRange **range;					//二维数组，数组中元素的数目为nb_ranges * nb_components
    int nb_ranges;
    int nb_components;						//每个component有nb_ranges个AVOptionRange
} AVOptionRanges;

  下面是FFmpeg代码中给出的示例：

 /* AV_OPT_TYPE_IMAGE_SIZE:
  * component index 0: range of pixel count (width * height).
  * component index 1: range of width.
  * component index 2: range of height.
  */
int range_index, component_index;
AVOptionRanges *ranges;
AVOptionRange *range[3]; //may require more than 3 in the future.
av_opt_query_ranges(&ranges, obj, key, AV_OPT_MULTI_COMPONENT_RANGE);
for (range_index = 0; range_index < ranges->nb_ranges; range_index++) {
    
    
    for (component_index = 0; component_index < ranges->nb_components; component_index++)
        range[component_index] = ranges->range[ranges->nb_ranges * component_index + range_index];
    //do something with range here.
}
av_opt_freep_ranges(&ranges);

相关API描述：

• int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags)：获取对应的key的取值范围，实现中只有一个AVOptionRange项：

    ranges->nb_ranges = 1;
    ranges->nb_components = 1;
    range->is_range = 1;

• int av_opt_query_ranges(AVOptionRanges **ranges_arg, void *obj, const char *key, int flags)：具体实现调用的是obj中的query_ranges，如果未定义则使用默认的av_opt_query_ranges_default；
• void av_opt_freep_ranges(AVOptionRanges **ranges)：释放AVOptionRanges；
• **

4 AVOption相关API

  AVOption相关API的第一个参数都需要是一个结构体指针，该结构的第一个成员必须是AVClass的指针。

• const AVOption *av_opt_next(const void *obj, const AVOption *prev)：返回相对于prev的下一个AVOption。实现比较简单既然有了prev且AVOption存储在数组中那么prev自增即可，只是多了一些边界检查；
  • obj：第一个成员为AVClass指针的结构体；
  • prev：需要寻找选项的上一个选项，如果为NULL则返回第一个；
  • 返回值：prev下一个选项；

const AVOption *av_opt_next(const void *obj, const AVOption *last){
    
    
    const AVClass *class;
    if (!obj)
        return NULL;
    class = *(const AVClass**)obj;
    if (!last && class && class->option && class->option[0].name)
        return class->option;
    if (last && last[1].name)
        return ++last;
    return NULL;
}

• void *av_opt_child_next(void *obj, void *prev)：使用AVClass中的child_next返回下一个可用的参数选型；

void *av_opt_child_next(void *obj, void *prev){
    
    
    const AVClass *c = *(AVClass **)obj;
    if (c->child_next)
        return c->child_next(obj, prev);
    return NULL;
}

• const AVClass *av_opt_child_class_iterate(const AVClass *parent, void * *iter)：搜寻子类的AVClass，c中没有子类的概念，这里的子类由AVClass中child_class_iterate定义，具体实现也是调用的child_class_iterate取搜索的；
  • iter：存储搜索标志位的地址；
• const AVOption *av_opt_find2(void *obj, const char *name, const char *unit, int opt_flags, int search_flags, void * *target_obj)：在obj中搜索目标参数：
  • 搜索成功的条件：(string(o->name) == string(name)) && ((o->flags & opt_flags) == opt_flags) && ((!unit && o->type != AV_OPT_TYPE_CONST) || (unit && o->type == AV_OPT_TYPE_CONST && o->unit && string(o->unit) == string(unit))))
  • obj：应该是一个第一个成员指针为AVClass的结构体；
  • name：希望搜索的参数的名称；
  • unit：搜索的参数所属的逻辑单元；
  • opt_flags：期望搜索的参数的标志位；
  • search_flags：搜索的目标的标志位，如果设置了AV_OPT_SEARCH_CHILDREN则搜索的是由child_class_iterate定义的子类；
  • target_obj：搜索的目标，如果未设置AV_OPT_SEARCH_CHILDREN则为NULL或者输入的obj，否则为对应的子类的指针或者NULL（是否为NULL根据search_flags是否设置了AV_OPT_SEARCH_FAKE_OBJ而定）；
  • const AVOption *av_opt_find(void *obj, const char *name, const char *unit, int opt_flags, int search_flags)：调用av_opt_find2实现，只不过无法搜索子类的选项；

const AVOption *av_opt_find2(void *obj, const char *name, const char *unit, int opt_flags, int search_flags, void **target_obj){
    
    
	//下面是简化的代码
    c= *(AVClass**)obj;
    if (search_flags & AV_OPT_SEARCH_CHILDREN) {
    
    
        if (search_flags & AV_OPT_SEARCH_FAKE_OBJ) {
    
    
            void *iter = NULL;
            const AVClass *child;
            while (child = av_opt_child_class_iterate(c, &iter))
                if (o = av_opt_find2(&child, name, unit, opt_flags, search_flags, NULL))
                    return o;
        } else {
    
    
            void *child = NULL;
            while (child = av_opt_child_next(obj, child))
                if (o = av_opt_find2(child, name, unit, opt_flags, search_flags, target_obj))
                    return o;
        }
    }

    while (o = av_opt_next(obj, o)) {
    
    
		if(符合条件 && target_obj)
                if (!(search_flags & AV_OPT_SEARCH_FAKE_OBJ))
                    *target_obj = obj;
                else
                    *target_obj = NULL;
            }
            return o;
        }
    }
    return NULL;
}

• av_opt_set(void *obj, const char *name, const char *val, int search_flags)：在obj中搜索name选项并设置对应的参数，如果对应的参数是只读参数或者搜索失败会返回错误；
  • obj：第一个成员为AVClass的结构体指针；
  • name：希望设置参数的选项的key；
  • val：key对应的值，以字符串的形式存储，具体的参数类型内部会根据AVOption的类型来进行转换；
  • search_flags：搜索目标选项的标志位，内部搜索通过av_opt_find2实现；

int av_opt_set(void *obj, const char *name, const char *val, int search_flags){
    
    
    int ret = 0;
    void *dst, *target_obj;
    const AVOption *o = av_opt_find2(obj, name, NULL, 0, search_flags, &target_obj);
	//然后将val根据类型转换成对应的值设置进o
}

• void av_opt_free(void *obj)：释放所有的AVOption，只有AV_OPT_TYPE_STRING|AV_OPT_TYPE_BINARY|AV_OPT_TYPE_DICT三中类型需要释放；
• int av_opt_copy(void *dst, const void *src)：拷贝一份；
• 其他设置参数的API，下面这些API基本都是设置对应的类型的具体实现，和av_opt_set的实现类似，先搜索再设置，只不过有些需要通过偏移量写入到obj的成员变量里，具体的作用从API的名称也能看出来不再赘述：
  • av_opt_set_defaults(void *s)：设置s中所有的AVOption值为默认值，s的以一个指针应该为AVClass；
  • av_opt_set_defaults2(void *s, int mask, int flags)：仅仅设置(opt->flags & mask) == flags的选项的默认值，av_opt_set_defaults也是调用av_opt_set_defaults2实现的；
  • av_set_options_string(void *ctx, const char *opts, const char *key_val_sep, const char *pairs_sep)：设置一系列参数；
    • ctx：第一个成员为AVClass的结构体指针；
    • opts：多个键值对，键值对之间以paris_seq为分隔符，键值对内以key_val_sep为分隔符，比如width=30;height=40;bitrate=3000；
    • key_val_sep：分隔key-val的字符串，比如key=value中分隔符为=；
    • pairs_sep：分隔一对键值对的字符串，比如key1=val1;key2=val2中分隔符为;；
  • int av_opt_set_from_string(void *ctx, const char *opts, const char *const *shorthand, const char *key_val_sep, const char *pairs_sep)：基本参数和定义和av_set_options_string类似，不同的是多了一个shorthand参数：
    • shorthand：多个字符串的数组，如果opts中的前几个键值对未解析出key，则会使用shorthand中的值作为key。比如opts="5:hello:size=pal",shorthand={ "num", "string", NULL };则设置的结果是num=5,string=hello；
  • int av_opt_set_dict(void *obj, struct AVDictionary * *options)：遍历options内的值然后将值一一设置进obj；
  • int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags)：类似av_opt_set_dict，search_flags作用于av_opt_set；
  • int av_opt_set_int (void *obj, const char *name, int64_t val, int search_flags)
  • int av_opt_set_double (void *obj, const char *name, double val, int search_flags)
  • int av_opt_set_q (void *obj, const char *name, AVRational val, int search_flags)
  • int av_opt_set_bin (void *obj, const char *name, const uint8_t *val, int size, int search_flags)
  • int av_opt_set_image_size(void *obj, const char *name, int w, int h, int search_flags)
  • int av_opt_set_pixel_fmt (void *obj, const char *name, enum AVPixelFormat fmt, int search_flags)
  • int av_opt_set_sample_fmt(void *obj, const char *name, enum AVSampleFormat fmt, int search_flags)
  • int av_opt_set_video_rate(void *obj, const char *name, AVRational val, int search_flags)
  • int av_opt_set_channel_layout(void *obj, const char *name, int64_t ch_layout, int search_flags)
  • int av_opt_set_dict_val(void *obj, const char *name, const AVDictionary *val, int search_flags)
• int av_opt_get (void *obj, const char *name, int search_flags, uint8_t * *out_val)：获取的实现就是通过avav_opt_find2搜索然后再将数据转成字符串传出；
• 其他获取的API：
  • int av_opt_flag_is_set(void *obj, const char *field_name, const char *flag_name)：获取某个flag是否设置，具体实现就是先搜索然后通过av_opt_get_int获取值；
    • obj：第一个成员为AVClass的结构体指针；
    • field_name：对应flag所属的标签；
    • flag_name：具体的flag的key；
  • int av_opt_get_key_value(const char * *ropts, const char *key_val_sep, const char *pairs_sep, unsigned flags, char * *rkey, char * *rval)：从给定的字符串键值对中解析出第一个键值对并返回；
  • int av_opt_get_int (void *obj, const char *name, int search_flags, int64_t *out_val)
  • int av_opt_get_double (void *obj, const char *name, int search_flags, double *out_val)
  • int av_opt_get_q (void *obj, const char *name, int search_flags, AVRational *out_val)
  • int av_opt_get_image_size(void *obj, const char *name, int search_flags, int *w_out, int *h_out)
  • int av_opt_get_pixel_fmt (void *obj, const char *name, int search_flags, enum AVPixelFormat *out_fmt)
  • int av_opt_get_sample_fmt(void *obj, const char *name, int search_flags, enum AVSampleFormat *out_fmt)
  • int av_opt_get_video_rate(void *obj, const char *name, int search_flags, AVRational *out_val)
  • int av_opt_get_channel_layout(void *obj, const char *name, int search_flags, int64_t *ch_layout)
  • int av_opt_get_dict_val(void *obj, const char *name, int search_flags, AVDictionary * *out_val)
  • void *av_opt_ptr(const AVClass *class, void *obj, const char *name)：返回AVClass所属Context中对应成员的地址，比如返回AVCodecContext->width的地址；
  • int av_opt_is_set_to_default_by_name(void *obj, const char *name, int search_flags)：通过name搜索然后通过av_opt_is_set_to_default获取；
  • int av_opt_serialize(void *obj, int opt_flags, int flags, char * *buffer, const char key_val_sep, const char pairs_sep)：将obj中的选项序列化为一个字符串，字符串中键值对间的间隔为pairs_sep，键值对内的间隔为key_val_sep；
• 其他API：
  • av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags)：通过av_log将当前context支持的选项输出，默认输出到控制台，可以通过FFmpeg内的av_log_callback重定向输出：
    • obj：是AVClass所属类的指针比如AVFormatContext；
    • av_log_obj：一般情况置空，可以传入对应的Context的指针来显示更丰富的内容；
    • req_flags和rej_flags**：用来过滤需要显示的内容，req_flags是显示需要显示的，rej_flags是不显示对应的内容。
  • 下面几个API在头文件中有定义但是看不到实现，从注释看和av_opt_set类似，只不过会将结果写会最后一个指针来校验是否写正确：
    • int av_opt_eval_flags (void *obj, const AVOption *o, const char *val, int *flags_out)
    • av_opt_eval_int (void *obj, const AVOption *o, const char *val, int *int_out)
    • int av_opt_eval_int64 (void *obj, const AVOption *o, const char *val, int64_t *int64_out)
    • int av_opt_eval_float (void *obj, const AVOption *o, const char *val, float *float_out)
    • int av_opt_eval_double(void *obj, const AVOption *o, const char *val, double *double_out)
    • int av_opt_eval_q (void *obj, const AVOption *o, const char *val, AVRational *q_out)