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

[Andrew Sayers]

On Tue, May 28, 2024 at 07:24:55PM +0200, Stefano Sabatini wrote:
> 
> I think we start with different assumptions: you assume that most of
> the readers are familiar with OOP jargon, and that they will leverage
> the OOP jargon to understand the FFmpeg API. I think this is

Not exactly.  I'm saying the document has two equally valid use cases:

1. non-OOP developers, who need us to add new information to their brains
2. OOP developers, who need us to replace existing information in their brains

So it's not a matter of "leveraging OOP" jargon so much as "calling out
OOP assumptions".  For example, I originally assumed AVClass was to FFmpeg
as the Object struct[1] is to GObject, and struggled to take anything onboard
until that been explicitly debunked.  You may even be able to see that
opinion gradually eroding in each rewrite of the context document.

But actually, two groups is probably over-simplifying.  Another group would be
people coming from other C projects, who have incompatible ideas about contexts
that would never occur to us.  Or Fortran developers, who (according to the
first link on Google[2]) can be expected to understand modules but not objects.

> misleading: historically what defined FFmpeg is its minimalistic
> approach, in this case we don't want the user, familiar with C, to be
> familiar with OOP in order to use and understand the FFmpeg API, as
> this is simply not necessary as FFmpeg is plain C language.
> 
> In fact, if this might help with some users, this will probably
> confuse all the others. Even more, if we adopt the FFmpeg jargon to
> OOP (using "context") we are adding more confusion, as now the OOP
> reader will have to adopt the FFmpeg jargon applied to OOP.
> 
> My advice is to move all the content to OOP to a dedicated section, or
> to make the references to OOP jargon as less as possible, to not get
> in the way with the non-OOP reader.

Earlier versions of the document probably drew too strong an analogy with OOP,
but I suspect the problem may be simpler in the latest draft.  The majority of
OOP references explain how things are different to OOP - it might be possible
to make these more readable, but they can't be moved or removed, because
replacing information involves calling out the old information first.  Only the
first few OOP references draw the analogy in the positive, aiming to show OOP
devs how this is similar but different.

Given the OOP vs. non-OOP distinction is too simplistic, the solution might be
to start the document with a collection of code samples - a generic C function,
a Python object, a JavaScript event listener, and an FFmpeg sample.  That would
show how "context" is a name for a broad concept you've probably used before,
without singling out OOP.  It would also reinforce the idea of the document as
a buffet of concepts - don't like the OOP example?  Never mind, here are some
procedural ones for you to enjoy.

> 
> > Aside: if FFmpeg had a blog, I could turn this discussion into a great post
> > called something like "reflections on object- vs. context-oriented development".
> > But the project's voice is more objective than that, so this document is limited
> > to discussing the subset of issues that relate specifically to the FFmpeg API.
> 
> One option would be the wiki:
> http://trac.ffmpeg.org/
> 
> but probably a personal blog entry would be better, given that this
> would not be reference material but more as an article (since the API
> and its own philosophy is a moving target).
> 
> > 
> > On Sat, May 25, 2024 at 01:00:14PM +0200, Stefano Sabatini wrote:
> > > > +Some functions fit awkwardly within FFmpeg's context idiom.  For example,
> > > > +av_ambient_viewing_environment_create_side_data() creates an
> > > > +AVAmbientViewingEnvironment context, then adds it to the side-data of an
> > > > +AVFrame context.
> > > 
> > > To go back to this unfitting example, can you state what would be
> > > fitting in this case?
> > 
> > "Awkwardly" probably isn't the right word to use, but that's a language choice
> > we can come back to.
> > 
> > The problem with FFmpeg's interface isn't that any one part is illogical,
> > it's that different parts of the interface follow incompatible logic.
> > 
> > It's hard to give specific examples, because any given learner's journey looks
> > like a random walk through the API, and you can always say "well nobody else
> > would have that problem".  But if everyone has a different problem, that means
> > everyone has *a* problem, even though there's no localised code fix.
> 
> Fine, but can you propose the signature of the functions that you
> would consider optimal in this case?

I think we largely agree on this, but since you ask -

The code solution would be to pick a rule and rewrite the entire codebase to
fit that rule.  I don't have a strong opinion about what the rule is, but one
example might be "the first context parameter to a function must be that
function's context", which I guess would mean renaming this to something like
"av_frame_create_ambient_viewing_environment_side_data()".  That would be a
huge amount of work to implement, and even more work to maintain, so yes it's
fine to just document it and move on.

> One option I suggested is to move the function to frame.h, but this
> would have other implications (that's why keeping as is looks to me
> like a reasonable tradeoff - you can consider it as a sort of static
> class method if you like).

That's fine for this example, but interesting in other ways.

I'm increasingly reading the API in terms of what signals different parts of it
emit.  For example, if a function ends with "_alloc", that signals it's probably
an allocator, but av_max_alloc() doesn't allocate `max`es, so that signal's
information value is less than 1.  I think you're saying the location of a
function is an important signal - what sort of things does it tell you?

[...]

[1] https://docs.gtk.org/gobject/class.Object.html
[2] https://fortranwiki.org/fortran/show/Object-oriented+programming