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

[Stefano Sabatini]

On date Wednesday 2024-05-29 11:50:40 +0100, Andrew Sayers wrote:
> Posting this separately, as these are practical "how does FFmpeg work" issues
> vaguely inspired by recent discussions.
> 
> 
> *How do namespaces work in FFmpeg?*
> 
> We've talked a bit about function namespaces recently.  One reason I've
> suggested they're a weak signal is because they aren't really addressed in the
> documentation.  How about adding something like this to the context doc:
> 
>     Most FFmpeg functions are grouped into namespaces, usually indicated by
>     prefixes (e.g. `av_format_*`) but sometimes indicated by infixes
>     (e.g. av_alloc_format_context()).  Namespaces group functions by *topic*,
>     which doesn't always correlate with *context*.  For example, `av_find_*`
>     functions search for information across various contexts.
> 
> 
> *Should external API devs treat Sw{r,s}Context as AVClass context structures?*
> 
> This is probably an uninteresting edge case, but just to be sure...
> 

> The website says Sw{r,s}Context start with AVClass[1], they have _get_class
> functions, are shown in `ffmpeg -h full`, and I haven't found anything that says
> to treat them differently to e.g. AVCodecContext.  So I'm pretty sure these
> are AVClass context structures, at least as far as internal devs are concerned.

It impacts the user as this changes the API. I guess when AVClass was
removed from AVFrame that was done with a major bump to advertise an
API break.

> But their definitions are only in the private interface, so the layout is just
> an implementation detail that can change without even a major version bump.
> AVFrame used to have a _get_class function despite never having an actual
> AVClass member, so that's not a signal to external API devs.  And `URLContext`
> appears in `ffmpeg -h full` despite having being made private long ago,
> so that's not much of a signal either.
> 
> My guess is that the above should be addressed with a patch like:
> 
> +/**
> + * @brief Context for SWResampler
> + *

> + * @note The public ABI only guarantees this is an AVOptions-enabled struct.
> + * Its size and other members are not a part of the public ABI.

This looks redundant to me, this is true for all the opaque structus,
and we don't want to repeat this again and again (this is a feature of
the C language, not of the API itself).

> + *
> + * @see
> + * - @ref Context
> + */
>  struct SwrContext {
> 
> Let me know if the above is on the right track.  If so, I'll queue up a patch
> for after the context document is done.

Better to treat this as a separate patch anyway.
 
> *Are AVOptions just command-line options?*

No, in fact this is not about comman-line options at all.

> 
> I have trouble with statements like "AVOptions is a framework for options",
> both because it's circular and because the term "option" is too broad to be
> meaningful.

AVOptions (or better the av_opt API) is a system to set
fields/properties/options on an enabled struct. This is a high level
API since it allows multiple options setting, validation, setting
from a dictionary etc., and enables to abstract the struct field name
(since the option names might be different from the field name).

> 
> I've previously pushed the word "reflection" on the assumption that options
> can be used anywhere variables are used.  For example, imagine a decoder that
> could be reconfigured on-the-fly to reduce CPU usage at the cost of displaying
> blurier images.  That can't be part of the public interface because it's
> codec-specific, but I could imagine updating some kind of "output_quality"
> AVOption as a user slides a slider up and down.
> 
> But the CLI tools are largely non-interactive, so have I just misunderstood?
> 
> How about saying "AVOptions is a framework for command-line options"?

It is not about CLI options, although you can use introspection to get
the supported options and build an interface to set them.