| Message ID | 20240429092407.2267590-3-ffmpeg-devel@pileofstuff.org |
|---|---|
| State | New |
| Headers | show |
| Series | [FFmpeg-devel,v4,1/4] doc: Explain what "context" means | expand |
| Context | Check | Description |
|---|---|---|
| yinshiyou/make_loongarch64 | success | Make finished |
| yinshiyou/make_fate_loongarch64 | success | Make fate finished |
Apr 29, 2024, 11:24 by ffmpeg-devel@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.
On Thu, May 02, 2024 at 01:01:43PM +0200, Lynne wrote: > Apr 29, 2024, 11:24 by ffmpeg-devel@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. I'll check when I get back, but sadly the documentation implies quotation marks are mandatory[0]. FWIW, it's rendered without quotes in the final documentation. I don't really follow the second part - surely if it's essential for readers to understand, and it's not common enough outside of FFmpeg that they can be assumed to already know it, there need to be links everywhere in order for the documentation to be any use to new readers? [0] https://www.doxygen.nl/manual/commands.html#cmdref
> On May 2, 2024, at 19:01, Lynne <dev@lynne.ee> wrote: > > Apr 29, 2024, 11:24 by ffmpeg-devel@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. > _______________________________________________ > 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".
On Thu, May 02, 2024 at 09:00:42PM +0800, Zhao Zhili wrote: > > > > On May 2, 2024, at 19:01, Lynne <dev@lynne.ee> wrote: > > > > Apr 29, 2024, 11:24 by ffmpeg-devel@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.
> On May 2, 2024, at 21:27, Andrew Sayers <ffmpeg-devel@pileofstuff.org> wrote: > > On Thu, May 02, 2024 at 09:00:42PM +0800, Zhao Zhili wrote: >> >> >>> On May 2, 2024, at 19:01, Lynne <dev@lynne.ee> wrote: >>> >>> Apr 29, 2024, 11:24 by ffmpeg-devel@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? Curl, libxml2, libevent. > 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 <mailto:ffmpeg-devel@ffmpeg.org> > https://ffmpeg.org/mailman/listinfo/ffmpeg-devel > > To unsubscribe, visit link above, or email > ffmpeg-devel-request@ffmpeg.org <mailto:ffmpeg-devel-request@ffmpeg.org> with subject "unsubscribe".
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.