[FFmpeg-devel] [PATCH v5 3/4] all: Link to "context" from all public contexts with documentation

From: Andrew Sayers <ffmpeg-devel@pileofstuff.org>
To: ffmpeg-devel@ffmpeg.org
Cc: Andrew Sayers <ffmpeg-devel@pileofstuff.org>
Subject: [FFmpeg-devel] [PATCH v5 3/4] all: Link to "context" from all public contexts with documentation
Date: Thu, 23 May 2024 21:00:42 +0100
Message-ID: <20240523200116.740461-4-ffmpeg-devel@pileofstuff.org> (raw)
In-Reply-To: <20240523200116.740461-1-ffmpeg-devel@pileofstuff.org>

The goal of putting these links in "@see" blocks is to provide hooks
for future developers to add links to other useful parts of the codebase.
---
 libavcodec/avcodec.h             | 3 +++
 libavcodec/bsf.h                 | 3 +++
 libavcodec/d3d11va.h             | 3 +++
 libavcodec/mediacodec.h          | 2 ++
 libavcodec/qsv.h                 | 3 +++
 libavcodec/vdpau.h               | 3 +++
 libavcodec/videotoolbox.h        | 3 +++
 libavfilter/avfilter.h           | 7 ++++++-
 libavformat/avformat.h           | 3 +++
 libavformat/avio.h               | 3 +++
 libavutil/audio_fifo.h           | 3 +++
 libavutil/hwcontext.h            | 6 ++++++
 libavutil/hwcontext_cuda.h       | 3 +++
 libavutil/hwcontext_d3d11va.h    | 6 ++++++
 libavutil/hwcontext_d3d12va.h    | 6 ++++++
 libavutil/hwcontext_drm.h        | 3 +++
 libavutil/hwcontext_dxva2.h      | 6 ++++++
 libavutil/hwcontext_mediacodec.h | 3 +++
 libavutil/hwcontext_opencl.h     | 6 ++++++
 libavutil/hwcontext_qsv.h        | 6 ++++++
 libavutil/hwcontext_vaapi.h      | 6 ++++++
 libavutil/hwcontext_vdpau.h      | 3 +++
 libavutil/hwcontext_vulkan.h     | 6 ++++++
 libavutil/lfg.h                  | 3 +++
 24 files changed, 98 insertions(+), 1 deletion(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 2da63c87ea..abc00ab394 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -441,6 +441,9 @@ typedef struct RcOverride{
  * The AVOption/command line parameter names differ in some cases from the C
  * structure field names for historic reasons or brevity.
  * sizeof(AVCodecContext) must not be used outside libav*.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVCodecContext {
     /**
diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
index a09c69f242..ee5fdd48d2 100644
--- a/libavcodec/bsf.h
+++ b/libavcodec/bsf.h
@@ -64,6 +64,9 @@
  * The fields in the struct will only be changed (by the caller or by the
  * filter) as described in their documentation, and are to be considered
  * immutable otherwise.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVBSFContext {
     /**
diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h
index 27f40e5519..686974b083 100644
--- a/libavcodec/d3d11va.h
+++ b/libavcodec/d3d11va.h
@@ -52,6 +52,9 @@
  * The application must make it available as AVCodecContext.hwaccel_context.
  *
  * Use av_d3d11va_alloc_context() exclusively to allocate an AVD3D11VAContext.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVD3D11VAContext {
     /**
diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h
index 4e9b56a618..43f049a609 100644
--- a/libavcodec/mediacodec.h
+++ b/libavcodec/mediacodec.h
@@ -29,6 +29,8 @@
  * This structure holds a reference to a android/view/Surface object that will
  * be used as output by the decoder.
  *
+ * @see
+ * - @ref Context
  */
 typedef struct AVMediaCodecContext {
 
diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h
index c156b08d07..8ab93af6b6 100644
--- a/libavcodec/qsv.h
+++ b/libavcodec/qsv.h
@@ -32,6 +32,9 @@
  * - decoding: hwaccel_context must be set on return from the get_format()
  *             callback
  * - encoding: hwaccel_context must be set before avcodec_open2()
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVQSVContext {
     /**
diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h
index 8021c25761..934c96b88c 100644
--- a/libavcodec/vdpau.h
+++ b/libavcodec/vdpau.h
@@ -74,6 +74,9 @@ typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *,
  *
  * The size of this structure is not a part of the public ABI and must not
  * be used outside of libavcodec.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVDPAUContext {
     /**
diff --git a/libavcodec/videotoolbox.h b/libavcodec/videotoolbox.h
index d68d76e400..81d90d63b6 100644
--- a/libavcodec/videotoolbox.h
+++ b/libavcodec/videotoolbox.h
@@ -53,6 +53,9 @@
  * between the caller and libavcodec for initializing Videotoolbox decoding.
  * Its size is not a part of the public ABI, it must be allocated with
  * av_videotoolbox_alloc_context() and freed with av_free().
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVideotoolboxContext {
     /**
diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h
index a34e61f23c..25ccd80433 100644
--- a/libavfilter/avfilter.h
+++ b/libavfilter/avfilter.h
@@ -403,7 +403,12 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output);
  */
 #define AVFILTER_THREAD_SLICE (1 << 0)
 
-/** An instance of a filter */
+/**
+ * An instance of a filter
+ *
+ * @see
+ * - @ref Context
+ */
 struct AVFilterContext {
     const AVClass *av_class;        ///< needed for av_log() and filters common options
 
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 8afdcd9fd0..18f20f0bb0 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -1253,6 +1253,9 @@ enum AVDurationEstimationMethod {
  * can be found in libavformat/options_table.h.
  * The AVOption/command line parameter names differ in some cases from the C
  * structure field names for historic reasons or brevity.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVFormatContext {
     /**
diff --git a/libavformat/avio.h b/libavformat/avio.h
index ebf611187d..d68f912a2f 100644
--- a/libavformat/avio.h
+++ b/libavformat/avio.h
@@ -156,6 +156,9 @@ enum AVIODataMarkerType {
  *       directly, they should only be set by the client application
  *       when implementing custom I/O. Normally these are set to the
  *       function pointers specified in avio_alloc_context()
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVIOContext {
     /**
diff --git a/libavutil/audio_fifo.h b/libavutil/audio_fifo.h
index fa5f59a2be..6fdb114af8 100644
--- a/libavutil/audio_fifo.h
+++ b/libavutil/audio_fifo.h
@@ -44,6 +44,9 @@
  * - Operates at the sample level rather than the byte level.
  * - Supports multiple channels with either planar or packed sample format.
  * - Automatic reallocation when writing to a full buffer.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVAudioFifo AVAudioFifo;
 
diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h
index bac30debae..6bbb96fcd6 100644
--- a/libavutil/hwcontext.h
+++ b/libavutil/hwcontext.h
@@ -56,6 +56,9 @@ enum AVHWDeviceType {
  * references are released, the AVHWDeviceContext itself will be freed,
  * optionally invoking a user-specified callback for uninitializing the hardware
  * state.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVHWDeviceContext {
     /**
@@ -111,6 +114,9 @@ typedef struct AVHWDeviceContext {
  * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor
  * yields a reference, whose data field points to the actual AVHWFramesContext
  * struct.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVHWFramesContext {
     /**
diff --git a/libavutil/hwcontext_cuda.h b/libavutil/hwcontext_cuda.h
index cbad434fea..0db5a69f0a 100644
--- a/libavutil/hwcontext_cuda.h
+++ b/libavutil/hwcontext_cuda.h
@@ -38,6 +38,9 @@ typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal;
 
 /**
  * This struct is allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVCUDADeviceContext {
     CUcontext cuda_ctx;
diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h
index 77d2d72f1b..5b7763e73f 100644
--- a/libavutil/hwcontext_d3d11va.h
+++ b/libavutil/hwcontext_d3d11va.h
@@ -41,6 +41,9 @@
 
 /**
  * This struct is allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVD3D11VADeviceContext {
     /**
@@ -127,6 +130,9 @@ typedef struct AVD3D11FrameDescriptor {
 
 /**
  * This struct is allocated as AVHWFramesContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVD3D11VAFramesContext {
     /**
diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h
index ff06e6f2ef..63281aa835 100644
--- a/libavutil/hwcontext_d3d12va.h
+++ b/libavutil/hwcontext_d3d12va.h
@@ -39,6 +39,8 @@
 /**
  * @brief This struct is allocated as AVHWDeviceContext.hwctx
  *
+ * @see
+ * - @ref Context
  */
 typedef struct AVD3D12VADeviceContext {
     /**
@@ -80,6 +82,8 @@ typedef struct AVD3D12VADeviceContext {
 /**
  * @brief This struct is used to sync d3d12 execution
  *
+ * @see
+ * - @ref Context
  */
 typedef struct AVD3D12VASyncContext {
     /**
@@ -122,6 +126,8 @@ typedef struct AVD3D12VAFrame {
 /**
  * @brief This struct is allocated as AVHWFramesContext.hwctx
  *
+ * @see
+ * - @ref Context
  */
 typedef struct AVD3D12VAFramesContext {
     /**
diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h
index 42709f215e..eb0b6e734a 100644
--- a/libavutil/hwcontext_drm.h
+++ b/libavutil/hwcontext_drm.h
@@ -153,6 +153,9 @@ typedef struct AVDRMFrameDescriptor {
  * DRM device.
  *
  * Allocated as AVHWDeviceContext.hwctx.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVDRMDeviceContext {
     /**
diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h
index e1b79bc0de..3accd8d070 100644
--- a/libavutil/hwcontext_dxva2.h
+++ b/libavutil/hwcontext_dxva2.h
@@ -35,6 +35,9 @@
 
 /**
  * This struct is allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVDXVA2DeviceContext {
     IDirect3DDeviceManager9 *devmgr;
@@ -42,6 +45,9 @@ typedef struct AVDXVA2DeviceContext {
 
 /**
  * This struct is allocated as AVHWFramesContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVDXVA2FramesContext {
     /**
diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h
index fc0263cabc..77d7d4e3a5 100644
--- a/libavutil/hwcontext_mediacodec.h
+++ b/libavutil/hwcontext_mediacodec.h
@@ -23,6 +23,9 @@
  * MediaCodec details.
  *
  * Allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVMediaCodecDeviceContext {
     /**
diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h
index ef54486c95..4c184484c9 100644
--- a/libavutil/hwcontext_opencl.h
+++ b/libavutil/hwcontext_opencl.h
@@ -59,6 +59,9 @@ typedef struct AVOpenCLFrameDescriptor {
  * OpenCL device details.
  *
  * Allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVOpenCLDeviceContext {
     /**
@@ -85,6 +88,9 @@ typedef struct AVOpenCLDeviceContext {
  * OpenCL-specific data associated with a frame pool.
  *
  * Allocated as AVHWFramesContext.hwctx.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVOpenCLFramesContext {
     /**
diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h
index 35530e4e93..b4a84c9893 100644
--- a/libavutil/hwcontext_qsv.h
+++ b/libavutil/hwcontext_qsv.h
@@ -31,6 +31,9 @@
 
 /**
  * This struct is allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVQSVDeviceContext {
     mfxSession session;
@@ -49,6 +52,9 @@ typedef struct AVQSVDeviceContext {
 
 /**
  * This struct is allocated as AVHWFramesContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVQSVFramesContext {
     /**
diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h
index 0b2e071cb3..02399ff7dc 100644
--- a/libavutil/hwcontext_vaapi.h
+++ b/libavutil/hwcontext_vaapi.h
@@ -64,6 +64,9 @@ enum {
  * VAAPI connection details.
  *
  * Allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVAAPIDeviceContext {
     /**
@@ -84,6 +87,9 @@ typedef struct AVVAAPIDeviceContext {
  * VAAPI-specific data associated with a frame pool.
  *
  * Allocated as AVHWFramesContext.hwctx.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVAAPIFramesContext {
     /**
diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h
index 1b7ea1e443..051af42dfc 100644
--- a/libavutil/hwcontext_vdpau.h
+++ b/libavutil/hwcontext_vdpau.h
@@ -31,6 +31,9 @@
 
 /**
  * This struct is allocated as AVHWDeviceContext.hwctx
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVDPAUDeviceContext {
     VdpDevice          device;
diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h
index cbbd2390c1..6dfe4badfe 100644
--- a/libavutil/hwcontext_vulkan.h
+++ b/libavutil/hwcontext_vulkan.h
@@ -41,6 +41,9 @@ typedef struct AVVkFrame AVVkFrame;
 /**
  * Main Vulkan context, allocated as AVHWDeviceContext.hwctx.
  * All of these can be set before init to change what the context uses
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVulkanDeviceContext {
     /**
@@ -173,6 +176,9 @@ typedef enum AVVkFrameFlags {
 
 /**
  * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVVulkanFramesContext {
     /**
diff --git a/libavutil/lfg.h b/libavutil/lfg.h
index e75a986f12..4e420b0e16 100644
--- a/libavutil/lfg.h
+++ b/libavutil/lfg.h
@@ -29,6 +29,9 @@
  * The exact layout, types and content of this struct may change and should
  * not be accessed directly. Only its `sizeof()` is guaranteed to stay the same
  * to allow easy instanciation.
+ *
+ * @see
+ * - @ref Context
  */
 typedef struct AVLFG {
     unsigned int state[64];
-- 
2.43.0

_______________________________________________
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".
