Add AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI (#2591)

Add experimental support for PixelInformationProperty syntax from HEIF
3rd Ed. Amd2 behind a compilation flag.

.github/workflows/ci-fuzztest.yml

@@ -48,6 +48,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_FUZZTEST=LOCAL
           -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
           -DAVIF_ENABLE_WERROR=ON

.github/workflows/ci-linux-coverage.yml

@@ -43,6 +43,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_ENABLE_WERROR=ON -DAVIF_ENABLE_COVERAGE=ON
           -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
       - name: Build libavif (ninja)

.github/workflows/ci-unix-shared-local.yml

@@ -57,6 +57,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_ENABLE_WERROR=ON
       - name: Build libavif (ninja)
         working-directory: ./build

.github/workflows/ci-unix-static.yml

@@ -62,6 +62,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_ENABLE_WERROR=ON
       - name: Build libavif (ninja)
         working-directory: ./build

.github/workflows/ci-windows-installed.yml

@@ -76,6 +76,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_ENABLE_WERROR=ON $env:AVIF_CMAKE_C_COMPILER $env:AVIF_CMAKE_CXX_COMPILER
       - name: Build libavif (ninja)
         working-directory: ./build

.github/workflows/ci-windows-shared-local.yml

@@ -57,6 +57,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_ENABLE_WERROR=ON $env:AVIF_CMAKE_C_COMPILER $env:AVIF_CMAKE_CXX_COMPILER
       - name: Build libavif (ninja)
         working-directory: ./build

.github/workflows/ci-windows.yml

@@ -70,6 +70,7 @@ jobs:
           -DAVIF_ENABLE_EXPERIMENTAL_YCGCO_R=ON
           -DAVIF_ENABLE_EXPERIMENTAL_MINI=ON
           -DAVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM=ON
+          -DAVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI=ON
           -DAVIF_ENABLE_WERROR=ON
       - name: Build libavif (ninja)
         working-directory: ./build

CHANGELOG.md

@@ -268,6 +268,8 @@ List of incompatible ABI changes in this release:
 * Add avifenc --no-overwrite flag to avoid overwriting output file.
 * Add avifenc --clli flag to set clli.
 * Add support for all transfer functions when using libsharpyuv.
+* Add experimental support for PixelInformationProperty syntax from HEIF 3rd Ed.
+  Amd2 behind the compilation flag AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI.
 
 ### Changed
 * Enable the libaom AV1E_SET_SKIP_POSTPROC_FILTERING codec control by default.

CMakeLists.txt

@@ -67,6 +67,7 @@ option(AVIF_ENABLE_WERROR "Treat all compiler warnings as errors" OFF)
 option(AVIF_ENABLE_EXPERIMENTAL_YCGCO_R "Enable experimental YCgCo-R matrix code" OFF)
 option(AVIF_ENABLE_EXPERIMENTAL_MINI "Enable experimental reduced header" OFF)
 option(AVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM "Enable experimental sample transform code" OFF)
+option(AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI "Enable experimental PixelInformationProperty syntax from HEIF 3rd Ed. Amd2" OFF)
 
 set(AVIF_PKG_CONFIG_EXTRA_LIBS_PRIVATE "")
 set(AVIF_PKG_CONFIG_EXTRA_REQUIRES_PRIVATE "")
@@ -351,6 +352,10 @@ if(AVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM)
     add_compile_definitions(AVIF_ENABLE_EXPERIMENTAL_SAMPLE_TRANSFORM)
 endif()
 
+if(AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI)
+    add_compile_definitions(AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI)
+endif()
+
 set(AVIF_SRCS
     src/alpha.c
     src/avif.c

include/avif/avif.h

@@ -220,6 +220,11 @@ typedef enum avifHeaderFormat
     // WARNING: Experimental feature. Produces files that are incompatible with older decoders.
     AVIF_HEADER_REDUCED,
 #endif
+#if defined(AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI)
+    // Use the full syntax of the PixelInformationProperty from HEIF 3rd edition Amendment 2.
+    // WARNING: Experimental feature. Produces files that may be incompatible with older decoders.
+    AVIF_HEADER_FULL_WITH_EXTENDED_PIXI,
+#endif
 } avifHeaderFormat;
 
 // ---------------------------------------------------------------------------

include/avif/internal.h

@@ -704,7 +704,7 @@ AVIF_NODISCARD avifBool avifROStreamReadString(avifROStream * stream, char * out
 AVIF_NODISCARD avifBool avifROStreamReadBoxHeader(avifROStream * stream, avifBoxHeader * header); // This fails if the size reported by the header cannot fit in the stream
 AVIF_NODISCARD avifBool avifROStreamReadBoxHeaderPartial(avifROStream * stream, avifBoxHeader * header, avifBool topLevel); // This doesn't require that the full box can fit in the stream
 AVIF_NODISCARD avifBool avifROStreamReadVersionAndFlags(avifROStream * stream, uint8_t * version, uint32_t * flags); // version and flags ptrs are both optional
-AVIF_NODISCARD avifBool avifROStreamReadAndEnforceVersion(avifROStream * stream, uint8_t enforcedVersion); // currently discards flags
+AVIF_NODISCARD avifBool avifROStreamReadAndEnforceVersion(avifROStream * stream, uint8_t enforcedVersion, uint32_t * flags); // flags ptr is optional
 // The following functions can read non-aligned bits.
 AVIF_NODISCARD avifBool avifROStreamSkipBits(avifROStream * stream, size_t bitCount);
 AVIF_NODISCARD avifBool avifROStreamReadBitsU8(avifROStream * stream, uint8_t * v, size_t bitCount);
@@ -788,6 +788,23 @@ typedef struct avifSequenceHeader
 
 AVIF_NODISCARD avifBool avifSequenceHeaderParse(avifSequenceHeader * header, const avifROData * sample, avifCodecType codecType);
 
+#if defined(AVIF_ENABLE_EXPERIMENTAL_EXTENDED_PIXI)
+// Subsampling type as defined in ISO/IEC 23008-12:2024/CDAM 2:2025 section 6.5.6.3.
+typedef enum avifPixiSubsamplingType
+{
+    AVIF_PIXI_444 = 0,
+    AVIF_PIXI_422 = 1,
+    AVIF_PIXI_420 = 2,
+    AVIF_PIXI_411 = 3,
+    AVIF_PIXI_440 = 4,
+    AVIF_PIXI_SUBSAMPLING_RESERVED = 5,
+} avifPixiSubsamplingType;
+
+// Mapping from subsampling_x, subsampling_y as defined in AV1 specification Section 6.4.2
+// to PixelInformationBox subsampling_type as defined in ISO/IEC 23008-12:2024/CDAM 2:2025 section 6.5.6.3.
+uint8_t avifCodecConfigurationBoxGetSubsamplingType(const avifCodecConfigurationBox * av1C, uint8_t channelIndex);
+#endif
+
 // ---------------------------------------------------------------------------
 // gain maps