[FFmpeg-devel] [PATCH v5 0/4] Explain what "context" means

[Andrew Sayers]

NOTE: this patchset depends on [1], and should not be applied before that.

I think it's important to guide readers between parts of FFmpeg, because
learning how the pieces of the puzzle fit together is a big part of the
newbie experience.  So this patchset replaces the "@ref Context for foo"
statements in public structs with "@see" blocks, giving us a hook we can
hang more links on in future.

That said, there's a rule against internal links from private structs,
so I've removed the @ref's from them.  By the way, is this rule written
somewhere?  If not, where would be a good place to write it?
And either way, it would be good to link to this as part of [2].

Previous patches had to change the language for many structs, but "@see" blocks
avoid the need to include those changes in this patchset.  Rather than waste
that work, I've temporarily moved those changes to the final patch in this set.
My feelings about that last patch aren't strong, but I guess I'll propose them
in a separate thread unless anyone wants them here or chucked altogether.


I've rewritten AVOptions and AVClass based on feedback.  The new version
reflects a hypothetical that's been going round my head all week...

Imagine you wanted to write a system that nudged people to try new codecs.
It might say e.g. "you seem to be using H.264, would you like to try H.265?"
Implementing that would probably involve a struct like:

struct AVOldNew {
  AVClass* old;
  AVClass* new;
};

That's a struct that begins with an AVClass*, but is clearly not an AVClass
context structure.  So the new version defines "AVClass context structure" and
"AVOptions-enabled struct" in terms of the way the structs are used instead of
their layout, which should be more useful and accurate to current practice,
while remaining compatible(ish) with the way the words are used in conversation.


I mentioned hwaccels in a previous message.  From another look around the code,
I think these are supposed to be completely invisible to an external API dev.
If not, please point me in the direction of any documentation I missed.

[1] https://ffmpeg.org/pipermail/ffmpeg-devel/2024-May/327958.html
[2] https://ffmpeg.org/pipermail/ffmpeg-devel/2024-May/327624.html