Request: Support API-4-style AVIF/HEIF gain-map encoding

[gregbenz]

libultrahdr currently supports API-4 for JPEG/R, allowing an application to provide an existing base image, gain-map image, and gain-map metadata for packaging without regenerating the gain map.

Could equivalent support be added for AVIF and HEIF output?

This would help applications such as libvips preserve an existing gain map when converting or saving an image. Without it, adopting libultrahdr v2 for AVIF/HEIF may require reconstructing HDR pixels and generating a new gain map, which is slower and can alter the original result.

Related broader transcoding request: #398.

[gregbenz]

@DichenZhang1 Would the maintainers be open to a PR for this? If so, guidance on the preferred input model—compressed images, raw images, or a staged implementation—would be very helpful.

[gregbenz]

Would this be the right initial scope for extending API-4 to AVIF and HEIF output?

• For JPEG-compressed base and gain-map inputs, decode the JPEGs and encode them directly as the selected AVIF or HEIF output. No intermediate JPEG would be created.
• Use the configured base and gain-map quality settings for the unavoidable cross-codec encoding.
• Preserve applicable ICC, Exif, and XMP metadata.
• Keep lossless passthrough of existing compressed AV1 or HEVC image items as separate follow-up work.

This would support the current libvips workflow when converting an existing JPEG gain-map image to AVIF or HEIF (to be clear, it would not route AVIF/HEIF sources through JPEG).

For an existing AVIF or HEIF input, should API-4 eventually support preserving compatible compressed base and gain-map items without recompression, or should that remain a separate container-level API?