From patchwork Wed May 15 15:54:19 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48897 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:3a48:b0:1af:fc2d:ff5a with SMTP id zu8csp1689640pzb; Wed, 15 May 2024 08:55:22 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCX5jw9XryvrxzuLEoOzRVzYok4J2Oxa0Qa4m5pp8jfFBAlg+9nfm34u1OIZpSFSWrSm16+IZ5BJ1WTvNZosJ2JNs3yoymQgfE966g== X-Google-Smtp-Source: AGHT+IEXptoK6dPgEdHLpEVvrNHanjATqDyTYZI5VblWBRjTmhKmRkORR9wK3QM0rXTmeckS01+l X-Received: by 2002:a17:906:30c7:b0:a59:a431:a8ce with SMTP id a640c23a62f3a-a5a2d55a7c3mr1128121066b.2.1715788521813; Wed, 15 May 2024 08:55:21 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1715788521; cv=none; d=google.com; s=arc-20160816; b=GuLbVi1JDn/szPZNEZnXZ6UTApOdKIf98Vdt5gIe7VCA9wyiGqNU/KYkTNwqmA1I5L DcxpPxsqbDawTUInZlNkhD+fxZwSr2vAk/EdIZeIzoIYokeWnGi++vGXv8g3TZyWBJ3n Bv+W+0OgbvrDCiEE1+5TZbs/+8ok1BxLyMT5Og8vTNRwNVjpPcX4/Jbr0mMpSAnTfKMl Mn4BL4haflLEHpV5I4ZrX5KeLnqY9cQ63nczV6fph/HfgpaooaUnQZ4aWmBGCCiWKOjn 0/MlrDQ7SCYlSZNIeMSgyjRKDdEVyTANHv/e60ughgeoDxp4z3EHF2zkVZdLoGpQvwq6 dnNw== 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=ZCK/TlhISA1otiAOVj3mOmerR1KeOkSulTOe47ykBHU=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=tBHOxy2IDk8CdiPU3JxEoXXg/Ln4lrhIlGbHoG/HGqV6iPAbjQRvNn4h6Lp7nF7hGV GX3euFpvC9EV6tCos8p8bCc3J7JAYm7hBwkCi+olEixyBhodCtigO3Wm3sluzIpfuUXJ LdAqbIEySqvqcYllBdZKKk2fHUHamL7A+SQgFAk/SIaIqDVvZVV9/6FAccbN0xTaR9Vv MuTFj0dM/aIE8N6DW8s2X6Qk6mOWO1lshnlYlmOH1t9rW5fZhhIVFcUdSvfPESFvzkLU 5DOAJA1R3RcowPblw/6fz8sdu6c75Su9/R30QxQOnwFTZXrb/MUY2ED9h1r+PqhDhHN7 ZN4Q==; 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-a5a17ba5e94si736795566b.660.2024.05.15.08.55.21; Wed, 15 May 2024 08:55:21 -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 11B6568D6F7; Wed, 15 May 2024 18:55:05 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 670D668D088 for ; Wed, 15 May 2024 18:54:58 +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-b.tch.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1s7Gy1-00127b-1W; Wed, 15 May 2024 16:54:57 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 May 2024 16:54:19 +0100 Message-ID: <20240515155446.3589239-2-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v4 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: /pP/aNn9rOiV Derived from detailed explanations kindly provided by Stefano Sabatini: https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325903.html --- doc/context.md | 394 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 doc/context.md diff --git a/doc/context.md b/doc/context.md new file mode 100644 index 0000000000..fb85b3f366 --- /dev/null +++ b/doc/context.md @@ -0,0 +1,394 @@ +# Introduction to contexts + +“%Context” is a name for a widely-used programming idiom. +This document explains the general idiom and the conventions FFmpeg has built around it. + +This document uses object-oriented analogies to help readers familiar with +[object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming) +learn about contexts. But contexts can also be used outside of OOP, +and even in situations where OOP isn't helpful. So these analogies +should only be used as a first step towards understanding contexts. + +## “Context” as a way to think about code + +A context is any data structure that is passed to several functions +(or several instances of the same function) that all operate on the same entity. +For example, [object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming) +languages usually provide member functions with a `this` or `self` value: + +```c +class my_cxx_class { + void my_member_function() { + // the implicit object parameter provides context for the member function: + std::cout << this; + } +}; +``` + +Contexts are a fundamental building block of OOP, but can also be used in procedural code. +For example, most callback functions can be understood to use contexts: + +```c +struct MyStruct { + int counter; +}; + +void my_callback( void *my_var_ ) { + // my_var provides context for the callback function: + struct MyStruct *my_var = (struct MyStruct *)my_var_; + printf("Called %d time(s)", ++my_var->counter); +} + +void init() { + struct MyStruct my_var; + my_var.counter = 0; + register_callback( my_callback, &my_var ); +} +``` + +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. + +## “Context” as a tool of communication + +“%Context“ can just be a word to understand code in your own head, +but it can also be a term you use to explain your interfaces. +Here is a version of the callback example that makes the context explicit: + +```c +struct CallbackContext { + int counter; +}; + +void my_callback( void *ctx_ ) { + // ctx provides context for the callback function: + struct CallbackContext *ctx = (struct CallbackContext *)ctx_; + printf("Called %d time(s)", ++ctx->counter); +} + +void init() { + struct CallbackContext ctx; + ctx.counter = 0; + register_callback( my_callback, &ctx ); +} +``` + +The difference here is subtle, but important. If a piece of code +*appears compatible with contexts*, then you are *allowed to think +that way*, but if a piece of code *explicitly states it uses +contexts*, then you are *required to follow that approach*. + +For example, imagine someone modified `MyStruct` in the earlier example +to count several unrelated events across the whole program. That would mean +it contained information about multiple entities, so was not a context. +But nobody ever *said* it was a context, so that isn't necessarily wrong. +However, proposing the same change to the `CallbackContext` in the later example +would violate a guarantee, and should be pointed out in a code review. + +@warning Guaranteeing to use contexts does not mean guaranteeing to use +object-oriented programming. For example, FFmpeg creates its contexts +procedurally instead of with constructors. + +## Contexts in the real world + +To understand how contexts are used in the real world, it might be +useful to compare [curl's MD5 hash context](https://github.com/curl/curl/blob/bbeeccdea8507ff50efca70a0b33d28aef720267/lib/curl_md5.h#L48) +with @ref AVMD5 "FFmpeg's equivalent context". + +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. Projects that use MD5 generally use some +kind of context, so comparing them can reveal differences between projects. + +```c +// Curl's MD5 context looks like this: +struct MD5_context { + const struct MD5_params *md5_hash; /* Hash function definition */ + void *md5_hashctx; /* Hash function context */ +}; + +// FFmpeg's MD5 context looks like this: +typedef struct AVMD5 { + uint64_t len; + uint8_t block[64]; + uint32_t ABCD[4]; +} AVMD5; +``` + +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 kind of data hiding is an advanced context-oriented +convention, and is discussed below. Using it in this case has strengths and +weaknesses. On one hand, it means changing the layout in a future version +of curl won't break downstream programs that used that data. On the other hand, +the MD5 algorithm has been stable for 30 years, so it's arguably more important +to let people dig in when debugging 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. + +## FFmpeg's advanced context-oriented conventions + +Projects that make heavy use of contexts tend to develop conventions +to make them more useful. This section discusses conventions used in FFmpeg, +some of which are used in other projects, others are unique to this project. + +### Naming: “Context” and “ctx” + +```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, ... ); +``` + +If an FFmpeg struct is intended for use as a context, its name usually +makes that clear. Exceptions to this rule include AVMD5 (discussed above), +which is only identified as a context by the functions that call it. + +If a function is associated with a context, its name usually +begins with some variant of the context name (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_`. + +If a function has a context parameter, it usually comes first and its name +often contains `ctx`. Exceptions include av_bsf_alloc(), which puts the +context argument second to emphasise it's an out variable. + +### Data hiding: private contexts + +```c +// Context structs often hide private context: +struct AVSomeContext { + void *priv_data; // sometimes just called "internal" +}; +``` + +Contexts usually 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. Hiding information in a private context +ensures it can be modified without affecting downstream software. + +Object-oriented programmers may be tempted to compare private contexts to +*private class members*. That's often accurate, but for example it can also +be used like a *virtual function table* - a list of functions that are +guaranteed to exist, but may be implemented differently for different +sub-classes. When thinking about private contexts, remember that FFmpeg +isn't *large enough* to need some common OOP techniques, even though it's +solving a problem that's *complex enough* to benefit from some rarer techniques. + +### Manage lifetime: allocate, initialize and free + +```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 freed with associated functions: + + 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 object) + * 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 + +FFmpeg's allocation stage is broadly similar to OOP, but can do some higher-level +operations. For example, AVOptions-enabled structs (discussed below) contain an +AVClass member that is set during allocation. + +FFmpeg's "configuration" and "initialization" stages combine to resemble OOP's +"initialization" stage. This can mislead object-oriented developers, +who are used to doing both at once. This means FFmpeg contexts don't have +a direct equivalent of OOP constructors, as they would be doing +two jobs in one function. + +FFmpeg's three-stage creation process is useful for complicated structures. +For example, AVCodecContext contains many members that *can* be set before +initialization, but in practice most programs set few if any of them. +Implementing this with a constructor would involve a function with a list +of arguments that was extremely long and changed whenever the struct was +updated. For contexts that don't need the extra flexibility, FFmpeg usually +provides 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. + +FFmpeg's "deallocation" stage is broadly similar to OOP, but can perform some +higher-level functions (similar to the allocation stage). + +Very few contexts need the flexibility of separate "closing" and +"deallocation" stages, so these are usually combined into a single function. +Closing functions usually end with "_close", while deallocation +functions usually end with "_free". + +### Reflection: AVOptions-enabled structs + +Object-oriented programming puts more focus on data hiding than FFmpeg needs, +but it also puts less focus on +[reflection](https://en.wikipedia.org/wiki/Reflection_(computer_programming)). + +To understand FFmpeg's reflection 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 any other programming languages you know. +[Python's argparse module](https://docs.python.org/3/library/argparse.html) +is a good example - its approach works well with far more complex programs +than `getopt`, but would you like to maintain an argparse implementation +with 15,000 options and growing? + +Most solutions assume you can just put all options in a single 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 reflect information about their user-configurable members, +including members in private contexts. + +An *AVOptions-enabled struct* is a struct that contains an AVClass element as +its first member, and uses that element to provide access to instances of +AVOption, each of which provides information about a single option. +The AVClass can also include more @ref AVClass "AVClasses" for private contexts, +making it possible to set options through the API that aren't +accessible directly. + +AVOptions-accessible members of a context should be accessed through the +AVOptions API whenever possible, even if they're not hidden away 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 layout. + +AVClass was created very early in FFmpeg's history, long before AVOptions. +Its name suggests some kind of relationship to an OOP +base [class](https://en.wikipedia.org/wiki/Class_(computer_programming)), +but the name has become less accurate as FFmpeg evolved, to the point where +AVClass and AVOption are largely synonymous in modern usage. The difference +might still matter if you need to support old versions of FFmpeg, +where you might find *AVClass context structures* (contain an AVClass element +as their first member) that are not *AVOptions-enabled* (don't use that element +to provide access to instances of AVOption). + +Object-oriented programmers may be tempted to compare @ref avoptions "AVOptions" +to OOP getters and setters. There is some overlap in functionality, but OOP +getters and setters are usually specific to a single member and don't provide +metadata about the member; whereas AVOptions has a single API that covers +every option, and provides help text etc. as well. + +Object-oriented programmers may be tempted to compare AVOptions-accessible +members of a public context to protected members of a class. Both provide +global access through an API, and unrestricted access for trusted friends. +But this is just a happy accident, not a guarantee. + +## Final example: context for a codec + +AVCodecContext is an AVOptions-enabled struct that contains information +about encoding or decoding one stream of data (e.g. the video in a movie). +It's a good example of many of the issues above. + +The name "AVCodecContext" tells us this is a context. Many of +@ref libavcodec/avcodec.h "its functions" start with an `avctx` parameter, +indicating this object 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::opaque or AVCodecContext::draw_horiz_band() if your +program happens to need them. + +AVCodecContext provides an abstract interface to many different *codecs*. +Options supported by many codecs (e.g. "bitrate") are kept in AVCodecContext +and reflected as AVOptions. Options that are specific to one codec are +stored in the internal context, and reflected from there. + +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. Whereas there are strict rules about +changing AVCodecContext, 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 +- reflects both types of options to users, with help text and detection of missing options +- hides implementation details (e.g. its encoding buffer) From patchwork Wed May 15 15:54:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48898 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:3a48:b0:1af:fc2d:ff5a with SMTP id zu8csp1689753pzb; Wed, 15 May 2024 08:55:32 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCVoyrtZYfr6Wif8j9CkgXsZaW9ni7Ol9zkSxod562op58d2WebGlF8Xlalz6/ccbyIQQEdVOhx+O9Xahph+qqPZxGHAxcYYZTViEg== X-Google-Smtp-Source: AGHT+IG0EpGM7pyYTUoMTd4kyW/zXAkf3mQcRfLDFm7kRN7zQ5CrwNbIrEwqz2DafJ30i/T02vjD X-Received: by 2002:a17:907:7748:b0:a59:cf38:5343 with SMTP id a640c23a62f3a-a5a2d5724dfmr1524487566b.27.1715788532520; Wed, 15 May 2024 08:55:32 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1715788532; cv=none; d=google.com; s=arc-20160816; b=e30kkRpwMn7Lnp88mKbxtc8QgBZoDuyJXODldwZKlOcWPAyfVj1xEWxaXJb5dve/Ot cWb5cTtyf9lrs5noDLUgC4m2T9/dT9y6qAjdCX2HUbImTaDFsRDVs/b3SQiQ8mi0gV/a 62ppLBnz3r8DMWPVQinW7YrSYGzbWwfxsqy/rr8u8OX/dVxgshzBrmPFD7kOluqiltKa WKAeXs673LWX8uOfy/gHlcu2DpYfErLlfbdWQyyAlS7MAOmzOjwGnu4zwKC8NoZnSBDV V/ndkH2wd8TcQBI18S11xCbzFuvhJk7oW4biLjliNI05K6Vmhvkn1tQk6AbvtfvN1YFJ GLrA== 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=RhJ+/cIM0AvfFbgpiYcOwkcNQ8959qem300KL3KKZzo=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=wbhqV5EGR9Iq/dHDCwNyhqtKK0TFNKve2+L3osTNyCdrKBVCc2pWcfg43yU3XffHWb gcoBdPER1s4dEc4YbU7AEs56to7MIeAH9RHSCthTXBwLdmknUOzf35tGzdjuErfqEplb WGP8yI80vpGy6ia+ngVzQU+rS+8Q+x2qVPteSFpUAR0eMpc0TAYCtlaMmrTk0Mct4QOe SqurAX9CfwV397jwQjAyb0Qv9v1yYJVGookBkL6fYwgkkmtmqFkoxVCJX+9DWTWaij/X 0/3gIKrreEK9A+zoMFRdGZQuG8MJK/tVND7b0rh0k6jcUp5zFnxnjwYJgNBotifj5RI8 CO1g==; 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-a5a17c2be1esi774317766b.921.2024.05.15.08.55.32; Wed, 15 May 2024 08:55:32 -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 048AD68D6FD; Wed, 15 May 2024 18:55:06 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 A037268D6D9 for ; Wed, 15 May 2024 18:54:58 +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-b.tch.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1s7Gy1-00127b-2t; Wed, 15 May 2024 16:54:58 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 May 2024 16:54:20 +0100 Message-ID: <20240515155446.3589239-3-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v4 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: BkmBBw1UjTKy --- libavutil/log.h | 11 ++++++++--- libavutil/opt.h | 7 ++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/libavutil/log.h b/libavutil/log.h index ab7ceabe22..cfbf416679 100644 --- a/libavutil/log.h +++ b/libavutil/log.h @@ -59,9 +59,14 @@ 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.). + * Metadata about an arbitrary data structure + * + * A @ref md_doc_2context "context struct" whose first member is a pointer + * to an AVClass object is called an "AVClass context structure" + * (e.g. AVCodecContext, AVFormatContext etc.). + * + * AVClass is often combined with @ref avoptions "AVOptions" to create + * "AVOptions-enabled structs" that can be easily configured by users. */ typedef struct AVClass { /** diff --git a/libavutil/opt.h b/libavutil/opt.h index 07e27a9208..e314e134c2 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -39,9 +39,10 @@ * @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. + * Builds on AVClass, adding a generic system to declare options. + * + * An option can have a help text, a type and a range of possible values. + * Options may then 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 From patchwork Wed May 15 15:54:21 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48899 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:3a48:b0:1af:fc2d:ff5a with SMTP id zu8csp1689846pzb; Wed, 15 May 2024 08:55:42 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCWQTTZekx739ik2dA1FcKAUX75gbEqv1Cx/QwRzlyT8H/+d1MtLu6e8mKhpxE5wjh7p28PAeW2qXUEiQke0G4jH837ZpyQHrinSLA== X-Google-Smtp-Source: AGHT+IHbqvb4msF6CobD4PFtUxBXA47UCHfkQ9rk26iaJYMwi1Vgw6xZEaP/XX/A7b2/zrA96sw6 X-Received: by 2002:a05:6512:688:b0:523:750f:99b8 with SMTP id 2adb3069b0e04-523750f9af9mr4349774e87.33.1715788542462; Wed, 15 May 2024 08:55:42 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1715788542; cv=none; d=google.com; s=arc-20160816; b=RIfXFCVtLPo52qqJJjWjVz0f9NMWE5SZycQkzSJ6kT3WT1mGR+IR2n6nKYKYhQ2lTc 4GxrOa76K7xHGwhDZnkjsaqBJfW61btoE7/pYxMGJf3wtWLZpai82lZz0CiIu029Jur5 XFxo15UK4mkj4kmjxtcpsDygxU5KQFakbJOqs6KSzJChghE6u6fwDIBwT7JmjWp35WZ9 ORwO9BicXIBgXM37WPSSCaRNftB486xUs54QagLA0g0API6sHNY5kFxaWFhPfDAwMzRr WWOBruxB6wOZ+qtSHWjeW53OlKBhbHP2ff5NVhciyXx3YypDCN335VoeTLUBlwSs6V8w CnZg== 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=3bPhjphoiYdWxgO2iaGTuque8EX7QlJ5k79Qo4H8A7Y=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=Nvxb1Y7h5xU9ZpCQ0Z+p18rPzzXF1lULNYqSpx0SRpAC978D62w+pU3gFV011jZuYc yzgxx5JO3DN0PgE8bafzkTOTe92sZzW6QxvgyO5kYERerHFIOisPPWfSW24gdRtpLUbE bk38kAQEbD7gOmQELrrXs+Gvkap7X4Z840LeAGn7+VtGOt7ltFLtRCrFA2x/lsjSPToE SbXDrJpjV03+2jR/rP0WsI062gZkea6hdwsLip4+aJpWApR/nXTmR3XiYiMTLeXrK6xq pFpiF2tQBkKp/m4d3nqNVGD8OJU/DxpfJLoxpPJC21zNhKSwsI/fpH8t4R2nOW7ArD2e 5n+Q==; 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-a5cdc248f30si31045966b.838.2024.05.15.08.55.42; Wed, 15 May 2024 08:55:42 -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 7150668D70D; Wed, 15 May 2024 18:55:08 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 23A7468D6DC for ; Wed, 15 May 2024 18:54:59 +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-b.tch.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1s7Gy2-00127b-0U; Wed, 15 May 2024 16:54:58 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 May 2024 16:54:21 +0100 Message-ID: <20240515155446.3589239-4-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v4 3/4] all: Link to "context" from all 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: kVYLISLZgjAj Some headings needed to be rewritten to accomodate the text, (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/h264dsp.h | 2 +- libavcodec/h264pred.h | 2 +- libavcodec/mediacodec.h | 2 +- libavcodec/mpegaudiodec_template.c | 2 +- libavcodec/pthread_frame.c | 4 ++-- libavcodec/qsv.h | 6 ++++-- libavcodec/sbr.h | 2 +- libavcodec/smacker.c | 2 +- libavcodec/vdpau.h | 3 ++- 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 | 6 +++--- libavutil/hwcontext_vdpau.h | 2 +- libavutil/hwcontext_vulkan.h | 4 ++-- libavutil/lfg.h | 2 +- 36 files changed, 66 insertions(+), 57 deletions(-) diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h index eed53c6c96..1d991a3c63 100644 --- a/libavcodec/aac/aacdec.h +++ b/libavcodec/aac/aacdec.h @@ -253,7 +253,7 @@ typedef struct AACDecDSP { } AACDecDSP; /** - * main AAC decoding context + * main AAC decoding @ref md_doc_2context "context" */ struct AACDecContext { const struct AVClass *class; diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h index d07960620e..1a645f4719 100644 --- a/libavcodec/aacenc.h +++ b/libavcodec/aacenc.h @@ -207,7 +207,7 @@ typedef struct AACPCEInfo { } AACPCEInfo; /** - * AAC encoder context + * AAC encoder @ref md_doc_2context "context" */ typedef struct AACEncContext { AVClass *av_class; diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h index 30812617cc..c725007077 100644 --- a/libavcodec/ac3enc.h +++ b/libavcodec/ac3enc.h @@ -152,7 +152,7 @@ typedef struct AC3Block { } AC3Block; /** - * AC-3 encoder private context. + * AC-3 encoder private @ref md_doc_2context "context" */ typedef struct AC3EncodeContext { AVClass *av_class; ///< AVClass used for AVOption diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h index 2dbd378ef8..f142ede63a 100644 --- a/libavcodec/amfenc.h +++ b/libavcodec/amfenc.h @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter { } AmfTraceWriter; /** -* AMF encoder context +* AMF encoder @ref md_doc_2context "context" */ typedef struct AmfContext { diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h index 05208bbee6..1527e376a9 100644 --- a/libavcodec/atrac.h +++ b/libavcodec/atrac.h @@ -39,7 +39,7 @@ typedef struct AtracGainInfo { } AtracGainInfo; /** - * Gain compensation context structure. + * Gain compensation @ref md_doc_2context "context" */ typedef struct AtracGCContext { float gain_tab1[16]; ///< gain compensation level table diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 2da63c87ea..4f7a5aa80d 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. + * @ref md_doc_2context "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 a09c69f242..bf79afa7cc 100644 --- a/libavcodec/bsf.h +++ b/libavcodec/bsf.h @@ -56,7 +56,7 @@ */ /** - * The bitstream filter state. + * Bitstream filter @ref md_doc_2context "context" * * 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..0ff64d2fef 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. + * @ref md_doc_2context "Context" structure for coded bitstream operations. */ typedef struct CodedBitstreamContext { /** diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h index 27f40e5519..ec0c472ab9 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. + * @ref md_doc_2context "Context" for the Direct3D11 FFmpeg HWAccel implementation * * The application must make it available as AVCodecContext.hwaccel_context. * diff --git a/libavcodec/h264dsp.h b/libavcodec/h264dsp.h index e0880c4d88..27256c5605 100644 --- a/libavcodec/h264dsp.h +++ b/libavcodec/h264dsp.h @@ -37,7 +37,7 @@ typedef void (*h264_biweight_func)(uint8_t *dst, uint8_t *src, int weightd, int weights, int offset); /** - * Context for storing H.264 DSP functions + * @ref md_doc_2context "Context" for storing H.264 DSP functions */ typedef struct H264DSPContext { /* weighted MC */ diff --git a/libavcodec/h264pred.h b/libavcodec/h264pred.h index cb008548fc..2b076f8846 100644 --- a/libavcodec/h264pred.h +++ b/libavcodec/h264pred.h @@ -89,7 +89,7 @@ #define PART_NOT_AVAILABLE -2 /** - * Context for storing H.264 prediction functions + * @ref md_doc_2context "Context" for storing H.264 prediction functions */ typedef struct H264PredContext { void(*pred4x4[9 + 3 + 3])(uint8_t *src, const uint8_t *topright, diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h index 4e9b56a618..9967a7cfb3 100644 --- a/libavcodec/mediacodec.h +++ b/libavcodec/mediacodec.h @@ -26,7 +26,7 @@ #include "libavcodec/avcodec.h" /** - * This structure holds a reference to a android/view/Surface object that will + * @ref md_doc_2context "Context" for the android/view/Surface object that will * be used as output by the decoder. * */ diff --git a/libavcodec/mpegaudiodec_template.c b/libavcodec/mpegaudiodec_template.c index c73b1e0054..15d63215d1 100644 --- a/libavcodec/mpegaudiodec_template.c +++ b/libavcodec/mpegaudiodec_template.c @@ -1691,7 +1691,7 @@ static int decode_frame_adu(AVCodecContext *avctx, AVFrame *frame, #if CONFIG_MP3ON4_DECODER || CONFIG_MP3ON4FLOAT_DECODER /** - * Context for MP3On4 decoder + * @ref md_doc_2context "Context" for MP3On4 decoder */ typedef struct MP3On4DecodeContext { int frames; ///< number of mp3 frames per block (number of mp3 decoder instances) diff --git a/libavcodec/pthread_frame.c b/libavcodec/pthread_frame.c index 67f09c1f48..74f05eedcf 100644 --- a/libavcodec/pthread_frame.c +++ b/libavcodec/pthread_frame.c @@ -71,7 +71,7 @@ typedef struct ThreadFrameProgress { } ThreadFrameProgress; /** - * Context used by codec threads and stored in their AVCodecInternal thread_ctx. + * @ref md_doc_2context "Context" used by codec threads and stored in their AVCodecInternal thread_ctx. */ typedef struct PerThreadContext { struct FrameThreadContext *parent; @@ -111,7 +111,7 @@ typedef struct PerThreadContext { } PerThreadContext; /** - * Context stored in the client AVCodecInternal thread_ctx. + * @ref md_doc_2context "Context" stored in the client AVCodecInternal thread_ctx. */ typedef struct FrameThreadContext { PerThreadContext *threads; ///< The contexts for each thread. diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h index c156b08d07..8b8160a4b1 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 + * @ref md_doc_2context "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..98ad9024a9 100644 --- a/libavcodec/sbr.h +++ b/libavcodec/sbr.h @@ -116,7 +116,7 @@ typedef struct SBRData { typedef struct SpectralBandReplication SpectralBandReplication; /** - * aacsbr functions pointers + * aacsbr functions pointer @ref md_doc_2context "context" */ typedef struct AACSBRContext { int (*sbr_lf_gen)(SpectralBandReplication *sbr, diff --git a/libavcodec/smacker.c b/libavcodec/smacker.c index 8f198d6957..1ca39a74a0 100644 --- a/libavcodec/smacker.c +++ b/libavcodec/smacker.c @@ -68,7 +68,7 @@ typedef struct HuffEntry { } HuffEntry; /** - * Context used for code reconstructing + * @ref md_doc_2context "Context" used for code reconstructing */ typedef struct HuffContext { int current; diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h index 8021c25761..227b85727d 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 + * @ref md_doc_2context "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 d68d76e400..f15e79f325 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. + * @ref md_doc_2context "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 a34e61f23c..54b5f9dc43 100644 --- a/libavfilter/avfilter.h +++ b/libavfilter/avfilter.h @@ -403,7 +403,7 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); */ #define AVFILTER_THREAD_SLICE (1 << 0) -/** An instance of a filter */ +/** @ref md_doc_2context "Context" for a filter */ 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..28243c06c4 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -1241,7 +1241,8 @@ enum AVDurationEstimationMethod { }; /** - * Format I/O context. + * Format I/O @ref md_doc_2context "context" + * * 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 ebf611187d..b525c93194 100644 --- a/libavformat/avio.h +++ b/libavformat/avio.h @@ -146,7 +146,8 @@ enum AVIODataMarkerType { }; /** - * Bytestream IO Context. + * Bytestream I/O @ref md_doc_2context "context" + * * 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 fa5f59a2be..de29715462 100644 --- a/libavutil/audio_fifo.h +++ b/libavutil/audio_fifo.h @@ -39,7 +39,7 @@ */ /** - * Context for an Audio FIFO Buffer. + * @ref md_doc_2context "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 bac30debae..60064cf08b 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. + * @ref md_doc_2context "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 @@ -103,9 +104,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. + * @ref md_doc_2context "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 cbad434fea..e259892688 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 + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVCUDADeviceContext { CUcontext cuda_ctx; diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h index 77d2d72f1b..101d1cb6f8 100644 --- a/libavutil/hwcontext_d3d11va.h +++ b/libavutil/hwcontext_d3d11va.h @@ -40,7 +40,7 @@ #include /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVD3D11VADeviceContext { /** @@ -126,7 +126,7 @@ typedef struct AVD3D11FrameDescriptor { } AVD3D11FrameDescriptor; /** - * This struct is allocated as AVHWFramesContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx */ typedef struct AVD3D11VAFramesContext { /** diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h index ff06e6f2ef..c623914c2b 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 This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx * */ typedef struct AVD3D12VADeviceContext { @@ -78,7 +78,7 @@ typedef struct AVD3D12VADeviceContext { } AVD3D12VADeviceContext; /** - * @brief This struct is used to sync d3d12 execution + * @brief This @ref md_doc_2context "context" is used to sync d3d12 execution * */ typedef struct AVD3D12VASyncContext { @@ -120,7 +120,7 @@ typedef struct AVD3D12VAFrame { } AVD3D12VAFrame; /** - * @brief This struct is allocated as AVHWFramesContext.hwctx + * @brief This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx * */ typedef struct AVD3D12VAFramesContext { diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h index 42709f215e..8329e69966 100644 --- a/libavutil/hwcontext_drm.h +++ b/libavutil/hwcontext_drm.h @@ -152,7 +152,7 @@ typedef struct AVDRMFrameDescriptor { /** * DRM device. * - * Allocated as AVHWDeviceContext.hwctx. + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx. */ typedef struct AVDRMDeviceContext { /** diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h index e1b79bc0de..c679c16af0 100644 --- a/libavutil/hwcontext_dxva2.h +++ b/libavutil/hwcontext_dxva2.h @@ -34,14 +34,14 @@ #include /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVDXVA2DeviceContext { IDirect3DDeviceManager9 *devmgr; } AVDXVA2DeviceContext; /** - * This struct is allocated as AVHWFramesContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx */ typedef struct AVDXVA2FramesContext { /** diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h index fc0263cabc..e81193247b 100644 --- a/libavutil/hwcontext_mediacodec.h +++ b/libavutil/hwcontext_mediacodec.h @@ -22,7 +22,7 @@ /** * MediaCodec details. * - * Allocated as AVHWDeviceContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVMediaCodecDeviceContext { /** diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h index ef54486c95..7abd97db2b 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 + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVOpenCLDeviceContext { /** @@ -84,7 +84,7 @@ typedef struct AVOpenCLDeviceContext { /** * OpenCL-specific data associated with a frame pool. * - * Allocated as AVHWFramesContext.hwctx. + * This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx. */ typedef struct AVOpenCLFramesContext { /** diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h index e2dba8ad83..b63ebddaef 100644 --- a/libavutil/hwcontext_qsv.h +++ b/libavutil/hwcontext_qsv.h @@ -30,7 +30,7 @@ */ /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVQSVDeviceContext { mfxSession session; @@ -48,7 +48,7 @@ typedef struct AVQSVDeviceContext { } AVQSVDeviceContext; /** - * This struct is allocated as AVHWFramesContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx */ typedef struct AVQSVFramesContext { mfxFrameSurface1 *surfaces; diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h index 0b2e071cb3..4a897eb851 100644 --- a/libavutil/hwcontext_vaapi.h +++ b/libavutil/hwcontext_vaapi.h @@ -63,7 +63,7 @@ enum { /** * VAAPI connection details. * - * Allocated as AVHWDeviceContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVVAAPIDeviceContext { /** @@ -83,7 +83,7 @@ typedef struct AVVAAPIDeviceContext { /** * VAAPI-specific data associated with a frame pool. * - * Allocated as AVHWFramesContext.hwctx. + * This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx. */ typedef struct AVVAAPIFramesContext { /** @@ -105,7 +105,7 @@ typedef struct AVVAAPIFramesContext { /** * VAAPI hardware pipeline configuration details. * - * Allocated with av_hwdevice_hwconfig_alloc(). + * This struct is allocated with av_hwdevice_hwconfig_alloc(). */ typedef struct AVVAAPIHWConfig { /** diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h index 1b7ea1e443..e305caa595 100644 --- a/libavutil/hwcontext_vdpau.h +++ b/libavutil/hwcontext_vdpau.h @@ -30,7 +30,7 @@ */ /** - * This struct is allocated as AVHWDeviceContext.hwctx + * This @ref md_doc_2context "context" is allocated as AVHWDeviceContext.hwctx */ typedef struct AVVDPAUDeviceContext { VdpDevice device; diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h index cbbd2390c1..1869870032 100644 --- a/libavutil/hwcontext_vulkan.h +++ b/libavutil/hwcontext_vulkan.h @@ -39,7 +39,7 @@ typedef struct AVVkFrame AVVkFrame; */ /** - * Main Vulkan context, allocated as AVHWDeviceContext.hwctx. + * Main Vulkan @ref md_doc_2context "context", allocated as AVHWDeviceContext.hwctx. * All of these can be set before init to change what the context uses */ typedef struct AVVulkanDeviceContext { @@ -172,7 +172,7 @@ typedef enum AVVkFrameFlags { } AVVkFrameFlags; /** - * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options + * This @ref md_doc_2context "context" is allocated as AVHWFramesContext.hwctx, used to set pool-specific options */ typedef struct AVVulkanFramesContext { /** diff --git a/libavutil/lfg.h b/libavutil/lfg.h index e75a986f12..7f4ff5b62f 100644 --- a/libavutil/lfg.h +++ b/libavutil/lfg.h @@ -25,7 +25,7 @@ #include /** - * Context structure for the Lagged Fibonacci PRNG. + * @ref md_doc_2context "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. From patchwork Wed May 15 15:54: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: 48900 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:3a48:b0:1af:fc2d:ff5a with SMTP id zu8csp1689965pzb; Wed, 15 May 2024 08:55:53 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCVXUmi+qVmFnLDMwoPVluu2Xtx7W5fyub8Cq261AxpFFF6O288VHiEKXmwEmi64VuhbBwVadwo0JyJmoT1RfuBgxDSx8EBfbJ8s9w== X-Google-Smtp-Source: AGHT+IHmFLU7yxwzxMg6SGGHrNd9YEBpYuMVKp/qXxiKJFFGL3VswG/+kyUyY8ecC/PW+s6ysO/7 X-Received: by 2002:ac2:5ecb:0:b0:520:9b91:2d5a with SMTP id 2adb3069b0e04-52210273cc1mr10236899e87.59.1715788553595; Wed, 15 May 2024 08:55:53 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1715788553; cv=none; d=google.com; s=arc-20160816; b=RF6ZMAeoi99+fpXlpyhqmhQqWBPW4k9BoWScnx6U93VEwjf2wdMTiLiJoSN2iMI4RB d9U7zazNhanx2GwYD6a2nZ5e/2ZwPPY26spLAzPMl0lQYQAV8M0JD4vXLIvRqQquqhRq F1cxzdHeDgQtT361eCFnqIQmLxkzrmJVFWr4H+zHGuoRKf7xvt24PQDjE95DPZPh8Aps VqeNl5ECRBbCD1gxui3huMB4x7LzpprdvWSaQKylH5mLXeW06rORnsAOjHTj8vbYKKcY 7zoJJ/ReNvf/AjKwNoPFQg82I/JHSlVAF7ooTuicrNSzJCC27FfJxRkm8fapYu7MZJFY so0w== 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=eDeWXGscI5EmSHS4t/H9OSspV5hN7slpwDl1rtBa9zI=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=VobHH2Uz0N8IB7q0ZXGkLSafOmZdUobb37hhbghsWZPp5072QPf4oDxaAWH6V9AKbI ukjqvoTIx+L4Ip7Y5C7R3AwusUagmpWYKf2joxJoAgELtax+Z4Jxn4gx2xps66uD4SeX fwBV3FVQihjtOQM4qFR+RLrjy6fz0CUiUlxoLfhZ6+Fm6x3X0VJrzqIZG4hiW9uOlbHV drW+70yHBfp1mIptNmqQBzPuP7SyQF7Ms03POGmXhYqId5rV6zalF7bFglD/DV1ZSlYF Up//Tiaq+6J33DsVCGUujMK09QIqL0B6bs2qMoH2py8qOpnlRHVmBOXAfeGCdY/3R0kB Hrlw==; 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-a5a17be6d19si809729366b.848.2024.05.15.08.55.53; Wed, 15 May 2024 08:55:53 -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 ED76868D714; Wed, 15 May 2024 18:55:09 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 6B71A68D6DC for ; Wed, 15 May 2024 18:54:59 +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-b.tch.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1s7Gy2-00127b-21; Wed, 15 May 2024 16:54:58 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Wed, 15 May 2024 16:54:22 +0100 Message-ID: <20240515155446.3589239-5-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v4 4/4] lavf: Add documentation for private "Context" classes 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: mICAd6AmWSB9 Doxygen thinks any text like "Context for foo" is a link to a struct called "Context". Add a description and a better link, to avoid confusing readers. --- libavformat/async.c | 3 +++ libavformat/cache.c | 3 +++ 2 files changed, 6 insertions(+) diff --git a/libavformat/async.c b/libavformat/async.c index e096b0bc6f..3c28d418ae 100644 --- a/libavformat/async.c +++ b/libavformat/async.c @@ -53,6 +53,9 @@ typedef struct RingBuffer int read_pos; } RingBuffer; +/** + * @brief @ref md_doc_2context "Context" for testing async + */ typedef struct Context { AVClass *class; URLContext *inner; diff --git a/libavformat/cache.c b/libavformat/cache.c index 5f78adba9d..3cc0edec82 100644 --- a/libavformat/cache.c +++ b/libavformat/cache.c @@ -52,6 +52,9 @@ typedef struct CacheEntry { int size; } CacheEntry; +/** + * @brief @ref md_doc_2context "Context" for a cache + */ typedef struct Context { AVClass *class; int fd;