Enhancing high dynamic range image rendering
Improve your app’s High Dynamic Range (HDR) image support with metadata.
Overview
HDR images support a wider range of brightness levels than traditional, standard dynamic range images, and provide significant visual improvements. Despite the visual benefits of HDR images, rendering them in full fidelity isn’t always the best option for your app. You may need to reduce HDR fidelity to lower your app’s power consumption, avoid causing eye strain, or improve mixed media or multiwindow experiences by matching the range of brightness between your images and the rest of the system UI.
You can precisely configure how the system presents HDR images with API support across photos and videos by setting a preferred dynamic range and adding hints for the system with metadata API. Additional information for rendering HDR images can be found in Supporting HDR images in your app.
Set the dynamic range you prefer
You can indicate the HDR fidelity you desire with the multiple content-rendering frameworks that include the preferredDynamicRange and its sibling properties. For graphics and images, Core Graphics and Core Animation offer the functionality in CGImage and CALayer. You can also find preferredDynamicRange in AVKit and UIKit frameworks: the AVPlayerViewController, Color, UIImageView, and NSImageView classes, offer a consistent API.
Each API supports three rendering styles:
Standard dynamic range
Constrained HDR rendering, which applies to mixed media and multiwindow applications
Full HDR, when an app renders content that maximizes the a display’s capabilities
Manage HDR metadata
HDR images capture a wide range of light values. You can take advantage of metadata on an HDR image to improve rendering by declaring how the system presents those light value ranges in context.
Headroom, for instance, is the ratio between the maximum HDR light level and the maximum SDR light level, and can be an attribute of either an image or a display. Image headroom identifies when an HDR image has a higher dynamic range than a display’s HDR capabilities informing you the image might not render as you expect. Core Graphics supports automatic bitmap context management, choosing appropriate bit depth, color space, and context target headroom based on the content. The system can make reasonable choices on behalf of your app even if the system doesn’t explicitly support HDR metadata.
contentAverageLightLevel establishes the average light level across all image pixels. Use CGContentToneMappingInfo.DynamicRange.constrained dynamic range to optimize rendering for multimedia and multiwindow usage. And .constrained rendering relies on contentAverageLightLevel metadata to adapt each HDR image according to its overall brightness, avoiding the possibility of bright HDR media overpowering other media, UI elements, or text.
Calculate HDR metadata
The system interprets headroom and average content light level from standard HDR metadata often present in HDR images and videos. When the information is available in the file, the system loads the metadata into memory automatically, along with the image data. When there’s no metadata, you can compute the information it might contain at load time. NSImage and UIImage always compute HDR metadata. Image I/O and Core Image only compute HDR metadata when the kCGComputeHDRStats option is set.
Images loaded without metadata receive default values for contentHeadroom (4.926) and contentAverageLightLevel (0.0).
HDR metadata may be calculated at any time with the copyWithCalculatedHDRStats() API. The system adds the calculated HDR statistics to the copied image, and doesn’t set the values on the original image.
CGImageRef image = originalCIImage.copyWithCalculatedHDRStats()Once the system calculates contentHeadroom and contentAverageLightLevel at load time or loads them along with the image data, you can access the values with get functions in Image I/O and Core Image to ensure you use the images in the appropriate contexts.