From: Andrew Sayers <ffmpeg-devel@pileofstuff.org> To: FFmpeg development discussions and patches <ffmpeg-devel@ffmpeg.org> Subject: Re: [FFmpeg-devel] [PATCH v4 1/4] doc: Explain what "context" means Date: Sun, 26 May 2024 13:06:52 +0100 Message-ID: <ZlMl3KTC36clwgIT@andrews-2024-laptop.sayers> (raw) In-Reply-To: <ZlG0PEPmYGJ18B8c@mariano> It feels like we've got through most of the mid-level "how FFmpeg works" stuff, and now we're left with language choices (e.g "options" vs. "introspection") and philosophical discussions (e.g. the relationship between contexts and OOP). It's probably best to philosophise first, then come back to language. This message has been sent as a reply to one specific message, but is actually springboarding off messages from two sub-threads. Hopefully that will keep the big questions contained in one place. On Sat, May 25, 2024 at 11:49:48AM +0200, Stefano Sabatini wrote: > What perplexes me is that "context" is not part of the standard OOP > jargon, so this is probably adding more to the confusion. This actually speaks to a more fundamental issue about how we learn. To be clear, everything I'm about to describe applies every human that ever lived, but starting with this message makes it easier to explain (for reasons that will hopefully become obvious). When you ask why "context" is not part of OOP jargon, one could equally ask why "object" isn't part of FFmpeg jargon. The document hints at some arguments: their lifetime stages are different, their rules are enforced at the language vs. community level, OOP encourages homogenous interfaces while FFmpeg embraces unique interfaces that precisely suit each use case, and so on. But the honest answer is much simpler - humans are lazy, and we want the things we learn today to resemble the things we learnt yesterday. Put another way - if we had infinite time every day, we could probably write an object-oriented interface to FFmpeg. But our time is sadly finite so we stick with the thing that's proven to work. Similarly, if our readers had infinite free time every day, they could probably learn a completely new approach to programming. But their time is finite, so they stick to what they know. That means people reading this document aren't just passively soaking up information, they're looking for shortcuts that fit their assumptions. And as anyone that's ever seen a political discussion can tell you, humans are *really good* at finding shortcuts that fit their assumptions. For example, when an OOP developer sees the words "alloc" and "init", they will assume these map precisely to OOP allocators and initializers. One reason for the long section about context lifetimes is because it needs to meet them where they are, then walk them step-by-step to a better place. 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. 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. For sake of argument, let's imagine a user who was a world-leading expert in Microsoft QBasic in the eighties, then fell into a forty-year coma and woke up in front of the FFmpeg documentation. In other words, a highly adept programmer with zero knowledge of programming conventions more recent than "a function is a special type of subroutine for returning a value". Their journey might look like... 1. there's this thing called "context", and some functions "have" contexts 2. sws_init_context() says "Initialize the swscaler context sws_context", and `sws_context` is a `SwsContext *`, so I think it has a SwsContext context 3. sws_alloc_context() says "Allocate an empty SwsContext", and it returns a `SwsContext *`, so I think it has the same context as sws_init_context() 4. avio_alloc_context() and avio_open2() are both variations on this theme, so I should look for creative ways to interpret things as "having" contexts 5. av_alloc_format_context() puts the type in the middle of the function name, so I should only treat prefixes as a weak signal 6. av_ambient_viewing_environment_create_side_data() allocates like an alloc, so I think the return value is the context; but it also operates on AVFrame in a way that affects related functions, so I think the arg is the context. Its prefix is too a weak a signal to be a tiebreaker, so I'll just guess one of them at random and wait until something goes wrong In the above case, the interface rewarded the developer for looking harder and harder for ways to call something a context, to the point where saying "neither" becomes inconceivable (or at best an admission of defeat). There's no way to avoid that sort of inconsistency in a project like FFmpeg, and explaining the logic behind each choice would involve an order of magnitude more documentation. So the only practical choice is to present a sort of conceptual buffet - "here are several ways to think about the problem, choose whatever suits your tastes". _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".
next prev parent reply other threads:[~2024-05-26 12:07 UTC|newest] Thread overview: 84+ messages / expand[flat|nested] mbox.gz Atom feed top 2024-04-18 15:06 [FFmpeg-devel] [PATCH 1/3] " Andrew Sayers 2024-04-18 15:06 ` [FFmpeg-devel] [PATCH 2/3] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-04-18 15:06 ` [FFmpeg-devel] [PATCH 3/3] all: Link to "context" from all contexts with documentation Andrew Sayers 2024-04-20 7:25 ` [FFmpeg-devel] [PATCH 1/3] doc: Explain what "context" means Stefano Sabatini 2024-04-20 12:18 ` Andrew Sayers 2024-04-20 16:13 ` Stefano Sabatini 2024-04-20 12:19 ` [FFmpeg-devel] [PATCH v2 " Andrew Sayers 2024-04-20 12:19 ` [FFmpeg-devel] [PATCH v2 2/3] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-04-20 12:19 ` [FFmpeg-devel] [PATCH v2 3/3] all: Link to "context" from all contexts with documentation Andrew Sayers 2024-04-20 16:48 ` [FFmpeg-devel] [PATCH v2 1/3] doc: Explain what "context" means Stefano Sabatini 2024-04-20 22:17 ` Andrew Sayers 2024-04-22 8:02 ` Stefano Sabatini 2024-04-22 15:56 ` [FFmpeg-devel] [PATCH v3 0/3] all: Link to "context" from all contexts with documentation Andrew Sayers 2024-04-22 15:56 ` [FFmpeg-devel] [PATCH v3 1/3] doc: Explain what "context" means Andrew Sayers 2024-04-22 17:05 ` Stefano Sabatini 2024-04-29 9:10 ` Andrew Sayers 2024-05-02 10:03 ` Andrew Sayers 2024-05-05 7:29 ` Stefano Sabatini 2024-05-05 21:04 ` Andrew Sayers 2024-05-22 10:37 ` Stefano Sabatini 2024-05-22 12:47 ` Andrew Sayers 2024-05-25 9:00 ` Stefano Sabatini 2024-04-29 9:24 ` [FFmpeg-devel] [PATCH v4 1/4] " Andrew Sayers 2024-04-29 9:24 ` [FFmpeg-devel] [PATCH v4 2/4] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-04-29 9:24 ` [FFmpeg-devel] [PATCH v4 3/4] all: Link to "context" from all contexts with documentation Andrew Sayers 2024-05-02 11:01 ` Lynne 2024-05-02 11:14 ` Andrew Sayers 2024-05-02 13:00 ` Zhao Zhili 2024-05-02 13:27 ` Andrew Sayers 2024-05-02 13:39 ` Zhao Zhili 2024-04-29 9:24 ` [FFmpeg-devel] [PATCH v4 4/4] lavf: Add documentation for private "Context" classes Andrew Sayers 2024-05-05 8:31 ` [FFmpeg-devel] [PATCH v4 1/4] doc: Explain what "context" means Andreas Rheinhardt 2024-05-05 10:34 ` Andrew Sayers 2024-04-22 15:56 ` [FFmpeg-devel] [PATCH v3 2/3] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-04-22 15:56 ` [FFmpeg-devel] [PATCH v3 3/3] all: Link to "context" from all contexts with documentation Andrew Sayers 2024-05-15 15:54 ` [FFmpeg-devel] [PATCH v4 0/4] Explain what "context" means Andrew Sayers 2024-05-15 15:54 ` [FFmpeg-devel] [PATCH v4 1/4] doc: " Andrew Sayers 2024-05-22 9:31 ` Stefano Sabatini 2024-05-22 16:07 ` Andrew Sayers 2024-05-25 9:49 ` Stefano Sabatini 2024-05-26 12:06 ` Andrew Sayers [this message] 2024-05-28 17:24 ` Stefano Sabatini 2024-05-29 10:10 ` Andrew Sayers 2024-05-29 10:50 ` Andrew Sayers 2024-05-29 11:06 ` Paul B Mahol 2024-05-29 14:18 ` Andrew Sayers 2024-05-29 16:06 ` Stefano Sabatini 2024-05-23 20:00 ` [FFmpeg-devel] [PATCH v5 0/4] " Andrew Sayers 2024-05-23 20:00 ` [FFmpeg-devel] [PATCH v5 1/4] doc: " Andrew Sayers 2024-05-25 11:00 ` Stefano Sabatini 2024-05-23 20:00 ` [FFmpeg-devel] [PATCH v5 2/4] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-05-25 9:57 ` Stefano Sabatini 2024-05-23 20:00 ` [FFmpeg-devel] [PATCH v5 3/4] all: Link to "context" from all public contexts with documentation Andrew Sayers 2024-05-23 20:00 ` [FFmpeg-devel] [PATCH v5 4/4] all: Rewrite documentation for contexts Andrew Sayers 2024-05-24 1:50 ` [FFmpeg-devel] [PATCH v5 0/4] Explain what "context" means Michael Niedermayer 2024-05-24 9:43 ` Andrew Sayers 2024-05-15 15:54 ` [FFmpeg-devel] [PATCH v4 2/4] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-05-22 10:04 ` Stefano Sabatini 2024-05-15 15:54 ` [FFmpeg-devel] [PATCH v4 3/4] all: Link to "context" from all contexts with documentation Andrew Sayers 2024-05-15 16:46 ` Lynne via ffmpeg-devel 2024-05-16 11:25 ` Andrew Sayers 2024-05-15 15:54 ` [FFmpeg-devel] [PATCH v4 4/4] lavf: Add documentation for private "Context" classes Andrew Sayers 2024-05-22 10:08 ` Stefano Sabatini 2024-05-22 14:47 ` Andrew Sayers 2024-05-22 15:24 ` Andreas Rheinhardt 2024-05-22 16:54 ` Andrew Sayers 2024-06-04 14:47 ` [FFmpeg-devel] [PATCH v6 0/4] doc: Explain what "context" means Andrew Sayers 2024-06-04 14:47 ` [FFmpeg-devel] [PATCH v6 1/4] " Andrew Sayers 2024-06-05 8:15 ` Anton Khirnov 2024-06-12 20:52 ` Stefano Sabatini 2024-06-13 14:20 ` Andrew Sayers 2024-06-15 9:17 ` Stefano Sabatini 2024-06-16 18:02 ` [FFmpeg-devel] Development process for explaining contexts (was Re: [PATCH v6 1/4] doc: Explain what "context" means) Andrew Sayers 2024-06-16 21:20 ` Paul B Mahol 2024-07-01 22:16 ` Stefano Sabatini 2024-07-02 9:56 ` Andrew Sayers 2024-07-06 11:33 ` Stefano Sabatini 2024-06-04 14:47 ` [FFmpeg-devel] [PATCH v6 2/4] lavu: Clarify relationship between AVClass, AVOption and context Andrew Sayers 2024-06-05 10:34 ` Stefano Sabatini 2024-06-05 12:46 ` Andrew Sayers 2024-06-04 14:47 ` [FFmpeg-devel] [PATCH v6 3/4] all: Link to "context" from all public contexts with documentation Andrew Sayers 2024-06-05 8:12 ` Anton Khirnov 2024-06-05 12:51 ` Andrew Sayers 2024-06-04 14:47 ` [FFmpeg-devel] [PATCH v6 4/4] all: Rewrite documentation for contexts Andrew Sayers
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=ZlMl3KTC36clwgIT@andrews-2024-laptop.sayers \ --to=ffmpeg-devel@pileofstuff.org \ --cc=ffmpeg-devel@ffmpeg.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Git Inbox Mirror of the ffmpeg-devel mailing list - see https://ffmpeg.org/mailman/listinfo/ffmpeg-devel This inbox may be cloned and mirrored by anyone: git clone --mirror https://master.gitmailbox.com/ffmpegdev/0 ffmpegdev/git/0.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 ffmpegdev ffmpegdev/ https://master.gitmailbox.com/ffmpegdev \ ffmpegdev@gitmailbox.com public-inbox-index ffmpegdev Example config snippet for mirrors. AGPL code for this site: git clone https://public-inbox.org/public-inbox.git