From patchwork Mon Apr 22 15:56:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48223 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:c906:b0:1a9:af23:56c1 with SMTP id gx6csp2384492pzb; Mon, 22 Apr 2024 08:59:04 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCVSc+wEQKxMepGdFO1i9sPln2YhmuwOmdg0JQUUJSbwJ3ko6hxgIyvhpSGKP4zCiJ0VRpCV9fCqZjhOVrhk7iEDiDtB1bREgtPJiQ== X-Google-Smtp-Source: AGHT+IGMs/jExDrMF/bzkoZaM+MivkGfQtTviWXk+TPg+ctgM4FXNKG4xI9FigSJl6pRfeS8J+G5 X-Received: by 2002:a17:906:c79a:b0:a58:7192:8fbe with SMTP id cw26-20020a170906c79a00b00a5871928fbemr670573ejb.60.1713801544550; Mon, 22 Apr 2024 08:59:04 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1713801544; cv=none; d=google.com; s=arc-20160816; b=sZev75ES4RR7N9cgBtPPxB3A/lr/Lhlk9aG8J5Rex7tu4B1FhTY6Dk57jT+TUTc95F 7vH5Moe/ErOsUbuGVj1rsQ2d+vKM67BCefHco3FfGb5Pqka9SnGec7yr6ZRAXjiyN2uW k72tfV6UBbsqXyuKAk0d2QrFhDnCph0M7ScYCsrVl63rFot1DsRnLJBXD3MHF1KTj+Oz UlLHYEhNkR+c/EK963blBX6CsV5VhcIN0awOoevrMcD5UyzpjLgif+aeXNeEvHtmphsi 7vZd5dzLyA97GNjEI2el8pToDnNK2XZTceafM6i9u+wM9YEvXt1sumNZUlSk+2n9Dq7I klOg== 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=sOTjzsHIgHPdwFE0z/NMAXrIZ80kxyhEIgwE4PjTPNw=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=FyEPfRRjBwS95HsttD5S5VxQP3TNooni45dyasAJuMtneIxhj3iq/rBkaokVAJIqQv b4wSgxzWOzoaJJAe3haj/d2Escra14SFTj8lZCY2pRHkdTCF1awjeQ0xFiaAKnEU+GS9 SKVBZ8b91FOttbTJbpZLLcwnnlbyOgfS3XmeXCBJVBf6GCdc8u351qRDyUM/wEOiikYU UR8Q+MP8yl/uDksdHVHSgfxDfqEPGSHhAScTuO9mlG5+g1KkFA7qwd0z2o64GdJPQ4x8 vVRNhNscmkHlgCzMj7RLW8wFCySLznkQA2aXBsKXIBXhkJ/vVREtUK591jjQSZO9y7Xz QiIQ==; 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 lb2-20020a170907784200b00a58740c19f6si122750ejc.581.2024.04.22.08.59.03; Mon, 22 Apr 2024 08:59:04 -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 EF44868D353; Mon, 22 Apr 2024 18:58:50 +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 1640D68D18B for ; Mon, 22 Apr 2024 18:58:43 +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 1ryw42-00B6rX-2U; Mon, 22 Apr 2024 16:58:42 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Mon, 22 Apr 2024 16:56:48 +0100 Message-ID: <20240422155836.385333-2-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> References: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v3 1/3] doc: Explain what "context" means X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: Nfxyr3ScABfi Derived from detailed explanations kindly provided by Stefano Sabatini: https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325903.html --- doc/context.md | 276 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 doc/context.md diff --git a/doc/context.md b/doc/context.md new file mode 100644 index 0000000000..73caacf54f --- /dev/null +++ b/doc/context.md @@ -0,0 +1,276 @@ +# Context-oriented programming + +Like many C projects, FFmpeg has adopted the subset of object-oriented techniques +that help solve its problems. Object-like structures are called "contexts", +and this document provides a general introduction to how they work. + +Object-oriented programming usually focusses on *access* as a primary concern. +For example, members of an object are visibly designated "private", "constant" +etc. to control how they are accessed. *Reflection* is a secondary concern, +where it is provided at all. For example, C++ has no built-in way to get a +string containing the name of a variable. + +Reflection is extremely important for FFmpeg, because user-facing options are +implemented by reflecting state at runtime. Limiting access is a secondary +concern, mainly important for ensuring implementation details can change +between versions. + +An object-oriented programmer learning FFmpeg should be careful not to fixate on +FFmpeg's access control features, nor to overlook its reflection capabilities. +Both are present, but have been given the level of focus appropriate for the task. + +## Example: modify text then print it + +The example below shows a context structure that receives input strings, +modifies them in some context-dependant way, then prints them to a specified +filehandle. + +```c +/** + * Type information, accessible at runtime. + * + * Useful when configuring objects. + */ +enum ModifyThenPrintDialect { + MODIFY_THEN_PRINT_PLAIN_TEXT = 0, + MODIFY_THEN_PRINT_REGEX = 1, + MODIFY_THEN_PRINT_REGEX_PCRE = 2 +}; + +/** + * User-facing information about types + * + * Useful for describing contexts to the user. + */ +static const char* ModifyThenPrintDialectName[] = { + "plain text", + "regular expression", + "Perl-compatible regular expression" +}; + +/** + * Context for functions that modify strings before printing them + */ +struct ModifyThenPrintContext { + + /** + * Information about the type of this particular instance + * + * Object-oriented programs would probably represent this example + * as a sub-class, but some instance-specific functionality + * behaves more like a mixin. + */ + enum ModifyThenPrintDialect dialect; + + /** + * Internal context + * + * Object-oriented programs would put private members in here, + * but could also use it to store a virtual function table + * or other "invisible" information. + */ + void* priv_data; + + /** + * User-configurable options + * + * Best set through an API, but can be set directly if necessary + * + * Data from users needs to be validated before it's set, and the API + * might e.g. want to update some internal buffer when these change. + * Setting this directly is always less robust than using an API, + * but might be worthwhile if you're willing to spend the time checking + * for edge cases, and don't mind your code misbehaving if future + * versions change the API but not the structure. + * + * Object-oriented programs would likely make these protected members, + * initialised in a constructor and accessed with getters and setters. + * Making them user-configurable would be left to the programmer. + */ + char *replace_this; + char *with_this; + + /** + * Programmer-configurable variable + * + * Object-oriented programs would represent this as a public member. + */ + FILE *out; + +}; + +/** + * Allocate and initialize a ModifyThenPrintContext + * + * This creates a new pointer, then fills in some sensible defaults. + * + * We can reasonably assume this function will initialise `priv_data` + * with a dialect-specific object, but shouldn't make any assumptions + * about what that object is. + * + * Object-oriented programs would likely represent this as an + * allocator function and a constructor. + */ +int ModifyThenPrintContext_alloc_context(struct ModifyThenPrintContext **ctx, + enum ModifyThenPrintDialect dialect, + FILE *out); + +/** + * Uninitialize and deallocate a ModifyThenPrintContext + * + * This does any work required by the internal context (e.g. deallocating + * `priv_data`), then deallocates the main context itself. + * + * Object-oriented programs would likely represent this as a + * destructor and a deallocator. + */ +int ModifyThenPrintContext_free(struct ModifyThenPrintContext *ctx); + +/** + * Configure a ModifyThenPrintContext + * + * This checks the arguments are valid in the context's dialect, + * then updates the options as necessary + * + * Object-oriented programs would likely represent this as a + * collection of setter functions. + */ +int ModifyThenPrintContext_configure(struct ModifyThenPrintContext *ctx, + char* replace_this, + char* with_this); + +/** + * Print the contents of a ModifyThenPrintContext to a filehandle + * + * Provides human-readable information about keys and values. + * + * Object-oriented programs would likely represent this with some kind of + * `serialise` operation. + */ +int ModifyThenPrintContext_dump(struct ModifyThenPrintContext **ctx, + FILE *dump_fh); + +/** + * Print a single message + * + * Object-oriented programs would likely represent this with a member function. + */ +int ModifyThenPrintContext_print(struct ModifyThenPrintContext *ctx, + char *msg); + +/** + * How this context might be used in practice + */ +int print_hello_world() +{ + + int ret = 0; + + struct ModifyThenPrintContext *ctx; + + if ( ModifyThenPrintContext_alloc_context( &ctx, MODIFY_THEN_PRINT_REGEX, stdout ) < 0 ) { + ret = -1; + goto EXIT_WITHOUT_CLEANUP; + } + + if ( ModifyThenPrintContext_configure(ctx, "Hi|Hullo", "Hello") < 0 ) { + ret = -1; + goto FINISH; + } + + if ( ModifyThenPrintContext_print( ctx, "Hi, world!\n" ) < 0 ) { + ret = -1; + goto FINISH; + } + + if ( ModifyThenPrintContext_print( ctx, "Hullo, world!\n" ) < 0 ) { + ret = -1; + goto FINISH; + } + + FINISH: + if ( ModifyThenPrintContext_free( ctx ) ) { + ret = -1; + goto EXIT_WITHOUT_CLEANUP; + } + + EXIT_WITHOUT_CLEANUP: + return ret; + +} +``` + +## FFmpeg context structures + +The example above is a generic example of a context structure and its +associated functions. Some FFmpeg contexts are no more complex than +that example, just as some objects are just key/value stores with some +functions attached. But here are some examples to show the variety of +contexts available in FFmpeg. + +AVHashContext presents a generic API for hashing data. @ref hash.h +"Its associated functions" show how to create, use and destroy a hash. +The exact algorithm is specified by passing a string to av_hash_alloc(), +and the list of strings can be retrieved from av_hash_names(). +Algorithm-specific internal context is stored in AVHashContext::ctx. + +AVCodecContext is a complex member representing data about an encoding or +decoding session. @ref avcodec.h "Its associated functions" provide an +abstract interface to encode and decode data. Like most widely-used contexts, +its first member is an AVClass pointer containing instance-specific information. +That means it's an *AVClass context structure* (discussed in more detail below). + +X264Context contains the internal context for an AVCodecContext that uses +the x264 library. @ref libx264.c "Its associated functions" provide a concrete +implementation for interacting with libx264. This class is not directly +accessible through FFmpeg's public interface, so unlike AVCodecContext it can +change significantly between releases. + +## Reflection with AVClass and AVOptions + +An *AVClass context structure* is a context whose first member is an AVClass +that reflects its contents. An *@ref avoptions "AVOptions"-enabled struct* +is a structure which reflects its contents using the @ref avoptions "AVOptions" +API. These terms have become synonymous in modern usage, but you might notice +some distinction when looking at code written after AVClass was developed but +before @ref avoptions "AVOptions" was added. + +At first glance, an object-oriented programmer might be tempted to look at AVClass +as a base class that contexts inherit from. But unlike a base class, an AVClass +doesn't imply any theoretical relationship between objects, and contexts of the +same type will often have different AVClass values. It's even theoretically possible +for a single AVClass to be shared between contexts of different types. A better +analogy would be to [C++ concepts](https://en.wikipedia.org/wiki/Concepts_(C%2B%2B)) +or [Java interfaces](https://en.wikipedia.org/wiki/Interface_(Java)). + +To understand how AVClass and @ref avoptions "AVOptions" work, +consider the requirements for a `libx264` encoder: + +- it has to support common encoder options like "bitrate" +- it has to support encoder-specific options like "profile" + - the exact options could change quickly if a legal ruling forces a change of backend +- it has to provide useful feedback to users about unsupported options + +Common encoder options like "bitrate" need to be stored in AVCodecContext itself +to avoid duplicating code, while encoder-specific options like "profile" have to +be stored in the X264Context instance stored in AVCodecContext::priv_data. +But both need to be presented to users (along with help text, default values etc.) +in a way that makes it easy to build user interfaces to get and set those options. + +A context's AVClass member contains a list of AVOption objects, describing +the user-configurable members of the class. It also contains functions to +iterate through a tree of AVClass objects representing internal context either +for the current object or for any class that could potentially exist in the +current version of FFmpeg. + +The @ref avoptions "AVOptions" API accepts any AVClass context structure, +looks through its AVOption data, and uses that to examine, introspect, and modify +the structure. Because the API doesn't contain any type-specific information, +it can be used to create a general user interface that adapts automatically +when e.g. a new version of FFmpeg adds a new configuration option. + +## Summary + +FFmpeg uses "contexts" in ways that are often resemble object-oriented programming. +But it focuses less on encapsulation within arbitrarily complex systems, +and more on providing reflectivity to make pleasant user interfaces. From patchwork Mon Apr 22 15:56:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48224 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:c906:b0:1a9:af23:56c1 with SMTP id gx6csp2384569pzb; Mon, 22 Apr 2024 08:59:13 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCU4NK2u2NKjIW+PIoVFlS2rU5fkUfkWKxA+DEEuAO6SqxTNy14zoVfGl9eGVu1UbLC2I/UEFqiRJCBQuGlugm/8Lm979dOgvWdSXw== X-Google-Smtp-Source: AGHT+IGcEeWCCzsDLUEAS7xqzR697ImCWz5EisjUNy61OyiWgDiMKSU0VyPUYvlxbl2Md9JX/jv3 X-Received: by 2002:a50:d6c3:0:b0:56f:dabb:ec79 with SMTP id l3-20020a50d6c3000000b0056fdabbec79mr6700188edj.3.1713801553419; Mon, 22 Apr 2024 08:59:13 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1713801553; cv=none; d=google.com; s=arc-20160816; b=EhdOaKTNj76RTqPGtcIbVnRrbZDWeaDYcC+wHOR7+NPtsgc8Z1Uk5tEfBnrPF19kMl uuR26iZV1fIPUvv7IGvb6ELY4B2OVqKkevOECoVyioihTpuAprjeT2AOLMidTnOXHtpl Ky68tIoRmGjdthn/f+pkeS0GN0X761Y5Rg6iSTcFHNlkGUGY2SoHjhjEGmyuZuiFL5mN 6LaGvwOSS/XzgAQRhWxtVvjPhjXUaNRqIdUjKm9sGXejQkf4Ier2x7cFPafnuwSWn+ju 9LqeDZyf/QDisgNefyv9WjHtMVh78XkWF3pycElpWUXAD1GZiqn6aN400CAmCWltaXEm v5mg== 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=0dcmLuRuc9U8hS0SrmTOQjt5Exi6MKPs5NeJd4hB1yk=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=UJ0rmywwY+4IhrqvYC39sl3HoAqUFeUaOTw9+Qs1amyC4DJOErC6oT1XczF/Z89tde 5FLSXUI0s/C6mfen7KVryJtHdDhgeIYpLHTArQ2V3LqbMH9JxUpW2zNuYfEr2k9s1iui hsIQMpbOx944DG+4i27K5CaUK6QCfSXP4hLY0wVO6vB48KSeJ5RMWpkAOn/AV/N/4k41 NPzXYsbQjUsDPYuE5QozbSNPHmwnAix/+5MKysKvDf7GLgg7v5e1n9mJUwq/S0X6o6gP 096GdjaAJB9lvGOAOjQqZ2kuJzx588mifYBzlFF7m9F6qG1qa9NiphGLTNqdOHeTPtNW MsMQ==; 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 26-20020a508e1a000000b0056e1193a35dsi5773047edw.257.2024.04.22.08.59.13; Mon, 22 Apr 2024 08:59:13 -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 3253C68D35C; Mon, 22 Apr 2024 18:58:52 +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 5216A68D18B for ; Mon, 22 Apr 2024 18:58:43 +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 1ryw43-00B6rX-0j; Mon, 22 Apr 2024 16:58:42 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Mon, 22 Apr 2024 16:56:49 +0100 Message-ID: <20240422155836.385333-3-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> References: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v3 2/3] 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: 2vzuvrb6jXSJ --- 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 e6013662f6..b817d15554 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 Mon Apr 22 15:56:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 48225 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:c906:b0:1a9:af23:56c1 with SMTP id gx6csp2384649pzb; Mon, 22 Apr 2024 08:59:22 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCVlJzX/9qU601d6gIO5YlM9aZIATNZ3kxYuEenGGaF0LsAXGSb+TqGGkJXywy/hBlmCBk2OWDYce5fpBJ3jCNk+FTbMhShr0KJpfg== X-Google-Smtp-Source: AGHT+IEz+5YB2u0PsUIjxeuh20jYSQ56oXDAo+X4dmUyEYQcryubvG3uRO3RhtYGWsYceZ+JAxHQ X-Received: by 2002:a50:ccd7:0:b0:56e:edc:9837 with SMTP id b23-20020a50ccd7000000b0056e0edc9837mr10052467edj.35.1713801562205; Mon, 22 Apr 2024 08:59:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1713801562; cv=none; d=google.com; s=arc-20160816; b=wc3T6KDGb2C9s8sTZGgmi+FK68KgGYEPZs/ZGp2tmxMWOIQ/jHQXPeRwCenXp9oDdU wCLwdYEalbF7jsKs0GplNBn0lbB0cXie8rTNUuMghSz8qm2ve2ZB68bdJ+Y133zv5K6c jrPPgo4Fb1UZGsJucJ50rcl6BJrwKhsYnU8ficrhOzNMI6wZgkRi0kT4kFkE/PfpR3uC 7pDQLVKDu2XMvNpsAuZNM7pKgdEpsV2+yItcyPbL3ml1IcNCjFmdX5mJSUYevPXW9GNo e1XqJVy9+FcrnTUXVHLKRXoKTfU+wUxbZYjPjaYeOjCSANdqG0GI1NoQfZ+puCLhgsFD DTjA== 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=21wLbixRqC8NNaxp6M6vMagMWtRkUHPMNSn32OGG6IU=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=iZcW8OTvsZgxQl4SXQoQ0n0DoencfnsRQJOssgswp1mpDMV3mvJfH+AGKJsvFLnXXc K80tySGKdcKlLjZYhaO+QXj8tuyEALlGAPLhHiopuk/V1KWe+UqixI32jEmQdwwnPuFF gwBye5C+6oWJnqZyTaJ9/Okl01cnTZeHo1B+5tqdcB59Q3fOIi1mmpVep/GQlkf11QR+ PXbw8oCM+tdZ6Obv9vDEANHEwTS1CKiDr2M0aQO16WGjmmQXMH1BZXctb5RZXvpnJsIi hWSJs0lhcmyWqyIVjBxabpbMEj+6FihvWr2vxSp+2AATGfzGVyNNHb5DOVPGal+1Ocif t33Q==; 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 b26-20020aa7df9a000000b00571b650402csi5993990edy.63.2024.04.22.08.59.21; Mon, 22 Apr 2024 08:59: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 6F08368D367; Mon, 22 Apr 2024 18:58:53 +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 E75CE68D18B for ; Mon, 22 Apr 2024 18:58:43 +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 1ryw43-00B6rX-1f; Mon, 22 Apr 2024 16:58:43 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Mon, 22 Apr 2024 16:56:50 +0100 Message-ID: <20240422155836.385333-4-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> References: <20240422155836.385333-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v3 3/3] 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: DhIR/ZXVauO4 Some headings needed to be rewritten to accomodate the text, (hopefully) without changing the meaning. --- libavcodec/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/d3d11va.h | 3 +-- libavcodec/mediacodec.h | 2 +- libavcodec/qsv.h | 6 ++++-- libavcodec/sbr.h | 2 +- libavcodec/vdpau.h | 3 ++- libavcodec/videotoolbox.h | 5 +++-- libavfilter/avfilter.h | 2 +- libavformat/avformat.h | 3 ++- libavformat/avio.h | 3 ++- 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 ++-- 28 files changed, 57 insertions(+), 48 deletions(-) diff --git a/libavcodec/aacdec.h b/libavcodec/aacdec.h index 1b245f9258..715886ae07 100644 --- a/libavcodec/aacdec.h +++ b/libavcodec/aacdec.h @@ -181,7 +181,7 @@ typedef struct DynamicRangeControl { } DynamicRangeControl; /** - * main AAC decoding context + * main AAC decoding @ref md_doc_2context "context" */ typedef struct AACDecContext { const struct AVClass *class; diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h index 8899f90ac7..755f0495a2 100644 --- a/libavcodec/aacenc.h +++ b/libavcodec/aacenc.h @@ -193,7 +193,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 968009a192..9180fedca7 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/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/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/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/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/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 { /**