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 D29364AF0B for ; Thu, 23 May 2024 20:01:49 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 7A31268D4B6; Thu, 23 May 2024 23:01:46 +0300 (EEST) Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id B236268D274 for ; Thu, 23 May 2024 23:01:39 +0300 (EEST) Received: from 0.b.4.b.7.4.0.8.c.4.a.5.d.8.b.2.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:2b8d:5a4c:8047:b4b0] helo=andrews-2024-laptop.lan) by painless-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1sAEd8-002Q1U-2z for ffmpeg-devel@ffmpeg.org; Thu, 23 May 2024 21:01:39 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Thu, 23 May 2024 21:00:39 +0100 Message-ID: <20240523200116.740461-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: References: MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v5 0/4] 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: 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 _______________________________________________ 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".