Opportunity:
libultrahdr v2 currently encodes gain-map AVIF with an SDR primary/base image. The HDR rendition is derived from that image using the gain map and its metadata.
This is the right default because it provides the broadest compatibility: any AVIF decoder can display the SDR primary even if it does not process gain maps. However, an optional HDR-base mode is compelling for HDR-first delivery:
-
Potentially better first-paint behavior. If a client can decode and display the primary image before the auxiliary gain-map data is available, an HDR base can immediately be tone-mapped for the available display headroom. With an SDR base, the presentation may initially appear as SDR and change to HDR once the gain map becomes available. Actual streaming behavior will depend on file layout and decoder implementation.
-
More flexible quality allocation. Because the HDR presentation is carried by the primary image, the auxiliary gain map may be compressed more aggressively when SDR reconstruction can tolerate it. This may reduce auxiliary-image size, although the total file-size tradeoff should be measured because the HDR primary will generally be 10-bit.
The existing SDR-base behavior should remain the default. Please consider adding an explicit optional mode that produces:
- HDR primary/base image
- Gain-map image
- SDR alternate rendition
HDR-base mode should initially be limited to AVIF. JPEG Ultra HDR should continue to require an SDR base to preserve its established compatibility contract.
Requested API behavior:
Please expose an encoder setting that explicitly selects whether the primary/base rendition is SDR or HDR. SDR should remain the default, and the selection should not be inferred from the input transfer function.
The example CLI should expose the same choice in a clear form, such as:
-B base rendition [0: SDR (default), 1: HDR]
The raw HDR + raw SDR API-1 workflow would be a good initial scope because both authored renditions are supplied by the caller. Unsupported codecs and input routes should return an error rather than silently falling back to SDR base.
Likely implementation areas:
-
ultrahdr_api.h and lib/src/ultrahdr_api.cpp
Store, validate, and dispatch the requested base rendition.
-
lib/include/ultrahdr/avifultrahdr.h and lib/src/avifultrahdr.cpp
Encode the actual HDR input as the primary item with its real bit depth, transfer function, primaries, matrix, and range. The tmap properties should describe the SDR alternate rendition.
-
lib/include/ultrahdr/gainmapmetadata.h and lib/src/gainmapmetadata.cpp
Support backwardDirection and direction-aware mapping of base/alternate headroom, offsets, gain-map values, and color-space selection. This should follow ISO 21496-1 rather than simply flipping a flag or negating the existing gain.
-
cmake/patches/libheif_pr1503.patch
Remove the current assumption that the base is 8-bit SDR and the derived rendition is 10-bit HDR. The patched encoding interface may need explicit base/alternate depth and color-property inputs.
-
examples/ultrahdr_app.cpp
Parse, document, validate, and pass the base-rendition option before uhdr_encode().
-
Tests
Verify unchanged SDR-base defaults, a genuine 10-bit PQ or HLG HDR primary, backward-direction metadata, SDR tmap properties, reconstructed SDR fidelity, and deterministic rejection of unsupported routes.
libavif provides useful existing behavior to reference. Its gain-map model supports either base/alternate headroom ordering, and avifgainmaputil swapbase can convert an SDR-base gain-map AVIF into an HDR-base gain-map AVIF:
https://github.com/AOMediaCodec/libavif/blob/main/include/avif/avif.h
https://github.com/AOMediaCodec/libavif/blob/main/apps/avifgainmaputil/swapbase_command.cc
libavif could be used as a semantic reference and independent test oracle, or its direction logic could be ported into the existing libheif-backed implementation. Adding libavif as another dependency is not required by this request.
Equivalent HEIF support could follow later. It is lower priority for this request and would additionally require a Main10-capable HEVC encoder path.
Adobe documents that a gain-map base rendition may be either SDR or HDR and provides downloadable sample photos that may be useful for interoperability comparisons: https://helpx.adobe.com/camera-raw/desktop/hdr-and-advanced-output/gain-map.html#resources
Opportunity:
libultrahdr v2 currently encodes gain-map AVIF with an SDR primary/base image. The HDR rendition is derived from that image using the gain map and its metadata.
This is the right default because it provides the broadest compatibility: any AVIF decoder can display the SDR primary even if it does not process gain maps. However, an optional HDR-base mode is compelling for HDR-first delivery:
Potentially better first-paint behavior. If a client can decode and display the primary image before the auxiliary gain-map data is available, an HDR base can immediately be tone-mapped for the available display headroom. With an SDR base, the presentation may initially appear as SDR and change to HDR once the gain map becomes available. Actual streaming behavior will depend on file layout and decoder implementation.
More flexible quality allocation. Because the HDR presentation is carried by the primary image, the auxiliary gain map may be compressed more aggressively when SDR reconstruction can tolerate it. This may reduce auxiliary-image size, although the total file-size tradeoff should be measured because the HDR primary will generally be 10-bit.
The existing SDR-base behavior should remain the default. Please consider adding an explicit optional mode that produces:
HDR-base mode should initially be limited to AVIF. JPEG Ultra HDR should continue to require an SDR base to preserve its established compatibility contract.
Requested API behavior:
Please expose an encoder setting that explicitly selects whether the primary/base rendition is SDR or HDR. SDR should remain the default, and the selection should not be inferred from the input transfer function.
The example CLI should expose the same choice in a clear form, such as:
-B base rendition [0: SDR (default), 1: HDR]
The raw HDR + raw SDR API-1 workflow would be a good initial scope because both authored renditions are supplied by the caller. Unsupported codecs and input routes should return an error rather than silently falling back to SDR base.
Likely implementation areas:
ultrahdr_api.h and lib/src/ultrahdr_api.cpp
Store, validate, and dispatch the requested base rendition.
lib/include/ultrahdr/avifultrahdr.h and lib/src/avifultrahdr.cpp
Encode the actual HDR input as the primary item with its real bit depth, transfer function, primaries, matrix, and range. The tmap properties should describe the SDR alternate rendition.
lib/include/ultrahdr/gainmapmetadata.h and lib/src/gainmapmetadata.cpp
Support backwardDirection and direction-aware mapping of base/alternate headroom, offsets, gain-map values, and color-space selection. This should follow ISO 21496-1 rather than simply flipping a flag or negating the existing gain.
cmake/patches/libheif_pr1503.patch
Remove the current assumption that the base is 8-bit SDR and the derived rendition is 10-bit HDR. The patched encoding interface may need explicit base/alternate depth and color-property inputs.
examples/ultrahdr_app.cpp
Parse, document, validate, and pass the base-rendition option before uhdr_encode().
Tests
Verify unchanged SDR-base defaults, a genuine 10-bit PQ or HLG HDR primary, backward-direction metadata, SDR tmap properties, reconstructed SDR fidelity, and deterministic rejection of unsupported routes.
libavif provides useful existing behavior to reference. Its gain-map model supports either base/alternate headroom ordering, and avifgainmaputil swapbase can convert an SDR-base gain-map AVIF into an HDR-base gain-map AVIF:
https://github.com/AOMediaCodec/libavif/blob/main/include/avif/avif.h
https://github.com/AOMediaCodec/libavif/blob/main/apps/avifgainmaputil/swapbase_command.cc
libavif could be used as a semantic reference and independent test oracle, or its direction logic could be ported into the existing libheif-backed implementation. Adding libavif as another dependency is not required by this request.
Equivalent HEIF support could follow later. It is lower priority for this request and would additionally require a Main10-capable HEVC encoder path.
Adobe documents that a gain-map base rendition may be either SDR or HDR and provides downloadable sample photos that may be useful for interoperability comparisons: https://helpx.adobe.com/camera-raw/desktop/hdr-and-advanced-output/gain-map.html#resources