FFmpeg庖丁解牛系列之option模块
关于option模块
option是FFmpeg中另一个很基础的模块，相对于log模块，代码量上要复杂一些。主要代码实现在如下两个文件中：
libavutil/opt.c
libavutil/opt.h关于AVOptions的介绍，直接参考log.h里的头文件注释吧：
AVOptions provide a generic system to declare options on arbitrary structs (“objects”). An option can have a help text, a type and a range of possible values. Options may then be enumerated, read and written to.
基于QQ浏览器自带的网络翻译软件（应该是腾讯翻译君），结果如下，翻译的还不错：
AVOptions提供了一个通用系统来声明任意结构中的选项(“对象”)。选项可以有帮助文本、类型和可能值的范围。然后可以枚举、读取和写入选项。实际上，是提供了一种通用方法，简便的对结构体成员变量进行赋值，并且不同的结构体是通用的。
简单使用的例子
下面的结构体是带option使能的，
typedef struct test_struct {
const AVClass *class;
int int_opt;
char *str_opt;
uint8_t *bin_opt;
int bin_len;
} test_struct;
static const AVOption test_options[] = {
{ "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
{ "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
AV_OPT_TYPE_STRING },
{ "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
AV_OPT_TYPE_BINARY },
{ NULL },
};
static const AVClass test_class = {
.class_name = "test class",
.item_name = av_default_item_name,
.option = test_options,
.version = LIBAVUTIL_VERSION_INT,
};继续分析注释里的讲解，
Next, when allocating your struct, you must ensure that the AVClass
pointer is set to the correct value. Then, av_opt_set_defaults() can
be called to initialize defaults. After that the struct is ready to be
used with the AVOptions API. When cleaning up, you may use the
av_opt_free() function to automatically free all the allocated string
and binary options.
接下来，在分配结构体时，必须确保AVClass指针设置为正确的值。然后，可以调用av_opt_set_defaults()来初始化默认值。之后，该结构体就做好了通过AVOptions API使用的准备工作了。
当准备清理时，您可以使用av_opt_free()函数自动释放所有分配的字符串和二进制选项。下面是具体的使用例子，分别介绍了在分配结构体和释放结构体时，需要额外进行的options操作。
test_struct *alloc_test_struct(void)
{
test_struct *ret = av_mallocz(sizeof(*ret));
ret->class = &test_class;
av_opt_set_defaults(ret);
return ret;
}
void free_test_struct(test_struct **foo)
{
av_opt_free(*foo);
av_freep(foo);
}嵌套的option使用
还是先来看注释说明，
It may happen that an AVOptions-enabled struct contains another
AVOptions-enabled struct as a member (e.g. AVCodecContext in
libavcodec exports generic options, while its priv_data field exports
codec-specific options). In such a case, it is possible to set up the
parent struct to export a child’s options. To do that, simply
implement AVClass.child_next() and AVClass.child_class_next() in the
parent struct’s AVClass.
还有的情况是，一个启用了AVOptions的结构体作为另一个启用了AVOptions的结构体的成员(例如，AVCodecContext中的libavcodec输出通用选项，而它的priv_data字段则输出编解码器特定选项)。在这样的情况下，可以设置父结构以导出子选项。要做到这一点，只需在父结构体的AVClass中实现AVClass.child_next()和AVClass.child_class_next() 即可。假设上面的test_struct现在还包含一个child_struct结构体字段，如下：
typedef struct child_struct {
AVClass *class;
int flags_opt;
} child_struct;
static const AVOption child_opts[] = {
{ "test_flags", "This is a test option of flags type.",
offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
{ NULL },
};
static const AVClass child_class = {
.class_name = "child class",
.item_name = av_default_item_name,
.option = child_opts,
.version = LIBAVUTIL_VERSION_INT,
};
void *child_next(void *obj, void *prev)
{
test_struct *t = obj;
if (!prev && t->child_struct)
return t->child_struct;
return NULL;
}
const AVClass child_class_next(const AVClass *prev)
{
return prev ? NULL : &child_class;
}Putting child_next() and child_class_next() as defined above into
test_class will now make child_struct’s options accessible through
test_struct (again, proper setup as described above needs to be done on
child_struct right after it is created).
将child_next()和child_class_next() 两个函数实现作为test_class 的成员函数，将使子结构的选项可以通过test_class 来获得(当然，如前所述，也需要在child_struct 创建时做正确的设置)，类似如下：
static const AVClass test_class = {
.class_name = "test class",
.item_name = av_default_item_name,
.option = test_options,
.version = LIBAVUTIL_VERSION_INT,
.child_class_next = child_class_next,
.child_next = child_next,
};From the above example it might not be clear why both child_next()
and child_class_next() are needed. The distinction is that child_next()
iterates over actually existing objects, while child_class_next()
iterates over all possible child classes. E.g. if an AVCodecContext
was initialized to use a codec which has private options, then its
child_next() will return AVCodecContext.priv_data and finish
iterating. OTOH child_class_next() on AVCodecContext.av_class will
iterate over all available codecs with private options.
上述例子可能不是很清晰，为什么需要两个函数child_next()
和child_class_next()实现而不是一个就可以呢？区别在于child_next()迭代实际存在的对象，而child_class_next()遍历所有可能的子类。例如，如果AVCodecContext初始化用于带private选项的编解码器，那么，child_next()将返回AVCodecContext.priv_data并完成迭代。另一方面，AVCodecContext.av_class的child_class_next()将遍历带private选项的所有可用编解码器。
简单的说，一个是遍历类，一个是搜索到对象立即停止。
命名常量option
It is possible to create named constants for options. Simply set the unit
field of the option the constants should apply to a string and
create the constants themselves as options of type AV_OPT_TYPE_CONST
with their unit field set to the same string.
Their default_val field should contain the value of the named
constant.
创建命名常量的option非常简单，只要设置结构体AVOption中的unit成员变量以常量字符串，并且设置option类型AVOptionType的值为AV_OPT_TYPE_CONST即可，在使用这些命名常量的option中，同样需要设置unit成员变量为相同的字符串，那么这些使用命名常量的option的默认值则包括了这些命名常量，包括的命名常量可以有多个。
继续前述例子，下面的例子为child_opts的test_flags添加了命名常量flag1，将下述内容放置到child_opts 数组即可，它们的unit成员变量都赋值了test_unit 的字符串，并且flag1的option类型是AV_OPT_TYPE_CONST 的。
{ "test_flags", "This is a test option of flags type.", offsetof(child_struct, flags_opt),
AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
{ "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0,
"test_unit" },主要结构体
typedef struct AVOption {
const char *name; /*选项名*/
const char *help;/*帮助文本*/
int offset;/*相对于context结构体的偏移，对于命名常量则为0*/
enum AVOptionType type;/**选项类型**/
/*默认值，联合体，只能是一种类型*/
union {
int64_t i64;
double dbl;
const char *str;
/* TODO those are unused now */
AVRational q;
} default_val;
double min; /*最小值*/
double max;/*最大值*/
int flags;/*标记*/
const char *unit;/*option归属者的名称，命名常量和非命名常量共享，可以是NULL*/
} AVOption;其中flags可取如下宏定义：
#define AV_OPT_FLAG_ENCODING_PARAM 1 /*编码参数*/
#define AV_OPT_FLAG_DECODING_PARAM 2 /*解码参数*/
#define AV_OPT_FLAG_METADATA 4 /*meta数据*/
#define AV_OPT_FLAG_AUDIO_PARAM 8 /*音频参数*/
#define AV_OPT_FLAG_VIDEO_PARAM 16 /*视频参数*/
#define AV_OPT_FLAG_SUBTITLE_PARAM 32 /*字幕参数*/
#define AV_OPT_FLAG_EXPORT 64 /*导出型参数，不大了解？*/
#define AV_OPT_FLAG_READONLY 128 /*只读参数*/
#define AV_OPT_FLAG_FILTERING_PARAM (1<<16) /*过滤参数？用于avfilter吗？*/下面是AVOptionRange结构体定义，顾名思义，这个结构体表示一个option的某种值的范围，虽然现在还不知道具体怎么用，但是我们先看看定义：
typedef struct AVOptionRange {
const char *str;/*字符串信息*/
double value_min, value_max;/*最小值和最大值，如果是字符串则表示最小和最大长度，如果表示视频尺寸则是最小和最大像素，或是宽度和高度*/
double component_min, component_max;/*最小和最大组件范围，对于字符串则表示Unicode编码的字符值范围，对于ASCII限定于0-127*/
int is_range;/*范围标记，1表示是一个范围，0表示就是单一的值，即最大值和最小值一样*/
} AVOptionRange;下面是结构体AVOptionRanges的定义，表示一个AVOptionRange的列表/数组（Array of option ranges），也就是多个component范围的集合，当然实际使用中大部分option类型都只有一个component，但也有些option类型包括多个AVOptionRange，比如对于图像AV_OPT_TYPE_IMAGE_SIZE类型，一个component范围是像素数，一个component范围是宽度，一个component范围是高度，那么这三个component AVOptionRange就组成了AVOptionRanges 结构体。这里一定要记住，AVOptionRange是关于option类型的一个结构体：
typedef struct AVOptionRanges {
AVOptionRange **range;/*范围值数组*/
int nb_ranges;/*每个component的range数量*/
int nb_components;/*component数量*/
} AVOptionRanges;使用方法例子，也是抄的opt.h里的注释部分，很明了，两级for循环：
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_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags);通过av_log显示对象相关的option值。obj表示AVClass类型的指针，av_log_obj表示待显示的对象指针，req_flags表示需要显示的内容flags标记，rej_flags则是相反的，拒绝显示的内容flags标记。
void av_opt_set_defaults(void *s);设置所有的option字段为默认值，s表示支持option使能的结构体，注意它的第一个成员变量必须是AVClass类型，类似AVFormatContext这种类型。
void av_opt_set_defaults2(void *s, int mask, int flags);功能类似前一函数，只是加了mask掩码条件，需满足条件(opt->flags & mask) == flags 。
int av_set_options_string(void *ctx, const char *opts, const char *key_val_sep,
const char *pairs_sep);顾名思义，此函数是设置options字符串的意思，设置到哪呢？就是参数ctx代表的上下文，要求这个上下文必须是AVClass类型的结构体，也就是说结构体的第一个成员变量是类型AVClass啦，例如AVFormatContext这种。当然了，有了AVClass就可以找到AVOption成员变量了。参数opts字符串是什么？是一个key/value键值对的字符串，包括了多个key/value值；那么参数key_val_seq和pairs_sep又是什么意思呢？key_val_seq是键值对key/value 间的分隔符，pairs_seq则是不同的键值对之间的分隔符。比如：“x=1:y=2:z=3”，“=”是key_val_seq，“：”是pairs_sep 。
int av_opt_set_from_string(void *ctx, const char *opts,const char *const *shorthand,
const char *key_val_sep, const char *pairs_sep);功能与上一个函数类似，但是加了shorthand参数，注释的意思是，如果opts里的key/value对里，某些对里没有key，则从shorthand数组里按顺序挨个找，shorthand数组里存储的是option的name，option name必须是如下范围：a-z A-Z 0-9 - . / _ ，shorthand notation速记符号的意思 。
void av_opt_free(void *obj);释放option，同样的，obj必须是AVClass类型的context对象。
int av_opt_flag_is_set(void *obj, const char *field_name, const char *flag_name);此函数判断是否设置了某个option值，也就是某个field_name是否设置了flag_name，这种情形在命名常量里用的比较多，前面我们也讲到了命名常量的定义。前述命名常量的例子里test_flags和flag1其实就是field_name和flag_name的关系，实际可能有多个命名常量（如flag2，flag3）可以为test_flags使用，但同一时间只能设置一个flag值。
int av_opt_set_dict(void *obj, struct AVDictionary **options);通过字典AVDictionary参数来设置option，而不是前述的字符串方式，obj必须是AVClass类型的context对象。
int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags);也是通过字典方式来设置option，但是带有搜索标记flag，flag在FFmpeg3.2.4里取如下宏定义：
#define AV_OPT_SEARCH_CHILDREN (1 << 0)/*搜索子对象*/
#define AV_OPT_SEARCH_FAKE_OBJ (1 << 1)/*搜索对象是伪造的，因为我们要求option的context必须是AVClass类型的，为了免去这些对象的分配，用double指针来替代AVClass指针，具体怎么用？不是很清楚*/int av_opt_get_key_value(const char **ropts,
const char *key_val_sep, const char *pairs_sep,
unsigned flags,
char **rkey, char **rval);从ropts里读取key和value值，flags值可取AV_OPT_FLAG_IMPLICIT_KEY，即接受没有key的value，key_val_sep和pairs_sep还是如前所述的分隔符。
int av_opt_eval_flags (void *obj, const AVOption *o, const char *val, int *flags_out);
int 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);这组函数的作用和av_opt_set()类似，但是结果是通过最后一个参数返回，而不是直接写入对象。？？具体用途不是很清楚。
const AVOption *av_opt_find(void *obj, const char *name, const char *unit,
int opt_flags, int search_flags);查找一个对象的option，同样的，obj必须是AVClass类型的context对象，如果是命名常量，还必须用到unit字段以标明命名常量所属，opt_flags指定搜索的类型，如前述宏定义AV_OPT_FLAG_ 开头的宏定义，search_flags则如前所述指定搜索的方式。
const AVOption *av_opt_find2(void *obj, const char *name, const char *unit,
int opt_flags, int search_flags, void **target_obj);
功能类似av_opt_find()，除了最后一个参数返回搜索到的option所属的对象，target_obj和obj可能不是一个，因为如果搜索参数search_flags里带了AV_OPT_SEARCH_CHILDREN标记的话，有可能搜到的是子对象。如果搜索参数search_flags带AV_OPT_SEARCH_FAKE_OBJ标记，则忽略此参数的返回值。
const AVOption *av_opt_next(const void *obj, const AVOption *prev);遍历obj对象的所有AVOption值，prev是上一个遍历的对象，可以为NULL，此时返回第一个option值。
void *av_opt_child_next(void *obj, void *prev);遍历obj对象的子对象的所有AVOption值。
const AVClass *av_opt_child_class_next(const AVClass *parent, const AVClass *prev);遍历parent类的子类，prev是上一个遍历的对象，可以为NULL，此时返回第一个子类。
int av_opt_set (void *obj, const char *name, const char *val, int search_flags);
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);这组函数设置对象obj的option值，设置的字段名是name，需设置的值是val；search_flags是传递给底层函数av_opt_find2使用的，所以功能类似前述。如果设置了AV_OPT_SEARCH_CHILDREN的flags，则option值会设置到obj的子对象里。
int av_opt_set_dict_val(void *obj, const char *name, const AVDictionary *val, int search_flags);重新设置新的AVDictionary到obj对象，val内存需要由函数调用者释放。
int av_opt_get (void *obj, const char *name, int search_flags, uint8_t **out_val);
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);这组函数获取obj对象的name字段的option值，并返回到out_val里。需要注意返回的字符串需要调用者释放内存。
int av_opt_get_dict_val(void *obj, const char *name, int search_flags, AVDictionary **out_val);功能类似，返回AVDictionary类型的值。
void *av_opt_ptr(const AVClass *avclass, void *obj, const char *name);获取一个对象option中name字段的地址指针，通过函数返回。
void av_opt_freep_ranges(AVOptionRanges **ranges);释放AVOptionRanges的所有内存。
int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags);获取obj对象里option中，name为key值的所有AVOptionRange集合。注意返回的结果必须通过av_opt_freep_ranges()函数释放内存。
int av_opt_copy(void *dest, const void *src);拷贝src对象的option到dest对象中。
int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags);与前一函数av_opt_query_ranges的区别在于，如果AVClass对象中，注册了下述成员，
int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags); 那么av_opt_query_ranges()会使用注册的这个函数进行搜索，而av_opt_query_ranges_default()则使用默认的函数进行搜索。此功能在version (52.12)之后方可使用。
int av_opt_is_set_to_default(void *obj, const AVOption *o);检查AVOption o是否正确的设置到了对象obj里，需要注意的是，o必须属于obj对象。此函数不能用于子对象选项的检查。
int av_opt_is_set_to_default_by_name(void *obj, const char *name, int search_flags);此函数是对前一函数的补充，增加了search_flags，所以可以结果AV_OPT_SEARCH_*相关的搜索属性，可以搜索子对象了。
#define AV_OPT_SERIALIZE_SKIP_DEFAULTS 0x00000001
#define AV_OPT_SERIALIZE_OPT_FLAGS_EXACT 0x00000002
int av_opt_serialize(void *obj, int opt_flags, int flags, char **buffer,
const char key_val_sep, const char pairs_sep);
将obj对象的option进行序列化处理（组装成key/value对字符串的方式），返回结果存放在buffer中，buffer需要由调用者释放内存。opt_flags接受AV_OPT_FLAG_IMPLICIT_KEY类型的选项，即允许不带key的value存在。宏定义AV_OPT_SERIALIZE_SKIP_DEFAULTS表示在序列化过程中忽略默认的option值，只取修改过的option；宏定义AV_OPT_SERIALIZE_OPT_FLAGS_EXACT则表示只抽取匹配opt_flags所定义的option值。
总结
上述内容我们仅仅分析了怎么使用AVOption模块，并未深入去分析其实现原理和代码，粗略看了一下，还是挺复杂的。从整个FFmpeg功能上来说，我们现阶段了解这个模块的使用即可，后续如果需要具体了解模块实现再深入分析。
虽然对AVOption的主要定义和接口进行了描述，但是有些注释还不是很清晰，待后续遇到问题时再逐步修订。