# 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)