lavu/opt: cosmetics, group (un)init and management functions together

1 files 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.
@@ -431,6 +425,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
  * key. ctx must be an AVClass context, storing is done using
@@ -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.
@@ -530,39 +672,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
  * @{
  * This group of functions can be used to evaluate 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
  * @{