From patchwork Thu May 16 12:26:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48927 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:3a48:b0:1af:fc2d:ff5a with SMTP id zu8csp2196889pzb; Thu, 16 May 2024 05:26:57 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCUry3+pQw499ISiZ3Le8IxuT5PlX8FkIvmf2ixCw3wUBmfC+DjYe9mALbCp2e45NnaR+6vs5Urn4VwiLias1foRjt1EWQjhZCSeVA== X-Google-Smtp-Source: AGHT+IFUTGuNb5pPhA/X3f9fqH5nYenI2KXu//aubsBTuVer0XcY+L8wA6n9SWuwW1u0u86oVlvA X-Received: by 2002:a2e:8ed5:0:b0:2e1:d48e:d5b3 with SMTP id 38308e7fff4ca-2e51fd4a624mr146025651fa.20.1715862417416; Thu, 16 May 2024 05:26:57 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1715862417; cv=none; d=google.com; s=arc-20160816; b=FauNyKFsfmTgvBZE8Pc8cb/k8cD8V460bcZi2BPryldHHaUgcz0aW+JNzTlqmU6sHx yo3Wi+gOI6UOD5+4Z02ItasL1UYeb17+vmGM2ePo5d1iG/6BJ0xKpD5EJxNfg2jxePt0 O0zo1k5e9qDOpp5Om584b/5c/5v/yUQxCjSgN0xgMmF5e3L3+jOp2+3iCQO7+wb+FztC qMq4GS0sW5S80BoPUXXmLYa8dDqaXUkXs8H+5R7Cu2aMJST8vw/n57VApBI7sSCf62z7 wBrQM85BOyyKJTtZvC/mFmU/7NceJnr0buXv/wKl3vrCzSSJ8XGo5uE7ucguk0CPrNE7 D2rg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:message-id:date:to:from :delivered-to; bh=nL3u33kMZT+oU1ikW4gG8eKq1CTnzZskSU3g0nAL0S4=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=KQPr7bXkn2EJZ0Lsjy7uaeytK8GHrnrdLXd1V7upHwu7RR7mgg+HHrMlEJmvd2Gg5s m8InK+cMxiGRFaeY38LRJVPb7+QqybLNw6XMhKG+lzTuh+fM37Bs/o/yePgOtEymHEAM EP9Ujhh5jQXMcUqGCvKJ569dLoJsbcSwPIEOagHRcr1eVddBu2fCzjNuAEEtndvTRxCG q4xSDQ+FYpwaZXbHZAEiz6V9DT5N9oSxMhxVGWAZ7y6Xqv226DErDpssfvM7cR2i1j5e R95aNOM23YKOH3V9Acd7IIONHipX5UzItOhNDMzUnQMRbrj0R3YA7jK6gPUsv3x9k7Oy hXYA==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id a640c23a62f3a-a5a17ba6330si845549366b.623.2024.05.16.05.26.56; Thu, 16 May 2024 05:26:57 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id A89BD68D4A3; Thu, 16 May 2024 15:26:53 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: IGpTBCGYAjuv 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: