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 324DF4A8BE for ; Thu, 18 Apr 2024 15:06:41 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 10EF068CEDD; Thu, 18 Apr 2024 18:06:38 +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 63E3768CA4D for ; Thu, 18 Apr 2024 18:06: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-b.tch.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1rxTLJ-000wcu-35; Thu, 18 Apr 2024 16:06:30 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Thu, 18 Apr 2024 16:06:12 +0100 Message-ID: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 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 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: Based largely on the explanation by Stefano Sabatini: https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325854.html --- doc/jargon.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 doc/jargon.md diff --git a/doc/jargon.md b/doc/jargon.md new file mode 100644 index 0000000000..3b78ffb61f --- /dev/null +++ b/doc/jargon.md @@ -0,0 +1,96 @@ +# 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 elsewhere. + +Consider a trivial program to print uppercase text: + +```c +/* + * Contextual information about where to print a series of messages + */ +struct UpperCasePrinterContext { + FILE* out; +}; + +/* + * Extra information about messages to print. + * This could be used multiple times in a single context, + * or reused several times across multiple contexts. + */ +struct PrintInfo { + char* str; +}; + +void print( + struct UpperCasePrinterContext * ctx, + struct PrintInfo * info +) { + for ( char* c = info->str; *c; ++c ) { + char C = toupper(*c); + fwrite( &C, 1, 1, ctx->out ); + } +} + +int main() +{ + struct PrintInfo hello, world; + struct UpperCasePrinterContext ctx; + + hello.str = "hello, "; + world.str = "world!\n"; + + ctx.out = stdout; + + print( &ctx, &hello ); + print( &ctx, &world ); + + return 0; +} +``` + +The `UpperCasePrinterContext` object contains the information that's about +the context of the current job (i.e. printing things to standard output). +Information with a lifetime different than that of the context is moved +to the `PrintInfo` object. + +FFmpeg's main context structures all happen to face some common problems: + +- querying, setting and getting options +- handling "private" internal context, including options for + a particular instance of the generic context +- configuring log message verbosity and content + +FFmpeg gradually converged on the AVClass struct to store this information, +then converged on the @ref avoptions "AVOptions" system to manipulate it, +so modern code often uses the terms "context", "AVClass context structure" +and "AVOptions-enabled struct" interchangeably. But it is occasionally +necessary to distinguish between them - for example, AVMediaCodecContext +is a context that does not use AVClass. + +To understand how this all works, consider some requirements for the +`libx264` encoder: + +- it has to support common encoder options like "bitrate" +- it has to support encoder-specific options like "profile" +- 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 to +users 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 you get +and set those values, and provides readable feedback about errors. Although +X264Context can be set by users, it is not part of the public interface, +so new releases can modify it without affecting the API version. + +FFmpeg itself uses context structures to handle FFmpeg-specific problems, +but the design pattern, as well as the AVClass and @ref avoptions "AVOptions" +implementations, are general solutions you can use for any purpose. -- 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".