Data Structures | |
struct | AVOption |
AVOption. More... | |
Modules | |
Evaluating option strings | |
This group of functions can be used to evaluate option strings and get numbers out of them. | |
Option setting functions | |
Those functions set the field of obj with the given name to value. | |
Option getting functions | |
Those functions get a value of the option with the given name from an object. | |
Defines | |
#define | AV_OPT_SEARCH_CHILDREN 0x0001 |
Search in possible children of the given object first. | |
#define | AV_OPT_SEARCH_FAKE_OBJ 0x0002 |
The obj passed to av_opt_find() is fake -- only a double pointer to AVClass instead of a required pointer to a struct containing AVClass. | |
Enumerations | |
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, AV_OPT_TYPE_CONST = 128, FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128 } |
Functions | |
attribute_deprecated const AVOption * | av_find_opt (void *obj, const char *name, const char *unit, int mask, int flags) |
Look for an option in obj. | |
attribute_deprecated int | av_set_string3 (void *obj, const char *name, const char *val, int alloc, const AVOption **o_out) |
Set the field of obj with the given name to value. | |
attribute_deprecated const AVOption * | av_set_double (void *obj, const char *name, double n) |
attribute_deprecated const AVOption * | av_set_q (void *obj, const char *name, AVRational n) |
attribute_deprecated const AVOption * | av_set_int (void *obj, const char *name, int64_t n) |
double | av_get_double (void *obj, const char *name, const AVOption **o_out) |
AVRational | av_get_q (void *obj, const char *name, const AVOption **o_out) |
int64_t | av_get_int (void *obj, const char *name, const AVOption **o_out) |
attribute_deprecated const char * | av_get_string (void *obj, const char *name, const AVOption **o_out, char *buf, int buf_len) |
attribute_deprecated const AVOption * | av_next_option (void *obj, const AVOption *last) |
int | av_opt_show2 (void *obj, void *av_log_obj, int req_flags, int rej_flags) |
Show the obj options. | |
void | av_opt_set_defaults (void *s) |
Set the values of all AVOption fields to their default values. | |
attribute_deprecated void | av_opt_set_defaults2 (void *s, int mask, int flags) |
int | av_set_options_string (void *ctx, const char *opts, const char *key_val_sep, const char *pairs_sep) |
Parse the key/value pairs list in opts. | |
void | av_opt_free (void *obj) |
Free all string and binary options in obj. | |
int | av_opt_flag_is_set (void *obj, const char *field_name, const char *flag_name) |
Check whether a particular flag is set in a flags field. | |
int | av_opt_set_dict (void *obj, struct AVDictionary **options) |
const AVOption * | av_opt_find (void *obj, const char *name, const char *unit, int opt_flags, int search_flags) |
Look for an option in an object. | |
const AVOption * | av_opt_find2 (void *obj, const char *name, const char *unit, int opt_flags, int search_flags, void **target_obj) |
Look for an option in an object. | |
const AVOption * | av_opt_next (void *obj, const AVOption *prev) |
Iterate over all AVOptions belonging to obj. | |
void * | av_opt_child_next (void *obj, void *prev) |
Iterate over AVOptions-enabled children of obj. | |
const AVClass * | av_opt_child_class_next (const AVClass *parent, const AVClass *prev) |
Iterate over potential AVOptions-enabled children of parent. | |
void * | av_opt_ptr (const AVClass *avclass, void *obj, const char *name) |
Gets a pointer to the requested field in a struct. |
An option can have a help text, a type and a range of possible values. Options may then be enumerated, read and written to.
All AVOptions-related information is stored in an AVClass. Therefore the first member of the struct must be a pointer to an AVClass describing it. The option field of the AVClass must be set to a NULL-terminated static array of AVOptions. Each AVOption must have a non-empty name, a type, a default value and for number-type AVOptions also a range of allowed values. It must also declare an offset in bytes from the start of the struct, where the field associated with this AVOption is located. Other fields in the AVOption struct should also be set when applicable, but are not required.
The following example illustrates an AVOptions-enabled struct:
typedef struct test_struct { AVClass *class; int int_opt; char *str_opt; uint8_t *bin_opt; int bin_len; } test_struct; static const AVOption options[] = { { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt), AV_OPT_TYPE_INT, { -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 = 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() must 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.
Continuing with the above example:
test_struct *alloc_test_struct(void) { test_struct *ret = av_malloc(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); }
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, { 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; }
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.
{ "test_flags", "This is a test option of flags type.", offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { 0 }, INT_MIN, INT_MAX, "test_unit" }, { "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { 16 }, 0, 0, "test_unit" },
The situation is more complicated with nesting. An AVOptions-enabled struct may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag to av_opt_find() will make the function search children recursively.
For enumerating there are basically two cases. The first is when you want to get all options that may potentially exist on the struct and its children (e.g. when constructing documentation). In that case you should call av_opt_child_class_next() recursively on the parent struct's AVClass. The second case is when you have an already initialized struct with all its children and you want to get all options that can be actually written or read from it. In that case you should call av_opt_child_next() recursively (and av_opt_next() on each result).
Similarly av_opt_get() will read any option type and convert it to a string which will be returned. Do not forget that the string is allocated, so you have to free it with av_free().
In some cases it may be more convenient to put all options into an AVDictionary and call av_opt_set_dict() on it. A specific case of this are the format/codec open functions in lavf/lavc which take a dictionary filled with option as a parameter. This allows to set some options that cannot be set otherwise, since e.g. the input file format is not known before the file is actually opened.
#define AV_OPT_SEARCH_CHILDREN 0x0001 |
Search in possible children of the given object first.
Definition at line 448 of file opt.h.
Referenced by av_get_string(), av_opt_find2(), ff_rtp_chain_mux_open(), and opt_default().
#define AV_OPT_SEARCH_FAKE_OBJ 0x0002 |
The obj passed to av_opt_find() is fake -- only a double pointer to AVClass instead of a required pointer to a struct containing AVClass.
This is useful for searching for options without needing to allocate the corresponding object.
Definition at line 456 of file opt.h.
Referenced by av_opt_find2(), av_opt_ptr(), filter_codec_opts(), and opt_default().
enum AVOptionType |
attribute_deprecated const AVOption* av_find_opt | ( | void * | obj, | |
const char * | name, | |||
const char * | unit, | |||
int | mask, | |||
int | flags | |||
) |
Look for an option in obj.
Look only for the options which have the flags set as specified in mask and flags (that is, for which it is the case that opt->flags & mask == flags).
[in] | obj | a pointer to a struct whose first element is a pointer to an AVClass |
[in] | name | the name of the option to look for |
[in] | unit | the unit of the option to look for, or any if NULL |
double av_get_double | ( | void * | obj, | |
const char * | name, | |||
const AVOption ** | o_out | |||
) |
int64_t av_get_int | ( | void * | obj, | |
const char * | name, | |||
const AVOption ** | o_out | |||
) |
AVRational av_get_q | ( | void * | obj, | |
const char * | name, | |||
const AVOption ** | o_out | |||
) |
attribute_deprecated const char* av_get_string | ( | void * | obj, | |
const char * | name, | |||
const AVOption ** | o_out, | |||
char * | buf, | |||
int | buf_len | |||
) |
attribute_deprecated const AVOption* av_next_option | ( | void * | obj, | |
const AVOption * | last | |||
) |
Iterate over potential AVOptions-enabled children of parent.
prev | result of a previous call to this function or NULL |
Definition at line 802 of file opt.c.
Referenced by av_opt_find2(), and show_help_children().
void* av_opt_child_next | ( | void * | obj, | |
void * | prev | |||
) |
Iterate over AVOptions-enabled children of obj.
prev | result of a previous call to this function or NULL |
Definition at line 794 of file opt.c.
Referenced by av_opt_find2().
const AVOption* av_opt_find | ( | void * | obj, | |
const char * | name, | |||
const char * | unit, | |||
int | opt_flags, | |||
int | search_flags | |||
) |
Look for an option in an object.
Consider only options which have all the specified flags set.
[in] | obj | A pointer to a struct whose first element is a pointer to an AVClass. Alternatively a double pointer to an AVClass, if AV_OPT_SEARCH_FAKE_OBJ search flag is set. |
[in] | name | The name of the option to look for. |
[in] | unit | When searching for named constants, name of the unit it belongs to. |
opt_flags | Find only options with all the specified flags set (AV_OPT_FLAG). | |
search_flags | A combination of AV_OPT_SEARCH_*. |
Definition at line 747 of file opt.c.
Referenced by av_get_string(), av_opt_flag_is_set(), av_set_double(), av_set_int(), av_set_q(), av_set_string3(), ffserver_opt_default(), filter_codec_opts(), opt_default(), and set_string_number().
const AVOption* av_opt_find2 | ( | void * | obj, | |
const char * | name, | |||
const char * | unit, | |||
int | opt_flags, | |||
int | search_flags, | |||
void ** | target_obj | |||
) |
Look for an option in an object.
Consider only options which have all the specified flags set.
[in] | obj | A pointer to a struct whose first element is a pointer to an AVClass. Alternatively a double pointer to an AVClass, if AV_OPT_SEARCH_FAKE_OBJ search flag is set. |
[in] | name | The name of the option to look for. |
[in] | unit | When searching for named constants, name of the unit it belongs to. |
opt_flags | Find only options with all the specified flags set (AV_OPT_FLAG). | |
search_flags | A combination of AV_OPT_SEARCH_*. | |
[out] | target_obj | if non-NULL, an object to which the option belongs will be written here. It may be different from obj if AV_OPT_SEARCH_CHILDREN is present in search_flags. This parameter is ignored if search_flags contain AV_OPT_SEARCH_FAKE_OBJ. |
Definition at line 753 of file opt.c.
Referenced by av_opt_find(), av_opt_find2(), av_opt_get(), av_opt_ptr(), av_opt_set(), get_number(), and set_number().
int av_opt_flag_is_set | ( | void * | obj, | |
const char * | field_name, | |||
const char * | flag_name | |||
) |
Check whether a particular flag is set in a flags field.
field_name | the name of the flag field option | |
flag_name | the name of the flag to check |
void av_opt_free | ( | void * | obj | ) |
Free all string and binary options in obj.
Definition at line 718 of file opt.c.
Referenced by av_write_trailer(), avcodec_close(), avformat_free_context(), ffurl_close(), and segment_end().
Iterate over all AVOptions belonging to obj.
obj | an AVOptions-enabled struct or a double pointer to an AVClass describing it. | |
prev | result of the previous call to av_opt_next() on this object or NULL |
Definition at line 56 of file opt.c.
Referenced by av_next_option(), av_opt_find2(), av_opt_free(), av_opt_set_defaults2(), opt_list(), and show_stream().
void* av_opt_ptr | ( | const AVClass * | avclass, | |
void * | obj, | |||
const char * | name | |||
) |
Gets a pointer to the requested field in a struct.
This function allows accessing a struct even when its fields are moved or renamed since the application making the access has been compiled,
Definition at line 809 of file opt.c.
Referenced by get_video_frame(), and transcode_video().
void av_opt_set_defaults | ( | void * | s | ) |
Set the values of all AVOption fields to their default values.
s | an AVOption-enabled struct (its first member must be a pointer to AVClass) |
Definition at line 598 of file opt.c.
Referenced by av_set_parameters(), avcodec_get_context_defaults3(), avcodec_open2(), avformat_alloc_output_context2(), avformat_get_context_defaults(), avformat_open_input(), avformat_write_header(), compact_init(), init(), json_init(), movie_common_init(), segment_start(), swr_alloc(), sws_alloc_context(), url_alloc_for_protocol(), and xml_init().
attribute_deprecated void av_opt_set_defaults2 | ( | void * | s, | |
int | mask, | |||
int | flags | |||
) |
Definition at line 604 of file opt.c.
Referenced by av_opt_set_defaults(), and avcodec_get_context_defaults3().
int av_opt_set_dict | ( | void * | obj, | |
struct AVDictionary ** | options | |||
) |
Definition at line 726 of file opt.c.
Referenced by avcodec_open2(), avformat_open_input(), avformat_write_header(), and ffurl_open().
int av_opt_show2 | ( | void * | obj, | |
void * | av_log_obj, | |||
int | req_flags, | |||
int | rej_flags | |||
) |
Show the obj options.
req_flags | requested flags for the options to show. Show only the options for which it is opt->flags & req_flags. | |
rej_flags | rejected flags for the options to show. Show only the options for which it is !(opt->flags & req_flags). | |
av_log_obj | log context to use for showing the options |
Definition at line 586 of file opt.c.
Referenced by show_help_children().
attribute_deprecated const AVOption* av_set_double | ( | void * | obj, | |
const char * | name, | |||
double | n | |||
) |
attribute_deprecated const AVOption* av_set_int | ( | void * | obj, | |
const char * | name, | |||
int64_t | n | |||
) |
int av_set_options_string | ( | void * | ctx, | |
const char * | opts, | |||
const char * | key_val_sep, | |||
const char * | pairs_sep | |||
) |
Parse the key/value pairs list in opts.
For each key/value pair found, stores the value in the field in ctx that is named like the key. ctx must be an AVClass context, storing is done using AVOptions.
opts | options string to parse, may be NULL | |
key_val_sep | a 0-terminated list of characters used to separate key from value | |
pairs_sep | a 0-terminated list of characters used to separate two pairs from each other |
Definition at line 698 of file opt.c.
Referenced by compact_init(), init(), json_init(), movie_common_init(), and xml_init().
attribute_deprecated const AVOption* av_set_q | ( | void * | obj, | |
const char * | name, | |||
AVRational | n | |||
) |
attribute_deprecated int av_set_string3 | ( | void * | obj, | |
const char * | name, | |||
const char * | val, | |||
int | alloc, | |||
const AVOption ** | o_out | |||
) |
Set the field of obj with the given name to value.
[in] | obj | A struct whose first element is a pointer to an AVClass. |
[in] | name | the name of the field to set |
[in] | val | The value to set. If the field is not of a string type, then the given string is parsed. SI postfixes and some named scalars are supported. If the field is of a numeric type, it has to be a numeric or named scalar. Behavior with more than one scalar and +- infix operators is undefined. If the field is of a flags type, it has to be a sequence of numeric scalars or named flags separated by '+' or '-'. Prefixing a flag with '+' causes it to be set without affecting the other flags; similarly, '-' unsets a flag. |
[out] | o_out | if non-NULL put here a pointer to the AVOption found |
alloc | this parameter is currently ignored |