From patchwork Tue Jun 4 14:47:21 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 49550 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9183:0:b0:460:55fa:d5ed with SMTP id s3csp2743492vqg; Tue, 4 Jun 2024 07:49:51 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCUi32wh4VQDSnk132xpvyCkOh/N71qABLI/nosu6A69N0TcIg+HZW7GEJa/coiBCHzwnm4SGnuLtmiAZA+rYuCzlineMWN8lJkBzQ== X-Google-Smtp-Source: AGHT+IEfgN5LU3IFzRV+TMGVF7iZZ6iUAZ8qboZ9MQbNrM/Qhhf644oCnaiU+MrNLiIYHlEM4qr2 X-Received: by 2002:a17:906:703:b0:a55:8f2a:950d with SMTP id a640c23a62f3a-a681fc5c73amr803480366b.16.1717512590812; Tue, 04 Jun 2024 07:49:50 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717512590; cv=none; d=google.com; s=arc-20160816; b=XPduenzFEN6x6V84tkaTfeY9cF4lfUbml0oUGU3kwdCWSW+9iKpUM9UN2j/39zfvlO j4onF+uXCFIU7nfx4zbWYQZU8GhB2ofwhdtn1ZJP90qEBRAsELudeaotQdVu3AAvUDSk yBVTi7h2KGYQvzooRZI7JmXfAhpbbxE7ilnU1JohNAy9H4PrQDSyiJ0nkW1J4HHqSv9r xmqGe+KJE8MjBBmtmqSs2xVaaL9dnOoXnz0cjJSUN03BjaJ9+oWfeHiEI/4M6IO9bm+L WofySAe/R34Qval8cFXfuYVUme0dGzpB8lVqpg8vd4L2VMomvs1nCJm03Og0Lldr2cGZ Mc0w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc: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=lJw9bqT9coUCEc0KnMAVwZZAu/N0kzDHVqvUjIjR5mU=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=ZnFudDVHHJKde7n/X05D/OKbFkSRvskoWN4UAuS9r9ZWAoQ8kT50kE4QDC5+6oQNkk Ul5Udj6/5fa3snWkoAaIX3R7+XH1AoCCXadvr98S3o3lCAqn77Jn5m2nWgknsN/6i6Gx Lt5pKDfwVvbA2CSHbYKuLvotAGl3+U1K1Y7iMn9kwl27d+et2oPN8YrdLEvxDpv3yAjR PkFFk4YGU1WeHhFzh+DLgsHwtAvMGa0Kdo7LzqWEh1Wk3dXngVsVyUt/9BXqbuKpr5Ux CT92rK70NTV229bD0kdiehIH2Ojdp/cxUP/haINx+tEtxrTMM9hYrkrsz9QWdof0O+PK /gIg==; 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 a640c23a62f3a-a68f828255esi249948266b.910.2024.06.04.07.49.50; Tue, 04 Jun 2024 07:49:50 -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 9E9DF68D70F; Tue, 4 Jun 2024 17:49:38 +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 91C1C68D6BA for ; Tue, 4 Jun 2024 17:49:31 +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 1sEVTe-007B97-1v; Tue, 04 Jun 2024 15:49:31 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Tue, 4 Jun 2024 15:47:21 +0100 Message-ID: <20240604144919.213799-2-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v6 1/4] 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 Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: gipqVRlD6QH0 Derived from explanations kindly provided by Stefano Sabatini and others: https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325903.html --- doc/context.md | 430 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 430 insertions(+) create mode 100644 doc/context.md diff --git a/doc/context.md b/doc/context.md new file mode 100644 index 0000000000..bd8cb58696 --- /dev/null +++ b/doc/context.md @@ -0,0 +1,430 @@ +@page Context Introduction to contexts + +@tableofcontents + +FFmpeg uses the term “context” to refer to an idiom +you have probably used before: + +```c +// C structs often share context between functions: + +FILE *my_file; // my_file stores information about a filehandle + +printf(my_file, "hello "); // my_file provides context to this function, +printf(my_file, "world!"); // and also to this function +``` + +```python +# Python classes provide context for the methods they contain: + +class MyClass: + def print(self,message): + if self.prev_message != message: + self.prev_message = message + print(message) +``` + + +```c +// Many JavaScript callbacks accept an optional context argument: + +const my_object = {}; + +my_array.forEach(function_1, my_object); +my_array.forEach(function_2, my_object); +``` + +Be careful comparing FFmpeg contexts to things you're already familiar with - +FFmpeg may sometimes happen to reuse words you recognise, but mean something +completely different. For example, the AVClass struct has nothing to do with +[object-oriented classes](https://en.wikipedia.org/wiki/Class_(computer_programming)). + +If you've used contexts in other C projects, you may want to read +@ref Context_comparison before the rest of the document. + +@section Context_general “Context” as a general concept + +@par +A context is any data structure used by several functions +(or several instances of the same function) that all operate on the same entity. + +In the broadest sense, “context” is just a way to think about code. +You can even use it to think about code written by people who have never +heard the term, or who would disagree with you about what it means. +Consider the following snippet: + +```c +struct DualWriter { + int fd1, fd2; +}; + +ssize_t write_to_two_files( + struct DualWriter *my_writer, + uint8_t *buf, + int buf_size +) { + + ssize_t bytes_written_1 = write(my_writer->fd1, buf, buf_size); + ssize_t bytes_written_2 = write(my_writer->fd2, buf, buf_size); + + if ( bytes_written_1 != bytes_written_2 ) { + // ... handle this edge case ... + } + + return bytes_written_1; + +} + +int main() { + + struct DualWriter my_writer; + my_writer.fd1 = open("file1", 0644, "wb"); + my_writer.fd2 = open("file2", 0644, "wb"); + + write_to_two_files(&my_writer, "hello ", sizeof("hello ")); + write_to_two_files(&my_writer, "world!", sizeof("world!")); + + close( my_writer.fd1 ); + close( my_writer.fd2 ); + +} +``` + +The term “context” doesn't appear anywhere in the snippet. But `DualWriter` +is passed to several instances of `write_to_two_files()` that operate on +the same entity, so it fits the definition of a context. + +When reading code that isn't explicitly described in terms of contexts, +remember that your interpretation may differ from other people's. +For example, FFmpeg's avio_alloc_context() accepts a set of callback functions +and an `opaque` argument - even though this function guarantees to *return* +a context, it does not require `opaque` to *provide* context for the callback +functions. So you could choose to pass a struct like `DualWriter` as the +`opaque` argument, or you could pass callbacks that use `stdin` and `stdout` +and just pass a `NULL` argument for `opaque`. + +When reading code that *is* explicitly described in terms of contexts, +remember that the term's meaning is guaranteed by *the project's community*, +not *the language it's written in*. That means guarantees may be more flexible +and change more over time. For example, programming languages that use +[encapsulation](https://en.wikipedia.org/wiki/Encapsulation_(computer_programming)) +will simply refuse to compile code that violates its rules about access, +while communities can put up with special cases if they improve code quality. + +The next section will discuss what specific conventions FFmpeg developers mean +when they describe parts of their code as using “contexts”. + +@section Context_ffmpeg FFmpeg contexts + +This section discusses specific context-related conventions used in FFmpeg. +Some of these are used in other projects, others are unique to this project. + +@subsection Context_indicating Indicating context: “Context”, “ctx” etc. + +```c +// Context struct names usually end with `Context`: +struct AVSomeContext { + ... +}; + +// Functions are usually named after their context, +// context parameters usually come first and are often called `ctx`: +void av_some_function(AVSomeContext *ctx, ...); +``` + +FFmpeg struct names usually signal whether they are contexts (e.g. AVBSFContext +or AVCodecContext). Exceptions to this rule include AVMD5, which is only +identified as a context by @ref libavutil/md5.c "the functions that call it". + +Function names usually signal the context they're associated with (e.g. +av_md5_alloc() or avcodec_alloc_context3()). Exceptions to this rule include +@ref avformat.h "AVFormatContext's functions", many of which begin with +just `av_`. + +Functions usually signal their context parameter by putting it first and +naming it some variant of `ctx`. Exceptions include av_bsf_alloc(), which puts +its context argument second to emphasise it's an out variable. + +Some functions fit awkwardly within FFmpeg's context idiom, so they send mixed +signals. For example, av_ambient_viewing_environment_create_side_data() creates +an AVAmbientViewingEnvironment context, then adds it to the side-data of an +AVFrame context. So its name hints at one context, its parameter hints at +another, and its documentation is silent on the issue. You might prefer to +think of such functions as not having a context, or as “receiving” one context +and “producing” another. + +@subsection Context_data_hiding Data hiding: private contexts + +```c +// Context structs often hide private context: +struct AVSomeContext { + void *priv_data; // sometimes just called "internal" +}; +``` + +Contexts present a public interface, so changing a context's members forces +everyone that uses the library to at least recompile their program, +if not rewrite it to remain compatible. Many contexts reduce this problem +by including a private context with a type that is not exposed in the public +interface. Hiding information this way ensures it can be modified without +affecting downstream software. + +Private contexts often store variables users aren't supposed to see +(similar to an [OOP](https://en.wikipedia.org/wiki/Object-oriented_programming) +private block), but can be used for more than just access control. They can +also store information shared between some but not all instances of a context +(e.g. codec-specific functionality), and @ref Context_avoptions +"AVOptions-enabled structs" can provide user configuration options through +the @ref avoptions "AVOptions API". + +@subsection Context_lifetime Manage lifetime: creation, use, destruction + +```c +void my_function(...) { + + // Context structs are allocated then initialized with associated functions: + + AVSomeContext *ctx = av_some_context_alloc(...); + + // ... configure ctx ... + + av_some_context_init(ctx, ...); + + // ... use ctx ... + + // Context structs are closed then freed with associated functions: + + av_some_context_close(ctx); + av_some_context_free(ctx); + +} +``` + +FFmpeg contexts go through the following stages of life: + +1. allocation (often a function that ends with `_alloc`) + * a range of memory is allocated for use by the structure + * memory is allocated on boundaries that improve caching + * memory is reset to zeroes, some internal structures may be initialized +2. configuration (implemented by setting values directly on the context) + * no function for this - calling code populates the structure directly + * memory is populated with useful values + * simple contexts can skip this stage +3. initialization (often a function that ends with `_init`) + * setup actions are performed based on the configuration (e.g. opening files) +5. normal usage + * most functions are called in this stage + * documentation implies some members are now read-only (or not used at all) + * some contexts allow re-initialization +6. closing (often a function that ends with `_close()`) + * teardown actions are performed (e.g. closing files) +7. deallocation (often a function that ends with `_free()`) + * memory is returned to the pool of available memory + +This can mislead object-oriented programmers, who expect something more like: + +1. allocation (usually a `new` keyword) + * a range of memory is allocated for use by the structure + * memory *may* be reset (e.g. for security reasons) +2. initialization (usually a constructor) + * memory is populated with useful values + * related setup actions are performed based on arguments (e.g. opening files) +3. normal usage + * most functions are called in this stage + * compiler enforces that some members are read-only (or private) + * no going back to the previous stage +4. finalization (usually a destructor) + * teardown actions are performed (e.g. closing files) +5. deallocation (usually a `delete` keyword) + * memory is returned to the pool of available memory + +The remainder of this section discusses FFmpeg's differences from OOP, to help +object-oriented programmers avoid misconceptions. You can safely skip this +section if you aren't familiar with the OOP lifetime described above. + +FFmpeg's allocation stage is broadly similar to the OOP stage of the same name. +Both set aside some memory for use by a new entity, but FFmpeg's stage can also +do some higher-level operations. For example, @ref Context_avoptions +"AVOptions-enabled structs" set their AVClass member during allocation. + +FFmpeg's configuration stage involves setting any variables you want before +you start using the context. Complicated FFmpeg structures like AVCodecContext +tend to have many members you *could* set, but in practice most programs set +few if any of them. The freeform configuration stage works better than bundling +these into the initialization stage, which would lead to functions with +impractically many parameters, and would mean each new option was an +incompatible change to the API. One way to understand the problem is to read +@ref Context_avoptions "the AVOptions section below" and think how a constructor +would handle those options. + +FFmpeg's initialization stage involves calling a function that sets the context +up based on your configuration. + +FFmpeg's first three stages do the same job as OOP's first two stages. +This can mislead object-oriented developers, who expect to do less work in the +allocation stage, and more work in the initialization stage. To simplify this, +most FFmpeg contexts provide a combined allocator and initializer function. +For historical reasons, suffixes like `_alloc`, `_init`, `_alloc_context` and +even `_open` can indicate the function does any combination of allocation and +initialization. + +FFmpeg's "closing" stage is broadly similar to OOP's "finalization" stage, +but some contexts allow re-initialization after finalization. For example, +SwrContext lets you call swr_close() then swr_init() to reuse a context. +Be aware that some FFmpeg functions happen to use the word "finalize" in a way +that has nothing to do with the OOP stage (e.g. av_bsf_list_finalize()). + +FFmpeg's "deallocation" stage is broadly similar to OOP, but can perform some +higher-level functions (similar to the allocation stage). + +Closing functions usually end with "_close", while deallocation +functions usually end with "_free". Very few contexts need the flexibility of +separate "closing" and "deallocation" stages, so many "_free" functions +implicitly close the context first. + +@subsection Context_avoptions Configuration options: AVOptions-enabled structs + +The @ref avoptions "AVOptions API" is a framework to configure user-facing +options, e.g. on the command-line or in GUI configuration forms. + +To understand FFmpeg's configuration requirements, run `ffmpeg -h full` on the +command-line, then ask yourself how you would implement all those options +with the C standard [`getopt` function](https://en.wikipedia.org/wiki/Getopt). +You can also ask the same question for other approaches - for example, how would +you maintain a GUI with 15,000+ configuration options? + +Most solutions assume you can just put all options in a single code block, +which is unworkable at FFmpeg's scale. Instead, we split configuration +across many *AVOptions-enabled structs*, which use the @ref avoptions +"AVOptions API" to inspect and configure options, including in private contexts. + +AVOptions-accessible members of a context should be accessed through the +@ref avoptions "AVOptions API" whenever possible, even if they're not hidden +in a private context. That ensures values are validated as they're set, and +means you won't have to do as much work if a future version of FFmpeg changes +the allowed values. + +Although not strictly required, it is best to only modify options during +the configuration stage. Initialized structs may be accessed by internal +FFmpeg threads, and modifying them can cause weird intermittent bugs. + +@subsection Context_logging Logging: AVClass context structures + +FFmpeg's @ref lavu_log "logging facility" needs to be simple to use, +but flexible enough to let people debug problems. And much like options, +it needs to work the same across a wide variety of unrelated structs. + +FFmpeg structs that support the logging framework are called *@ref AVClass +context structures*. The name @ref AVClass was chosen early in FFmpeg's +development, but in practice it only came to store information about +logging, and about options. + +@section Context_further Further information about contexts + +So far, this document has provided a theoretical guide to FFmpeg contexts. +This final section provides some alternative approaches to the topic, +which may help round out your understanding. + +@subsection Context_example Learning by example: context for a codec + +It can help to learn contexts by doing a deep dive into a specific struct. +This section will discuss AVCodecContext - an AVOptions-enabled struct +that contains information about encoding or decoding one stream of data +(e.g. the video in a movie). + +The name "AVCodecContext" tells us this is a context. Many of +@ref libavcodec/avcodec.h "its functions" start with an `avctx` parameter, +indicating this parameter provides context for that function. + +AVCodecContext::internal contains the private context. For example, +codec-specific information might be stored here. + +AVCodecContext is allocated with avcodec_alloc_context3(), initialized with +avcodec_open2(), and freed with avcodec_free_context(). Most of its members +are configured with the @ref avoptions "AVOptions API", but for example you +can set AVCodecContext::draw_horiz_band() if your program happens to need it. + +AVCodecContext provides an abstract interface to many different *codecs*. +Options supported by many codecs (e.g. "bitrate") are kept in AVCodecContext +and exposed with AVOptions. Options that are specific to one codec are +stored in the private context, and also exposed with AVOptions. + +AVCodecContext::av_class contains logging metadata to ensure all codec-related +error messages look the same, plus implementation details about options. + +To support a specific codec, AVCodecContext's private context is set to +an encoder-specific data type. For example, the video codec +[H.264](https://en.wikipedia.org/wiki/Advanced_Video_Coding) is supported via +[the x264 library](https://www.videolan.org/developers/x264.html), and +implemented in X264Context. Although included in the documentation, X264Context +is not part of the public API. That means FFmpeg's @ref ffmpeg_versioning +"strict rules about changing public structs" aren't as important here, so a +version of FFmpeg could modify X264Context or replace it with another type +altogether. An adverse legal ruling or security problem could even force us to +switch to a completely different library without a major version bump. + +The design of AVCodecContext provides several important guarantees: + +- lets you use the same interface for any codec +- supports common encoder options like "bitrate" without duplicating code +- supports encoder-specific options like "profile" without bulking out the public interface +- exposes both types of options to users, with help text and detection of missing options +- provides uniform logging output +- hides implementation details (e.g. its encoding buffer) + +@subsection Context_comparison Learning by comparison: FFmpeg vs. Curl contexts + +It can help to learn contexts by comparing how different projects tackle +similar problems. This section will compare @ref AVMD5 "FFmpeg's MD5 context" +with [curl 8.8.0's equivalent](https://github.com/curl/curl/blob/curl-8_8_0/lib/md5.c#L48). + +The [MD5 algorithm](https://en.wikipedia.org/wiki/MD5) produces +a fixed-length digest from arbitrary-length data. It does this by calculating +the digest for a prefix of the data, then loading the next part and adding it +to the previous digest, and so on. + +```c +// FFmpeg's MD5 context looks like this: +typedef struct AVMD5 { + uint64_t len; + uint8_t block[64]; + uint32_t ABCD[4]; +} AVMD5; + +// Curl 8.8.0's MD5 context looks like this: +struct MD5_context { + const struct MD5_params *md5_hash; /* Hash function definition */ + void *md5_hashctx; /* Hash function context */ +}; +``` + +Curl's struct name ends with `_context`, guaranteeing contexts are the correct +interpretation. FFmpeg's struct does not explicitly say it's a context, but +@ref libavutil/md5.c "its functions do" so we can reasonably assume +it's the intended interpretation. + +Curl's struct uses `void *md5_hashctx` to avoid guaranteeing +implementation details in the public interface, whereas FFmpeg makes +everything accessible. This disagreement about data hiding is a good example +of how contexts can be used differently. Hiding the data means changing the +layout in a future version of curl won't break downstream programs that used +that data. But the MD5 algorithm has been stable for 30 years, and making the +data public makes it easier for people to follow a bug in their own code. + +Curl's struct is declared as `struct { ... }`, whereas FFmpeg uses +`typedef struct { ... } `. These conventions are used with both +context and non-context structs, so don't say anything about contexts as such. +Specifically, FFmpeg's convention is a workaround for an issue with C grammar: + +```c +void my_function(...) { + int my_var; // good + MD5_context my_curl_ctx; // error: C needs you to explicitly say "struct" + struct MD5_context my_curl_ctx; // good: added "struct" + AVMD5 my_ffmpeg_ctx; // good: typedef's avoid the need for "struct" +} +``` + +Both MD5 implementations are long-tested, widely-used examples of contexts +in the real world. They show how contexts can solve the same problem +in different ways. From patchwork Tue Jun 4 14:47:22 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 49551 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9183:0:b0:460:55fa:d5ed with SMTP id s3csp2743573vqg; Tue, 4 Jun 2024 07:50:01 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCU+X+JUoSgGU3Fquy/E3R6yZnZO7MbeeYqQpiRQ0cwabz/+FIXzWHwBreIJbrjntv/aWJesQ2U2223S42WGqo33vmBDmHxEERzdWw== X-Google-Smtp-Source: AGHT+IEMkjm9umip5Yrvt7vA8l2AT9N+WifdJcq15euND9kvQGl7436ZCSFPW2uuUuiujzOf5K/G X-Received: by 2002:a17:906:130e:b0:a62:2cae:c02 with SMTP id a640c23a62f3a-a6822049d08mr832187266b.61.1717512601082; Tue, 04 Jun 2024 07:50:01 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717512601; cv=none; d=google.com; s=arc-20160816; b=MW5EUiaK/2Ek5ceggJKEA0ZCLXXGIESj2ap3Nby/SV54EXIVyQu2kpgXStPAUis9Kh N3GmKzc9OddyuTWRDU4L0oM0k2UnHaukuGAIW1EH4jdUz34mIeu+fIainIAKBavZa1j4 jlFS/ASrQcGqrpkTW+pouQ4Q7dhH3STeYjYOVVz30GP04DLVGlEj0UPNOHZOeN3QDLHL WA0eOcFDpECu3zvo6vfrlulIYITGvtPCBiHiVayfHwGcDI7VqtOEizeAwxdSEKJgBSn7 PyDl80xTOLvkcaKnLygvl5w9gya1817R0y4uZINS9eXXe5kFdrRI6gsyQMc7JEnyu4TA PJ3w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc: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=roVkJZhGECd0Asj9r7/lP67MQva6YTWgziDI70M+FJw=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=P4dDWmQ+K8DjNGAD4FgrTpMglw8MJk8e21wSTvZuRP0Yb8Qtgj8ZefC6ShevYdoljA lG/pQbdS/ahlPzQvbJ8Voug4w6QnnYXrLoep0JRnuxiggEtEFRncEP/dzQuc4BhgPW/4 UCP8oQ5Q8AbF2Yx8oyYqjK4rrbG24ilDzPx2T0Mt4uU0GTx5WKco5y6FyW+5zjFoj2cX 0V7XHi3Tk4W+y4DqYRzU6tDf/e4gBtc79zHnqanw3Z2RcpCm5Ta3iZ2Umhn2DX2P17ZI X0jA/8mPt5fBhanNqyciLfMef+6B6JptpOLsuq8K8fw49AHTyP8o5UH2cJzuUEtshLpB g26Q==; 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 a640c23a62f3a-a68b5b3314esi360659766b.161.2024.06.04.07.50.00; Tue, 04 Jun 2024 07:50:01 -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 D222C68D711; Tue, 4 Jun 2024 17:49:39 +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 D234C68D6FC for ; Tue, 4 Jun 2024 17:49:31 +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 1sEVTf-007B97-05; Tue, 04 Jun 2024 15:49:31 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Tue, 4 Jun 2024 15:47:22 +0100 Message-ID: <20240604144919.213799-3-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v6 2/4] lavu: Clarify relationship between AVClass, AVOption and context 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 Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: 5NFUAD7VGFnr --- libavutil/log.h | 16 +++++++++++++--- libavutil/opt.h | 26 +++++++++++++++++++++----- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/libavutil/log.h b/libavutil/log.h index ab7ceabe22..88b35897c6 100644 --- a/libavutil/log.h +++ b/libavutil/log.h @@ -59,9 +59,19 @@ typedef enum { struct AVOptionRanges; /** - * Describe the class of an AVClass context structure. That is an - * arbitrary struct of which the first field is a pointer to an - * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.). + * Generic Logging facilities and configuration options + * + * Logging and AVOptions functions expect to be passed structs + * whose first member is a pointer-to-@ref AVClass. + * + * Structs that only use logging facilities are often referred to as + * "AVClass context structures", while those that provide configuration + * options are called "AVOptions-enabled structs". + * + * @see + * * @ref lavu_log + * * @ref avoptions + * * @ref Context */ typedef struct AVClass { /** diff --git a/libavutil/opt.h b/libavutil/opt.h index 07e27a9208..cdee8f7d28 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -39,9 +39,16 @@ * @defgroup avoptions AVOptions * @ingroup lavu_data * @{ - * AVOptions provide a generic system to declare options on arbitrary structs - * ("objects"). An option can have a help text, a type and a range of possible - * values. Options may then be enumerated, read and written to. + * + * Inspection and configuration for AVClass context structures + * + * Provides a generic API to declare and manage options on any struct + * whose first member is a pointer-to-@ref AVClass. Structs with private + * contexts can use that AVClass to return further @ref AVClass "AVClass"es + * that allow access to options in the private structs. + * + * Each option can have a help text, a type and a range of possible values. + * Options may be enumerated, read and written to. * * There are two modes of access to members of AVOption and its child structs. * One is called 'native access', and refers to access from the code that @@ -53,11 +60,20 @@ * question is allowed to access the field. This allows us to extend the * semantics of those fields without breaking API compatibility. * + * Note that AVOptions is not reentrant, and that many FFmpeg functions access + * options from separate threads. Unless otherwise indicated, it is best to + * avoid modifying options once a struct has been initialized. + * + * @see + * * @ref lavu_log + * * @ref Context + * * @section avoptions_scope Scope of AVOptions * * AVOptions is designed to support any set of multimedia configuration options - * that can be defined at compile-time. Although it is mainly used to expose - * FFmpeg options, you are welcome to adapt it to your own use case. + * that can be defined at compile-time and set at object creation time. Although + * it is mainly used to expose FFmpeg options, you are welcome to adapt it + * to your own use case. * * No single approach can ever fully solve the problem of configuration, * but please submit a patch if you believe you have found a problem From patchwork Tue Jun 4 14:47:23 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 49552 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9183:0:b0:460:55fa:d5ed with SMTP id s3csp2743669vqg; Tue, 4 Jun 2024 07:50:11 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCU1owPNrFRhsPPOPtWZmJ15e5CWKdFkmizdrzpUSTDQptH2dLwv5z+JidnEGP7sZvK9KuirMfX6WAj9ILoI6GKBLmNwNovmXX+Wfg== X-Google-Smtp-Source: AGHT+IEilDukgl3rZsDb/aHb7Ez/riGV7HUX2MKFgq+vhC0y4YVvCBKj794NCsLWXTSobHpxw+PF X-Received: by 2002:a19:5f53:0:b0:51d:5f0b:816f with SMTP id 2adb3069b0e04-52b89590e7cmr6494933e87.15.1717512610873; Tue, 04 Jun 2024 07:50:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717512610; cv=none; d=google.com; s=arc-20160816; b=mKMsvsF7Cixg9ouO/nLrCt2xuNFyxNd93NIwFZFNGEp91FygrtHXeGS2GzbObDVaY4 rbX9N6SVrSK5mXMFLoysQB0zVQsp42C0DyMrKhBvcxTNjeI5iBJJIKBNMxvxXqf/kLvy GUN03j0KfK1ECtlAjHTfwpknBR++VTnWpQ4G4MlLlDOd67LZ970MmPyWOPLddQlb5Gjk EwpBCRcd8pl0/2H3sZHgI+Qg0J2IL7c4wrerSaaugOyQVJBH5rSlDFwTtqgMuxcxfjNX k1AFP9uk/uDXSCRw6ObCf0xjJZLSoJ5AmwShYK+bNxQecHWnsPCWvy5Mv7+42z31WBkR brkA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc: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=w2HoygRQ1VXlFo0MCGBqUWVzBYns1k5Hhjg6YMNnzoI=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=JY3uRmpW6Ajq5eQngA8s+u4Jlyco3D2uHKrBlrMgSZRivEH4UGlubZTZ3Tn54t4Gyq 7Lee46+zqM9VxCkppHT0zTznBTOUXyMH3ulrlz4hfs5M1K6JJE4U7OvGcXFIl9qqB8eB e8QkAvwAIoTcE6cjCOy8W1y5Qp4NBSdu/xIHJ4gStLdrmUZ3yXxkXnyGQqkJKYbKpMyz ZZzPGbwVgA8ebKHMRteuQw3YjIWOXw5C59t5ayIR37E9AeO+4xtYCEw+RbiAahUmoE27 cAXvv4BGoaRKoaqHlH6iTjI7PQ50fGnH41YZxsL6wh5UDoI3bVtyi1obqJmbn+dxWUER esqQ==; 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 a640c23a62f3a-a68fae59f1esi249499266b.771.2024.06.04.07.50.10; Tue, 04 Jun 2024 07:50:10 -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 E024E68D70C; Tue, 4 Jun 2024 17:49:40 +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 4C4EF68D702 for ; Tue, 4 Jun 2024 17:49:32 +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 1sEVTf-007B97-0q; Tue, 04 Jun 2024 15:49:31 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Tue, 4 Jun 2024 15:47:23 +0100 Message-ID: <20240604144919.213799-4-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v6 3/4] all: Link to "context" from all public contexts with documentation 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 Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: RWH6an9lazQx The goal of putting these links in "@see" blocks is to provide hooks for future developers to add links to other useful parts of the codebase. --- libavcodec/avcodec.h | 3 +++ libavcodec/bsf.h | 3 +++ libavcodec/d3d11va.h | 3 +++ libavcodec/mediacodec.h | 2 ++ libavcodec/qsv.h | 3 +++ libavcodec/vdpau.h | 3 +++ libavcodec/videotoolbox.h | 3 +++ libavfilter/avfilter.h | 7 ++++++- libavformat/avformat.h | 3 +++ libavformat/avio.h | 3 +++ libavutil/audio_fifo.h | 3 +++ libavutil/hwcontext.h | 6 ++++++ libavutil/hwcontext_cuda.h | 3 +++ libavutil/hwcontext_d3d11va.h | 6 ++++++ libavutil/hwcontext_d3d12va.h | 6 ++++++ libavutil/hwcontext_drm.h | 3 +++ libavutil/hwcontext_dxva2.h | 6 ++++++ libavutil/hwcontext_mediacodec.h | 3 +++ libavutil/hwcontext_opencl.h | 6 ++++++ libavutil/hwcontext_qsv.h | 6 ++++++ libavutil/hwcontext_vaapi.h | 6 ++++++ libavutil/hwcontext_vdpau.h | 3 +++ libavutil/hwcontext_vulkan.h | 6 ++++++ libavutil/lfg.h | 3 +++ 24 files changed, 98 insertions(+), 1 deletion(-) diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 2da63c87ea..abc00ab394 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -441,6 +441,9 @@ typedef struct RcOverride{ * The AVOption/command line parameter names differ in some cases from the C * structure field names for historic reasons or brevity. * sizeof(AVCodecContext) must not be used outside libav*. + * + * @see + * - @ref Context */ typedef struct AVCodecContext { /** diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h index a09c69f242..ee5fdd48d2 100644 --- a/libavcodec/bsf.h +++ b/libavcodec/bsf.h @@ -64,6 +64,9 @@ * The fields in the struct will only be changed (by the caller or by the * filter) as described in their documentation, and are to be considered * immutable otherwise. + * + * @see + * - @ref Context */ typedef struct AVBSFContext { /** diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h index 27f40e5519..686974b083 100644 --- a/libavcodec/d3d11va.h +++ b/libavcodec/d3d11va.h @@ -52,6 +52,9 @@ * The application must make it available as AVCodecContext.hwaccel_context. * * Use av_d3d11va_alloc_context() exclusively to allocate an AVD3D11VAContext. + * + * @see + * - @ref Context */ typedef struct AVD3D11VAContext { /** diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h index 4e9b56a618..43f049a609 100644 --- a/libavcodec/mediacodec.h +++ b/libavcodec/mediacodec.h @@ -29,6 +29,8 @@ * This structure holds a reference to a android/view/Surface object that will * be used as output by the decoder. * + * @see + * - @ref Context */ typedef struct AVMediaCodecContext { diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h index c156b08d07..8ab93af6b6 100644 --- a/libavcodec/qsv.h +++ b/libavcodec/qsv.h @@ -32,6 +32,9 @@ * - decoding: hwaccel_context must be set on return from the get_format() * callback * - encoding: hwaccel_context must be set before avcodec_open2() + * + * @see + * - @ref Context */ typedef struct AVQSVContext { /** diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h index 8021c25761..934c96b88c 100644 --- a/libavcodec/vdpau.h +++ b/libavcodec/vdpau.h @@ -74,6 +74,9 @@ typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *, * * The size of this structure is not a part of the public ABI and must not * be used outside of libavcodec. + * + * @see + * - @ref Context */ typedef struct AVVDPAUContext { /** diff --git a/libavcodec/videotoolbox.h b/libavcodec/videotoolbox.h index d68d76e400..81d90d63b6 100644 --- a/libavcodec/videotoolbox.h +++ b/libavcodec/videotoolbox.h @@ -53,6 +53,9 @@ * between the caller and libavcodec for initializing Videotoolbox decoding. * Its size is not a part of the public ABI, it must be allocated with * av_videotoolbox_alloc_context() and freed with av_free(). + * + * @see + * - @ref Context */ typedef struct AVVideotoolboxContext { /** diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h index a34e61f23c..25ccd80433 100644 --- a/libavfilter/avfilter.h +++ b/libavfilter/avfilter.h @@ -403,7 +403,12 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); */ #define AVFILTER_THREAD_SLICE (1 << 0) -/** An instance of a filter */ +/** + * An instance of a filter + * + * @see + * - @ref Context + */ struct AVFilterContext { const AVClass *av_class; ///< needed for av_log() and filters common options diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 8afdcd9fd0..18f20f0bb0 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -1253,6 +1253,9 @@ enum AVDurationEstimationMethod { * can be found in libavformat/options_table.h. * The AVOption/command line parameter names differ in some cases from the C * structure field names for historic reasons or brevity. + * + * @see + * - @ref Context */ typedef struct AVFormatContext { /** diff --git a/libavformat/avio.h b/libavformat/avio.h index ebf611187d..d68f912a2f 100644 --- a/libavformat/avio.h +++ b/libavformat/avio.h @@ -156,6 +156,9 @@ enum AVIODataMarkerType { * directly, they should only be set by the client application * when implementing custom I/O. Normally these are set to the * function pointers specified in avio_alloc_context() + * + * @see + * - @ref Context */ typedef struct AVIOContext { /** diff --git a/libavutil/audio_fifo.h b/libavutil/audio_fifo.h index fa5f59a2be..6fdb114af8 100644 --- a/libavutil/audio_fifo.h +++ b/libavutil/audio_fifo.h @@ -44,6 +44,9 @@ * - Operates at the sample level rather than the byte level. * - Supports multiple channels with either planar or packed sample format. * - Automatic reallocation when writing to a full buffer. + * + * @see + * - @ref Context */ typedef struct AVAudioFifo AVAudioFifo; diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h index bac30debae..6bbb96fcd6 100644 --- a/libavutil/hwcontext.h +++ b/libavutil/hwcontext.h @@ -56,6 +56,9 @@ enum AVHWDeviceType { * references are released, the AVHWDeviceContext itself will be freed, * optionally invoking a user-specified callback for uninitializing the hardware * state. + * + * @see + * - @ref Context */ typedef struct AVHWDeviceContext { /** @@ -111,6 +114,9 @@ typedef struct AVHWDeviceContext { * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor * yields a reference, whose data field points to the actual AVHWFramesContext * struct. + * + * @see + * - @ref Context */ typedef struct AVHWFramesContext { /** diff --git a/libavutil/hwcontext_cuda.h b/libavutil/hwcontext_cuda.h index cbad434fea..0db5a69f0a 100644 --- a/libavutil/hwcontext_cuda.h +++ b/libavutil/hwcontext_cuda.h @@ -38,6 +38,9 @@ typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal; /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVCUDADeviceContext { CUcontext cuda_ctx; diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h index 77d2d72f1b..5b7763e73f 100644 --- a/libavutil/hwcontext_d3d11va.h +++ b/libavutil/hwcontext_d3d11va.h @@ -41,6 +41,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVD3D11VADeviceContext { /** @@ -127,6 +130,9 @@ typedef struct AVD3D11FrameDescriptor { /** * This struct is allocated as AVHWFramesContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVD3D11VAFramesContext { /** diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h index ff06e6f2ef..63281aa835 100644 --- a/libavutil/hwcontext_d3d12va.h +++ b/libavutil/hwcontext_d3d12va.h @@ -39,6 +39,8 @@ /** * @brief This struct is allocated as AVHWDeviceContext.hwctx * + * @see + * - @ref Context */ typedef struct AVD3D12VADeviceContext { /** @@ -80,6 +82,8 @@ typedef struct AVD3D12VADeviceContext { /** * @brief This struct is used to sync d3d12 execution * + * @see + * - @ref Context */ typedef struct AVD3D12VASyncContext { /** @@ -122,6 +126,8 @@ typedef struct AVD3D12VAFrame { /** * @brief This struct is allocated as AVHWFramesContext.hwctx * + * @see + * - @ref Context */ typedef struct AVD3D12VAFramesContext { /** diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h index 42709f215e..eb0b6e734a 100644 --- a/libavutil/hwcontext_drm.h +++ b/libavutil/hwcontext_drm.h @@ -153,6 +153,9 @@ typedef struct AVDRMFrameDescriptor { * DRM device. * * Allocated as AVHWDeviceContext.hwctx. + * + * @see + * - @ref Context */ typedef struct AVDRMDeviceContext { /** diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h index e1b79bc0de..3accd8d070 100644 --- a/libavutil/hwcontext_dxva2.h +++ b/libavutil/hwcontext_dxva2.h @@ -35,6 +35,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVDXVA2DeviceContext { IDirect3DDeviceManager9 *devmgr; @@ -42,6 +45,9 @@ typedef struct AVDXVA2DeviceContext { /** * This struct is allocated as AVHWFramesContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVDXVA2FramesContext { /** diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h index fc0263cabc..77d7d4e3a5 100644 --- a/libavutil/hwcontext_mediacodec.h +++ b/libavutil/hwcontext_mediacodec.h @@ -23,6 +23,9 @@ * MediaCodec details. * * Allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVMediaCodecDeviceContext { /** diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h index ef54486c95..4c184484c9 100644 --- a/libavutil/hwcontext_opencl.h +++ b/libavutil/hwcontext_opencl.h @@ -59,6 +59,9 @@ typedef struct AVOpenCLFrameDescriptor { * OpenCL device details. * * Allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVOpenCLDeviceContext { /** @@ -85,6 +88,9 @@ typedef struct AVOpenCLDeviceContext { * OpenCL-specific data associated with a frame pool. * * Allocated as AVHWFramesContext.hwctx. + * + * @see + * - @ref Context */ typedef struct AVOpenCLFramesContext { /** diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h index 35530e4e93..b4a84c9893 100644 --- a/libavutil/hwcontext_qsv.h +++ b/libavutil/hwcontext_qsv.h @@ -31,6 +31,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVQSVDeviceContext { mfxSession session; @@ -49,6 +52,9 @@ typedef struct AVQSVDeviceContext { /** * This struct is allocated as AVHWFramesContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVQSVFramesContext { /** diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h index 0b2e071cb3..02399ff7dc 100644 --- a/libavutil/hwcontext_vaapi.h +++ b/libavutil/hwcontext_vaapi.h @@ -64,6 +64,9 @@ enum { * VAAPI connection details. * * Allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVVAAPIDeviceContext { /** @@ -84,6 +87,9 @@ typedef struct AVVAAPIDeviceContext { * VAAPI-specific data associated with a frame pool. * * Allocated as AVHWFramesContext.hwctx. + * + * @see + * - @ref Context */ typedef struct AVVAAPIFramesContext { /** diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h index 1b7ea1e443..051af42dfc 100644 --- a/libavutil/hwcontext_vdpau.h +++ b/libavutil/hwcontext_vdpau.h @@ -31,6 +31,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVVDPAUDeviceContext { VdpDevice device; diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h index cbbd2390c1..6dfe4badfe 100644 --- a/libavutil/hwcontext_vulkan.h +++ b/libavutil/hwcontext_vulkan.h @@ -41,6 +41,9 @@ typedef struct AVVkFrame AVVkFrame; /** * Main Vulkan context, allocated as AVHWDeviceContext.hwctx. * All of these can be set before init to change what the context uses + * + * @see + * - @ref Context */ typedef struct AVVulkanDeviceContext { /** @@ -173,6 +176,9 @@ typedef enum AVVkFrameFlags { /** * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options + * + * @see + * - @ref Context */ typedef struct AVVulkanFramesContext { /** diff --git a/libavutil/lfg.h b/libavutil/lfg.h index e75a986f12..4e420b0e16 100644 --- a/libavutil/lfg.h +++ b/libavutil/lfg.h @@ -29,6 +29,9 @@ * The exact layout, types and content of this struct may change and should * not be accessed directly. Only its `sizeof()` is guaranteed to stay the same * to allow easy instanciation. + * + * @see + * - @ref Context */ typedef struct AVLFG { unsigned int state[64]; From patchwork Tue Jun 4 14:47:24 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 49553 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9183:0:b0:460:55fa:d5ed with SMTP id s3csp2743780vqg; Tue, 4 Jun 2024 07:50:22 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCV3vCMOON8+0NH1y6CATHWH8AWMkbxcnYHUHlvj9j/QAK6rUFhqwE4MuXwsmqx5LqUKwMts9UX9wglaqlKvwoV9EHhEXarSJA1fkw== X-Google-Smtp-Source: AGHT+IEtRcWZ4/+slfMsVJI9VcByOxzPrZHclG2vlGLZhHQEGiQPmlKdQyR/tkm4OZPzM47x1Ywh X-Received: by 2002:a50:cd93:0:b0:578:72d4:e3b0 with SMTP id 4fb4d7f45d1cf-57a364b6f0emr8115443a12.36.1717512622044; Tue, 04 Jun 2024 07:50:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717512622; cv=none; d=google.com; s=arc-20160816; b=SO8ubtSDOy/s+Qb+2Wsplck//Z+fDrw2wao2TwbU5tPqoasYMAFwuUIQk2o4UA4OT7 yA6RN8cb9i36RoKRFu7KMgFGAZSQHs47rPvS208OnpVhCkvj/KAwLYuviMjoEu35SbRx 0VGfkR7NRv3OBfSeRNdXEcWscAc71HB99vcQR0ifiELHEElIhf8iye5vib66wb18Hyhc sM3WnfeAeZAE/ZvD+6WziduV4G3peJZisSVRJLyBZfKXh0WyzzzbAnh4K3C4CekoCLmx 1TWmghGCLoKGS1U44r0QzCilgvZg30Ugc/H6n8gW4rNWZt9yqUEM88YB61yMHm933v0m fPUw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc: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=Lpz2xOeR2kA8/sIzi3H6FNDMNAgFt6El+H12/RB9EXw=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=SQdNt/Boe0Q5FH4HKj6PC5uVhtNtANxoKP2rnDjjNc3egGsvJ9j54/ikGsO+jbJGVK YmYHAcMYULA8CTtgCqp20md8Gy6SAoC7XyUUH9zdqt6nX2sXUWVglEP0Bk7Jss8LW8Pc iQODWVMjoBGUA6o3tkz9cetvp6oDC6tAhhH8I7j8R9TUlY8eqd2nO03HY5B45jm6bKs4 5JlUJjABsbqsEWCyMRysDqN/XWZr2e+OsudXudmVVFwWUoVKv+2UA9NfBjkiXWLglhGR 608DhBFbOptKhpIE/zqm4OzUBsDHr6YaQAY3aewzmh7YLEirJfKdowZGK2n0vgpVEPCx mIFA==; 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-57a31c677acsi5038513a12.208.2024.06.04.07.50.21; Tue, 04 Jun 2024 07:50:22 -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 EA43068D70D; Tue, 4 Jun 2024 17:49:41 +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 B194B68D6A9 for ; Tue, 4 Jun 2024 17:49:32 +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 1sEVTf-007B97-2K; Tue, 04 Jun 2024 15:49:32 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Tue, 4 Jun 2024 15:47:24 +0100 Message-ID: <20240604144919.213799-5-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v6 4/4] all: Rewrite documentation for contexts 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 Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: zPj06eS7GtKb Make their documentation more readable and similar to each other, (hopefully) without changing the meaning. --- libavcodec/aac/aacdec.h | 2 +- libavcodec/aacenc.h | 2 +- libavcodec/ac3enc.h | 2 +- libavcodec/amfenc.h | 2 +- libavcodec/atrac.h | 2 +- libavcodec/avcodec.h | 3 ++- libavcodec/bsf.h | 2 +- libavcodec/cbs.h | 2 +- libavcodec/d3d11va.h | 3 +-- libavcodec/mediacodec.h | 4 ++-- libavcodec/pthread_frame.c | 4 ++-- libavcodec/qsv.h | 6 ++++-- libavcodec/sbr.h | 2 +- libavcodec/vdpau.h | 5 +++-- libavcodec/videotoolbox.h | 5 +++-- libavfilter/avfilter.h | 2 +- libavformat/avformat.h | 3 ++- libavformat/avio.h | 3 ++- libavutil/audio_fifo.h | 2 +- libavutil/hwcontext.h | 21 ++++++++++++--------- libavutil/hwcontext_cuda.h | 2 +- libavutil/hwcontext_d3d11va.h | 4 ++-- libavutil/hwcontext_d3d12va.h | 6 +++--- libavutil/hwcontext_drm.h | 2 +- libavutil/hwcontext_dxva2.h | 4 ++-- libavutil/hwcontext_mediacodec.h | 2 +- libavutil/hwcontext_opencl.h | 4 ++-- libavutil/hwcontext_qsv.h | 4 ++-- libavutil/hwcontext_vaapi.h | 4 ++-- libavutil/hwcontext_vdpau.h | 2 +- libavutil/hwcontext_vulkan.h | 5 +++-- libavutil/lfg.h | 3 ++- 32 files changed, 65 insertions(+), 54 deletions(-) diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h index ee21a94007..f0d613afd9 100644 --- a/libavcodec/aac/aacdec.h +++ b/libavcodec/aac/aacdec.h @@ -441,7 +441,7 @@ typedef struct AACDecDSP { } AACDecDSP; /** - * main AAC decoding context + * Context for decoding AAC */ struct AACDecContext { const struct AVClass *class; diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h index d07960620e..3e710c7fac 100644 --- a/libavcodec/aacenc.h +++ b/libavcodec/aacenc.h @@ -207,7 +207,7 @@ typedef struct AACPCEInfo { } AACPCEInfo; /** - * AAC encoder context + * Context for encoding AAC */ typedef struct AACEncContext { AVClass *av_class; diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h index 5e98ad188b..e5abe0a856 100644 --- a/libavcodec/ac3enc.h +++ b/libavcodec/ac3enc.h @@ -153,7 +153,7 @@ typedef struct AC3Block { struct PutBitContext; /** - * AC-3 encoder private context. + * Private context for encoding AC-3 */ typedef struct AC3EncodeContext { AVClass *av_class; ///< AVClass used for AVOption diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h index 2dbd378ef8..184897beeb 100644 --- a/libavcodec/amfenc.h +++ b/libavcodec/amfenc.h @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter { } AmfTraceWriter; /** -* AMF encoder context +* Context for encoding AMF */ typedef struct AmfContext { diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h index 05208bbee6..e760f0384d 100644 --- a/libavcodec/atrac.h +++ b/libavcodec/atrac.h @@ -39,7 +39,7 @@ typedef struct AtracGainInfo { } AtracGainInfo; /** - * Gain compensation context structure. + * Context for gain compensation */ typedef struct AtracGCContext { float gain_tab1[16]; ///< gain compensation level table diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index abc00ab394..2fed4757ed 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -430,7 +430,8 @@ typedef struct RcOverride{ #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0) /** - * main external API structure. + * Context for an encode or decode session + * * New fields can be added to the end with minor version bumps. * Removal, reordering and changes to existing fields require a major * version bump. diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h index ee5fdd48d2..fadcfc5d47 100644 --- a/libavcodec/bsf.h +++ b/libavcodec/bsf.h @@ -56,7 +56,7 @@ */ /** - * The bitstream filter state. + * Context for bitstream filtering * * This struct must be allocated with av_bsf_alloc() and freed with * av_bsf_free(). diff --git a/libavcodec/cbs.h b/libavcodec/cbs.h index d479b1ac2d..c074dd11ec 100644 --- a/libavcodec/cbs.h +++ b/libavcodec/cbs.h @@ -214,7 +214,7 @@ typedef void (*CBSTraceWriteCallback)(void *trace_context, int64_t value); /** - * Context structure for coded bitstream operations. + * Context for coded bitstream operations */ typedef struct CodedBitstreamContext { /** diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h index 686974b083..5ffee2b3be 100644 --- a/libavcodec/d3d11va.h +++ b/libavcodec/d3d11va.h @@ -46,8 +46,7 @@ */ /** - * This structure is used to provides the necessary configurations and data - * to the Direct3D11 FFmpeg HWAccel implementation. + * Context for the Direct3D11 FFmpeg HWAccel implementation * * The application must make it available as AVCodecContext.hwaccel_context. * diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h index 43f049a609..49af9513b0 100644 --- a/libavcodec/mediacodec.h +++ b/libavcodec/mediacodec.h @@ -26,8 +26,8 @@ #include "libavcodec/avcodec.h" /** - * This structure holds a reference to a android/view/Surface object that will - * be used as output by the decoder. + * Context for the android/view/Surface object that will + * be used as output by the decoder * * @see * - @ref Context diff --git a/libavcodec/pthread_frame.c b/libavcodec/pthread_frame.c index 982e4a64c5..c462159022 100644 --- a/libavcodec/pthread_frame.c +++ b/libavcodec/pthread_frame.c @@ -69,7 +69,7 @@ typedef struct ThreadFrameProgress { } ThreadFrameProgress; /** - * Context used by codec threads and stored in their AVCodecInternal thread_ctx. + * Context used by codec threads and allocated as AVCodecInternal.thread_ctx */ typedef struct PerThreadContext { struct FrameThreadContext *parent; @@ -113,7 +113,7 @@ typedef struct PerThreadContext { } PerThreadContext; /** - * Context stored in the client AVCodecInternal thread_ctx. + * Context allocated as AVCodecInternal.thread_ctx */ typedef struct FrameThreadContext { PerThreadContext *threads; ///< The contexts for each thread. diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h index 8ab93af6b6..9d36197fbf 100644 --- a/libavcodec/qsv.h +++ b/libavcodec/qsv.h @@ -26,8 +26,10 @@ #include "libavutil/buffer.h" /** - * This struct is used for communicating QSV parameters between libavcodec and - * the caller. It is managed by the caller and must be assigned to + * Context for communicating QSV parameters between libavcodec + * and the caller. + * + * It is managed by the caller and must be assigned to * AVCodecContext.hwaccel_context. * - decoding: hwaccel_context must be set on return from the get_format() * callback diff --git a/libavcodec/sbr.h b/libavcodec/sbr.h index fe3a39603a..ea0760776c 100644 --- a/libavcodec/sbr.h +++ b/libavcodec/sbr.h @@ -116,7 +116,7 @@ typedef struct SBRData { typedef struct SpectralBandReplication SpectralBandReplication; /** - * aacsbr functions pointers + * Context for aacsbr functions */ typedef struct AACSBRContext { int (*sbr_lf_gen)(SpectralBandReplication *sbr, diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h index 934c96b88c..e20f37ef2a 100644 --- a/libavcodec/vdpau.h +++ b/libavcodec/vdpau.h @@ -64,8 +64,9 @@ typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *, const VdpBitstreamBuffer *); /** - * This structure is used to share data between the libavcodec library and - * the client video application. + * Context to share data between the libavcodec library and + * the client video application + * * This structure will be allocated and stored in AVCodecContext.hwaccel_context * by av_vdpau_bind_context(). Members can be set by the user once * during initialization or through each AVCodecContext.get_buffer() diff --git a/libavcodec/videotoolbox.h b/libavcodec/videotoolbox.h index 81d90d63b6..dfc5c1a5a5 100644 --- a/libavcodec/videotoolbox.h +++ b/libavcodec/videotoolbox.h @@ -49,8 +49,9 @@ #include "libavutil/attributes.h" /** - * This struct holds all the information that needs to be passed - * between the caller and libavcodec for initializing Videotoolbox decoding. + * Context for information passed between the caller and libavcodec + * for initializing Videotoolbox decoding + * * Its size is not a part of the public ABI, it must be allocated with * av_videotoolbox_alloc_context() and freed with av_free(). * diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h index 25ccd80433..15aaba6ea2 100644 --- a/libavfilter/avfilter.h +++ b/libavfilter/avfilter.h @@ -404,7 +404,7 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); #define AVFILTER_THREAD_SLICE (1 << 0) /** - * An instance of a filter + * Context for a filter * * @see * - @ref Context diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 18f20f0bb0..d8abab56d8 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -1241,7 +1241,8 @@ enum AVDurationEstimationMethod { }; /** - * Format I/O context. + * Context for format I/O + * * New fields can be added to the end with minor version bumps. * Removal, reordering and changes to existing fields require a major * version bump. diff --git a/libavformat/avio.h b/libavformat/avio.h index d68f912a2f..bf017f1338 100644 --- a/libavformat/avio.h +++ b/libavformat/avio.h @@ -146,7 +146,8 @@ enum AVIODataMarkerType { }; /** - * Bytestream IO Context. + * Context for bytestream I/O + * * New public fields can be added with minor version bumps. * Removal, reordering and changes to existing public fields require * a major version bump. diff --git a/libavutil/audio_fifo.h b/libavutil/audio_fifo.h index 6fdb114af8..ab56ef69f5 100644 --- a/libavutil/audio_fifo.h +++ b/libavutil/audio_fifo.h @@ -39,7 +39,7 @@ */ /** - * Context for an Audio FIFO Buffer. + * Context for an Audio FIFO Buffer * * - Operates at the sample level rather than the byte level. * - Supports multiple channels with either planar or packed sample format. diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h index 6bbb96fcd6..18d25a644c 100644 --- a/libavutil/hwcontext.h +++ b/libavutil/hwcontext.h @@ -41,12 +41,13 @@ enum AVHWDeviceType { }; /** - * This struct aggregates all the (hardware/vendor-specific) "high-level" state, - * i.e. state that is not tied to a concrete processing configuration. - * E.g., in an API that supports hardware-accelerated encoding and decoding, - * this struct will (if possible) wrap the state that is common to both encoding - * and decoding and from which specific instances of encoders or decoders can be - * derived. + * Context for (hardware/vendor-specific) "high-level" state + * + * "High-level state" is anything that is not tied to a concrete processing + * configuration. E.g., in an API that supports hardware-accelerated encoding + * and decoding, this struct will (if possible) wrap the state that is common + * to both encoding and decoding and from which specific instances of encoders + * or decoders can be derived. * * This struct is reference-counted with the AVBuffer mechanism. The * av_hwdevice_ctx_alloc() constructor yields a reference, whose data field @@ -106,9 +107,11 @@ typedef struct AVHWDeviceContext { } AVHWDeviceContext; /** - * This struct describes a set or pool of "hardware" frames (i.e. those with - * data not located in normal system memory). All the frames in the pool are - * assumed to be allocated in the same way and interchangeable. + * Context for a pool of "hardware" frames (those with data not located + * in normal system memory) + * + * All the frames in the pool are assumed to be allocated in the same way and + * interchangeable. * * This struct is reference-counted with the AVBuffer mechanism and tied to a * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor diff --git a/libavutil/hwcontext_cuda.h b/libavutil/hwcontext_cuda.h index 0db5a69f0a..bb380d5450 100644 --- a/libavutil/hwcontext_cuda.h +++ b/libavutil/hwcontext_cuda.h @@ -37,7 +37,7 @@ typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal; /** - * This struct is allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h index 5b7763e73f..ce07f84450 100644 --- a/libavutil/hwcontext_d3d11va.h +++ b/libavutil/hwcontext_d3d11va.h @@ -40,7 +40,7 @@ #include /** - * This struct is allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context @@ -129,7 +129,7 @@ typedef struct AVD3D11FrameDescriptor { } AVD3D11FrameDescriptor; /** - * This struct is allocated as AVHWFramesContext.hwctx + * Context allocated as AVHWFramesContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h index 63281aa835..f741fc00e8 100644 --- a/libavutil/hwcontext_d3d12va.h +++ b/libavutil/hwcontext_d3d12va.h @@ -37,7 +37,7 @@ #include /** - * @brief This struct is allocated as AVHWDeviceContext.hwctx + * @brief Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context @@ -80,7 +80,7 @@ typedef struct AVD3D12VADeviceContext { } AVD3D12VADeviceContext; /** - * @brief This struct is used to sync d3d12 execution + * @brief Context for syncing d3d12 execution * * @see * - @ref Context @@ -124,7 +124,7 @@ typedef struct AVD3D12VAFrame { } AVD3D12VAFrame; /** - * @brief This struct is allocated as AVHWFramesContext.hwctx + * @brief Context allocated as AVHWFramesContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h index eb0b6e734a..f8aa75c5cf 100644 --- a/libavutil/hwcontext_drm.h +++ b/libavutil/hwcontext_drm.h @@ -152,7 +152,7 @@ typedef struct AVDRMFrameDescriptor { /** * DRM device. * - * Allocated as AVHWDeviceContext.hwctx. + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h index 3accd8d070..a2320ea18a 100644 --- a/libavutil/hwcontext_dxva2.h +++ b/libavutil/hwcontext_dxva2.h @@ -34,7 +34,7 @@ #include /** - * This struct is allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context @@ -44,7 +44,7 @@ typedef struct AVDXVA2DeviceContext { } AVDXVA2DeviceContext; /** - * This struct is allocated as AVHWFramesContext.hwctx + * Context allocated as AVHWFramesContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h index 77d7d4e3a5..ada61fa61e 100644 --- a/libavutil/hwcontext_mediacodec.h +++ b/libavutil/hwcontext_mediacodec.h @@ -22,7 +22,7 @@ /** * MediaCodec details. * - * Allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h index 4c184484c9..0c3ef04fc6 100644 --- a/libavutil/hwcontext_opencl.h +++ b/libavutil/hwcontext_opencl.h @@ -58,7 +58,7 @@ typedef struct AVOpenCLFrameDescriptor { /** * OpenCL device details. * - * Allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context @@ -87,7 +87,7 @@ typedef struct AVOpenCLDeviceContext { /** * OpenCL-specific data associated with a frame pool. * - * Allocated as AVHWFramesContext.hwctx. + * Context allocated as AVHWFramesContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h index b4a84c9893..afdddbce0e 100644 --- a/libavutil/hwcontext_qsv.h +++ b/libavutil/hwcontext_qsv.h @@ -30,7 +30,7 @@ */ /** - * This struct is allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context @@ -51,7 +51,7 @@ typedef struct AVQSVDeviceContext { } AVQSVDeviceContext; /** - * This struct is allocated as AVHWFramesContext.hwctx + * Context allocated as AVHWFramesContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h index 02399ff7dc..a6c1b25415 100644 --- a/libavutil/hwcontext_vaapi.h +++ b/libavutil/hwcontext_vaapi.h @@ -63,7 +63,7 @@ enum { /** * VAAPI connection details. * - * Allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context @@ -86,7 +86,7 @@ typedef struct AVVAAPIDeviceContext { /** * VAAPI-specific data associated with a frame pool. * - * Allocated as AVHWFramesContext.hwctx. + * Context allocated as AVHWFramesContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h index 051af42dfc..a2e6fcf5ba 100644 --- a/libavutil/hwcontext_vdpau.h +++ b/libavutil/hwcontext_vdpau.h @@ -30,7 +30,7 @@ */ /** - * This struct is allocated as AVHWDeviceContext.hwctx + * Context allocated as AVHWDeviceContext.hwctx * * @see * - @ref Context diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h index 6dfe4badfe..3766546100 100644 --- a/libavutil/hwcontext_vulkan.h +++ b/libavutil/hwcontext_vulkan.h @@ -39,7 +39,8 @@ typedef struct AVVkFrame AVVkFrame; */ /** - * Main Vulkan context, allocated as AVHWDeviceContext.hwctx. + * Context for Vulkan, allocated as AVHWDeviceContext.hwctx + * * All of these can be set before init to change what the context uses * * @see @@ -175,7 +176,7 @@ typedef enum AVVkFrameFlags { } AVVkFrameFlags; /** - * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options + * Context allocated as AVHWFramesContext.hwctx, used to set pool-specific options * * @see * - @ref Context diff --git a/libavutil/lfg.h b/libavutil/lfg.h index 4e420b0e16..4ee7834fe4 100644 --- a/libavutil/lfg.h +++ b/libavutil/lfg.h @@ -25,7 +25,8 @@ #include /** - * Context structure for the Lagged Fibonacci PRNG. + * Context structure for the Lagged Fibonacci PRNG + * * The exact layout, types and content of this struct may change and should * not be accessed directly. Only its `sizeof()` is guaranteed to stay the same * to allow easy instanciation.