| Message ID | 20240604144919.213799-4-ffmpeg-devel@pileofstuff.org |
|---|---|
| State | New |
| Headers | show |
| Series | doc: Explain what "context" means | expand |
| Context | Check | Description |
|---|---|---|
| yinshiyou/make_loongarch64 | success | Make finished |
| yinshiyou/make_fate_loongarch64 | success | Make fate finished |
| andriy/make_x86 | success | Make finished |
| andriy/make_fate_x86 | success | Make fate finished |
Quoting Andrew Sayers (2024-06-04 16:47:23) > The goal of putting these links in "@see" blocks is to provide hooks > for future developers to add links to other useful parts of the codebase. > --- > libavcodec/avcodec.h | 3 +++ > libavcodec/bsf.h | 3 +++ > libavcodec/d3d11va.h | 3 +++ > libavcodec/mediacodec.h | 2 ++ > libavcodec/qsv.h | 3 +++ > libavcodec/vdpau.h | 3 +++ > libavcodec/videotoolbox.h | 3 +++ > libavfilter/avfilter.h | 7 ++++++- > libavformat/avformat.h | 3 +++ > libavformat/avio.h | 3 +++ > libavutil/audio_fifo.h | 3 +++ > libavutil/hwcontext.h | 6 ++++++ > libavutil/hwcontext_cuda.h | 3 +++ > libavutil/hwcontext_d3d11va.h | 6 ++++++ > libavutil/hwcontext_d3d12va.h | 6 ++++++ > libavutil/hwcontext_drm.h | 3 +++ > libavutil/hwcontext_dxva2.h | 6 ++++++ > libavutil/hwcontext_mediacodec.h | 3 +++ > libavutil/hwcontext_opencl.h | 6 ++++++ > libavutil/hwcontext_qsv.h | 6 ++++++ > libavutil/hwcontext_vaapi.h | 6 ++++++ > libavutil/hwcontext_vdpau.h | 3 +++ > libavutil/hwcontext_vulkan.h | 6 ++++++ > libavutil/lfg.h | 3 +++ > 24 files changed, 98 insertions(+), 1 deletion(-) IMO this is pointless churn.
Note: I somehow managed to send this message directly to Anton before - sorry Anton for the message spam, please reply to this one if you want the list to see it! On Wed, Jun 05, 2024 at 10:12:47AM +0200, Anton Khirnov wrote: > Quoting Andrew Sayers (2024-06-04 16:47:23) > > The goal of putting these links in "@see" blocks is to provide hooks > > for future developers to add links to other useful parts of the codebase. > > --- > > libavcodec/avcodec.h | 3 +++ > > libavcodec/bsf.h | 3 +++ > > libavcodec/d3d11va.h | 3 +++ > > libavcodec/mediacodec.h | 2 ++ > > libavcodec/qsv.h | 3 +++ > > libavcodec/vdpau.h | 3 +++ > > libavcodec/videotoolbox.h | 3 +++ > > libavfilter/avfilter.h | 7 ++++++- > > libavformat/avformat.h | 3 +++ > > libavformat/avio.h | 3 +++ > > libavutil/audio_fifo.h | 3 +++ > > libavutil/hwcontext.h | 6 ++++++ > > libavutil/hwcontext_cuda.h | 3 +++ > > libavutil/hwcontext_d3d11va.h | 6 ++++++ > > libavutil/hwcontext_d3d12va.h | 6 ++++++ > > libavutil/hwcontext_drm.h | 3 +++ > > libavutil/hwcontext_dxva2.h | 6 ++++++ > > libavutil/hwcontext_mediacodec.h | 3 +++ > > libavutil/hwcontext_opencl.h | 6 ++++++ > > libavutil/hwcontext_qsv.h | 6 ++++++ > > libavutil/hwcontext_vaapi.h | 6 ++++++ > > libavutil/hwcontext_vdpau.h | 3 +++ > > libavutil/hwcontext_vulkan.h | 6 ++++++ > > libavutil/lfg.h | 3 +++ > > 24 files changed, 98 insertions(+), 1 deletion(-) > > IMO this is pointless churn. That's like saying caches are pointless bloat - it's not about correctness, it's about performance. Actually, I've been talking about "performance" a lot round here, but not really explained what I mean... Imagine a smart young developer who learned C at university and is now dipping their toe in the world of actual C development. They've come up with an idea for a little app that's different enough from the examples to force themselves not to just copy/paste example code. It's simple enough that an experienced developer like you would only need half a day for the whole project, so they allow themselves a weekend to get it done. "Performance" in this case means "can they finish the project in their ~16 hour time budget?" Assuming they're half as productive as you would be, 8 of their 16 hours go on programming, leaving 8 hours to learn FFmpeg. They've never written real-world C before, so they don't know what a context is. And they only have a narrow understanding of OOP, so as soon as they see words like "object" and "class", they assume you're referring to the precise version of OOP their Java lecturer taught them about. So the longer they spend poking round looking for information, the more misconceptions they're going to develop. Even if we assume they find the context document after one hour of searching, they fully understand the document with no reading time, and only need one extra hour to unlearn the misconceptions they developed, that's still cost a quarter of their remaining time budget. To an expert, these links are unnecessary verbiage pointing to a document that explains things that are blindingly obvious. But to a newbie, they're an important optimisation that can make the difference between finishing a project or having to give up on FFmpeg altogether.
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 2da63c87ea..abc00ab394 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -441,6 +441,9 @@ typedef struct RcOverride{ * The AVOption/command line parameter names differ in some cases from the C * structure field names for historic reasons or brevity. * sizeof(AVCodecContext) must not be used outside libav*. + * + * @see + * - @ref Context */ typedef struct AVCodecContext { /** diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h index a09c69f242..ee5fdd48d2 100644 --- a/libavcodec/bsf.h +++ b/libavcodec/bsf.h @@ -64,6 +64,9 @@ * The fields in the struct will only be changed (by the caller or by the * filter) as described in their documentation, and are to be considered * immutable otherwise. + * + * @see + * - @ref Context */ typedef struct AVBSFContext { /** diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h index 27f40e5519..686974b083 100644 --- a/libavcodec/d3d11va.h +++ b/libavcodec/d3d11va.h @@ -52,6 +52,9 @@ * The application must make it available as AVCodecContext.hwaccel_context. * * Use av_d3d11va_alloc_context() exclusively to allocate an AVD3D11VAContext. + * + * @see + * - @ref Context */ typedef struct AVD3D11VAContext { /** diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h index 4e9b56a618..43f049a609 100644 --- a/libavcodec/mediacodec.h +++ b/libavcodec/mediacodec.h @@ -29,6 +29,8 @@ * This structure holds a reference to a android/view/Surface object that will * be used as output by the decoder. * + * @see + * - @ref Context */ typedef struct AVMediaCodecContext { diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h index c156b08d07..8ab93af6b6 100644 --- a/libavcodec/qsv.h +++ b/libavcodec/qsv.h @@ -32,6 +32,9 @@ * - decoding: hwaccel_context must be set on return from the get_format() * callback * - encoding: hwaccel_context must be set before avcodec_open2() + * + * @see + * - @ref Context */ typedef struct AVQSVContext { /** diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h index 8021c25761..934c96b88c 100644 --- a/libavcodec/vdpau.h +++ b/libavcodec/vdpau.h @@ -74,6 +74,9 @@ typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *, * * The size of this structure is not a part of the public ABI and must not * be used outside of libavcodec. + * + * @see + * - @ref Context */ typedef struct AVVDPAUContext { /** diff --git a/libavcodec/videotoolbox.h b/libavcodec/videotoolbox.h index d68d76e400..81d90d63b6 100644 --- a/libavcodec/videotoolbox.h +++ b/libavcodec/videotoolbox.h @@ -53,6 +53,9 @@ * between the caller and libavcodec for initializing Videotoolbox decoding. * Its size is not a part of the public ABI, it must be allocated with * av_videotoolbox_alloc_context() and freed with av_free(). + * + * @see + * - @ref Context */ typedef struct AVVideotoolboxContext { /** diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h index a34e61f23c..25ccd80433 100644 --- a/libavfilter/avfilter.h +++ b/libavfilter/avfilter.h @@ -403,7 +403,12 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output); */ #define AVFILTER_THREAD_SLICE (1 << 0) -/** An instance of a filter */ +/** + * An instance of a filter + * + * @see + * - @ref Context + */ struct AVFilterContext { const AVClass *av_class; ///< needed for av_log() and filters common options diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 8afdcd9fd0..18f20f0bb0 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -1253,6 +1253,9 @@ enum AVDurationEstimationMethod { * can be found in libavformat/options_table.h. * The AVOption/command line parameter names differ in some cases from the C * structure field names for historic reasons or brevity. + * + * @see + * - @ref Context */ typedef struct AVFormatContext { /** diff --git a/libavformat/avio.h b/libavformat/avio.h index ebf611187d..d68f912a2f 100644 --- a/libavformat/avio.h +++ b/libavformat/avio.h @@ -156,6 +156,9 @@ enum AVIODataMarkerType { * directly, they should only be set by the client application * when implementing custom I/O. Normally these are set to the * function pointers specified in avio_alloc_context() + * + * @see + * - @ref Context */ typedef struct AVIOContext { /** diff --git a/libavutil/audio_fifo.h b/libavutil/audio_fifo.h index fa5f59a2be..6fdb114af8 100644 --- a/libavutil/audio_fifo.h +++ b/libavutil/audio_fifo.h @@ -44,6 +44,9 @@ * - Operates at the sample level rather than the byte level. * - Supports multiple channels with either planar or packed sample format. * - Automatic reallocation when writing to a full buffer. + * + * @see + * - @ref Context */ typedef struct AVAudioFifo AVAudioFifo; diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h index bac30debae..6bbb96fcd6 100644 --- a/libavutil/hwcontext.h +++ b/libavutil/hwcontext.h @@ -56,6 +56,9 @@ enum AVHWDeviceType { * references are released, the AVHWDeviceContext itself will be freed, * optionally invoking a user-specified callback for uninitializing the hardware * state. + * + * @see + * - @ref Context */ typedef struct AVHWDeviceContext { /** @@ -111,6 +114,9 @@ typedef struct AVHWDeviceContext { * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor * yields a reference, whose data field points to the actual AVHWFramesContext * struct. + * + * @see + * - @ref Context */ typedef struct AVHWFramesContext { /** diff --git a/libavutil/hwcontext_cuda.h b/libavutil/hwcontext_cuda.h index cbad434fea..0db5a69f0a 100644 --- a/libavutil/hwcontext_cuda.h +++ b/libavutil/hwcontext_cuda.h @@ -38,6 +38,9 @@ typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal; /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVCUDADeviceContext { CUcontext cuda_ctx; diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h index 77d2d72f1b..5b7763e73f 100644 --- a/libavutil/hwcontext_d3d11va.h +++ b/libavutil/hwcontext_d3d11va.h @@ -41,6 +41,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVD3D11VADeviceContext { /** @@ -127,6 +130,9 @@ typedef struct AVD3D11FrameDescriptor { /** * This struct is allocated as AVHWFramesContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVD3D11VAFramesContext { /** diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h index ff06e6f2ef..63281aa835 100644 --- a/libavutil/hwcontext_d3d12va.h +++ b/libavutil/hwcontext_d3d12va.h @@ -39,6 +39,8 @@ /** * @brief This struct is allocated as AVHWDeviceContext.hwctx * + * @see + * - @ref Context */ typedef struct AVD3D12VADeviceContext { /** @@ -80,6 +82,8 @@ typedef struct AVD3D12VADeviceContext { /** * @brief This struct is used to sync d3d12 execution * + * @see + * - @ref Context */ typedef struct AVD3D12VASyncContext { /** @@ -122,6 +126,8 @@ typedef struct AVD3D12VAFrame { /** * @brief This struct is allocated as AVHWFramesContext.hwctx * + * @see + * - @ref Context */ typedef struct AVD3D12VAFramesContext { /** diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h index 42709f215e..eb0b6e734a 100644 --- a/libavutil/hwcontext_drm.h +++ b/libavutil/hwcontext_drm.h @@ -153,6 +153,9 @@ typedef struct AVDRMFrameDescriptor { * DRM device. * * Allocated as AVHWDeviceContext.hwctx. + * + * @see + * - @ref Context */ typedef struct AVDRMDeviceContext { /** diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h index e1b79bc0de..3accd8d070 100644 --- a/libavutil/hwcontext_dxva2.h +++ b/libavutil/hwcontext_dxva2.h @@ -35,6 +35,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVDXVA2DeviceContext { IDirect3DDeviceManager9 *devmgr; @@ -42,6 +45,9 @@ typedef struct AVDXVA2DeviceContext { /** * This struct is allocated as AVHWFramesContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVDXVA2FramesContext { /** diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h index fc0263cabc..77d7d4e3a5 100644 --- a/libavutil/hwcontext_mediacodec.h +++ b/libavutil/hwcontext_mediacodec.h @@ -23,6 +23,9 @@ * MediaCodec details. * * Allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVMediaCodecDeviceContext { /** diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h index ef54486c95..4c184484c9 100644 --- a/libavutil/hwcontext_opencl.h +++ b/libavutil/hwcontext_opencl.h @@ -59,6 +59,9 @@ typedef struct AVOpenCLFrameDescriptor { * OpenCL device details. * * Allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVOpenCLDeviceContext { /** @@ -85,6 +88,9 @@ typedef struct AVOpenCLDeviceContext { * OpenCL-specific data associated with a frame pool. * * Allocated as AVHWFramesContext.hwctx. + * + * @see + * - @ref Context */ typedef struct AVOpenCLFramesContext { /** diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h index 35530e4e93..b4a84c9893 100644 --- a/libavutil/hwcontext_qsv.h +++ b/libavutil/hwcontext_qsv.h @@ -31,6 +31,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVQSVDeviceContext { mfxSession session; @@ -49,6 +52,9 @@ typedef struct AVQSVDeviceContext { /** * This struct is allocated as AVHWFramesContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVQSVFramesContext { /** diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h index 0b2e071cb3..02399ff7dc 100644 --- a/libavutil/hwcontext_vaapi.h +++ b/libavutil/hwcontext_vaapi.h @@ -64,6 +64,9 @@ enum { * VAAPI connection details. * * Allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVVAAPIDeviceContext { /** @@ -84,6 +87,9 @@ typedef struct AVVAAPIDeviceContext { * VAAPI-specific data associated with a frame pool. * * Allocated as AVHWFramesContext.hwctx. + * + * @see + * - @ref Context */ typedef struct AVVAAPIFramesContext { /** diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h index 1b7ea1e443..051af42dfc 100644 --- a/libavutil/hwcontext_vdpau.h +++ b/libavutil/hwcontext_vdpau.h @@ -31,6 +31,9 @@ /** * This struct is allocated as AVHWDeviceContext.hwctx + * + * @see + * - @ref Context */ typedef struct AVVDPAUDeviceContext { VdpDevice device; diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h index cbbd2390c1..6dfe4badfe 100644 --- a/libavutil/hwcontext_vulkan.h +++ b/libavutil/hwcontext_vulkan.h @@ -41,6 +41,9 @@ typedef struct AVVkFrame AVVkFrame; /** * Main Vulkan context, allocated as AVHWDeviceContext.hwctx. * All of these can be set before init to change what the context uses + * + * @see + * - @ref Context */ typedef struct AVVulkanDeviceContext { /** @@ -173,6 +176,9 @@ typedef enum AVVkFrameFlags { /** * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options + * + * @see + * - @ref Context */ typedef struct AVVulkanFramesContext { /** diff --git a/libavutil/lfg.h b/libavutil/lfg.h index e75a986f12..4e420b0e16 100644 --- a/libavutil/lfg.h +++ b/libavutil/lfg.h @@ -29,6 +29,9 @@ * The exact layout, types and content of this struct may change and should * not be accessed directly. Only its `sizeof()` is guaranteed to stay the same * to allow easy instanciation. + * + * @see + * - @ref Context */ typedef struct AVLFG { unsigned int state[64];