Use the maximum potential headroom if EDR content isn't currently being displayed.

Also document that the HDR properties can change dynamically at runtime.

include/SDL3/SDL_render.h

@@ -344,13 +344,13 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend
  *   SDL_COLORSPACE_SRGB.
  * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is
  *   SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with
- *   HDR enabled.
+ *   HDR enabled. This property can change dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
  * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the
  *   SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is
- *   automatically multiplied into the color scale.
+ *   automatically multiplied into the color scale. This property can change dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
  * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range
  *   that can be displayed, in terms of the SDR white point. When HDR is not
- *   enabled, this will be 1.0.
+ *   enabled, this will be 1.0. This property can change dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
  * - `SDL_PROP_RENDERER_D3D9_DEVICE_POINTER`: the IDirect3DDevice9 associated
  *   with the renderer
  * - `SDL_PROP_RENDERER_D3D11_DEVICE_POINTER`: the ID3D11Device associated

include/SDL3/SDL_video.h

@@ -355,15 +355,15 @@ extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void);
  *
  * The following read-only properties are provided by SDL:
  *
- * - `SDL_PROP_DISPLAY_HDR_ENABLED_BOOLEAN`: true if the display has HDR
- *   headroom above the SDR white point.
+ * - `SDL_PROP_DISPLAY_HDR_ENABLED_BOOLEAN`: true if the display has HDR 
+ *   headroom above the SDR white point. This property can change dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
  * - `SDL_PROP_DISPLAY_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the
  *   SDL_COLORSPACE_SRGB_LINEAR colorspace. On Windows this corresponds to the
  *   SDR white level in scRGB colorspace, and on Apple platforms this is
- *   always 1.0 for EDR content.
+ *   always 1.0 for EDR content. This property can change dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
  * - `SDL_PROP_DISPLAY_HDR_HEADROOM_FLOAT`: the additional high dynamic range
  *   that can be displayed, in terms of the SDR white point. When HDR is not
- *   enabled, this will be 1.0.
+ *   enabled, this will be 1.0. This property can change dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
  *
  * \param displayID the instance ID of the display to query
  * \returns a valid property ID on success or 0 on failure; call

src/video/cocoa/SDL_cocoamodes.m

@@ -299,7 +299,11 @@ static void Cocoa_GetHDRProperties(CGDirectDisplayID displayID, SDL_HDRDisplayPr
     if (@available(macOS 10.15, *)) {
         NSScreen *screen = GetNSScreenForDisplayID(displayID);
         if (screen) {
-            HDR->HDR_headroom = screen.maximumExtendedDynamicRangeColorComponentValue;
+            if (screen.maximumExtendedDynamicRangeColorComponentValue > 1.0f) {
+                HDR->HDR_headroom = screen.maximumExtendedDynamicRangeColorComponentValue;
+            } else {
+                HDR->HDR_headroom = screen.maximumPotentialExtendedDynamicRangeColorComponentValue;
+            }
         }
     }
 #endif

src/video/uikit/SDL_uikitmodes.m

@@ -247,7 +247,11 @@ int UIKit_AddDisplay(UIScreen *uiscreen, SDL_bool send_event)
 
 #ifndef SDL_PLATFORM_TVOS
     if (@available(iOS 16.0, *)) {
-        display.HDR.HDR_headroom = uiscreen.currentEDRHeadroom;
+        if (uiscreen.currentEDRHeadroom > 1.0f) {
+            display.HDR.HDR_headroom = uiscreen.currentEDRHeadroom;
+        } else {
+            display.HDR.HDR_headroom = uiscreen.potentialEDRHeadroom;
+        }
     }
 #endif /* !SDL_PLATFORM_TVOS */