[FFmpeg-devel] [PATCH 1/3] doc: Explain what "context" means

[Andrew Sayers]

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.
+
+ at 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