PR Details

This PR introduces support for rendering to High Dynamic Range (HDR) displays by enabling configuration of the swap chain's output color space and pixel format.

Key Changes:

1. ColorSpaceType Enum: Added a new Stride.Graphics.ColorSpaceType enum (in ColorSpace.cs) which mirrors the DXGI_COLOR_SPACE_TYPE values.
2. GraphicsPresenter.SetOutputColorSpace Method: Added a new public method GraphicsPresenter.SetOutputColorSpace(ColorSpaceType colorSpace, PixelFormat format). This is the primary way for users to configure the desired output. Calling this method will:
   • Update the presenter's description.
   • Recreate the underlying swap chain (using IDXGISwapChain3::SetColorSpace1 on D3D11/12) with the specified color space.
   • Resize back buffer and depth stencil buffers accordingly.
3. Integration:
   • PresentationParameters now includes an OutputColorSpace property.
   • GameWindowRenderer uses this property and allows setting PreferredOutputColorSpace to trigger a presenter update.
   • The Direct3D SwapChainGraphicsPresenter applies the OutputColorSpace when creating/recreating the swap chain.
   • Comments added to clarify which PixelFormat and ColorSpaceType combinations are intended for specific HDR standards (scRGB, HDR10).

How to Use HDR Output:

To enable HDR rendering, you need to get the Game.GraphicsDevice.Presenter and call the new SetOutputColorSpace method with the appropriate ColorSpaceType and PixelFormat. This should typically be done after the game has started and the graphics device is initialized, for example, within a game script's Start or Update method.

Common combinations include:

• HDR10 / BT.2100 PQ: Use ColorSpaceType.RgbFullG2084NoneP2020 with PixelFormat.R10G10B10A2_UNorm. This requires the rendering pipeline to output colors matching the PQ transfer function and Rec.2020 primaries.
• scRGB (Linear): Use ColorSpaceType.RgbFullG10NoneP709 with PixelFormat.R16G16B16A16_Float. This allows for linear rendering in a wider gamut, relying on the Windows Desktop Window Manager (DWM) for final conversion to the display.
• Standard SDR with gamma 2.2: Use ColorSpaceType.RgbFullG22NoneP709 with an 8-bit format like PixelFormat.R8G8B8A8_UNorm_SRgb.

Example Script:

using Stride.Engine;
using Stride.Graphics;
using Stride.Core.Diagnostics;
using System; 

namespace MyGameNamespace;

public class SetHdrOnStart : StartupScript
{
    public override void Start()
    {
        try
        {
            Game.GraphicsDevice.Presenter.SetOutputColorSpace(
                ColorSpaceType.RgbFullG10NoneP709,
                PixelFormat.R16G16B16A16_Float
            );
        }
        catch (Exception ex)
        {
            Log.Error($"Failed to set HDR color space: {ex.Message}", ex);
        }
    }
}

Important Considerations:

• Hardware/OS Support: HDR output requires a compatible display, GPU, drivers, and OS configuration (e.g., "Use HDR" enabled in Windows display settings). The SetOutputColorSpace call may fail if the combination is not supported. Error handling is recommended.
• Rendering Pipeline: When using HDR output (especially HDR10/PQ), the game's rendering pipeline (lighting, tonemapping, color grading) needs to be adjusted to correctly produce colors within the target color space and dynamic range. Using scRGB allows for a more traditional linear rendering workflow, with the OS handling the final tone mapping.
• Performance: Using higher bit-depth formats like R16G16B16A16_Float increases memory bandwidth usage compared to standard 8-bit formats.

See also Microsoft's documentation on HDR with DirectX:

• Using DirectX with high dynamic range displays and advanced color
• DXGI_COLOR_SPACE_TYPE enumeration

Types of changes

• Docs change / refactoring / dependency upgrade
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My change requires a change to the documentation.
• I have added tests to cover my changes.
• All new and existing tests passed.
• I have built and run the editor to try this change out.