[FFmpeg-cvslog] lavc: clarify meaning of avctx.level option

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Sat Aug 26 02:34:06 2023 +0200| [6f421d9d4eb8425ce2ecb1f7f18b79ede3c60de9] | committer: Stefano Sabatini

lavc: clarify meaning of avctx.level option

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=6f421d9d4eb8425ce2ecb1f7f18b79ede3c60de9
---

 doc/codecs.texi            | 5 ++++-
 libavcodec/avcodec.h       | 6 ++++--
 libavcodec/options_table.h | 2 +-
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/codecs.texi b/doc/codecs.texi
index a155939606..5b950b4560 100644
--- a/doc/codecs.texi
+++ b/doc/codecs.texi
@@ -697,10 +697,13 @@ profiles are documented in the relevant encoder documentation.
 
 @item level @var{integer} (@emph{encoding,audio,video})
 
+Set the encoder level. This level depends on the specific codec, and
+might correspond to the profile level. It is set by default to
+ at samp{unknown}.
+
 Possible values:
 @table @samp
 @item unknown
-
 @end table
 
 @item lowres @var{integer} (@emph{decoding,audio,video})
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 09400b97b0..3916f66980 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -1730,8 +1730,10 @@ typedef struct AVCodecContext {
 #endif
 
     /**
-     * level
-     * - encoding: Set by user.
+     * Encoding level descriptor.
+     * - encoding: Set by user, corresponds to a specific level defined by the
+     *   codec, usually corresponding to the profile level, if not specified it
+     *   is set to FF_LEVEL_UNKNOWN.
      * - decoding: Set by libavcodec.
      * See AV_LEVEL_* in defs.h.
      */
diff --git a/libavcodec/options_table.h b/libavcodec/options_table.h
index f2155232cf..ee243d9894 100644
--- a/libavcodec/options_table.h
+++ b/libavcodec/options_table.h
@@ -226,7 +226,7 @@ static const AVOption avcodec_options[] = {
 {"profile", NULL, OFFSET(profile), AV_OPT_TYPE_INT, {.i64 = AV_PROFILE_UNKNOWN }, INT_MIN, INT_MAX, V|A|E|CC, "avctx.profile"},
 {"unknown", NULL, 0, AV_OPT_TYPE_CONST, {.i64 = AV_PROFILE_UNKNOWN }, INT_MIN, INT_MAX, V|A|E, "avctx.profile"},
 {"main10",  NULL, 0, AV_OPT_TYPE_CONST, {.i64 = AV_PROFILE_HEVC_MAIN_10 }, INT_MIN, INT_MAX, V|E, "avctx.profile"},
-{"level", NULL, OFFSET(level), AV_OPT_TYPE_INT, {.i64 = FF_LEVEL_UNKNOWN }, INT_MIN, INT_MAX, V|A|E|CC, "avctx.level"},
+{"level", "encoding level, usually corresponding to the profile level, codec-specific", OFFSET(level), AV_OPT_TYPE_INT, {.i64 = FF_LEVEL_UNKNOWN }, INT_MIN, INT_MAX, V|A|E|CC, "avctx.level"},
 {"unknown", NULL, 0, AV_OPT_TYPE_CONST, {.i64 = FF_LEVEL_UNKNOWN }, INT_MIN, INT_MAX, V|A|E, "avctx.level"},
 {"lowres", "decode at 1= 1/2, 2=1/4, 3=1/8 resolutions", OFFSET(lowres), AV_OPT_TYPE_INT, {.i64 = 0 }, 0, INT_MAX, V|A|D},
 {"cmp", "full-pel ME compare function", OFFSET(me_cmp), AV_OPT_TYPE_INT, {.i64 = DEFAULT }, INT_MIN, INT_MAX, V|E, "cmp_func"},