[FFmpeg-devel] [PATCH v2] lavu/opt: Discuss AV_OPT_FLAG_RUNTIME_PARAM more explicitly

[Stefano Sabatini]

On date Thursday 2024-06-06 17:02:06 +0100, Andrew Sayers wrote:
> After a struct is initialized, only options with the
> AV_OPT_FLAG_RUNTIME_PARAM flag can be modified.
> 
> Make that clearer, for the sake of readers who would otherwise
> assume all options can be modified at any time.
> ---
>  libavutil/opt.h | 26 +++++++++++++++++++++++++-
>  1 file changed, 25 insertions(+), 1 deletion(-)
> 
> diff --git a/libavutil/opt.h b/libavutil/opt.h
> index 07e27a9208..d23c10bcf5 100644
> --- a/libavutil/opt.h
> +++ b/libavutil/opt.h
> @@ -53,6 +53,9 @@
>   * question is allowed to access the field. This allows us to extend the
>   * semantics of those fields without breaking API compatibility.
>   *
> + * Note: only options with the AV_OPT_FLAG_RUNTIME_PARAM flag can be
> + * modified after the struct is initialized.
> + *
>   * @section avoptions_scope Scope of AVOptions
>   *
>   * AVOptions is designed to support any set of multimedia configuration options
> @@ -300,7 +303,7 @@ enum AVOptionType{
>  #define AV_OPT_FLAG_BSF_PARAM       (1 << 8)
>  

>  /**
> - * A generic parameter which can be set by the user at runtime.
> + * A generic parameter which can be set by the user after initialization.
>   */
>  #define AV_OPT_FLAG_RUNTIME_PARAM   (1 << 15)

I'm fine with changing the description, but then I wonder if we should
also rename the flag accordingly (by adding a new alias and
deprecating the old one):
AV_OPT_FLAG_POST_INIT_SETTABLE_PARAM
??

>  /**
> @@ -483,6 +486,9 @@ typedef struct AVOptionRanges {
>  /**
>   * Set the values of all AVOption fields to their default values.
>   *

> + * Note: after a struct is initialized, only options with the
> + * AV_OPT_FLAG_RUNTIME_PARAM flag can be modified.
> + *

drop this note and the following ones, this is assumed by the flags so
there is no need to repeat this all over