[FFmpeg-cvslog] lavc/avcodec.h: extend documentation for avcodec_open2()
Stefano Sabatini
git at videolan.org
Sun Mar 12 17:50:53 EET 2023
ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Tue Feb 28 23:26:43 2023 +0100| [dcf963f4906fa594aea3e54d3f2f84637624acca] | committer: Stefano Sabatini
lavc/avcodec.h: extend documentation for avcodec_open2()
In particular, clarify how to set options in the codec context, and
mention when to use avcodec_parameters_to_context().
Fix trac issues:
http://trac.ffmpeg.org/ticket/5781
http://trac.ffmpeg.org/ticket/5838
> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=dcf963f4906fa594aea3e54d3f2f84637624acca
---
libavcodec/avcodec.h | 36 +++++++++++++++++++++++++++++++-----
1 file changed, 31 insertions(+), 5 deletions(-)
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 87ebee22b1..30f1d312f4 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -2429,9 +2429,16 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
* avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
* retrieving a codec.
*
- * @note Always call this function before using decoding routines (such as
- * @ref avcodec_receive_frame()).
+ * Depending on the codec, you might need to set options in the codec context
+ * also for decoding (e.g. width, height, or the pixel or audio sample format in
+ * the case the information is not available in the bitstream, as when decoding
+ * raw audio or video).
*
+ * Options in the codec context can be set either by setting them in the options
+ * AVDictionary, or by setting the values in the context itself, directly or by
+ * using the av_opt_set() API before calling this function.
+ *
+ * Example:
* @code
* av_dict_set(&opts, "b", "2.5M", 0);
* codec = avcodec_find_decoder(AV_CODEC_ID_H264);
@@ -2444,17 +2451,36 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
* exit(1);
* @endcode
*
+ * In the case AVCodecParameters are available (e.g. when demuxing a stream
+ * using libavformat, and accessing the AVStream contained in the demuxer), the
+ * codec parameters can be copied to the codec context using
+ * avcodec_parameters_to_context(), as in the following example:
+ *
+ * @code
+ * AVStream *stream = ...;
+ * context = avcodec_alloc_context3(codec);
+ * if (avcodec_parameters_to_context(context, stream->codecpar) < 0)
+ * exit(1);
+ * if (avcodec_open2(context, codec, NULL) < 0)
+ * exit(1);
+ * @endcode
+ *
+ * @note Always call this function before using decoding routines (such as
+ * @ref avcodec_receive_frame()).
+ *
* @param avctx The context to initialize.
* @param codec The codec to open this context for. If a non-NULL codec has been
* previously passed to avcodec_alloc_context3() or
* for this context, then this parameter MUST be either NULL or
* equal to the previously passed codec.
- * @param options A dictionary filled with AVCodecContext and codec-private options.
- * On return this object will be filled with options that were not found.
+ * @param options A dictionary filled with AVCodecContext and codec-private
+ * options, which are set on top of the options already set in
+ * avctx, can be NULL. On return this object will be filled with
+ * options that were not found in the avctx codec context.
*
* @return zero on success, a negative value on error
* @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
- * av_dict_set(), av_opt_find().
+ * av_dict_set(), av_opt_set(), av_opt_find(), avcodec_parameters_to_context()
*/
int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);
More information about the ffmpeg-cvslog
mailing list