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 0D519499AD for ; Sat, 25 May 2024 09:00:22 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id ADF8F68D4F4; Sat, 25 May 2024 12:00:19 +0300 (EEST) Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D55A968D4A5 for ; Sat, 25 May 2024 12:00:13 +0300 (EEST) Received: by mail-wr1-f41.google.com with SMTP id ffacd0b85a97d-35508106cc2so1318843f8f.2 for ; Sat, 25 May 2024 02:00:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1716627612; x=1717232412; darn=ffmpeg.org; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:to:from:date:from:to:cc:subject :date:message-id:reply-to; bh=557Qn/WVnG7sw7O+BmvIdECIwn5f3eWZ9Ammq1qK4Ew=; b=VjslQ7OYvvworAXPP1GBpQ9O8EAV+vk8E17xzZHh3UyDRNPxQNh/v9bHTmkB2/j6Ed iyIg7t8++xeFsu936todbeuPGv0YOcCwjZDPBYEBi8BxIOU95x83QHtZyvXhMI53+vde d7E0Vqyfzs6pe4ReSaX27Ri+SkbOuxU7I0e0kJtnUUzCCfk/8/sMlcDX3tlOFfx0tRYY oBEgYtBy6Co4teZU7absWhxAMpaeNXV4OoCNQg6Zfw3lsnKs+smpH223Ca3pHGqC3c8X 2ipd0S8R9mSPhtyHETD9K780jiFWhJrgP0EZUu4QwNDOGksLmG72ZBmeAWYwu+r+WWax krKA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1716627612; x=1717232412; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:to:from:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=557Qn/WVnG7sw7O+BmvIdECIwn5f3eWZ9Ammq1qK4Ew=; b=DRYdjE6XouqER2gkVVH4JLbEUBfyiwu0LPpFyVSLzipD0OC1sSv+C9FLplf3e7f7LG PaKUKLAp31N/Bw1TyhCxFq2Tj8PrlxDqY6pNRX/hlgCOnG4RkstEAuEeIkD3HMFgMKzO RmBURwJQXTGGVbgdW2zATMf+xZC6p2tVhgvNrWnwaPkJTJ6AIz2HOU19KApVxTdddQ1J 0y9X25ZMyPZjjzcr0ltddaaQdc8Zv9rRu5iA12Z6SxD0omQjWjQ1JLQoJGJ1HGr1o5tc o9Na6PEtn7MFuZfUBQN6RDFEF7WNGol9+Orlhu70xFYJ8bR+GyemetOxQj+f+hmxpe/D 3F6w== X-Gm-Message-State: AOJu0Yy+FissbcY5eZP89CGeZJngWmKH8zXQxW/4QSZzQJyiX19gJSaQ IBqF3S0OYZ5sRCHjxDANiTQ21WztN+RBtw26we4hew8CtH/RN6NkHCAXFA== X-Google-Smtp-Source: AGHT+IHk5GkQujBJjNMWqfI8IdGnF/fM/MSz1MjJNdFCqE58EjjLxmcIB6Wspw375aQ776g5J8t9oQ== X-Received: by 2002:a5d:452c:0:b0:354:df59:c9a4 with SMTP id ffacd0b85a97d-35526c15982mr2667773f8f.9.1716627611495; Sat, 25 May 2024 02:00:11 -0700 (PDT) Received: from mariano (dynamic-adsl-84-220-189-10.clienti.tiscali.it. [84.220.189.10]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-3557a1c936esm3507101f8f.83.2024.05.25.02.00.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 25 May 2024 02:00:10 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id 1BBDDBFCE8; Sat, 25 May 2024 11:00:09 +0200 (CEST) Date: Sat, 25 May 2024 11:00:09 +0200 From: Stefano Sabatini To: FFmpeg development discussions and patches Message-ID: Mail-Followup-To: FFmpeg development discussions and patches 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: User-Agent: Mutt/2.1.4 (2021-12-11) 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 date Wednesday 2024-05-22 13:47:36 +0100, Andrew Sayers wrote: > 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). >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? av_ambient_viewing_environment_ defines the namespace. In this case we are not using the av_frame_ API since we want to have all the ambient API defined in a single place. Alternatively we might have extended the av_frame API (e.g. av_frame_create_ambient_viewing_environment_side_data()), but we wanted to avoid to reference the ambient API in the minimal frame API, so this approach makes perfect sense to me and I cannot see major inconsistencies. You can think about it in terms of a static or class constructor function, where AVFrame is simply an argument of the contructor. What is the approach that you would have expected in this 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. I see, but I still see an excessive use of the context concept in place of the simpler and more natural use of parameters (in this case AVFrame is simply the input element), and this scheme is pretty common in C APIs (note that ambient is a simple structure, no need to use AVClass or options for this simple struct), so I see no need to tag this as an edge case. _______________________________________________ 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".