315 lines
8.8 KiB
Markdown
315 lines
8.8 KiB
Markdown
# HDR & Color Management
|
|
|
|
Jay supports HDR (High Dynamic Range) output and the Wayland color management
|
|
protocol. This chapter explains how HDR works in Jay and walks through
|
|
enabling it.
|
|
|
|
## Prerequisites
|
|
|
|
HDR in Jay requires:
|
|
|
|
- The **Vulkan renderer**. The OpenGL renderer does not support color
|
|
management or HDR. Vulkan is the default when available; you can verify
|
|
with `jay randr show` (look for the "Api" field under your GPU) or switch
|
|
to it in the [control center](control-center.md) GPUs pane.
|
|
- A **monitor that supports HDR**. The display must advertise PQ (Perceptual
|
|
Quantizer) support and BT.2020 colorimetry through its EDID. Run
|
|
`jay randr show` to see which color spaces and EOTFs your display supports.
|
|
|
|
## Quick start
|
|
|
|
Enable HDR10 on a specific output using the CLI:
|
|
|
|
```shell
|
|
~$ jay randr output DP-1 colors set bt2020 pq
|
|
```
|
|
|
|
Or in your configuration file:
|
|
|
|
```toml
|
|
[[outputs]]
|
|
match.serial-number = "33K03894SL0"
|
|
color-space = "bt2020"
|
|
transfer-function = "pq"
|
|
```
|
|
|
|
Enable the color management protocol so that applications can communicate
|
|
their color spaces to the compositor:
|
|
|
|
```shell
|
|
~$ jay color-management enable
|
|
```
|
|
|
|
Or in your configuration file:
|
|
|
|
```toml
|
|
[color-management]
|
|
enabled = true
|
|
```
|
|
|
|
To return to SDR:
|
|
|
|
```shell
|
|
~$ jay randr output DP-1 colors set default default
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Run `jay randr` to find connector names and serial numbers for your
|
|
> displays.
|
|
|
|
## Concepts
|
|
|
|
### Color space
|
|
|
|
The color space determines the range of colors (gamut) the output uses.
|
|
|
|
`default`
|
|
: sRGB gamut. This is the standard gamut for desktop displays.
|
|
|
|
`bt2020`
|
|
: BT.2020 gamut. A much wider gamut used by HDR10 and modern cinema standards.
|
|
|
|
### Transfer function (EOTF)
|
|
|
|
The transfer function (technically the Electro-Optical Transfer Function)
|
|
controls how encoded pixel values are mapped to display luminance.
|
|
|
|
`default`
|
|
: Gamma 2.2. The traditional SDR transfer function.
|
|
|
|
`pq`
|
|
: Perceptual Quantizer (SMPTE ST 2084). The HDR10 transfer function, designed
|
|
to cover luminance levels from 0 to 10,000 cd/m^2.
|
|
|
|
Setting `color-space = "bt2020"` and `transfer-function = "pq"` together
|
|
activates HDR10 mode. Jay sends the appropriate HDR metadata infoframe to the
|
|
display, including the display's mastering luminance and primaries from its
|
|
EDID.
|
|
|
|
### Brightness
|
|
|
|
The brightness setting controls SDR content luminance in cd/m^2. This
|
|
determines how bright non-HDR content appears on an HDR display.
|
|
|
|
With the `default` (gamma 2.2) transfer function, the default brightness is
|
|
the maximum the display supports, anchored at 80 cd/m^2. Setting brightness
|
|
below 80 makes SDR content dimmer while creating HDR headroom above it.
|
|
|
|
With the `pq` transfer function, the default brightness is 203 cd/m^2 (the
|
|
ITU reference level for SDR content in an HDR signal).
|
|
|
|
```toml
|
|
[[outputs]]
|
|
match.serial-number = "33K03894SL0"
|
|
color-space = "bt2020"
|
|
transfer-function = "pq"
|
|
brightness = 250
|
|
```
|
|
|
|
```shell
|
|
~$ jay randr output DP-1 brightness 250
|
|
~$ jay randr output DP-1 brightness default
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Brightness has no effect unless the Vulkan renderer is in use.
|
|
|
|
### Blend space
|
|
|
|
When Jay composites overlapping translucent surfaces, the blend space
|
|
determines in which color space the alpha blending is performed.
|
|
|
|
`srgb`
|
|
: Classic desktop blending in sRGB space. This is the default and matches the
|
|
behavior of most other compositors.
|
|
|
|
`linear`
|
|
: Blending in linear light. This is physically correct but can make
|
|
semi-transparent elements appear brighter than expected.
|
|
|
|
```toml
|
|
[[outputs]]
|
|
match.serial-number = "33K03894SL0"
|
|
blend-space = "linear"
|
|
```
|
|
|
|
```shell
|
|
~$ jay randr output DP-1 blend-space linear
|
|
```
|
|
|
|
### Native gamut
|
|
|
|
By default, Jay assumes all displays use sRGB primaries. This matches the
|
|
behavior of most other compositors, but most modern displays actually have a
|
|
wider gamut (e.g. 95% DCI-P3 coverage). Because the display interprets
|
|
sRGB-intended color values in its wider native gamut, colors appear more
|
|
saturated than they should.
|
|
|
|
Setting `use-native-gamut = true` tells Jay the display's actual primaries
|
|
from its EDID, allowing the compositor to map colors correctly. This produces
|
|
less saturated but more accurate colors, and allows color-managed applications
|
|
to address the full display gamut.
|
|
|
|
```toml
|
|
[[outputs]]
|
|
match.serial-number = "33K03894SL0"
|
|
use-native-gamut = true
|
|
```
|
|
|
|
```shell
|
|
~$ jay randr output DP-1 use-native-gamut true
|
|
```
|
|
|
|
This setting has no effect when the display is already operating in a wide
|
|
color space like BT.2020.
|
|
|
|
### Framebuffer format
|
|
|
|
The default framebuffer format (`xrgb8888`) uses 8 bits per channel, which
|
|
can cause banding in HDR content. For HDR, consider a higher-precision format:
|
|
|
|
- `xrgb2101010` or `argb2101010` -- 10 bits per channel. Good balance between
|
|
precision and performance.
|
|
- `xbgr16161616f` or `abgr16161616f` -- 16-bit floating point per channel.
|
|
Maximum precision.
|
|
|
|
```toml
|
|
[[outputs]]
|
|
match.serial-number = "33K03894SL0"
|
|
color-space = "bt2020"
|
|
transfer-function = "pq"
|
|
format = "xrgb2101010"
|
|
```
|
|
|
|
```shell
|
|
~$ jay randr output DP-1 format set xrgb2101010
|
|
```
|
|
|
|
> [!TIP]
|
|
> Run `jay randr show --formats` to see which formats your display supports.
|
|
|
|
## Color management protocol
|
|
|
|
The Wayland color management protocol (`wp_color_manager_v1`) lets
|
|
applications communicate their color space to the compositor. This enables
|
|
color-aware applications to render correctly regardless of the output's color
|
|
settings -- for example, an image viewer can tag its surfaces as sRGB and Jay
|
|
will map the colors to the output's actual gamut and transfer function.
|
|
|
|
The protocol is **disabled by default** and must be enabled explicitly:
|
|
|
|
```toml
|
|
[color-management]
|
|
enabled = true
|
|
```
|
|
|
|
Or at runtime:
|
|
|
|
```shell
|
|
~$ jay color-management enable
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Changing this setting has no effect on applications that are already running.
|
|
> They must be restarted to discover the protocol.
|
|
|
|
Color management availability requires both the protocol to be enabled **and**
|
|
the Vulkan renderer to be active. Check with:
|
|
|
|
```shell
|
|
~$ jay color-management status
|
|
```
|
|
|
|
This prints one of:
|
|
|
|
`Enabled`
|
|
: The protocol is enabled and available to clients.
|
|
|
|
`Enabled (Unavailable)`
|
|
: The protocol is enabled but unavailable -- usually because the OpenGL
|
|
renderer is in use.
|
|
|
|
`Disabled`
|
|
: The protocol is disabled.
|
|
|
|
The [control center](control-center.md) **Color Management** pane shows the
|
|
same information as a toggle and a read-only availability indicator.
|
|
|
|
### Supported capabilities
|
|
|
|
Jay's color management implementation supports:
|
|
|
|
- **Parametric image descriptions** with custom primaries, luminances, and
|
|
transfer functions (including power curves).
|
|
- **Named primaries**: sRGB, BT.2020, DCI-P3, Display P3, Adobe RGB, and
|
|
others.
|
|
- **Named transfer functions**: sRGB, PQ (ST 2084), gamma 2.2, gamma 2.4,
|
|
BT.1886, linear, and others.
|
|
- **Mastering display metadata** for HDR content.
|
|
- **Windows scRGB** compatibility.
|
|
|
|
ICC profile creation is not supported.
|
|
|
|
## Checking display capabilities
|
|
|
|
Use `jay randr show` to inspect what your display supports:
|
|
|
|
```shell
|
|
~$ jay randr show
|
|
```
|
|
|
|
The output for each connector includes:
|
|
|
|
- **Color spaces** -- which color spaces the display supports (e.g. `default`,
|
|
`bt2020`), with the current setting marked.
|
|
- **EOTFs** -- which transfer functions the display supports (e.g. `default`,
|
|
`pq`), with the current setting marked.
|
|
- **Brightness range** -- minimum and maximum luminance from the EDID, in
|
|
cd/m^2.
|
|
- **Current brightness** -- displayed if a custom value is set.
|
|
- **Blend space** -- current blend space setting.
|
|
- **Native gamut** -- the display's CIE xy primaries for red, green, blue, and
|
|
white point.
|
|
|
|
## Complete example
|
|
|
|
A typical HDR configuration for a monitor that supports HDR10:
|
|
|
|
```toml
|
|
[[outputs]]
|
|
match.serial-number = "33K03894SL0"
|
|
color-space = "bt2020"
|
|
transfer-function = "pq"
|
|
brightness = 203
|
|
format = "xrgb2101010"
|
|
blend-space = "linear"
|
|
|
|
[color-management]
|
|
enabled = true
|
|
```
|
|
|
|
This sets the output to HDR10 with 10-bit color, physically correct blending,
|
|
and enables the color management protocol so applications can communicate
|
|
their color spaces.
|
|
|
|
## Control center
|
|
|
|
The Outputs pane in the [control center](control-center.md) (`alt-c` by
|
|
default) provides GUI controls for all HDR-related settings per output:
|
|
Colorimetry, EOTF, Custom Brightness, Format, Blend Space, Use Native Gamut,
|
|
and a read-only Native Gamut display. See
|
|
[Outputs (Monitors)](configuration/outputs.md) for details on each field.
|
|
|
|
The Color Management pane has a toggle to enable/disable the protocol and a
|
|
read-only indicator showing whether color management is currently available.
|
|
|
|
## See also
|
|
|
|
- [Outputs (Monitors)](configuration/outputs.md) -- per-output configuration
|
|
reference including all color and HDR fields
|
|
- [Miscellaneous](configuration/misc.md) -- the `[color-management]` config
|
|
table
|
|
- [Command-Line Interface](cli.md) -- `jay randr output` color commands and
|
|
`jay color-management`
|
|
- [GPUs](configuration/gpu.md) -- renderer selection (Vulkan is required for
|
|
HDR)
|