From patchwork Thu May 23 20:00:39 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 35131 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:542:0:b0:460:55fa:d5ed with SMTP id 63csp1292058vqf; Thu, 23 May 2024 13:01:51 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCWfIBYfSigi849+/0j26h0BSf0v6bBkk23Hu6qga2DfGTvOYjiLL4FgpnPMXZd0AWyOaVM34f2It5nUKB2NcSj458sfFbhFWRLWVg== X-Google-Smtp-Source: AGHT+IEyBhL1DKJt4m5cm3JxVfR3Z955YaZ/GUk3HvTdh9Upt2h3MSrGRRA9g4Qy8EnkpdmEP4XZ X-Received: by 2002:a50:aad2:0:b0:578:4cb1:bcdb with SMTP id 4fb4d7f45d1cf-578519b29a3mr237658a12.33.1716494511070; Thu, 23 May 2024 13:01:51 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1716494511; cv=none; d=google.com; s=arc-20160816; b=Glrlsk4oio3nVjoUdLtx3W/9ydjsZVHV05CsZo5ofmEP4oXO2I3sQCbGD8IbFYuKvE qHoUK56+2lEjK3Sfrc26lXd9e83pBhDrluwT12/R37uBi6eYxMTih9GGHrvpOgjBZuQE eoV+Y9iDb15HtEzwojcHfjNKaGPluktKOfkqyuNu/jFIpzqHed8Vo4MWmjdujz0+Tg1u 1RQ3Z3bXbvYxJHIw5wIZb0OhzYJq00irSVCq9yyGEUmDUOJpHk2PE6YZvi3ExbD41f1K yE8nCFTb0SzZImVp2dxTSDB1D9c7HTc12UYxwEMkANA/yyGirFOknKRc4PhIIK05M5ja Kc7w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:references:in-reply-to:message-id :date:to:from:delivered-to; bh=4mg+vytBBLFKyYbZbQAJio6qJpOLUqxc4o/tz0LtJCA=; fh=YOA8vD9MJZuwZ71F/05pj6KdCjf6jQRmzLS+CATXUQk=; b=VlyFhZDgCLc8UkhE5D45mM5KpMckcSSW98Q7aWf+6fg7PYUK6VaDV4ekQAFc0Ammvb Iel/sAl+Vidj99YEkQWPmpBP0yYW5pu5xQTjggVLj+tKurxEpug3mWQsqaQMJhZzYlr2 eqkJcNhVuZF6BKVK0qcN4qM8oMbC9MLWCbMMbBHlq1NTMuolbWfLrrrQnNv6TQ+Sujza 0gHCc43H2uZ4rE+EfMMn5GZbUu8PoHb7fMKOBhbDooyh7tYUKNDTtQr6GJBsOR0nqsz/ VI+vI1JQEmkIUjlDeE36GIzYZKCcB98dP2pFJVz1j9lPcN5Y7WkAShdeb+ZumH7ZqIOB ib1A==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id 4fb4d7f45d1cf-57852495ea9si50885a12.450.2024.05.23.13.01.50; Thu, 23 May 2024 13:01:51 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id B778568D4DF; Thu, 23 May 2024 23:01:46 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: TcLST9rBQOZy 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