[FFmpeg-devel] [PATCH v6 3/4] all: Link to "context" from all public contexts with documentation

[Andrew Sayers]

Note: I somehow managed to send this message directly to Anton before - sorry
Anton for the message spam, please reply to this one if you want the list to
see it!

On Wed, Jun 05, 2024 at 10:12:47AM +0200, Anton Khirnov wrote:
> Quoting Andrew Sayers (2024-06-04 16:47:23)
> > The goal of putting these links in "@see" blocks is to provide hooks
> > for future developers to add links to other useful parts of the codebase.
> > ---
> >  libavcodec/avcodec.h             | 3 +++
> >  libavcodec/bsf.h                 | 3 +++
> >  libavcodec/d3d11va.h             | 3 +++
> >  libavcodec/mediacodec.h          | 2 ++
> >  libavcodec/qsv.h                 | 3 +++
> >  libavcodec/vdpau.h               | 3 +++
> >  libavcodec/videotoolbox.h        | 3 +++
> >  libavfilter/avfilter.h           | 7 ++++++-
> >  libavformat/avformat.h           | 3 +++
> >  libavformat/avio.h               | 3 +++
> >  libavutil/audio_fifo.h           | 3 +++
> >  libavutil/hwcontext.h            | 6 ++++++
> >  libavutil/hwcontext_cuda.h       | 3 +++
> >  libavutil/hwcontext_d3d11va.h    | 6 ++++++
> >  libavutil/hwcontext_d3d12va.h    | 6 ++++++
> >  libavutil/hwcontext_drm.h        | 3 +++
> >  libavutil/hwcontext_dxva2.h      | 6 ++++++
> >  libavutil/hwcontext_mediacodec.h | 3 +++
> >  libavutil/hwcontext_opencl.h     | 6 ++++++
> >  libavutil/hwcontext_qsv.h        | 6 ++++++
> >  libavutil/hwcontext_vaapi.h      | 6 ++++++
> >  libavutil/hwcontext_vdpau.h      | 3 +++
> >  libavutil/hwcontext_vulkan.h     | 6 ++++++
> >  libavutil/lfg.h                  | 3 +++
> >  24 files changed, 98 insertions(+), 1 deletion(-)
> 
> IMO this is pointless churn.

That's like saying caches are pointless bloat - it's not about correctness,
it's about performance.  Actually, I've been talking about "performance" a lot
round here, but not really explained what I mean...

Imagine a smart young developer who learned C at university and is now dipping
their toe in the world of actual C development.  They've come up with an idea
for a little app that's different enough from the examples to force themselves
not to just copy/paste example code.  It's simple enough that an experienced
developer like you would only need half a day for the whole project, so they
allow themselves a weekend to get it done.   "Performance" in this case means
"can they finish the project in their ~16 hour time budget?"

Assuming they're half as productive as you would be, 8 of their 16 hours go on
programming, leaving 8 hours to learn FFmpeg.

They've never written real-world C before, so they don't know what a context is.
And they only have a narrow understanding of OOP, so as soon as they see words
like "object" and "class", they assume you're referring to the precise version
of OOP their Java lecturer taught them about.  So the longer they spend poking
round looking for information, the more misconceptions they're going to develop.
Even if we assume they find the context document after one hour of searching,
they fully understand the document with no reading time, and only need one
extra hour to unlearn the misconceptions they developed, that's still cost
a quarter of their remaining time budget.

To an expert, these links are unnecessary verbiage pointing to a document
that explains things that are blindingly obvious.  But to a newbie, they're
an important optimisation that can make the difference between finishing
a project or having to give up on FFmpeg altogether.