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-requ...@ffmpeg.org with subject "unsubscribe".