On Thu, May 02, 2024 at 09:00:42PM +0800, Zhao Zhili wrote:
>
>
> > On May 2, 2024, at 19:01, Lynne <d...@lynne.ee> wrote:
> >
> > Apr 29, 2024, 11:24 by ffmpeg-de...@pileofstuff.org:
> >
> >> 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 4cf764e2e9..71d61813f4 100644
> >> --- a/libavcodec/aac/aacdec.h
> >> +++ b/libavcodec/aac/aacdec.h
> >> @@ -248,7 +248,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 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/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 <stdint.h>
> >>
> >> /**
> >> - * 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 <d3d12video.h>
> >>
> >> /**
> >> - * @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 <dxva2api.h>
> >>
> >> /**
> >> - * 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 <stdint.h>
> >>
> >> /**
> >> - * 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.
> >>
> >
> > Could you at least not put "context" in quotation marks?
> > To be honest, I'm not sure this makes documentation any better.
> > A context is an essential term we use in our codebase that's pretty
> > universal. Explaining again and again at every mention is annoying.
>
> +1. I don’t think “context" is specific to FFmpeg, it’s like common naming
> conventions.
Ooh, I don't suppose you've got some examples? I know some other C
projects use similar concepts, but a compatible use of the word
"context" would really help explain things to newbies.
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
