RepoMirrors/ffmpeg
1
0
Fork 0
mirror of https://git.ffmpeg.org/ffmpeg.git synced 2025-02-18 04:47:12 +00:00
Code Issues Projects Releases Wiki Activity

lavc/avcodec.h: extend documentation for avcodec_open2()

Browse Source 
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
This commit is contained in:
Stefano Sabatini 2023-02-28 23:26:43 +01:00
parent 358588c820
commit dcf963f490
1 changed files with 31 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
libavcodec/avcodec.h
View File

@ -2429,9 +2429,16 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
* avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for * avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
* retrieving a codec. * retrieving a codec.
* *
* @note Always call this function before using decoding routines (such as * Depending on the codec, you might need to set options in the codec context
* @ref avcodec_receive_frame()). * 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 * @code
* av_dict_set(&opts, "b", "2.5M", 0); * av_dict_set(&opts, "b", "2.5M", 0);
* codec = avcodec_find_decoder(AV_CODEC_ID_H264); * codec = avcodec_find_decoder(AV_CODEC_ID_H264);
@ -2444,17 +2451,36 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
* exit(1); * exit(1);
* @endcode * @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 avctx The context to initialize.
* @param codec The codec to open this context for. If a non-NULL codec has been * @param codec The codec to open this context for. If a non-NULL codec has been
* previously passed to avcodec_alloc_context3() or * previously passed to avcodec_alloc_context3() or
* for this context, then this parameter MUST be either NULL or * for this context, then this parameter MUST be either NULL or
* equal to the previously passed codec. * equal to the previously passed codec.
* @param options A dictionary filled with AVCodecContext and codec-private options. * @param options A dictionary filled with AVCodecContext and codec-private
* On return this object will be filled with options that were not found. * 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 * @return zero on success, a negative value on error
* @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(), * @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); int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);