[FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for avcodec_open2()

[FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for avcodec_open2()

[Stefano Sabatini]

In particular, clarify how to set options in the codec context, and mention when to use
avcodec_parameters_to_context().

Fix trac issue http://trac.ffmpeg.org/ticket/5781.
---
 libavcodec/avcodec.h | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 9a0fe97cad..2b7fb27721 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -2418,8 +2418,9 @@ 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()).
+ * Options on the codec context can be either set by providing the options
+ * specified in an AVDictionary, or by setting the values on the context itself,
+ * directly or by using the av_opt_set() API.
  *
  * @code
  * av_dict_set(&opts, "b", "2.5M", 0);
@@ -2433,17 +2434,35 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
  *     exit(1);
  * @endcode
  *
+ * In 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 code:
+ *
+ * @code
+ * context = avcodec_alloc_context3(codec);
+ * if (avcodec_parameters_to_context(*dec_ctx, 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 avctx.
  *
  * @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);
 
-- 
2.25.1

_______________________________________________
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".

Re: [FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for avcodec_open2()

[Stefano Sabatini]

[-- Attachment #1: Type: text/plain, Size: 452 bytes --]

On date Tuesday 2023-02-28 23:28:56 +0100, Stefano Sabatini wrote:
> In particular, clarify how to set options in the codec context, and mention when to use
> avcodec_parameters_to_context().
> 
> Fix trac issue http://trac.ffmpeg.org/ticket/5781.
> ---
>  libavcodec/avcodec.h | 29 ++++++++++++++++++++++++-----
>  1 file changed, 24 insertions(+), 5 deletions(-)

Updated with some more information, after I realized there was another
related issue.

[-- Attachment #2: 0001-lavc-avcodec.h-extend-documentation-for-avcodec_open.patch --]
[-- Type: text/x-diff, Size: 3442 bytes --]

From e4e5622d1c4eac5dde4065b260523e4fd9ada85c Mon Sep 17 00:00:00 2001
From: Stefano Sabatini <stefasab@gmail.com>
Date: Tue, 28 Feb 2023 23:26:43 +0100
Subject: [PATCH] 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
---
 libavcodec/avcodec.h | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 9a0fe97cad..fbf1d3d83c 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -2418,8 +2418,14 @@ 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
+ * case the information is not is not available in the bitstream, e.g. as in
+ * case of decoding raw audio or video).
+ *
+ * Options on the codec context can be either set by providing the options
+ * specified in an AVDictionary, or by setting the values on the context itself,
+ * directly or by using the av_opt_set() API.
  *
  * @code
  * av_dict_set(&opts, "b", "2.5M", 0);
@@ -2433,17 +2439,35 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
  *     exit(1);
  * @endcode
  *
+ * In 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 code:
+ *
+ * @code
+ * context = avcodec_alloc_context3(codec);
+ * if (avcodec_parameters_to_context(*dec_ctx, 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 avctx.
  *
  * @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);
 
-- 
2.25.1


[-- Attachment #3: Type: text/plain, Size: 251 bytes --]

_______________________________________________
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".

Re: [FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for avcodec_open2()

["zhilizhao(赵志立)"]

> On Mar 1, 2023, at 06:40, Stefano Sabatini <stefasab@gmail.com> wrote:
> 
> On date Tuesday 2023-02-28 23:28:56 +0100, Stefano Sabatini wrote:
>> In particular, clarify how to set options in the codec context, and mention when to use
>> avcodec_parameters_to_context().
>> 
>> Fix trac issue http://trac.ffmpeg.org/ticket/5781.
>> ---
>> libavcodec/avcodec.h | 29 ++++++++++++++++++++++++-----
>> 1 file changed, 24 insertions(+), 5 deletions(-)
> 

> 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
> ---
>  libavcodec/avcodec.h | 34 +++++++++++++++++++++++++++++-----
>  1 file changed, 29 insertions(+), 5 deletions(-)
> 
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index 9a0fe97cad..fbf1d3d83c 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -2418,8 +2418,14 @@ 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
> + * case the information is not is not available in the bitstream, e.g. as in

'is not is not'

> + * case of decoding raw audio or video).

in ’the’ case of.

> + *
> + * Options on the codec context can be either set by providing the options
> + * specified in an AVDictionary, or by setting the values on the context itself,
> + * directly or by using the av_opt_set() API.
>   *
>   * @code
>   * av_dict_set(&opts, "b", "2.5M", 0);
> @@ -2433,17 +2439,35 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
>   *     exit(1);
>   * @endcode
>   *
> + * In 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 code:
> + *
> + * @code
> + * context = avcodec_alloc_context3(codec);
> + * if (avcodec_parameters_to_context(*dec_ctx, codecpar) < 0)
> + *     exit(1);
> + * if (avcodec_open2(context, codec, NULL) < 0)
> + *     exit(1);

What’s the dec_ctx?

> + * @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 avctx.
>   *
>   * @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);
>  
> -- 
> 2.25.1



_______________________________________________
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".

Re: [FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for avcodec_open2()

[Stefano Sabatini]

[-- Attachment #1: Type: text/plain, Size: 1922 bytes --]

On date Wednesday 2023-03-01 15:04:16 +0800, "zhilizhao(赵志立)" wrote:
> > diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> > index 9a0fe97cad..fbf1d3d83c 100644
> > --- a/libavcodec/avcodec.h
> > +++ b/libavcodec/avcodec.h
> > @@ -2418,8 +2418,14 @@ 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
> > + * case the information is not is not available in the bitstream, e.g. as in
> 
> 'is not is not'
> 
> > + * case of decoding raw audio or video).
> 
> in ’the’ case of.
> 
> > + *
> > + * Options on the codec context can be either set by providing the options
> > + * specified in an AVDictionary, or by setting the values on the context itself,
> > + * directly or by using the av_opt_set() API.
> >   *
> >   * @code
> >   * av_dict_set(&opts, "b", "2.5M", 0);
> > @@ -2433,17 +2439,35 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
> >   *     exit(1);
> >   * @endcode
> >   *
> > + * In 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 code:
> > + *
> > + * @code
> > + * context = avcodec_alloc_context3(codec);
> > + * if (avcodec_parameters_to_context(*dec_ctx, codecpar) < 0)
> > + *     exit(1);
> > + * if (avcodec_open2(context, codec, NULL) < 0)
> > + *     exit(1);
> 
> What’s the dec_ctx?

Updated, thanks for the feedback.

[-- Attachment #2: 0001-lavc-avcodec.h-extend-documentation-for-avcodec_open.patch --]
[-- Type: text/x-diff, Size: 3518 bytes --]

From 672de0e5d15ab8a22f3957222680d847f60bced8 Mon Sep 17 00:00:00 2001
From: Stefano Sabatini <stefasab@gmail.com>
Date: Tue, 28 Feb 2023 23:26:43 +0100
Subject: [PATCH 1/2] 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
---
 libavcodec/avcodec.h | 36 +++++++++++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 87ebee22b1..f630fafe24 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -2429,8 +2429,15 @@ 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 on the codec context can be set either by setting them in the
+ * provided options AVDictionary, or by setting the values on the context
+ * itself, directly or by using the av_opt_set() API before calling the
+ * function.
  *
  * @code
  * av_dict_set(&opts, "b", "2.5M", 0);
@@ -2444,17 +2451,36 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
  *     exit(1);
  * @endcode
  *
+ * In 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 code:
+ *
+ * @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);
 
-- 
2.25.1


[-- Attachment #3: Type: text/plain, Size: 251 bytes --]

_______________________________________________
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".

Re: [FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for avcodec_open2()

[Stefano Sabatini]

On date Sunday 2023-03-05 12:57:38 +0100, Stefano Sabatini wrote:
> On date Wednesday 2023-03-01 15:04:16 +0800, "zhilizhao(赵志立)" wrote:
[...]
> Updated, thanks for the feedback.

> From 672de0e5d15ab8a22f3957222680d847f60bced8 Mon Sep 17 00:00:00 2001
> From: Stefano Sabatini <stefasab@gmail.com>
> Date: Tue, 28 Feb 2023 23:26:43 +0100
> Subject: [PATCH 1/2] 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
> ---
>  libavcodec/avcodec.h | 36 +++++++++++++++++++++++++++++++-----
>  1 file changed, 31 insertions(+), 5 deletions(-)

Applied with a few minor fixes.
_______________________________________________
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".