From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 06F5F489EF for ; Wed, 22 May 2024 12:47:53 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id AFF0A68D371; Wed, 22 May 2024 15:47:50 +0300 (EEST) Received: from b-painless.mh.aa.net.uk (b-painless.mh.aa.net.uk [81.187.30.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id C228268CF9D for ; Wed, 22 May 2024 15:47:43 +0300 (EEST) Received: from d.d.4.7.5.a.7.e.a.b.5.5.d.2.9.3.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:392d:55ba:e7a5:74dd] helo=andrews-2024-laptop.sayers) by painless-b.tch.aa.net.uk with smtp (Exim 4.96) (envelope-from ) id 1s9lNf-00DsuM-06 for ffmpeg-devel@ffmpeg.org; Wed, 22 May 2024 13:47:43 +0100 Date: Wed, 22 May 2024 13:47:36 +0100 From: Andrew Sayers To: FFmpeg development discussions and patches Message-ID: References: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> <20240422155836.385333-2-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Subject: Re: [FFmpeg-devel] [PATCH v3 1/3] doc: Explain what "context" means X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: On Wed, May 22, 2024 at 12:37:37PM +0200, Stefano Sabatini wrote: > On date Sunday 2024-05-05 22:04:36 +0100, Andrew Sayers wrote: > > I'm still travelling, so the following thoughts might be a bit > > half-formed. But I wanted to get some feedback before sitting down > > for a proper think. > [...] > > > > I've also gone through the code looking for edge cases we haven't covered. > > > > Here are some questions trying to prompt an "oh yeah I forgot to mention > > > > that"-type answer. Anything where the answer is more like "that should > > > > probably be rewritten to be clearer", let me know and I'll avoid confusing > > > > newbies with it. > > > > > > > > > > > av_ambient_viewing_environment_create_side_data() takes an AVFrame as its > > > > first argument, and returns a new AVAmbientViewingEnvironment. What is the > > > > context object for that function - AVFrame or AVAmbientViewingEnvironment? > > > > > > But this should be clear from the doxy: > > > > > > /** > > > * Allocate and add an AVAmbientViewingEnvironment structure to an existing > > > * AVFrame as side data. > > > * > > > * @return the newly allocated struct, or NULL on failure > > > */ > > > AVAmbientViewingEnvironment *av_ambient_viewing_environment_create_side_data(AVFrame *frame); > > > > I'm afraid it's not clear, at least to me. I think you're saying the > > AVFrame is the context because a "create" function can't have a > > context any more than a C++ "new" can be called as a member. But the > > function's prefix points to the other conclusion, and neither signal > > is clear enough on its own. > > No, what I'm saying is that in some cases you don't need to think in > terms of contexts, in this case there is no context at all, the > function takes a frame and modify it, and returns the ambient > environment to be used by the following functions. This should be very > clear by reading the doxy. There is no rule dictating the first param > of each FFmpeg function should be a "context". I'm still writing up a reply to your longer feedback, but on this topic... This function is in the "av_ambient_viewing_environment" namespace, and returns an object that is clearly used as a context for other functions. So saying "stop thinking about contexts" just leaves a negative space and a bad thing to fill it with (confusion in my case). I've found it useful to think about "receiving" vs. "producing" a context: * avcodec_alloc_context3() produces a context, but does not receive one * sws_init_context() receives a context, but does not produce one * av_ambient_viewing_environment_create_side_data() receives one context, and produces another How about if the document mostly talks about functions as having contexts, then follows it up with something like: There are some edge cases where this doesn't work. . If you find contexts a useful metaphor in these cases, you might prefer to think about them as "receiving" and "producing" contexts. ... or something similar that acknowledges contexts are unnecessary here, but provides a solution for people that want to use them anyway. _______________________________________________ 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".