From patchwork Sat Apr 20 12:19:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48186 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:c906:b0:1a9:af23:56c1 with SMTP id gx6csp1215882pzb; Sat, 20 Apr 2024 05:19:58 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCXr/GktzjSEFRlum8gQpmSLd6fLgyhTXvZUdkl/jInVaEHXHZ8nIT5P83HNGh7EGE89r9sG1HYKfHn7KN69X9/tqTvH8094lab5rg== X-Google-Smtp-Source: AGHT+IEno1EaLroz+beD9udSyijfwkq2kwbSSN1fd12bDT/WqKGP1mnUEfkHVNUYj2uemThJzjvC X-Received: by 2002:a2e:9798:0:b0:2d8:918f:55fa with SMTP id y24-20020a2e9798000000b002d8918f55famr3181157lji.18.1713615598146; Sat, 20 Apr 2024 05:19:58 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1713615598; cv=none; d=google.com; s=arc-20160816; b=BNjukFolfV0WKZoqj3aiC+V84TMtnqaYHkjvard4ovLkkT9kks8zHbvHqAZ5Fhg9EU WhSjtl2ykau+NWjMWBGeZdu3E9rq/IAFPGr/72iuTfzoeYzBZXnoVqoSX07opa0cb5fy 0o5AqYEY9+10LELRmAR5nuWtEBd6+6yvPbW9od0fSGkaiz6sqbZG6LX8x5qqp1OmBEhA ILMyziHFK0a5X8dFanbTxPmQOJFL9RJSnKRozSVfhy2ny2z0ym00CaDHcw39aCVKai4S 4vewqSit1YLTIxrxKV7RMvID4yrb3CSFMbk4Phzi6pS1WzDKM15a69WnHzun/qmGDCY2 hKJg== 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=1yCLu1ztF0VrgisfMKI6LeDrPnYD9gPc8i6eiYgabPU=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=ZwclJe/r8vvOXXzZ5oP3xBBcqZOGgOj1FRR4exrKSalKwAUdHF19OS6z970MzzCRBD ScBAl/bJfkLBxOepw6c42OFoeEJRdQg+zYQbFrp7IpLwxZ0KJmBgjp6OOFqwoz73jxaf N9qZ9uwATs/zYFucZElk3LRd2jY5dxdX6Jhred7mQPwNUrs7OFHP50KghufysKnAZw3q C6d4vuDEltpy2Xwv/conJa5cv+Un4jOWcXJQMsmeeeUxvCG7CRe/+tGtIUfHz0jwd2l9 4N0S/1mU3LqF4EjAaBP0Gjyp/FPeKogJ9e4fy2JcFyxSy4AFXSyeXlyFrAqpFVh8uSGn TkCw==; 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 k23-20020aa7c397000000b005702414f58csi3523478edq.478.2024.04.20.05.19.57; Sat, 20 Apr 2024 05:19:58 -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 6DCF868D220; Sat, 20 Apr 2024 15:19:55 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from b-painless.mh.aa.net.uk (unknown [81.187.30.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 557C568ABD7 for ; Sat, 20 Apr 2024 15:19:48 +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 1ry9h5-004Qdg-2L; Sat, 20 Apr 2024 13:19:47 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Sat, 20 Apr 2024 13:19:41 +0100 Message-ID: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: References: MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v2 1/3] doc: Explain what "context" means 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: LamPRND+ckTz Based largely on the explanation by Stefano Sabatini: https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325854.html --- doc/jargon.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 doc/jargon.md diff --git a/doc/jargon.md b/doc/jargon.md new file mode 100644 index 0000000000..f967b5c8bc --- /dev/null +++ b/doc/jargon.md @@ -0,0 +1,169 @@ +# Jargon + +Terms used throughout the code that developers may need to know. + +@anchor context + +## Context + +A design pattern that stores the context (e.g. configuration) for a series +of operations in a "context" structure, and moves other information with +a longer or shorter lifetime elsewhere. + +Consider a code snippet to modify text then print it: + +```c +/** + * Contextual information about printing a series of messages + */ +struct ModifyThenPrintContext { + + /** + * Members of the context usually are usually part of its public API... + */ + FILE *out; + + /** + * ... but check the documentation just in case + */ + [[deprecated]] + int no_longer_part_of_the_public_api; + + /** + * The "internal context" is private to the context itself. + * + * Unlike the members above, the private context is not guaranteed + * and can change arbitrarily between versions. + */ + void* priv_data; +}; + +/** + * Long-lifetime information, reused by many contexts + */ +enum ModifyThenPrintDialect { + MODIFY_THEN_PRINT_PLAIN_TEXT, + MODIFY_THEN_PRINT_REGEX, + MODIFY_THEN_PRINT_REGEX_PCRE +}; + +/** + * Short-lifetime information, used repeatedly in a single context + */ +struct ModifyThenPrintMessage { + char *str; + char *replace_this; + char *with_this; +}; + +/** + * Allocate and initialize a ModifyThenPrintContext + * + * This creates a new pointer, then fills in some sensible defaults. + * + * We can reasonably assume this function will initialise `priv_data` + * with a dialect-specific object, but shouldn't make any assumptions + * about what that object is. + * + */ +int ModifyThenPrintContext_alloc_context(struct ModifyThenPrintContext **ctx, + FILE *out, + enum ModifyThenPrintDialect dialect); + +/** + * Uninitialize and deallocate a ModifyThenPrintContext + * + * This does any work required by the private context in `priv_data` + * (e.g. deallocating it), then deallocates the main context itself. + * + */ +int ModifyThenPrintContext_free(struct ModifyThenPrintContext *ctx); + +/** + * Print a single message + */ +int ModifyThenPrintContext_print(struct ModifyThenPrintContext *ctx, + struct ModifyThenPrintMessage *msg); + +int print_hello_world() +{ + + int ret = 0; + + struct ModifyThenPrintContext *ctx; + + struct ModifyThenPrintMessage hello_world; + + if ( ModifyThenPrintContext_alloc_context( &ctx, stdout, MODIFY_THEN_PRINT_REGEX ) < 0 ) { + ret = -1; + goto EXIT_WITHOUT_CLEANUP; + } + + hello_world.replace_this = "Hi|Hullo"; + hello_world.with_this = "Hello"; + + hello_world.str = "Hi, world!\n"; + if ( ModifyThenPrintContext_print( ctx, &hello_world ) < 0 ) { + ret = -1; + goto FINISH; + } + + hello_world.str = "Hullo, world!\n"; + if ( ModifyThenPrintContext_print( ctx, &hello_world ) < 0 ) { + ret = -1; + goto FINISH; + } + + FINISH: + if ( ModifyThenPrintContext_free( ctx ) ) { + ret = -1; + goto EXIT_WITHOUT_CLEANUP; + } + + EXIT_WITHOUT_CLEANUP: + return ret; + +} +``` + +In the example above, the `ModifyThenPrintContext` object contains information +that's needed for exactly the lifetime of the current job (i.e. how to modify +and where to print). Information with a longer or shorter lifetime is moved +to `ModifyThenPrintDialect` and `ModifyThenPrintMessage`. + +FFmpeg uses the context pattern to solve a variety of problems. But the most +common contexts (AVCodecContext, AVFormatContext etc.) tend to have a lot of +requirements in common: + +- need to query, set and get options + - including options whose implementation is not part of the public API +- need to configure log message verbosity and content + +FFmpeg gradually converged on the AVClass struct to store that information, +then converged on the @ref avoptions "AVOptions" system to manipulate it. +So the terms "context", "AVClass context structure" and "AVOptions-enabled +struct" are often used interchangeably when it's not important to emphasise +the difference. But for example, AVMediaCodecContext uses the context +pattern, but is not an AVClass context structure, so cannot be manipulated +with AVOptions. + +To understand AVClass context structures, consider the `libx264` encoder: + +- it has to support common encoder options like "bitrate" +- it has to support encoder-specific options like "profile" + - the exact options could change quickly if a legal ruling forces a change of backend +- it has to provide useful feedback about unsupported options + +Common encoder options like "bitrate" are stored in the AVCodecContext class, +while encoder-specific options like "profile" are stored in an X264Context +instance in AVCodecContext::priv_data. These options are then exposed through +a tree of AVOption objects, which include user-visible help text and +machine-readable information about the memory location to read/write +each option. Common @ref avoptions "AVOptions" functionality lets end users +get and set those values, and provides readable feedback about errors. But +even though they can be manipulated through an API, the X264Context class is +private and new releases can modify it without affecting the public interface. + +FFmpeg itself uses the context design pattern to solve many problems. +You can use this pattern anywhere it would be useful, and may want to use +AVClass and @ref avoptions "AVOptions" if they're relevant to your situation. From patchwork Sat Apr 20 12:19:42 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48187 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:c906:b0:1a9:af23:56c1 with SMTP id gx6csp1215970pzb; Sat, 20 Apr 2024 05:20:08 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCVFzxSt9rZ3aVJT2JDLVBObDs5+6XxgsdltEj98A0Olo6Fg+jxm6/iTXyS4HLi1bsbKuto/4NzXAOS0nTZCMZGpYaGeoavKrzQO1w== X-Google-Smtp-Source: AGHT+IG734UMidYNZQYuZLIeDYakZ+WMG5RdJKETAGNTYze0+Oyg/K0Olv14bMPuXMuzrpyZWp/W X-Received: by 2002:a2e:2a82:0:b0:2d8:a82f:50a0 with SMTP id q124-20020a2e2a82000000b002d8a82f50a0mr3108670ljq.35.1713615608660; Sat, 20 Apr 2024 05:20:08 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1713615608; cv=none; d=google.com; s=arc-20160816; b=izN3ATcUQVECTY1hIoBSNxVdIZl9NtfavHEArdN2aOssALhuojvqLCjnjwDYs+0Dw/ +WRW0ChjTlSUF7m6nz1VXHIB24jPkSI1fyOc1YKPFKd341evHhn9v/hxvNlUGoEl0q4O TRX3gxWWALeVN78eC59wdJZiyIB9/9La7ewxANaxWDUABsmM9Ku5c46Mula7UF7qs1c2 OHEtWoeh9BElispg8TzOFQoSVrHDvN5qWfeoaBNcnOb4gQhyTz5Fx/GBBu/NQTpJqvmN 8wrMuO1b788/6D+d7MhMnbldl9eeDCtiZ9Sc9BhV3ucMmELz18PiSh0zkjH5+pLLa+6f CqgA== 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=mVBqIVbgAEy6v8llddqWMLXE2LLeNC+eGeXqwrq0PZ0=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=mrxhovr+Mwoa0775IcDKdWZrCtNmRmbl4tcUsoVErFF3YKw3mSSAXdU8f2MHY6kQ16 9fiMRe73B7fMTsmO9CxJS2KJ1OgZQwFzSaDCoIVK0eBiUVWkr/f2/OWKZrCeF6ei9YJY nLE/iifRRzVGHoXtiMp+JNGDLWIF2wWFiL28tbx4OBX4U2L8EPzsPu9MbdCSkLMIul4N 1RUrrt46ZeBuyR97nybvwm6G+Uy9WZZuAKY7dNzMh6ERr5BbciZtmZu1DIi4cQYShe4+ bUurqQiUIUaXpDXFBFZgSIxkqTMgkLj3NM7/cY4TiCyR47+USq5qNEPnY7U6gr4c3d1G 65lQ==; 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 16-20020a05651c009000b002d4376f5b5fsi1701848ljq.188.2024.04.20.05.20.08; Sat, 20 Apr 2024 05:20:08 -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 7352068D229; Sat, 20 Apr 2024 15:19:56 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from b-painless.mh.aa.net.uk (unknown [81.187.30.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 9E17568ABD7 for ; Sat, 20 Apr 2024 15:19:48 +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 1ry9h6-004Qdg-0D; Sat, 20 Apr 2024 13:19:48 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Sat, 20 Apr 2024 13:19:42 +0100 Message-ID: <20240420121943.201032-2-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> References: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v2 2/3] 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: E872tW4qiKTS --- libavutil/log.h | 11 ++++++++--- libavutil/opt.h | 7 ++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/libavutil/log.h b/libavutil/log.h index ab7ceabe22..b5c739dab1 100644 --- a/libavutil/log.h +++ b/libavutil/log.h @@ -59,9 +59,14 @@ 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.). + * Metadata about an arbitrary data structure + * + * A @ref context "context struct" whose first member is a pointer + * to an AVClass object is called an "AVClass context structure" + * (e.g. AVCodecContext, AVFormatContext etc.). + * + * AVClass is often combined with @ref avoptions "AVOptions" to create + * "AVOptions-enabled structs" that can be easily configured by users. */ typedef struct AVClass { /** diff --git a/libavutil/opt.h b/libavutil/opt.h index e6013662f6..b817d15554 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -39,9 +39,10 @@ * @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. + * Builds on AVClass, adding a generic system to declare options. + * + * An option can have a help text, a type and a range of possible values. + * Options may then 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 From patchwork Sat Apr 20 12:19: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: 48188 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:c906:b0:1a9:af23:56c1 with SMTP id gx6csp1216042pzb; Sat, 20 Apr 2024 05:20:18 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCXxRvEdlWEzEifqy0LcE2npyFb+3EMMT+GriPXD8B7MXaHpwTahwu9AAkvsQ8QAnKnUWjWDSskEBKigSfrPGq0g8sxTTE84C8cGPQ== X-Google-Smtp-Source: AGHT+IE00Aqm17wVpW6cOKOs6AT29kaGimy0z7ERC7EVu9wOnIDaMdi/X04IukgAr+2np9C3CSi/ X-Received: by 2002:a05:600c:1f81:b0:418:5e80:a722 with SMTP id je1-20020a05600c1f8100b004185e80a722mr3602398wmb.24.1713615617864; Sat, 20 Apr 2024 05:20:17 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1713615617; cv=none; d=google.com; s=arc-20160816; b=087qgHfRuUshWRNS4Ndr35KuRdFEuPR3c9j3AHvgfyra5g80UFC9Vra4ltCk5RUiG2 7HtMh3TIQk9jb1g7HLfFoId9yzxHJRmtFHkupeGA4hvmZL++7/0Ipn3pZhHamNoFpk3A ibFRfRB7rxOM07M7bG57aeLMp5qs97nIubZSpUwz07GLJjHHRZ0cEqlc8fPrPPXcX9y3 yYw3TmnNxpumIxFg9jNa3n3dQXFnocdJgP0yttKatwJ/2LI6AyFJRc3hRgqVLvhDp7FF DTcfPPJ8KCUbcTsS5+I1m0y2VTMmkc+5ZSuEXwubbOXn4jpQ+InLbrNC3o/CmOoISOoL 7Biw== 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=uM95jNlgmA22WNN9A+LrkkJTWw86Tl/i8joP+UuY2Hw=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=lAO9ux3uOFDiMAj07vXt89CQ2NpvWe7Z5La+hY2nti9U2ejac3IlLonMA3cKlwDeJ7 Rx7QOUzOd5gZP6z3x6Y/5n2EMKHLYqEFpi+P15uepMKJKYLn3OkF/6Dv783ZXotPMGZe J8xvYa4kr+PC9DckaCkgStTJ4cyToKoraaYhKMzYjf1ilPE9MjdW69ocFsUaeI+ckxPR B6mT6awvGDGOJcUdbUVZqBT7F/kSyg7ROmKNkkTlppZTQtITt0izU/TFTwRBGzt3MYxo 6Y19U80X1cthebioBrXdQeRk3o/eoV6JF7a6cfVzkXana9z2UchRFB8EU9ue0If8CkJL zu4A==; 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 gs30-20020a1709072d1e00b00a52435a5878si3612062ejc.529.2024.04.20.05.20.17; Sat, 20 Apr 2024 05:20:17 -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 47BEA68D234; Sat, 20 Apr 2024 15:19:57 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from b-painless.mh.aa.net.uk (unknown [81.187.30.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 350FC68ABD7 for ; Sat, 20 Apr 2024 15:19:49 +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 1ry9h6-004Qdg-18; Sat, 20 Apr 2024 13:19:48 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Sat, 20 Apr 2024 13:19:43 +0100 Message-ID: <20240420121943.201032-3-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> References: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v2 3/3] all: Link to "context" from all contexts with documentation 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: 1ZWksIC9NskE Some headings needed to be rewritten to accomodate the text, (hopefully) without changing the meaning. --- libavcodec/aacdec.h | 2 +- libavcodec/aacenc.h | 2 +- libavcodec/ac3enc.h | 2 +- libavcodec/amfenc.h | 2 +- libavcodec/atrac.h | 2 +- libavcodec/avcodec.h | 3 ++- libavcodec/bsf.h | 2 +- libavcodec/d3d11va.h | 3 +-- libavcodec/mediacodec.h | 2 +- libavcodec/qsv.h | 6 ++++-- libavcodec/sbr.h | 2 +- libavcodec/vdpau.h | 3 ++- libavcodec/videotoolbox.h | 5 +++-- libavfilter/avfilter.h | 2 +- libavformat/avformat.h | 3 ++- libavformat/avio.h | 3 ++- libavutil/hwcontext.h | 21 ++++++++++++--------- libavutil/hwcontext_cuda.h | 2 +- libavutil/hwcontext_d3d11va.h | 4 ++-- libavutil/hwcontext_d3d12va.h | 6 +++--- libavutil/hwcontext_drm.h | 2 +- libavutil/hwcontext_dxva2.h | 4 ++-- libavutil/hwcontext_mediacodec.h | 2 +- libavutil/hwcontext_opencl.h | 4 ++-- libavutil/hwcontext_qsv.h | 4 ++-- libavutil/hwcontext_vaapi.h | 6 +++--- libavutil/hwcontext_vdpau.h | 2 +- libavutil/hwcontext_vulkan.h | 4 ++-- 28 files changed, 57 insertions(+), 48 deletions(-) diff --git a/libavcodec/aacdec.h b/libavcodec/aacdec.h index 1b245f9258..3a5317cd54 100644 --- a/libavcodec/aacdec.h +++ b/libavcodec/aacdec.h @@ -181,7 +181,7 @@ typedef struct DynamicRangeControl { } DynamicRangeControl; /** - * main AAC decoding context + * main AAC decoding @ref context "context" */ typedef struct AACDecContext { const struct AVClass *class; diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h index 8899f90ac7..c91f99bc6c 100644 --- a/libavcodec/aacenc.h +++ b/libavcodec/aacenc.h @@ -193,7 +193,7 @@ typedef struct AACPCEInfo { } AACPCEInfo; /** - * AAC encoder context + * AAC encoder @ref context "context" */ typedef struct AACEncContext { AVClass *av_class; diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h index 30812617cc..4b6b3c222b 100644 --- a/libavcodec/ac3enc.h +++ b/libavcodec/ac3enc.h @@ -152,7 +152,7 @@ typedef struct AC3Block { } AC3Block; /** - * AC-3 encoder private context. + * AC-3 encoder private @ref context "context" */ typedef struct AC3EncodeContext { AVClass *av_class; ///< AVClass used for AVOption diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h index 2dbd378ef8..71138e7f76 100644 --- a/libavcodec/amfenc.h +++ b/libavcodec/amfenc.h @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter { } AmfTraceWriter; /** -* AMF encoder context +* AMF encoder @ref context "context" */ typedef struct AmfContext { diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h index 05208bbee6..acdd0a741a 100644 --- a/libavcodec/atrac.h +++ b/libavcodec/atrac.h @@ -39,7 +39,7 @@ typedef struct AtracGainInfo { } AtracGainInfo; /** - * Gain compensation context structure. + * Gain compensation @ref context "context" */ typedef struct AtracGCContext { float gain_tab1[16]; ///< gain compensation level table diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 968009a192..a1f1430dde 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -430,7 +430,8 @@ typedef struct RcOverride{ #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0) /** - * main external API structure. + * @ref context "Context" for an encode or decode session + * * New fields can be added to the end with minor version bumps. * Removal, reordering and changes to existing fields require a major * version bump. diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h index a09c69f242..23c3cc87e4 100644 --- a/libavcodec/bsf.h +++ b/libavcodec/bsf.h @@ -56,7 +56,7 @@ */ /** - * The bitstream filter state. + * Bitstream filter @ref context "context" * * This struct must be allocated with av_bsf_alloc() and freed with * av_bsf_free(). diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h index 27f40e5519..087c99f161 100644 --- a/libavcodec/d3d11va.h +++ b/libavcodec/d3d11va.h @@ -46,8 +46,7 @@ */ /** - * This structure is used to provides the necessary configurations and data - * to the Direct3D11 FFmpeg HWAccel implementation. + * @ref context "Context" for the Direct3D11 FFmpeg HWAccel implementation * * The application must make it available as AVCodecContext.hwaccel_context. * diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h index 4e9b56a618..d983e7ff1a 100644 --- a/libavcodec/mediacodec.h +++ b/libavcodec/mediacodec.h @@ -26,7 +26,7 @@ #include "libavcodec/avcodec.h" /** - * This structure holds a reference to a android/view/Surface object that will + * @ref context "Context" for the android/view/Surface object that will * be used as output by the decoder. * */ diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h index c156b08d07..e75351ae27 100644 --- a/libavcodec/qsv.h +++ b/libavcodec/qsv.h @@ -26,8 +26,10 @@ #include "libavutil/buffer.h" /** - * This struct is used for communicating QSV parameters between libavcodec and - * the caller. It is managed by the caller and must be assigned to + * @ref context "Context" for communicating QSV parameters between libavcodec + * and the caller. + * + * It is managed by the caller and must be assigned to * AVCodecContext.hwaccel_context. * - decoding: hwaccel_context must be set on return from the get_format() * callback diff --git a/libavcodec/sbr.h b/libavcodec/sbr.h index fe3a39603a..65f7a6da8f 100644 --- a/libavcodec/sbr.h +++ b/libavcodec/sbr.h @@ -116,7 +116,7 @@ typedef struct SBRData { typedef struct SpectralBandReplication SpectralBandReplication; /** - * aacsbr functions pointers + * aacsbr functions pointer @ref context "context" */ typedef struct AACSBRContext { int (*sbr_lf_gen)(SpectralBandReplication *sbr, diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h index 8021c25761..a9ff8b5f47 100644 --- a/libavcodec/vdpau.h +++ b/libavcodec/vdpau.h @@ -64,8 +64,9 @@ typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *, const VdpBitstreamBuffer *); /** - * This structure is used to share data between the libavcodec library and + * @ref context "Context" to share data between the libavcodec library and * the client video application. + * * This structure will be allocated and stored in AVCodecContext.hwaccel_context * by av_vdpau_bind_context(). Members can be set by the user once * during initialization or through each AVCodecContext.get_buffer() diff --git a/libavcodec/videotoolbox.h b/libavcodec/videotoolbox.h index d68d76e400..ece008157c 100644 --- a/libavcodec/videotoolbox.h +++ b/libavcodec/videotoolbox.h @@ -49,8 +49,9 @@ #include "libavutil/attributes.h" /** - * This struct holds all the information that needs to be passed - * between the caller and libavcodec for initializing Videotoolbox decoding. + * @ref context "Context" for information passed between the caller and libavcodec + * for initializing Videotoolbox decoding. + * * Its size is not a part of the public ABI, it must be allocated with * av_videotoolbox_alloc_context() and freed with av_free(). */ diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h index a34e61f23c..41bdc30d89 100644 --- a/libavfilter/avfilter.h +++ b/libavfilter/avfilter.h @@ -403,7 +403,7 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); */ #define AVFILTER_THREAD_SLICE (1 << 0) -/** An instance of a filter */ +/** @ref context "Context" for a filter */ struct AVFilterContext { const AVClass *av_class; ///< needed for av_log() and filters common options diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 8afdcd9fd0..6bb08a0b0c 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -1241,7 +1241,8 @@ enum AVDurationEstimationMethod { }; /** - * Format I/O context. + * Format I/O @ref context "context" + * * New fields can be added to the end with minor version bumps. * Removal, reordering and changes to existing fields require a major * version bump. diff --git a/libavformat/avio.h b/libavformat/avio.h index ebf611187d..e18d542377 100644 --- a/libavformat/avio.h +++ b/libavformat/avio.h @@ -146,7 +146,8 @@ enum AVIODataMarkerType { }; /** - * Bytestream IO Context. + * Bytestream I/O @ref context "context" + * * New public fields can be added with minor version bumps. * Removal, reordering and changes to existing public fields require * a major version bump. diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h index bac30debae..f94f44906c 100644 --- a/libavutil/hwcontext.h +++ b/libavutil/hwcontext.h @@ -41,12 +41,13 @@ enum AVHWDeviceType { }; /** - * This struct aggregates all the (hardware/vendor-specific) "high-level" state, - * i.e. state that is not tied to a concrete processing configuration. - * E.g., in an API that supports hardware-accelerated encoding and decoding, - * this struct will (if possible) wrap the state that is common to both encoding - * and decoding and from which specific instances of encoders or decoders can be - * derived. + * @ref context "Context" for (hardware/vendor-specific) "high-level" state. + * + * "High-level state" is anything that is not tied to a concrete processing + * configuration. E.g., in an API that supports hardware-accelerated encoding + * and decoding, this struct will (if possible) wrap the state that is common + * to both encoding and decoding and from which specific instances of encoders + * or decoders can be derived. * * This struct is reference-counted with the AVBuffer mechanism. The * av_hwdevice_ctx_alloc() constructor yields a reference, whose data field @@ -103,9 +104,11 @@ typedef struct AVHWDeviceContext { } AVHWDeviceContext; /** - * This struct describes a set or pool of "hardware" frames (i.e. those with - * data not located in normal system memory). All the frames in the pool are - * assumed to be allocated in the same way and interchangeable. + * @ref context "context" for a pool of "hardware" frames (those with + * data not located in normal system memory) + * + * All the frames in the pool are assumed to be allocated in the same way and + * interchangeable. * * This struct is reference-counted with the AVBuffer mechanism and tied to a * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor diff --git a/libavutil/hwcontext_cuda.h b/libavutil/hwcontext_cuda.h index cbad434fea..befa978cf9 100644 --- a/libavutil/hwcontext_cuda.h +++ b/libavutil/hwcontext_cuda.h @@ -37,7 +37,7 @@ typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal; /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVCUDADeviceContext { CUcontext cuda_ctx; diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h index 77d2d72f1b..eac7d6062a 100644 --- a/libavutil/hwcontext_d3d11va.h +++ b/libavutil/hwcontext_d3d11va.h @@ -40,7 +40,7 @@ #include /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVD3D11VADeviceContext { /** @@ -126,7 +126,7 @@ typedef struct AVD3D11FrameDescriptor { } AVD3D11FrameDescriptor; /** - * This struct is allocated as AVHWFramesContext.hwctx + * This @ref context "context" is allocated as AVHWFramesContext.hwctx */ typedef struct AVD3D11VAFramesContext { /** diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h index ff06e6f2ef..d170f74b4d 100644 --- a/libavutil/hwcontext_d3d12va.h +++ b/libavutil/hwcontext_d3d12va.h @@ -37,7 +37,7 @@ #include /** - * @brief This struct is allocated as AVHWDeviceContext.hwctx + * @brief This @ref context "context" is allocated as AVHWDeviceContext.hwctx * */ typedef struct AVD3D12VADeviceContext { @@ -78,7 +78,7 @@ typedef struct AVD3D12VADeviceContext { } AVD3D12VADeviceContext; /** - * @brief This struct is used to sync d3d12 execution + * @brief This @ref context "context" is used to sync d3d12 execution * */ typedef struct AVD3D12VASyncContext { @@ -120,7 +120,7 @@ typedef struct AVD3D12VAFrame { } AVD3D12VAFrame; /** - * @brief This struct is allocated as AVHWFramesContext.hwctx + * @brief This @ref context "context" is allocated as AVHWFramesContext.hwctx * */ typedef struct AVD3D12VAFramesContext { diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h index 42709f215e..b7b1bad171 100644 --- a/libavutil/hwcontext_drm.h +++ b/libavutil/hwcontext_drm.h @@ -152,7 +152,7 @@ typedef struct AVDRMFrameDescriptor { /** * DRM device. * - * Allocated as AVHWDeviceContext.hwctx. + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx. */ typedef struct AVDRMDeviceContext { /** diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h index e1b79bc0de..b77b7293ab 100644 --- a/libavutil/hwcontext_dxva2.h +++ b/libavutil/hwcontext_dxva2.h @@ -34,14 +34,14 @@ #include /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVDXVA2DeviceContext { IDirect3DDeviceManager9 *devmgr; } AVDXVA2DeviceContext; /** - * This struct is allocated as AVHWFramesContext.hwctx + * This @ref context "context" is allocated as AVHWFramesContext.hwctx */ typedef struct AVDXVA2FramesContext { /** diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h index fc0263cabc..39381b56c5 100644 --- a/libavutil/hwcontext_mediacodec.h +++ b/libavutil/hwcontext_mediacodec.h @@ -22,7 +22,7 @@ /** * MediaCodec details. * - * Allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVMediaCodecDeviceContext { /** diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h index ef54486c95..fc5b1bb24f 100644 --- a/libavutil/hwcontext_opencl.h +++ b/libavutil/hwcontext_opencl.h @@ -58,7 +58,7 @@ typedef struct AVOpenCLFrameDescriptor { /** * OpenCL device details. * - * Allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVOpenCLDeviceContext { /** @@ -84,7 +84,7 @@ typedef struct AVOpenCLDeviceContext { /** * OpenCL-specific data associated with a frame pool. * - * Allocated as AVHWFramesContext.hwctx. + * This @ref context "context" is allocated as AVHWFramesContext.hwctx. */ typedef struct AVOpenCLFramesContext { /** diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h index e2dba8ad83..c7cc88627b 100644 --- a/libavutil/hwcontext_qsv.h +++ b/libavutil/hwcontext_qsv.h @@ -30,7 +30,7 @@ */ /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVQSVDeviceContext { mfxSession session; @@ -48,7 +48,7 @@ typedef struct AVQSVDeviceContext { } AVQSVDeviceContext; /** - * This struct is allocated as AVHWFramesContext.hwctx + * This @ref context "context" is allocated as AVHWFramesContext.hwctx */ typedef struct AVQSVFramesContext { mfxFrameSurface1 *surfaces; diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h index 0b2e071cb3..e1940a5fe0 100644 --- a/libavutil/hwcontext_vaapi.h +++ b/libavutil/hwcontext_vaapi.h @@ -63,7 +63,7 @@ enum { /** * VAAPI connection details. * - * Allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVVAAPIDeviceContext { /** @@ -83,7 +83,7 @@ typedef struct AVVAAPIDeviceContext { /** * VAAPI-specific data associated with a frame pool. * - * Allocated as AVHWFramesContext.hwctx. + * This @ref context "context" is allocated as AVHWFramesContext.hwctx. */ typedef struct AVVAAPIFramesContext { /** @@ -105,7 +105,7 @@ typedef struct AVVAAPIFramesContext { /** * VAAPI hardware pipeline configuration details. * - * Allocated with av_hwdevice_hwconfig_alloc(). + * This struct is allocated with av_hwdevice_hwconfig_alloc(). */ typedef struct AVVAAPIHWConfig { /** diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h index 1b7ea1e443..b26f7f171e 100644 --- a/libavutil/hwcontext_vdpau.h +++ b/libavutil/hwcontext_vdpau.h @@ -30,7 +30,7 @@ */ /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVVDPAUDeviceContext { VdpDevice device; diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h index cbbd2390c1..d6897a96fa 100644 --- a/libavutil/hwcontext_vulkan.h +++ b/libavutil/hwcontext_vulkan.h @@ -39,7 +39,7 @@ typedef struct AVVkFrame AVVkFrame; */ /** - * Main Vulkan context, allocated as AVHWDeviceContext.hwctx. + * Main Vulkan @ref context "context", allocated as AVHWDeviceContext.hwctx. * All of these can be set before init to change what the context uses */ typedef struct AVVulkanDeviceContext { @@ -172,7 +172,7 @@ typedef enum AVVkFrameFlags { } AVVkFrameFlags; /** - * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options + * This @ref context "context" is allocated as AVHWFramesContext.hwctx, used to set pool-specific options */ typedef struct AVVulkanFramesContext { /**