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

[Stefano Sabatini]

On date Thursday 2024-04-18 16:06:12 +0100, Andrew Sayers wrote:
> 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

We currently have a single .md file in doc (for historical reason we
still stick to texinfo). Also how is this integrated into doxygen?


> @@ -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
> + */

Style:
/**
 * Contextual information about where to print a series of messages
 */

> +struct UpperCasePrinterContext {
> +    FILE* out;

here and below, use:
VAR *out;

for overall consistency with the project style.

> +};
> +
> +/*
> + * 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;
> +}

I'm not sure this is a fitting example. Usually the context is a
public structure and the internal context (which corresponds to the
PrintInfo struct) is private to the implementation. In this case the
API user is not interested at all at its implmentation.

You can think the context provides the "object"/instance where some
operations are done - this is alike in object oriented programming,
where the context corresponds to the self, so that you create/allocate
the object, initialize it, and invoke operations on the object.

So using this analogy, the example would be:

struct UpperCasePrinterContext {...};

// this corresponds to a "method" defined on the context/object
void uppercase_printer_print(UpperCasePrinterContext *ctx, const char *str);

Or maybe you want to define the property in the context itself, so you
do:
uppercase_ctx.str = "foobar";

then you have:
void uppercase_printer_print(UpperCasePrinterContext *ctx);

On a typical FFmpeg context you typically do (see
doc/examples/encode.c example):
    // create the context
    c = avcodec_alloc_context3(codec);

    // set parameters, either in the context or by using the av_opt API
    c->bit_rate = 400000;
    c->width = 352;
    c->height = 288;
    c->time_base = (AVRational){1, 25};
    c->framerate = (AVRational){25, 1};
    // ...

    // invoke the methods defined in the context
    ret = avcodec_send_frame(enc_ctx, frame);
    if (ret < 0) {
        fprintf(stderr, "Error sending a frame for encoding\n");
        exit(1);
    }

    while (ret >= 0) {
        ret = avcodec_receive_packet(enc_ctx, pkt);
        if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
            return;
        else if (ret < 0) {
            fprintf(stderr, "Error during encoding\n");
            exit(1);
        }
        ...
        av_packet_unref(pkt);
    }

[...]

Note also that "context" in the FFmpeg jargon is not very specific
because it might be different depending on the implementation, for
example it might not have an av_opt_* interface (for example
libavutil/hash.h).

> +```
> +

> +The `UpperCasePrinterContext` object contains the information that's about
> +the context of the current job (i.e. printing things to standard output).

I find this confusing, it is essentially saying that the context (the
"object") is the context of the current job.

> +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,

Can it? The X264Context is defined within the implementation, so it is
not exposed to the user, the only way to set it is through the private
options to be set through the AVCodecContext options through the
av_opt API - in other words you cannot set the context directly as you
do with the "generic" options defined in the AVCodecContext.

> it is not part of the public interface, so new releases can modify
> it without affecting the API version.

[...]