[FFmpeg-cvslog] avutil/film_grain_params: add metadata to common struct

[Niklas Haas]

ffmpeg | branch: master | Niklas Haas <git at haasn.dev> | Fri Mar 15 11:42:42 2024 +0100| [35d2960dcd0acc6265129f53329cb364960e6492] | committer: Niklas Haas

avutil/film_grain_params: add metadata to common struct

This is needed for AV1 film grain as well, when using AFGS1 streams.
Also add extra width/height and subsampling information, which AFGS1
cares about, as part of the same API bump. (And in principle, H274
should also expose this information, since it is needed downstream to
correctly adjust the chroma grain frequency to the subsampling ratio)

Deprecate the equivalent H274-exclusive fields. To avoid breaking ABI,
add the new fields after the union; but with enough of a paper trail to
hopefully re-order them on the next bump.

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

 doc/APIchanges                |  6 +++++
 libavutil/film_grain_params.h | 57 ++++++++++++++++++++++++++++++++++++++++---
 libavutil/version.h           |  3 ++-
 3 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/doc/APIchanges b/doc/APIchanges
index 2796b4d0c2..f27e88105d 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -2,6 +2,12 @@ The last version increases of all libraries were on 2024-03-07
 
 API changes, most recent first:
 
+2024-03-xx - xxxxxxxxxx - lavu 59.5.100 - film_grain_params.h
+  Add AVFilmGrainParams.color_range, color_primaries, color_trc, color_space,
+  width, height, subsampling_x, subsampling_y, bit_depth_luma and
+  bit_depth_chroma. Deprecate the corresponding fields from
+  AVFilmGrainH274Params.
+
 2024-03-xx - xxxxxxxxxx - lavc 61.3.100 - jni.h
   Add av_jni_set_android_app_ctx() and av_jni_get_android_app_ctx().
 
diff --git a/libavutil/film_grain_params.h b/libavutil/film_grain_params.h
index f3bd0a4a6a..a9f243351c 100644
--- a/libavutil/film_grain_params.h
+++ b/libavutil/film_grain_params.h
@@ -136,20 +136,42 @@ typedef struct AVFilmGrainH274Params {
      */
     int model_id;
 
-    /**
-     * Specifies the bit depth used for the luma component.
-     */
+#if FF_API_H274_FILM_GRAIN_VCS
+  /**
+   * TODO: On this ABI bump, please also re-order the fields in
+   * AVFilmGrainParams (see below)
+   */
+
+  /**
+   * Specifies the bit depth used for the luma component.
+   *
+   * @deprecated use AVFilmGrainParams.bit_depth_luma.
+   */
+    attribute_deprecated
     int bit_depth_luma;
 
     /**
      * Specifies the bit depth used for the chroma components.
+     *
+     * @deprecated use AVFilmGrainParams.bit_depth_chroma.
      */
+    attribute_deprecated
     int bit_depth_chroma;
 
+    /**
+     * Specifies the video signal characteristics.
+     *
+     * @deprecated use AVFilmGrainParams.color_{range,primaries,trc,space}.
+     */
+    attribute_deprecated
     enum AVColorRange                  color_range;
+    attribute_deprecated
     enum AVColorPrimaries              color_primaries;
+    attribute_deprecated
     enum AVColorTransferCharacteristic color_trc;
+    attribute_deprecated
     enum AVColorSpace                  color_space;
+#endif
 
     /**
      * Specifies the blending mode used to blend the simulated film grain
@@ -231,11 +253,40 @@ typedef struct AVFilmGrainParams {
      * Additional fields may be added both here and in any structure included.
      * If a codec's film grain structure differs slightly over another
      * codec's, fields within may change meaning depending on the type.
+     *
+     * TODO: Move this to the end of the structure, at the next ABI bump.
      */
     union {
         AVFilmGrainAOMParams aom;
         AVFilmGrainH274Params h274;
     } codec;
+
+    /**
+     * Intended display resolution. May be 0 if the codec does not specify
+     * any restrictions.
+     */
+
+    int width, height;
+
+    /**
+     * Intended subsampling ratio, or 0 for luma-only streams.
+     */
+    int subsampling_x, subsampling_y;
+
+    /**
+     * Intended video signal characteristics.
+     */
+    enum AVColorRange                  color_range;
+    enum AVColorPrimaries              color_primaries;
+    enum AVColorTransferCharacteristic color_trc;
+    enum AVColorSpace                  color_space;
+
+    /**
+     * Intended bit depth, or 0 for unknown/unspecified.
+     */
+    int bit_depth_luma;
+    int bit_depth_chroma;
+
 } AVFilmGrainParams;
 
 /**
diff --git a/libavutil/version.h b/libavutil/version.h
index 882003f719..64a467fa41 100644
--- a/libavutil/version.h
+++ b/libavutil/version.h
@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  59
-#define LIBAVUTIL_VERSION_MINOR   4
+#define LIBAVUTIL_VERSION_MINOR   5
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \
@@ -111,6 +111,7 @@
 #define FF_API_FRAME_KEY                (LIBAVUTIL_VERSION_MAJOR < 60)
 #define FF_API_PALETTE_HAS_CHANGED      (LIBAVUTIL_VERSION_MAJOR < 60)
 #define FF_API_VULKAN_CONTIGUOUS_MEMORY (LIBAVUTIL_VERSION_MAJOR < 60)
+#define FF_API_H274_FILM_GRAIN_VCS      (LIBAVUTIL_VERSION_MAJOR < 60)
 
 /**
  * @}