From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 4BF084AC27 for ; Thu, 16 May 2024 12:26:55 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 628CB68D499; Thu, 16 May 2024 15:26:53 +0300 (EEST) Received: from b-painless.mh.aa.net.uk (b-painless.mh.aa.net.uk [81.187.30.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id AA92468D2DC for ; Thu, 16 May 2024 15:26:46 +0300 (EEST) Received: from 0.b.4.b.7.4.0.8.c.4.a.5.d.8.b.2.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:2b8d:5a4c:8047:b4b0] helo=andrews-2024-laptop.lan) by painless-b.tch.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1s7aC5-002hLc-1T; Thu, 16 May 2024 13:26:45 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Thu, 16 May 2024 13:26:43 +0100 Message-ID: <20240516122643.3789916-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH] avutil/opt: Say more often that AV_OPT_SEARCH_CHILDREN searches children first X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Andrew Sayers Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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-request@ffmpeg.org with subject "unsubscribe".