Should CAMetalLayer wantsExtendedDynamicRangeContent be considered deprecated?
Some links for context:
CAMetalLayer wantsExtendedDynamicRangeContent for iOS 16+
CALayer wantsExtendedDynamicRangeContent for iOS 17+
CALayer preferredDynamicRange for iOS 26+
So Metal got it, then CALayer got it, then CALayer got a more extensible one in iOS26 and wantsExtendedDynamicRangeContent got marked Deprecated. But it's not marked as deprecated on the CAMetalLayer.
I tested it and setting preferredDynamicRange on the CALayer worked to allow my CAMetalLayer to show HDR content on both iOS 27 and tvOS 27. I don't know if there's some reason though (performance for example?) to prefer setting the property on the CAMetalLayer rather than the CALayer.
I'm asking because I want react-native-webgpu to support HDR on tvOS, but right now they're using CAMetalLayer wantsExtendedDynamicRangeContent which has no tvOS support. https://github.com/wcandillon/react-native-webgpu/pull/607
The CAMetalLayer version of wantsExtendedDynamicRangeContent isn't marked deprecated in the iOS, tvOS, and macOS 27.2 SDKs. Only the CALayer property is deprecated, with the message "Use preferredDynamicRange instead." The CAMetalLayer property is available in iOS 16 and later and macOS 10.11 and later, and unavailable in tvOS, as you found. The code examples in articles linked from Displaying HDR content in a Metal layer still set it.
I didn't find a documented performance reason to prefer the CAMetalLayer property. One documented difference is tone mapping. WWDC23 session Support HDR images in your app covered the CALayer property when it arrived in iOS 17. The session describes the difference this way: "the CALayer property enables tone mapping of the layer contents, while the CAMetalLayer does not." iOS 18, tvOS 18, and macOS 15 added toneMapMode, which CALayer.h describes as "Options that control when to tone map CALayer contents and CAMetalLayer drawables." It defaults to automatic, which lets the OS decide. The other values are never and ifSupported.
In CALayer.h, the deprecated property's comment recommends migrating to preferredDynamicRange. It says preferredDynamicRange "requires that the layer contain a CGColor or `contents' with headroom tagging greater than 1.0 in order to activate EDR." For contentsHeadroom, the header says "CAMetalLayers can use this value to define how much headroom is needed by their MTLDrawables." It also says that setting the property "can help reduce the power impact when using a limited amount of dynamic range." Both properties are available in tvOS 26 and later.
If you'd like the documentation to say how the CAMetalLayer property relates to preferredDynamicRange, please file a bug report using Feedback Assistant. Once you've filed it, post the FB number here.