From cc0bd9da7084518f3612e30252cd7f6e2d23ccaa Mon Sep 17 00:00:00 2001 From: Anton Khirnov Date: Thu, 8 Feb 2024 09:30:44 +0100 Subject: lavu/opt: cosmetics, group (un)init and management functions together --- libavutil/opt.h | 298 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 154 insertions(+), 144 deletions(-) diff --git a/libavutil/opt.h b/libavutil/opt.h index d72d65052f..e2b6ba1f35 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -402,15 +402,9 @@ typedef struct AVOptionRanges { } AVOptionRanges; /** - * Show the obj options. - * - * @param req_flags requested flags for the options to show. Show only the - * options for which it is opt->flags & req_flags. - * @param rej_flags rejected flags for the options to show. Show only the - * options for which it is !(opt->flags & req_flags). - * @param av_log_obj log context to use for showing the options + * @defgroup opt_mng AVOption (un)initialization and inspection. + * @{ */ -int av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags); /** * Set the values of all AVOption fields to their default values. @@ -430,6 +424,158 @@ void av_opt_set_defaults(void *s); */ void av_opt_set_defaults2(void *s, int mask, int flags); +/** + * Free all allocated objects in obj. + */ +void av_opt_free(void *obj); + +/** + * Iterate over all AVOptions belonging to obj. + * + * @param obj an AVOptions-enabled struct or a double pointer to an + * AVClass describing it. + * @param prev result of the previous call to av_opt_next() on this object + * or NULL + * @return next AVOption or NULL + */ +const AVOption *av_opt_next(const void *obj, const AVOption *prev); + +/** + * Iterate over AVOptions-enabled children of obj. + * + * @param prev result of a previous call to this function or NULL + * @return next AVOptions-enabled child or NULL + */ +void *av_opt_child_next(void *obj, void *prev); + +/** + * Iterate over potential AVOptions-enabled children of parent. + * + * @param iter a pointer where iteration state is stored. + * @return AVClass corresponding to next potential child or NULL + */ +const AVClass *av_opt_child_class_iterate(const AVClass *parent, void **iter); + +#define AV_OPT_SEARCH_CHILDREN (1 << 0) /**< 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. This is + * useful for searching for options without needing to allocate the corresponding + * object. + */ +#define AV_OPT_SEARCH_FAKE_OBJ (1 << 1) + +/** + * In av_opt_get, return NULL if the option has a pointer type and is set to NULL, + * rather than returning an empty string. + */ +#define AV_OPT_ALLOW_NULL (1 << 2) + +/** + * Allows av_opt_query_ranges and av_opt_query_ranges_default to return more than + * one component for certain option types. + * @see AVOptionRanges for details. + */ +#define AV_OPT_MULTI_COMPONENT_RANGE (1 << 12) + +/** + * Look for an option in an object. Consider only options which + * have all the specified flags set. + * + * @param[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. + * @param[in] name The name of the option to look for. + * @param[in] unit When searching for named constants, name of the unit + * it belongs to. + * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG). + * @param search_flags A combination of AV_OPT_SEARCH_*. + * + * @return 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_opt_set(). Use special calls which take an options + * AVDictionary (e.g. avformat_open_input()) to set options found with this + * flag. + */ +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. + * + * @param[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. + * @param[in] name The name of the option to look for. + * @param[in] unit When searching for named constants, name of the unit + * it belongs to. + * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG). + * @param search_flags A combination of AV_OPT_SEARCH_*. + * @param[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. + * + * @return A pointer to the option found, or NULL if no option + * was found. + */ +const AVOption *av_opt_find2(void *obj, const char *name, const char *unit, + int opt_flags, int search_flags, void **target_obj); + +/** + * Show the obj options. + * + * @param req_flags requested flags for the options to show. Show only the + * options for which it is opt->flags & req_flags. + * @param rej_flags rejected flags for the options to show. Show only the + * options for which it is !(opt->flags & req_flags). + * @param av_log_obj log context to use for showing the options + */ +int av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags); + +/** + * Extract a key-value pair from the beginning of a string. + * + * @param 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) + * @param key_val_sep a 0-terminated list of characters used to separate + * key from value, for example '=' + * @param pairs_sep a 0-terminated list of characters used to separate + * two pairs from each other, for example ':' or ',' + * @param flags flags; see the AV_OPT_FLAG_* values below + * @param rkey parsed key; must be freed using av_free() + * @param rval parsed value; must be freed using av_free() + * + * @return >=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 + * + */ +int av_opt_get_key_value(const char **ropts, + const char *key_val_sep, const char *pairs_sep, + unsigned flags, + char **rkey, char **rval); + +enum { + + /** + * Accept to parse a value without a key; the key will then be returned + * as NULL. + */ + AV_OPT_FLAG_IMPLICIT_KEY = 1, +}; + +/** + * @} + */ + /** * 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 @@ -480,10 +626,6 @@ int av_set_options_string(void *ctx, const char *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); -/** - * Free all allocated objects in obj. - */ -void av_opt_free(void *obj); /** * Check whether a particular flag is set in a flags field. @@ -529,39 +671,6 @@ int av_opt_set_dict(void *obj, struct AVDictionary **options); */ int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags); -/** - * Extract a key-value pair from the beginning of a string. - * - * @param 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) - * @param key_val_sep a 0-terminated list of characters used to separate - * key from value, for example '=' - * @param pairs_sep a 0-terminated list of characters used to separate - * two pairs from each other, for example ':' or ',' - * @param flags flags; see the AV_OPT_FLAG_* values below - * @param rkey parsed key; must be freed using av_free() - * @param rval parsed value; must be freed using av_free() - * - * @return >=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 - * - */ -int av_opt_get_key_value(const char **ropts, - const char *key_val_sep, const char *pairs_sep, - unsigned flags, - char **rkey, char **rval); - -enum { - - /** - * Accept to parse a value without a key; the key will then be returned - * as NULL. - */ - AV_OPT_FLAG_IMPLICIT_KEY = 1, -}; - /** * @defgroup opt_eval_funcs Evaluating option strings * @{ @@ -586,105 +695,6 @@ int av_opt_eval_q (void *obj, const AVOption *o, const char *val, AVRational * @} */ -#define AV_OPT_SEARCH_CHILDREN (1 << 0) /**< 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. This is - * useful for searching for options without needing to allocate the corresponding - * object. - */ -#define AV_OPT_SEARCH_FAKE_OBJ (1 << 1) - -/** - * In av_opt_get, return NULL if the option has a pointer type and is set to NULL, - * rather than returning an empty string. - */ -#define AV_OPT_ALLOW_NULL (1 << 2) - -/** - * Allows av_opt_query_ranges and av_opt_query_ranges_default to return more than - * one component for certain option types. - * @see AVOptionRanges for details. - */ -#define AV_OPT_MULTI_COMPONENT_RANGE (1 << 12) - -/** - * Look for an option in an object. Consider only options which - * have all the specified flags set. - * - * @param[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. - * @param[in] name The name of the option to look for. - * @param[in] unit When searching for named constants, name of the unit - * it belongs to. - * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG). - * @param search_flags A combination of AV_OPT_SEARCH_*. - * - * @return 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_opt_set(). Use special calls which take an options - * AVDictionary (e.g. avformat_open_input()) to set options found with this - * flag. - */ -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. - * - * @param[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. - * @param[in] name The name of the option to look for. - * @param[in] unit When searching for named constants, name of the unit - * it belongs to. - * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG). - * @param search_flags A combination of AV_OPT_SEARCH_*. - * @param[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. - * - * @return A pointer to the option found, or NULL if no option - * was found. - */ -const AVOption *av_opt_find2(void *obj, const char *name, const char *unit, - int opt_flags, int search_flags, void **target_obj); - -/** - * Iterate over all AVOptions belonging to obj. - * - * @param obj an AVOptions-enabled struct or a double pointer to an - * AVClass describing it. - * @param prev result of the previous call to av_opt_next() on this object - * or NULL - * @return next AVOption or NULL - */ -const AVOption *av_opt_next(const void *obj, const AVOption *prev); - -/** - * Iterate over AVOptions-enabled children of obj. - * - * @param prev result of a previous call to this function or NULL - * @return next AVOptions-enabled child or NULL - */ -void *av_opt_child_next(void *obj, void *prev); - -/** - * Iterate over potential AVOptions-enabled children of parent. - * - * @param iter a pointer where iteration state is stored. - * @return AVClass corresponding to next potential child or NULL - */ -const AVClass *av_opt_child_class_iterate(const AVClass *parent, void **iter); - /** * @defgroup opt_set_funcs Option setting functions * @{ -- cgit v1.2.3