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

[Andrew Sayers]

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.

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


*Are AVOptions just command-line options?*

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.

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"?

[1] https://ffmpeg.org/doxygen/trunk/structSwrContext.html