From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 8EC3E49823 for ; Sat, 20 Apr 2024 07:26:04 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id F011668D1BE; Sat, 20 Apr 2024 10:26:01 +0300 (EEST) Received: from mail-ej1-f54.google.com (mail-ej1-f54.google.com [209.85.218.54]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id CE0A868CDFE for ; Sat, 20 Apr 2024 10:25:55 +0300 (EEST) Received: by mail-ej1-f54.google.com with SMTP id a640c23a62f3a-a559bbdb7b4so20012166b.1 for ; Sat, 20 Apr 2024 00:25:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1713597955; x=1714202755; darn=ffmpeg.org; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date:from:to:cc :subject:date:message-id:reply-to; bh=Np1lIA3tST3A9iI26d5v2R13HvrT81r0RUZS9Akyru4=; b=LbZs5bN5E3k7c+tiChdiwpoHYMI1q/TASb7uk2aSeq/RQRl4/l5I+z/IYB2S+mvmpu 5paKZPw7lum8rSQl7V7zlSrmo0QPPK0wpeb1vBd4iWJoM10iNoLrI5WcYwX6ITEJWWwW SAJZEb5+iCMyDppQQ3IVJknHuSJBPNG0E5oNQhA4ulTraIAI1pydr0efKBh/67tX0xlY NTeIlv8yHZI1x9oGCZ5f7b9NfAkZCVkAs+R7AFMxC2UR2CrpBdR/CzE2y8mjhjjFFtd6 6ZlAAhI/XZ5S7wh/wgFwJ4C1AqG7AAmYxRFHnJtKK+e5+R/q2Wh91Cc7/HwijAcvu4tM C60w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713597955; x=1714202755; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=Np1lIA3tST3A9iI26d5v2R13HvrT81r0RUZS9Akyru4=; b=isZgrWj5yfQ/sWEBdOgXnR0K42p4XGE6b92qRf/sEvrE6j0ey4b2rwsiFGONx5qzyg oBYmpW80ngSVGi6T8qMn6B+L0dT8dquWEBoI/B7P1cC28b24/DUGtQ1f/Mf6ZdpP/91q 59FpQj4mK9EVDETzN//9/JEJKaaakw5NPBM7dRt3h03niyQVcSQ5k/PAZRti5c6qgy4M 771E649QL6p4TdT9Tn010KomWisD1nW8z2kwshDPdd0ZY1gjbGGAU6OrP01MEDJUOpzR ehJSU3I97RFnWA0n0PBsuZkcJvJhp/9Qnlazt2YTFNADrnJXPGbPBJtaNHm0NYb8Jfnx 2Vdw== X-Gm-Message-State: AOJu0Yyayvun5mNIu3OvArb5n6AsT0vcftZiDIoDIsg0WG5RKXI+pbgw BEbDDE1d/JWbzcf3VaTGkDzAF/5FjGKm9zw/zLTmHJfqQtf2JOwQUE72Hg== X-Google-Smtp-Source: AGHT+IHAl7EgpCzaLBwxvQpK5bVQ9ZSFAD0v9qLfTON/67wYt46a22ELb+5SWcq2ox1tQphrv1I9ow== X-Received: by 2002:a17:906:c2d7:b0:a55:3f2f:4b40 with SMTP id ch23-20020a170906c2d700b00a553f2f4b40mr2647269ejb.68.1713597954394; Sat, 20 Apr 2024 00:25:54 -0700 (PDT) Received: from mariano (host-87-17-49-61.retail.telecomitalia.it. [87.17.49.61]) by smtp.gmail.com with ESMTPSA id jr13-20020a170906a98d00b00a4e03823107sm3054408ejb.210.2024.04.20.00.25.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 20 Apr 2024 00:25:53 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id 19D05BFCE8; Sat, 20 Apr 2024 09:25:52 +0200 (CEST) Date: Sat, 20 Apr 2024 09:25:52 +0200 From: Stefano Sabatini To: FFmpeg development discussions and patches Message-ID: Mail-Followup-To: FFmpeg development discussions and patches , Andrew Sayers References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> User-Agent: Mutt/2.1.4 (2021-12-11) Subject: Re: [FFmpeg-devel] [PATCH 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 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: On date Thursday 2024-04-18 16:06:12 +0100, Andrew Sayers wrote: > Based largely on the explanation by Stefano Sabatini: > https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325854.html > --- > doc/jargon.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 96 insertions(+) > create mode 100644 doc/jargon.md > > diff --git a/doc/jargon.md b/doc/jargon.md > new file mode 100644 > index 0000000000..3b78ffb61f > --- /dev/null > +++ b/doc/jargon.md We currently have a single .md file in doc (for historical reason we still stick to texinfo). Also how is this integrated into doxygen? > @@ -0,0 +1,96 @@ > +# Jargon > + > +Terms used throughout the code that developers may need to know. > + > +@anchor context > + > +## Context > + > +A design pattern that stores the context (e.g. configuration) for a series > +of operations in a "context" structure, and moves other information elsewhere. > + > +Consider a trivial program to print uppercase text: > + > +```c > +/* > + * Contextual information about where to print a series of messages > + */ Style: /** * Contextual information about where to print a series of messages */ > +struct UpperCasePrinterContext { > + FILE* out; here and below, use: VAR *out; for overall consistency with the project style. > +}; > + > +/* > + * Extra information about messages to print. > + * This could be used multiple times in a single context, > + * or reused several times across multiple contexts. > + */ > +struct PrintInfo { > + char* str; > +}; > + > +void print( > + struct UpperCasePrinterContext * ctx, > + struct PrintInfo * info > +) { > + for ( char* c = info->str; *c; ++c ) { > + char C = toupper(*c); > + fwrite( &C, 1, 1, ctx->out ); > + } > +} > + > +int main() > +{ > + struct PrintInfo hello, world; > + struct UpperCasePrinterContext ctx; > + > + hello.str = "hello, "; > + world.str = "world!\n"; > + > + ctx.out = stdout; > + > + print( &ctx, &hello ); > + print( &ctx, &world ); > + > + return 0; > +} I'm not sure this is a fitting example. Usually the context is a public structure and the internal context (which corresponds to the PrintInfo struct) is private to the implementation. In this case the API user is not interested at all at its implmentation. You can think the context provides the "object"/instance where some operations are done - this is alike in object oriented programming, where the context corresponds to the self, so that you create/allocate the object, initialize it, and invoke operations on the object. So using this analogy, the example would be: struct UpperCasePrinterContext {...}; // this corresponds to a "method" defined on the context/object void uppercase_printer_print(UpperCasePrinterContext *ctx, const char *str); Or maybe you want to define the property in the context itself, so you do: uppercase_ctx.str = "foobar"; then you have: void uppercase_printer_print(UpperCasePrinterContext *ctx); On a typical FFmpeg context you typically do (see doc/examples/encode.c example): // create the context c = avcodec_alloc_context3(codec); // set parameters, either in the context or by using the av_opt API c->bit_rate = 400000; c->width = 352; c->height = 288; c->time_base = (AVRational){1, 25}; c->framerate = (AVRational){25, 1}; // ... // invoke the methods defined in the context ret = avcodec_send_frame(enc_ctx, frame); if (ret < 0) { fprintf(stderr, "Error sending a frame for encoding\n"); exit(1); } while (ret >= 0) { ret = avcodec_receive_packet(enc_ctx, pkt); if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) return; else if (ret < 0) { fprintf(stderr, "Error during encoding\n"); exit(1); } ... av_packet_unref(pkt); } [...] Note also that "context" in the FFmpeg jargon is not very specific because it might be different depending on the implementation, for example it might not have an av_opt_* interface (for example libavutil/hash.h). > +``` > + > +The `UpperCasePrinterContext` object contains the information that's about > +the context of the current job (i.e. printing things to standard output). I find this confusing, it is essentially saying that the context (the "object") is the context of the current job. > +Information with a lifetime different than that of the context is moved > +to the `PrintInfo` object. > + > +FFmpeg's main context structures all happen to face some common problems: > + > +- querying, setting and getting options > +- handling "private" internal context, including options for > + a particular instance of the generic context > +- configuring log message verbosity and content > + > +FFmpeg gradually converged on the AVClass struct to store this information, > +then converged on the @ref avoptions "AVOptions" system to manipulate it, > +so modern code often uses the terms "context", "AVClass context structure" > +and "AVOptions-enabled struct" interchangeably. But it is occasionally > +necessary to distinguish between them - for example, AVMediaCodecContext > +is a context that does not use AVClass. > + > +To understand how this all works, consider some requirements for the > +`libx264` encoder: > + > +- it has to support common encoder options like "bitrate" > +- it has to support encoder-specific options like "profile" > +- it has to provide useful feedback about unsupported options > + > +Common encoder options like "bitrate" are stored in the AVCodecContext class, > +while encoder-specific options like "profile" are stored in an X264Context > +instance in AVCodecContext::priv_data. These options are then exposed to > +users through a tree of AVOption objects, which include user-visible help > +text and machine-readable information about the memory location to read/write > +each option. Common @ref avoptions "AVOptions" functionality lets you get > +and set those values, and provides readable feedback about errors. > Although X264Context can be set by users, Can it? The X264Context is defined within the implementation, so it is not exposed to the user, the only way to set it is through the private options to be set through the AVCodecContext options through the av_opt API - in other words you cannot set the context directly as you do with the "generic" options defined in the AVCodecContext. > it is not part of the public interface, so new releases can modify > it without affecting the API version. [...] _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".