|
FFmpeg
|
Modules | |
| AVOption (un)initialization and inspection. | |
| Setting and modifying option values | |
| Reading option values | |
Data Structures | |
| struct | AVOptionArrayDef |
| May be set as default_val for AV_OPT_TYPE_FLAG_ARRAY options. More... | |
| struct | AVOption |
| AVOption. More... | |
| struct | AVOptionRange |
| A single allowed range of values, or a single allowed value. More... | |
| struct | AVOptionRanges |
| List of AVOptionRange structs. More... | |
Macros | |
| #define | AV_OPT_FLAG_ENCODING_PARAM (1 << 0) |
| A generic parameter which can be set by the user for muxing or encoding. More... | |
| #define | AV_OPT_FLAG_DECODING_PARAM (1 << 1) |
| A generic parameter which can be set by the user for demuxing or decoding. More... | |
| #define | AV_OPT_FLAG_AUDIO_PARAM (1 << 3) |
| #define | AV_OPT_FLAG_VIDEO_PARAM (1 << 4) |
| #define | AV_OPT_FLAG_SUBTITLE_PARAM (1 << 5) |
| #define | AV_OPT_FLAG_EXPORT (1 << 6) |
| The option is intended for exporting values to the caller. More... | |
| #define | AV_OPT_FLAG_READONLY (1 << 7) |
| The option may not be set through the AVOptions API, only read. More... | |
| #define | AV_OPT_FLAG_BSF_PARAM (1 << 8) |
| A generic parameter which can be set by the user for bit stream filtering. More... | |
| #define | AV_OPT_FLAG_RUNTIME_PARAM (1 << 15) |
| A generic parameter which can be set by the user at runtime. More... | |
| #define | AV_OPT_FLAG_FILTERING_PARAM (1 << 16) |
| A generic parameter which can be set by the user for filtering. More... | |
| #define | AV_OPT_FLAG_DEPRECATED (1 << 17) |
| Set if option is deprecated, users should refer to AVOption.help text for more information. More... | |
| #define | AV_OPT_FLAG_CHILD_CONSTS (1 << 18) |
| Set if option constants can also reside in child objects. More... | |
Functions | |
| void | av_opt_freep_ranges (AVOptionRanges **ranges) |
| Free an AVOptionRanges struct and set it to NULL. More... | |
| int | av_opt_query_ranges (AVOptionRanges **, void *obj, const char *key, int flags) |
| Get a list of allowed ranges for the given option. More... | |
| int | av_opt_query_ranges_default (AVOptionRanges **, void *obj, const char *key, int flags) |
| Get a default list of allowed ranges for the given option. More... | |
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.
There are two modes of access to members of AVOption and its child structs. One is called 'native access', and refers to access from the code that declares the AVOption in question. The other is 'foreign access', and refers to access from other code.
Certain struct members in this header are documented as 'native access only' or similar - it means that only the code that declared the AVOption in question is allowed to access the field. This allows us to extend the semantics of those fields without breaking API compatibility.
This section describes how to add AVOptions capabilities to a struct.
All AVOptions-related information is stored in an AVClass. Therefore the first member of the struct should 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:
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.
Continuing with the above example:
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_iterate() in the parent struct's AVClass. Assuming that the test_struct from above now also contains a child_struct field:
Putting child_next() and child_class_iterate() 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).
From the above example it might not be clear why both child_next() and child_class_iterate() are needed. The distinction is that child_next() iterates over actually existing objects, while child_class_iterate() 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_iterate() on AVCodecContext.av_class will iterate over all available codecs with private options.
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. For example, to add some named constants for the test_flags option above, put the following into the child_opts array:
This section deals with accessing options in an AVOptions-enabled struct. Such structs in FFmpeg are e.g. AVCodecContext in libavcodec or AVFormatContext in libavformat.
The basic functions for examining options are av_opt_next(), which iterates over all options defined for one object, and av_opt_find(), which searches for an option with the given name.
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_iterate() 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).
When setting options, you often have a string read directly from the user. In such a case, simply passing it to av_opt_set() is enough. For non-string type options, av_opt_set() will parse the string according to the option type.
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 makes it possible 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_FLAG_ENCODING_PARAM (1 << 0) |
| #define AV_OPT_FLAG_DECODING_PARAM (1 << 1) |
| #define AV_OPT_FLAG_EXPORT (1 << 6) |
| #define AV_OPT_FLAG_READONLY (1 << 7) |
| #define AV_OPT_FLAG_BSF_PARAM (1 << 8) |
| #define AV_OPT_FLAG_RUNTIME_PARAM (1 << 15) |
| #define AV_OPT_FLAG_FILTERING_PARAM (1 << 16) |
| #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) |
| enum AVOptionType |
| Enumerator | |
|---|---|
| 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_BOOL | |
| AV_OPT_TYPE_CHLAYOUT | |
| AV_OPT_TYPE_FLAG_ARRAY | May be combined with another regular option type to declare an array option. For array options, AVOption::offset should refer to a pointer corresponding to the option type. The pointer should be immediately followed by an unsigned int that will store the number of elements in the array. |
| void av_opt_freep_ranges | ( | AVOptionRanges ** | ranges | ) |
Free an AVOptionRanges struct and set it to NULL.
Definition at line 2220 of file opt.c.
Referenced by opt_list().
| int av_opt_query_ranges | ( | AVOptionRanges ** | , |
| void * | obj, | ||
| const char * | key, | ||
| int | flags | ||
| ) |
Get a list of allowed ranges for the given option.
The returned list may depend on other fields in obj like for example profile.
| flags | is a bitmask of flags, undefined flags should not be set and should be ignored AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, |
The result must be freed with av_opt_freep_ranges.
Definition at line 2131 of file opt.c.
Referenced by opt_list().
| int av_opt_query_ranges_default | ( | AVOptionRanges ** | , |
| void * | obj, | ||
| const char * | key, | ||
| int | flags | ||
| ) |
Get a default list of allowed ranges for the given option.
This list is constructed without using the AVClass.query_ranges() callback and can be used as fallback from within the callback.
| flags | is a bitmask of flags, undefined flags should not be set and should be ignored AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, |
The result must be freed with av_opt_free_ranges.
Definition at line 2149 of file opt.c.
Referenced by av_opt_query_ranges().
1.8.17