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

[Paul B Mahol]

On Wed, May 29, 2024 at 12:50 PM Andrew Sayers <ffmpeg-devel at pileofstuff.org>
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.
>
> 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"?
>

ffmpeg is cli tool

libavfilter is library

AVOptions is certainly and primarily not framework for command-line options.


>
> [1] https://ffmpeg.org/doxygen/trunk/structSwrContext.html
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request at ffmpeg.org with subject "unsubscribe".
>