FFmpeg  1.2.4
Modules | Functions
Evaluating option strings
AVOptions

This group of functions can be used to evaluate option strings and get numbers out of them. More...

Modules

 Option setting functions
 Those functions set the field of obj with the given name to value.

Functions

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)

Detailed Description

This group of functions can be used to evaluate option strings and get numbers out of them.

They do the same thing as av_opt_set(), except the result is written into the caller-supplied pointer.

Parameters
obja struct whose first element is a pointer to AVClass.
oan option for which the string is to be evaluated.
valstring to be evaluated.
*_outvalue of the string will be written here.
Returns
0 on success, a negative number on failure.

< offset must point to a pointer immediately followed by an int for the length

< offset must point to two consecutive integers

< offset must point to a pointer immediately followed by an int for the length

AVOption

short English help text

Todo:
What about other languages?

The offset relative to the context structure where the option value is stored. It should be 0 for named constants.

the default value for scalar options

< minimum valid value for the option

< maximum valid value for the option

The logical unit to which the option belongs. Non-constant options and corresponding named constants share the same unit. May be NULL.

A single allowed range of values, or a single allowed value.

< For string ranges this represents the min/max length, for dimensions this represents the min/max pixel count

< For string this represents the unicode range for chars, 0-127 limits to ASCII

< if set to 1 the struct encodes a range, if set to 0 a single value

List of AVOptionRange structs

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]obja pointer to a struct whose first element is a pointer to an AVClass
[in]namethe name of the option to look for
[in]unitthe 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.

Set the field of obj with the given name to value.

Parameters
[in]objA struct whose first element is a pointer to an AVClass.
[in]namethe name of the field to set
[in]valThe 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_outif non-NULL put here a pointer to the AVOption found
allocthis 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()

Show the obj options.

Parameters
req_flagsrequested flags for the options to show. Show only the options for which it is opt->flags & req_flags.
rej_flagsrejected flags for the options to show. Show only the options for which it is !(opt->flags & req_flags).
av_log_objlog context to use for showing the options

Set the values of all AVOption fields to their default values.

Parameters
san AVOption-enabled struct (its first member must be a pointer to AVClass)

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
optsoptions string to parse, may be NULL
key_val_sepa 0-terminated list of characters used to separate key from value
pairs_sepa 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

Parse the key-value pairs list in opts. For each key=value pair found, set the value of the corresponding option in ctx.

Parameters
ctxthe AVClass object to set options on
optsthe options string, key-value pairs separated by a delimiter
shorthanda 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_sepa 0-terminated list of characters used to separate key from value, for example '='
pairs_sepa 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.

Free all string and binary options in obj.

Check whether a particular flag is set in a flags field.

Parameters
field_namethe name of the flag field option
flag_namethe 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.

Set all the options from a given dictionary on an object.

Parameters
obja struct whose first element is a pointer to AVClass
optionsoptions to process. This dictionary will be freed and replaced by a new one containing all options not found in obj. Of course this new dictionary needs to be freed by caller with av_dict_free().
Returns
0 on success, a negative AVERROR if some option was found in obj, but could not be set.
See Also
av_dict_copy()

Extract a key-value pair from the beginning of a string.

Parameters
roptspointer 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_sepa 0-terminated list of characters used to separate key from value, for example '='
pairs_sepa 0-terminated list of characters used to separate two pairs from each other, for example ':' or ','
flagsflags; see the AV_OPT_FLAG_* values below
rkeyparsed key; must be freed using av_free()
rvalparsed 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

Accept to parse a value without a key; the key will then be returned as NULL.

This group of functions can be used to evaluate option strings and get numbers out of them. They do the same thing as av_opt_set(), except the result is written into the caller-supplied pointer.

Parameters
obja struct whose first element is a pointer to AVClass.
oan option for which the string is to be evaluated.
valstring to be evaluated.
*_outvalue of the string will be written here.
Returns
0 on success, a negative number on failure.

< offset must point to a pointer immediately followed by an int for the length

< offset must point to two consecutive integers

< offset must point to a pointer immediately followed by an int for the length

AVOption

short English help text

Todo:
What about other languages?

The offset relative to the context structure where the option value is stored. It should be 0 for named constants.

the default value for scalar options

< minimum valid value for the option

< maximum valid value for the option

The logical unit to which the option belongs. Non-constant options and corresponding named constants share the same unit. May be NULL.

A single allowed range of values, or a single allowed value.

< For string ranges this represents the min/max length, for dimensions this represents the min/max pixel count

< For string this represents the unicode range for chars, 0-127 limits to ASCII

< if set to 1 the struct encodes a range, if set to 0 a single value

List of AVOptionRange structs

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]obja pointer to a struct whose first element is a pointer to an AVClass
[in]namethe name of the option to look for
[in]unitthe 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.

Set the field of obj with the given name to value.

Parameters
[in]objA struct whose first element is a pointer to an AVClass.
[in]namethe name of the field to set
[in]valThe 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_outif non-NULL put here a pointer to the AVOption found
allocthis 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()

Show the obj options.

Parameters
req_flagsrequested flags for the options to show. Show only the options for which it is opt->flags & req_flags.
rej_flagsrejected flags for the options to show. Show only the options for which it is !(opt->flags & req_flags).
av_log_objlog context to use for showing the options

Set the values of all AVOption fields to their default values.

Parameters
san AVOption-enabled struct (its first member must be a pointer to AVClass)

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
optsoptions string to parse, may be NULL
key_val_sepa 0-terminated list of characters used to separate key from value
pairs_sepa 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

Parse the key-value pairs list in opts. For each key=value pair found, set the value of the corresponding option in ctx.

Parameters
ctxthe AVClass object to set options on
optsthe options string, key-value pairs separated by a delimiter
shorthanda 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_sepa 0-terminated list of characters used to separate key from value, for example '='
pairs_sepa 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.

Free all string and binary options in obj.

Check whether a particular flag is set in a flags field.

Parameters
field_namethe name of the flag field option
flag_namethe 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.

Set all the options from a given dictionary on an object.

Parameters
obja struct whose first element is a pointer to AVClass
optionsoptions to process. This dictionary will be freed and replaced by a new one containing all options not found in obj. Of course this new dictionary needs to be freed by caller with av_dict_free().
Returns
0 on success, a negative AVERROR if some option was found in obj, but could not be set.
See Also
av_dict_copy()

Extract a key-value pair from the beginning of a string.

Parameters
roptspointer 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_sepa 0-terminated list of characters used to separate key from value, for example '='
pairs_sepa 0-terminated list of characters used to separate two pairs from each other, for example ':' or ','
flagsflags; see the AV_OPT_FLAG_* values below
rkeyparsed key; must be freed using av_free()
rvalparsed 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

Accept to parse a value without a key; the key will then be returned as NULL.

This group of functions can be used to evaluate option strings and get numbers out of them. They do the same thing as av_opt_set(), except the result is written into the caller-supplied pointer.

Parameters
obja struct whose first element is a pointer to AVClass.
oan option for which the string is to be evaluated.
valstring to be evaluated.
*_outvalue of the string will be written here.
Returns
0 on success, a negative number on failure.

Function Documentation

int av_opt_eval_double ( void obj,
const AVOption o,
const char *  val,
double *  double_out 
)
int av_opt_eval_flags ( void obj,
const AVOption o,
const char *  val,
int *  flags_out 
)
int av_opt_eval_float ( void obj,
const AVOption o,
const char *  val,
float *  float_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_q ( void obj,
const AVOption o,
const char *  val,
AVRational q_out 
)