diff mbox series

[FFmpeg-devel,1/2] lavc: fix and extend AVCodecContext.hwaccel_context doxy

Message ID 20220903183930.9223-1-anton@khirnov.net
State Accepted
Commit 0a811f8f944ae051a5e50c1435eae5eb272ef0b4
Headers show
Series [FFmpeg-devel,1/2] lavc: fix and extend AVCodecContext.hwaccel_context doxy | expand

Checks

Context Check Description
yinshiyou/make_loongarch64 success Make finished
yinshiyou/make_fate_loongarch64 success Make fate finished
andriy/make_x86 success Make finished
andriy/make_fate_x86 success Make fate finished

Commit Message

Anton Khirnov Sept. 3, 2022, 6:39 p.m. UTC 
Mention:
- that it is legacy and optional (every hwaccel that uses it can also
  work with hwcontext, though some optional information can only be
  signalled throught hwaccel_context)
- that it can be used for encoders (only qsvenc currently)
- ownership and lifetime
---
 libavcodec/avcodec.h | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)
diff mbox series

Patch

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 65c8535359..7db5d1b1c5 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -1388,13 +1388,26 @@  typedef struct AVCodecContext {
     const struct AVHWAccel *hwaccel;
 
     /**
-     * Hardware accelerator context.
-     * For some hardware accelerators, a global context needs to be
-     * provided by the user. In that case, this holds display-dependent
-     * data FFmpeg cannot instantiate itself. Please refer to the
-     * FFmpeg HW accelerator documentation to know how to fill this.
-     * - encoding: unused
-     * - decoding: Set by user
+     * Legacy hardware accelerator context.
+     *
+     * For some hardware acceleration methods, the caller may use this field to
+     * signal hwaccel-specific data to the codec. The struct pointed to by this
+     * pointer is hwaccel-dependent and defined in the respective header. Please
+     * refer to the FFmpeg HW accelerator documentation to know how to fill
+     * this.
+     *
+     * In most cases this field is optional - the necessary information may also
+     * be provided to libavcodec through @ref hw_frames_ctx or @ref
+     * hw_device_ctx (see avcodec_get_hw_config()). However, in some cases it
+     * may be the only method of signalling some (optional) information.
+     *
+     * The struct and its contents are owned by the caller.
+     *
+     * - encoding: May be set by the caller before avcodec_open2(). Must remain
+     *             valid until avcodec_free_context().
+     * - decoding: May be set by the caller in the get_format() callback.
+     *             Must remain valid until the next get_format() call,
+     *             or avcodec_free_context() (whichever comes first).
      */
     void *hwaccel_context;