AVOptions provide a generic system to declare options on arbitrary structs ("objects").
More...
Modules
This group of functions can be used to evaluate option strings and get numbers out of them.
Those functions set the field of obj with the given name to value.
Those functions get a value of the option with the given name from an object.
Data Structures
A single allowed range of values, or a single allowed value.
More...
Macros
Search in possible children of the given object first.
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,
AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'),
AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'),
AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'),
AV_OPT_TYPE_VIDEO_RATE = MKBETAG('V','R','A','T'),
AV_OPT_TYPE_DURATION = MKBETAG('D','U','R',' '),
AV_OPT_TYPE_COLOR = MKBETAG('C','O','L','R'),
AV_OPT_TYPE_CHANNEL_LAYOUT = MKBETAG('C','H','L','A'),
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
Look for an option in obj.
Set the field of obj with the given name to value.
Show the obj options.
Set the values of all
AVOption fields to their default values.
Parse the key/value pairs list in opts.
int
av_opt_set_from_string (
void *ctx, const char *opts, const char *const *shorthand, const char *key_val_sep, const char *pairs_sep)
Parse the key-value pairs list in opts.
Free all string and binary options in obj.
Check whether a particular flag is set in a flags field.
Set all the options from a given dictionary on an object.
int
av_opt_get_key_value (const char **ropts, const char *key_val_sep, const char *pairs_sep, unsigned
flags, char **rkey, char **rval)
Extract a key-value pair from the beginning of a string.
Look for an option in an object.
Look for an option in an object.
Iterate over all AVOptions belonging to obj.
Iterate over AVOptions-enabled children of obj.
Iterate over potential AVOptions-enabled children of parent.
Gets a pointer to the requested field in a struct.
Get a list of allowed ranges for the given option.
Get a default list of allowed ranges for the given option.
Detailed Description
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.
Implementing AVOptions
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:
typedef struct test_struct {
int int_opt;
char *str_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),
{ "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
{ "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
{ NULL },
};
static const AVClass test_class = {
.option = test_options,
};
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:
test_struct *alloc_test_struct(void)
{
ret->class = &test_class;
}
void free_test_struct(test_struct **foo)
{
}
Nesting
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. Assuming that the test_struct from above now also contains a child_struct field:
typedef struct child_struct {
int flags_opt;
} child_struct;
{ "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 = {
.option = child_opts,
};
void *child_next(void *obj, void *prev)
{
if (!prev && t->child_struct)
return t->child_struct;
return NULL
}
{
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).
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.
Named constants
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:
{ "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" },
Using AVOptions
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.
Examining AVOptions
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_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).
Reading and writing AVOptions
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 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.
Macro Definition Documentation
#define AV_OPT_SEARCH_CHILDREN 0x0001
Search in possible children of the given object first.
- Examples:
- doc/examples/filtering_audio.c.
Definition at line 540 of file opt.h.
Referenced by av_get_string(), av_opt_find2(), av_probe_input_buffer2(), configure_output_audio_filter(), ff_rtp_chain_mux_open(), init(), init_filters(), insert_trim(), lavfi_read_header(), open_input_file(), open_output_file(), opt_default(), parse_key_value_pair(), and process_options().
#define AV_OPT_SEARCH_FAKE_OBJ 0x0002
Enumeration Type Documentation
- 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_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
FF_OPT_TYPE_FLAGS
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
offset must point to a pointer immediately followed by an int for the length
FF_OPT_TYPE_CONST
Definition at line 220 of file opt.h.
- Enumerator:
-
AV_OPT_FLAG_IMPLICIT_KEY
Accept to parse a value without a key; the key will then be returned as NULL.
Definition at line 507 of file opt.h.
Function Documentation
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).
- Parameters
-
[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
- Returns
- a pointer to the option found, or NULL if no option has been found
- Deprecated:
- use av_opt_find.
Definition at line 45 of file opt.c.
const char *
name,
const char *
val,
int
alloc,
)
Set the field of obj with the given name to value.
- Parameters
-
[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
- Returns
- 0 if the value has been set, or an AVERROR code in case of error: AVERROR_OPTION_NOT_FOUND if no matching option exists AVERROR(ERANGE) if the value is out of range AVERROR(EINVAL) if the value is not valid
- Deprecated:
- use av_opt_set()
Definition at line 246 of file opt.c.
const char *
name,
double
n
)
const char *
name,
int64_t
n
)
double av_get_double
(
void *
obj,
const char *
name,
)
int64_t av_get_int
(
void *
obj,
const char *
name,
)
const char *
name,
char *
buf,
int
buf_len
)
- Parameters
-
buf a buffer which is used for returning non string values as strings, can be NULL
buf_len allocated length in bytes of buf
Definition at line 579 of file opt.c.
int av_opt_show2
(
void *
obj,
int
req_flags,
int
rej_flags
)
Show the obj options.
- Parameters
-
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 1052 of file opt.c.
Referenced by show_help_children().
Set the values of all AVOption fields to their default values.
- Parameters
-
s an AVOption-enabled struct (its first member must be a pointer to
AVClass)
Definition at line 1064 of file opt.c.
Referenced by av_opencl_init(), av_opencl_set_option(), avcodec_get_context_defaults3(), avcodec_open2(), avfilter_graph_alloc(), avformat_alloc_output_context2(), avformat_get_context_defaults(), avformat_open_input(), avresample_alloc_context(), ff_filter_alloc(), init_muxer(), swr_alloc(), sws_alloc_context(), url_alloc_for_protocol(), and writer_open().
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.
- Parameters
-
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
- Returns
- the number of successfully set key/value pairs, or a negative value corresponding to an AVERROR code in case of error: AVERROR(EINVAL) if opts cannot be parsed, the error code issued by av_set_string3() if a key/value pair cannot be set
Definition at line 1186 of file opt.c.
Referenced by writer_open().
int av_opt_set_from_string
(
void *
ctx,
const char *
opts,
const char *const *
shorthand,
const char *
key_val_sep,
const char *
pairs_sep
)
Parse the key-value pairs list in opts.
For each key=value pair found, set the value of the corresponding option in ctx.
- Parameters
-
ctx the
AVClass object to set options on
opts the options string, key-value pairs separated by a delimiter
shorthand a NULL-terminated array of options names for shorthand notation: if the first field in opts has no key part, the key is taken from the first element of shorthand; then again for the second, etc., until either opts is finished, shorthand is finished or a named option is found; after that, all options must be named
key_val_sep a 0-terminated list of characters used to separate key from value, for example '='
pairs_sep a 0-terminated list of characters used to separate two pairs from each other, for example ':' or ','
- Returns
- the number of successfully set key=value pairs, or a negative value corresponding to an AVERROR code in case of error: AVERROR(EINVAL) if opts cannot be parsed, the error code issued by av_set_string3() if a key/value pair cannot be set
Options names must use only the following characters: a-z A-Z 0-9 - . / _ Separators must use characters distinct from option names and from each other.
Definition at line 1266 of file opt.c.
Free all string and binary options in obj.
Definition at line 1318 of file opt.c.
Referenced by av_opencl_free_option(), av_opencl_uninit(), av_write_trailer(), avcodec_close(), avcodec_copy_context(), avfilter_free(), avformat_free_context(), avresample_free(), ffurl_closep(), seg_write_trailer(), and writer_close().
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.
- Parameters
-
field_name the name of the flag field option
flag_name the name of the flag to check
- Returns
- non-zero if the flag is set, zero if the flag isn't set, isn't of the right type, or the flags field doesn't exist.
Definition at line 861 of file opt.c.
Referenced by ff_rtp_get_payload_type().
int av_opt_set_dict
(
void *
obj,
)
int av_opt_get_key_value
(
const char **
ropts,
const char *
key_val_sep,
const char *
pairs_sep,
unsigned
flags,
char **
rkey,
char **
rval
)
Extract a key-value pair from the beginning of a string.
- Parameters
-
ropts pointer to the options string, will be updated to point to the rest of the string (one of the pairs_sep or the final NUL)
key_val_sep a 0-terminated list of characters used to separate key from value, for example '='
pairs_sep a 0-terminated list of characters used to separate two pairs from each other, for example ':' or ','
flags flags; see the AV_OPT_FLAG_* values below
rkey parsed key; must be freed using
av_free() rval parsed value; must be freed using
av_free()
- Returns
- >=0 for success, or a negative value corresponding to an AVERROR code in case of error; in particular: AVERROR(EINVAL) if no key is present
Definition at line 1244 of file opt.c.
Referenced by av_opt_set_from_string(), init_report(), parse_slave_options(), and process_options().
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.
- Parameters
-
[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_*.
- Returns
- A pointer to the option found, or NULL if no option was found.
- Note
- Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable directly with av_set_string3(). Use special calls which take an options AVDictionary (e.g. avformat_open_input()) to set options found with this flag.
Definition at line 1347 of file opt.c.
Referenced by av_get_string(), av_opt_flag_is_set(), av_opt_query_ranges_default(), av_set_double(), av_set_int(), av_set_q(), av_set_string3(), ffserver_opt_default(), filter_codec_opts(), init(), init_dict(), open_input_file(), open_output_file(), opt_find(), process_options(), and set_string_number().
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.
- Parameters
-
[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.
- Returns
- A pointer to the option found, or NULL if no option was found.
Definition at line 1353 of file opt.c.
Referenced by av_opt_find(), av_opt_find2(), av_opt_get(), av_opt_get_channel_layout(), av_opt_get_image_size(), av_opt_ptr(), av_opt_set(), av_opt_set_bin(), av_opt_set_channel_layout(), av_opt_set_image_size(), av_opt_set_video_rate(), get_format(), get_number(), set_format(), and set_number().
Iterate over AVOptions-enabled children of obj.
- Parameters
-
prev result of a previous call to this function or NULL
- Returns
- next AVOptions-enabled child or NULL
Definition at line 1397 of file opt.c.
Referenced by av_opt_find2().
Iterate over potential AVOptions-enabled children of parent.
- Parameters
-
prev result of a previous call to this function or NULL
- Returns
- AVClass corresponding to next potential child or NULL
Definition at line 1405 of file opt.c.
Referenced by av_opt_find2(), and show_help_children().
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,
- Returns
- a pointer to the field, it can be cast to the correct type and read or written to.
Definition at line 1412 of file opt.c.
Referenced by decode_video().
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.
- Parameters
-
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
The result must be freed with av_opt_freep_ranges.
- Returns
- >= 0 on success, a negative errro code otherwise
Definition at line 1420 of file opt.c.
Referenced by opt_list().
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.
- Parameters
-
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
The result must be freed with av_opt_free_ranges.
- Returns
- >= 0 on success, a negative errro code otherwise
Definition at line 1434 of file opt.c.
Referenced by av_opt_query_ranges().