This behaviour is already mentioned in the documentation for
AV_OPT_SEARCH_CHILDREN itself, but that's quite easy to miss.
Knowing that child options *override* parent ones is useful for users,
so it's worth mentioning in all the places they would look.
av_opt_find() had a note that av_opt_find2() was missing.
Assume that wasn't deliberate, and copy it over.
---
libavutil/opt.h | 20 ++++++++++++++------
1 file changed, 14 insertions(+), 6 deletions(-)
diff --git a/libavutil/opt.h b/libavutil/opt.h
index 07e27a9208..24b807ec66 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -211,7 +211,7 @@
*
* 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.
+ * to av_opt_find() will make the function recursively search children first.
*
* 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
@@ -570,10 +570,11 @@ const AVClass *av_opt_child_class_iterate(const AVClass
*parent, void **iter);
* @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.
+ * @note If AV_OPT_SEARCH_CHILDREN is set, this function will return an
+ * option from the first matching child class, or the specified class if
+ * no child matches. Options from child classes may not be settable directly
+ * with av_opt_set(), so 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);
@@ -598,6 +599,12 @@ const AVOption *av_opt_find(void *obj, const char *name,
const char *unit,
*
* @return A pointer to the option found, or NULL if no option
* was found.
+ *
+ * @note If AV_OPT_SEARCH_CHILDREN is set, this function will return an
+ * option from the first matching child class, or the specified class if
+ * no child matches. Options from child classes may not be settable directly
+ * with av_opt_set(), so use special calls which take an options AVDictionary
+ * (e.g. avformat_open_input()) to set options found with this flag.
*/
const AVOption *av_opt_find2(void *obj, const char *name, const char *unit,
int opt_flags, int search_flags, void
**target_obj);
@@ -780,7 +787,8 @@ int av_opt_copy(void *dest, const void *src);
* key=value parameters. Values containing ':' special characters must be
* escaped.
* @param search_flags flags passed to av_opt_find2. I.e. if
AV_OPT_SEARCH_CHILDREN
- * is passed here, then the option may be set on a child of obj.
+ * is passed here, av_opt_set() will set the first matching child if possible,
+ * or obj if no child matches.
*
* @return 0 if the value has been set, or an AVERROR code in case of
* error:
--
2.43.0
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
