>Psychtoolbox>PsychGLImageProcessing

PsychHDR - Support and control stimulus display to HDR “High dynamic range” displays.

This driver provides both, the setup code for the HDR main setup command
PsychImaging(‘AddTask’, ‘General’, ‘EnableHDR’), to get HDR display enabled
for a specific Psychtoolbox onscreen window on a specific HDR display, and
utility subfunctions for user-scripts to call after initial setup, to modify
HDR display behaviour.

HDR currently only works on graphics card + operating system combinations which
support both the OpenGL and Vulkan rendering api’s and also efficient OpenGL-Vulkan
interoperation. Additionally, the Vulkan driver, graphics card, and your display
device must support at least the HDR-10 standard for high dynamic range display.

As of April 2021, these graphics cards would be suitable:

• Modern AMD (RX 500 “Polaris” and later recommended) and NVidia [(GeForce]((GeForce) 1000
  “Pascal” and later recommended) graphics cards under a Microsoft Windows-10
  operating system, which is up to date for the year 2021.

• Modern AMD graphics cards (like above) under modern GNU/Linux (Ubuntu 18.04.4-LTS
  at a minimum (untested!), or better Ubuntu 20.04-LTS and later recommended), with
  the AMD open-source Vulkan driver “amdvlk”. Install driver release 2020-Q3.5 from
  September 2020, which was tested, or any later versions. Note that release
  2023-Q3.3 from September 2023 was the last release to support pre-Navi gpu’s like
  Polaris and Vega. Later versions only support AMD Navi and later with RDNA graphics
  architecture.

The following webpage has amdvlk download and installation instructions:

https://github.com/GPUOpen-Drivers/AMDVLK/releases

• Some Apple Mac computers, e.g., the MacBookPro 2017 15 inch Retina with AMD
  graphics, under macOS 10.15.4 Catalina or later, do now have experimental and
  limited HDR support. This has been tested with macOS 10.15.7 Catalina final,
  on the MBP 2017 with AMD Radeon Pro 560 in a limited way on an external HDR-10
  monitor, connected via USB-C to DisplayPort adapter. Precision of content
  reproduction during leight testing was worse than on Linux and Windows. The
  presentation timing was awful and unreliable, and performance was bad. Flexibility
  and functionality was very limited in comparison to Windows-10, and even more so
  compared to Linux. Querying HDR display properties from the HDR display is not
  supported due to macOS limitations, and high performance HDR movie playback is
  completely missing due to severe deficiencies of Apple’s OpenGL implementation.
  This uses the Apple Metal EDR “Extended dynamic range” support in macOS. Note
  that Vulkan and HDR support on macOS is considered alpha quality at best, and
  we do not provide any support for this feature. As always, if you care about
  the quality of your results, use preferrably Linux, or Windows-10 instead.

  You need at least MoltenVK version 1.1.4 and LunarG Vulkan SDK 1.2.182.0 from
  5th July 2021 or later. MoltenVK v1.1.5 or later is recommended at this time.

Download link for the MoltenVK open-source “Vulkan on Metal” driver:

https://sdk.lunarg.com/sdk/download/latest/mac/vulkan-sdk.dmg
Overview on: https://vulkan.lunarg.com/sdk/home

HDR functionality is demonstrated in multiple demos:

SimpleHDRDemo.m as a simple starter for basic image display and rendering.
HDRViewer.m as a more fancy static image viewer.
HDRTest.m for testing HDR reproduction with a colorimeter supported by Psychtoolbox.
MinimalisticOpenGLDemo.m with the optional ‘hdr’ parameter set to 1 for most basic OpenGL rendering in HDR.
PlayMoviesDemo.m with the optional ‘hdr’ parameter set to 1 for playback of HDR movies.

Useful helper functions beyond PsychImaging(‘AddTask’, ‘General’, ‘EnableHDR’);
for basic HDR setup and configuration, and PsychHDR() for tweaking, are
the HDRRead() command for reading some HDR image file formats, e.g.,
Radiance .hdr or OpenEXR .exr, ComputeHDRStaticMetadataType1ContentLightLevels()
for computing HDR static metadata type one for an image or stack of
images, and ConvertRGBSourceToRGBTargetColorSpace() for converting images
from a source color space / gamut to a destination color space / gamut.

Most often you won’t call this function directly, but Psychtoolbox will call
it appropriately from the PsychImaging() function. Read relevant sections
related to ‘EnableHDR’ in ‘help PsychImaging’ first, before venturing into the
subfunctions offered by this function.

User accessible commands and their meaning

oldVerbosity = PsychHDR(‘Verbosity’ [, verbosity]);

• Returns and optionally sets level of ‘verbosity’ for driver debug output.
  ‘verbosity’ = New level of verbosity: 0 = Silent, 1 = Errors only, 2 = Warnings,
  3 = Info, 4 = Debug, 5 – … = Higher debug levels.

isSupported = PsychHDR(‘Supported’);

• Returns if HDR visual stimulus display is in principle supported on this setup.
  1 = Supported, 0 = No driver, hardware or operating system support.

hdrProperties = PsychHDR(‘GetHDRProperties’, window);

• Returns hdrProperties, a struct with information about the HDR display properties
  of the onscreen window ‘window’. Most importantly, it returns information about the
  native color gamut of the HDR display device and its brightness range. The following
  fields in hdrProperties exist at least:

  ‘Valid’ Are the HDR display properties valid? 0 = No, as no data could be
  queried from the display, 1 = Yes, data has been queried from display and is
  supposed to represent actual display HDR capabilities and properties.

  ‘HDRMode’ 0 = None (SDR), 1 = Basic HDR-10 enabled with BT-2020 color space, 10
  bpc color precision, and ST-2084 PQ Perceptual Quantizer EOTF.

  ‘LocalDimmingControl’ 0 = No, 1 = Local dimming control supported.

  ‘MinLuminance’ Minimum supported luminance in nits.

  ‘MaxLuminance’ Maximum supported peak / burst luminance in nits. This is often
  only achievable for a small area of the display surface over extended
  periods of time, e.g., only for 10% of the pixel area. The full display
  may only be able to sustain that luminance for a few seconds.

  ‘MaxFrameAverageLightLevel’ Maximum sustainable supported luminance in nits.

  ‘MaxContentLightLevel’ Maximum desired content light level in nits.

  ‘ColorGamut’ A 2-by-4 matrix encoding the CIE-1931 2D chromaticity coordinates of the
  red, green, and blue color primaries in columns 1, 2 and 3, and
  the white-point in column 4.

oldlocalDimmmingEnable = PsychHDR(‘HDRLocalDimming’, window [, localDimmmingEnable]);

• Return and/or set HDR local backlight dimming enable setting for display
  associated with window ‘window’.

  This function returns the currently set HDR local backlight dimming setting for
  dynamic contrast control on the HDR display monitor associated with window
  ‘window’.

  Return argument ‘oldlocalDimmmingEnable’ is the current setting.
  The optional ‘localDimmingEnable’ is the new setting to apply. This will only
  work if the display and display driver supports the VK_AMD_display_native_hdr
  Vulkan extension. As of July 2020, only “AMD FreeSync2 HDR compliant” HDR
  monitors under Windows-10 with an AMD graphics card in fullscreen mode support
  this.

  The hdrProperties = PsychHDR(‘GetHDRProperties’, window); function allows to query
  if the current setup supports this function. Please note that this function will
  always report the selected ‘localDimmingEnable’ setting made by your code on a
  nominally supported setup. There is no way for our driver to detect if the mode
  change on the display was accepted, as the operating system provides no feedback
  about this. At least one model of “compatible” monitor is already known to
  ignore this setting, unknown if this is an AMD driver bug or monitor firmware
  bug. Tread carefully! Manual control of this setting on the monitor itself may
  be the safer choice.

a) oldHdrMetadata = PsychHDR(‘HDRMetadata’, window, metadataType [, maxFrameAverageLightLevel][, maxContentLightLevel][, minLuminance][, maxLuminance][, colorGamut]);
b) oldHdrMetadata = PsychHDR(‘HDRMetadata’, window [, newHdrMetadata]);

• Return and/or set HDR metadata for presentation window ‘window’.

  This function returns the currently defined HDR metadata that is sent
  to the HDR display associated with the window ‘window’. It optionally
  allows to define new HDR metadata to send to the display, starting with
  the next presented visual stimulus image, ie. the successfull completion
  of the next Screen(‘Flip’).

  The mandatory parameter ‘metadataType’ specifies the format in which
  HDR metadata should be returned or set.

  Return argument ‘oldHdrMetadata’ is a struct with information about the
  current metadata. Optionally you can define new metadata to be sent to
  the display in one of the two formats a) or b) shown above: Either a)
  as separate parameters, or b) as a ‘newHdrMetadata’ struct. If you use
  the separate parameters format a) and specify any new settings, but
  omit some of the optional parameter values or leave them [] empty, then
  those values will remain at their current / old values. If you use the
  struct format b), then you must pass in a non-empty ‘newHdrMetadata’
  struct which contains the same fields as the struct returned in
  ‘oldHdrMetadata’, with all fields for the given ‘MetadataType’ properly
  defined, otherwise an error will occur. Format b) is useful as a
  convenience for querying ‘oldHdrMetadata’, then modifying some of its
  values, and then passing this modified variant back in as
  ‘newHdrMetadata’. For HDR movie playback, Screen(‘OpenMovie’) also
  optionally returns a suitable hdrStaticMetaData struct in the right
  format for passing it as ‘newHdrMetadata’.

The following fields in the struct and as new settings are defined:

‘MetadataType’ Type of metadata to send or query. Currently only a
value of 0 is supported, which defines “Static HDR metadata type 1”, as
used and specified by the HDR standards CTA-861-3 / CTA-861-G (content
light levels) and SMPTE 2086 (mastering display color properties, ie.
color volume).

The content light level properties ‘MaxFrameAverageLightLevel’ and
‘MaxContentLightLevel’ default to 0 at startup, which signals to the
display device that they are unknown, a reasonable assumption for
dynamically rendered content with prior unknown maximum values over a
whole session.

‘MaxFrameAverageLightLevel’ Maximum frame average light level of the visual
content in nits, range 0 - 65535 nits.

‘MaxContentLightLevel’ Maximum light level of the visual content in
nits, range 0 - 65535 nits.

The following mastering display properties (~ color volume) default to
the properties of the connected HDR display monitor for presentation, if
they could be queried from the connected monitor. It is advisable to
override them with the real properties of the mastering display, e.g.,
for properly mastered movie content or image files where this data may
be available.

‘MinLuminance’ Minimum supported luminance of the mastering display in
nits, range 0 - 6.5535 nits.

‘MaxLuminance’ Maximum supported luminance of the mastering display in
nits, range 0 - 65535 nits.

‘ColorGamut’ A 2-by-4 matrix encoding the CIE-1931 2D chromaticity
coordinates of the red, green, and blue color primaries in columns 1,
2, and 3, and the location of the white-point in column 4. This defines
the color space and gamut in which the visual content was produced.