From patchwork Tue Jun 4 14:47:22 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 49551 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9183:0:b0:460:55fa:d5ed with SMTP id s3csp2743573vqg; Tue, 4 Jun 2024 07:50:01 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCU+X+JUoSgGU3Fquy/E3R6yZnZO7MbeeYqQpiRQ0cwabz/+FIXzWHwBreIJbrjntv/aWJesQ2U2223S42WGqo33vmBDmHxEERzdWw== X-Google-Smtp-Source: AGHT+IEMkjm9umip5Yrvt7vA8l2AT9N+WifdJcq15euND9kvQGl7436ZCSFPW2uuUuiujzOf5K/G X-Received: by 2002:a17:906:130e:b0:a62:2cae:c02 with SMTP id a640c23a62f3a-a6822049d08mr832187266b.61.1717512601082; Tue, 04 Jun 2024 07:50:01 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717512601; cv=none; d=google.com; s=arc-20160816; b=MW5EUiaK/2Ek5ceggJKEA0ZCLXXGIESj2ap3Nby/SV54EXIVyQu2kpgXStPAUis9Kh N3GmKzc9OddyuTWRDU4L0oM0k2UnHaukuGAIW1EH4jdUz34mIeu+fIainIAKBavZa1j4 jlFS/ASrQcGqrpkTW+pouQ4Q7dhH3STeYjYOVVz30GP04DLVGlEj0UPNOHZOeN3QDLHL WA0eOcFDpECu3zvo6vfrlulIYITGvtPCBiHiVayfHwGcDI7VqtOEizeAwxdSEKJgBSn7 PyDl80xTOLvkcaKnLygvl5w9gya1817R0y4uZINS9eXXe5kFdrRI6gsyQMc7JEnyu4TA PJ3w== 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:references:in-reply-to :message-id:date:to:from:delivered-to; bh=roVkJZhGECd0Asj9r7/lP67MQva6YTWgziDI70M+FJw=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=P4dDWmQ+K8DjNGAD4FgrTpMglw8MJk8e21wSTvZuRP0Yb8Qtgj8ZefC6ShevYdoljA lG/pQbdS/ahlPzQvbJ8Voug4w6QnnYXrLoep0JRnuxiggEtEFRncEP/dzQuc4BhgPW/4 UCP8oQ5Q8AbF2Yx8oyYqjK4rrbG24ilDzPx2T0Mt4uU0GTx5WKco5y6FyW+5zjFoj2cX 0V7XHi3Tk4W+y4DqYRzU6tDf/e4gBtc79zHnqanw3Z2RcpCm5Ta3iZ2Umhn2DX2P17ZI X0jA/8mPt5fBhanNqyciLfMef+6B6JptpOLsuq8K8fw49AHTyP8o5UH2cJzuUEtshLpB g26Q==; 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-a68b5b3314esi360659766b.161.2024.06.04.07.50.00; Tue, 04 Jun 2024 07:50:01 -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 D222C68D711; Tue, 4 Jun 2024 17:49:39 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D234C68D6FC for ; Tue, 4 Jun 2024 17:49:31 +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-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1sEVTf-007B97-05; Tue, 04 Jun 2024 15:49:31 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Tue, 4 Jun 2024 15:47:22 +0100 Message-ID: <20240604144919.213799-3-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v6 2/4] lavu: Clarify relationship between AVClass, AVOption and context 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: 5NFUAD7VGFnr --- libavutil/log.h | 16 +++++++++++++--- libavutil/opt.h | 26 +++++++++++++++++++++----- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/libavutil/log.h b/libavutil/log.h index ab7ceabe22..88b35897c6 100644 --- a/libavutil/log.h +++ b/libavutil/log.h @@ -59,9 +59,19 @@ typedef enum { struct AVOptionRanges; /** - * Describe the class of an AVClass context structure. That is an - * arbitrary struct of which the first field is a pointer to an - * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.). + * Generic Logging facilities and configuration options + * + * Logging and AVOptions functions expect to be passed structs + * whose first member is a pointer-to-@ref AVClass. + * + * Structs that only use logging facilities are often referred to as + * "AVClass context structures", while those that provide configuration + * options are called "AVOptions-enabled structs". + * + * @see + * * @ref lavu_log + * * @ref avoptions + * * @ref Context */ typedef struct AVClass { /** diff --git a/libavutil/opt.h b/libavutil/opt.h index 07e27a9208..cdee8f7d28 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -39,9 +39,16 @@ * @defgroup avoptions AVOptions * @ingroup lavu_data * @{ - * AVOptions provide a generic system to declare options on arbitrary structs - * ("objects"). An option can have a help text, a type and a range of possible - * values. Options may then be enumerated, read and written to. + * + * Inspection and configuration for AVClass context structures + * + * Provides a generic API to declare and manage options on any struct + * whose first member is a pointer-to-@ref AVClass. Structs with private + * contexts can use that AVClass to return further @ref AVClass "AVClass"es + * that allow access to options in the private structs. + * + * Each option can have a help text, a type and a range of possible values. + * Options may be enumerated, read and written to. * * There are two modes of access to members of AVOption and its child structs. * One is called 'native access', and refers to access from the code that @@ -53,11 +60,20 @@ * question is allowed to access the field. This allows us to extend the * semantics of those fields without breaking API compatibility. * + * Note that AVOptions is not reentrant, and that many FFmpeg functions access + * options from separate threads. Unless otherwise indicated, it is best to + * avoid modifying options once a struct has been initialized. + * + * @see + * * @ref lavu_log + * * @ref Context + * * @section avoptions_scope Scope of AVOptions * * AVOptions is designed to support any set of multimedia configuration options - * that can be defined at compile-time. Although it is mainly used to expose - * FFmpeg options, you are welcome to adapt it to your own use case. + * that can be defined at compile-time and set at object creation time. Although + * it is mainly used to expose FFmpeg options, you are welcome to adapt it + * to your own use case. * * No single approach can ever fully solve the problem of configuration, * but please submit a patch if you believe you have found a problem