wry/book/src/configuration/gpu.md

# GPUs

Jay configures graphics cards (DRM devices) through the `[[drm-devices]]`
array. This is primarily useful on multi-GPU systems for selecting the render
device, choosing a graphics API, and tuning per-device settings.

> [!NOTE]
> DRM device configuration in `config.toml` is only applied when a device is
> first discovered after the configuration is loaded. To change settings at
> runtime, use `jay randr` or the `configure-drm-device` action.

## Matching GPUs

Every `[[drm-devices]]` entry requires a `match` field. When `match` is a
**table**, all specified fields must match (AND). When `match` is an **array**,
any entry matching is sufficient (OR).

### By PCI vendor and model (recommended)

PCI IDs are stable, unique identifiers. Use `jay randr` to find them:

```shell
~$ jay randr
```

```toml
[[drm-devices]]
match = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}
gfx-api = "Vulkan"
```

### By vendor or model name

```toml
[[drm-devices]]
match.vendor = "Advanced Micro Devices, Inc. [AMD/ATI]"
```

```toml
[[drm-devices]]
match.model = "Raphael"
```

### By syspath or devnode

The `syspath` is usually stable across reboots:

```toml
[[drm-devices]]
match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0"
```

The `devnode` (e.g. `/dev/dri/card0`) is typically not stable.

## Naming GPUs

Assign a `name` to reference a device from other parts of the config:

```toml
[[drm-devices]]
name = "dedicated"
match = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}

[[drm-devices]]
name = "integrated"
match = {
    pci-vendor = 0x1002,
    pci-model = 0x164e,
}
```

Names can then be used in `render-device`, shortcuts, and actions:

```toml
render-device.name = "dedicated"
```

```toml
[shortcuts]
alt-v = {
    type = "configure-drm-device",
    dev = {
        match.name = "dedicated",
        gfx-api = "Vulkan",
    },
}
alt-o = {
    type = "configure-drm-device",
    dev = {
        match.name = "dedicated",
        gfx-api = "OpenGl",
    },
}
```

## Graphics API

Jay supports two rendering backends per device:

`Vulkan`
: Uses libvulkan. The primary renderer -- use this unless you have a specific
  reason not to. Required for HDR. All devices in the system must support DRM
  format modifiers (most do, except AMD GPUs older than RX 5000).

`OpenGl`
: Uses libEGL + libGLESv2. Maintained for backwards compatibility only. No new
  features will be added to this renderer.

### Per-device API

```toml
[[drm-devices]]
match = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}
gfx-api = "Vulkan"
```

### Default API for all devices

Set the top-level `gfx-api` to apply to any device without a per-device
override:

```toml
gfx-api = "Vulkan"
```

This only takes effect for devices discovered after the config is loaded.

## Direct scanout

Direct scanout lets the compositor hand a client's buffer directly to the
display hardware, bypassing composition. This can reduce latency and power
usage, but may cause visual glitches with some hardware or applications.

### Per-device

```toml
[[drm-devices]]
match = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}
direct-scanout = false
```

### Global toggle

```toml
direct-scanout = false
```

## Flip margin

The flip margin is the time (in milliseconds) between the compositor
initiating a page flip and the output's vertical blank event. It determines
the minimum achievable input latency. The default is 1.5 ms.

```toml
[[drm-devices]]
match = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}
flip-margin-ms = 2.0
```

If the margin is set too small, the compositor will dynamically increase it to
avoid missed frames.

## Explicit sync

Explicit sync coordinates buffer access between the compositor and GPU drivers.
It is enabled by default and generally should not be disabled:

```toml
explicit-sync = true
```

> [!WARNING]
> This setting cannot be changed after the compositor has started. It can only
> be set in `config.toml` before launching Jay.

## Render device

On multi-GPU systems, select which GPU performs compositing with the
`render-device` field. The first matching device is used:

```toml
render-device.name = "dedicated"

[[drm-devices]]
name = "dedicated"
match = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}

[[drm-devices]]
name = "integrated"
match = {
    pci-vendor = 0x1002,
    pci-model = 0x164e,
}
gfx-api = "OpenGl"
```

You can also match directly without naming:

```toml
render-device = {
    pci-vendor = 0x1002,
    pci-model = 0x73ff,
}
```

> [!NOTE]
> Changing the render device at runtime (via the `set-render-device` action)
> may cause windows to become invisible until they are resized or otherwise
> redrawn.

## Runtime changes

### Listing GPUs

```shell
~$ jay randr
```

This shows all DRM devices with their PCI IDs, vendor/model names, current
API, and other settings.

### Changing settings at runtime

Use `jay randr` subcommands:

```shell
~$ jay randr card <card> api vulkan
~$ jay randr card <card> direct-scanout enable
~$ jay randr card <card> primary
```

### Using shortcuts

The `configure-drm-device` action applies settings from a keybinding:

```toml
[shortcuts]
alt-F5 = {
    type = "configure-drm-device",
    dev = {
        match.name = "dedicated",
        gfx-api = "Vulkan",
    },
}
alt-F6 = {
    type = "configure-drm-device",
    dev = {
        match.name = "dedicated",
        gfx-api = "OpenGl",
    },
}
```

The `set-render-device` action switches the compositing GPU:

```toml
[shortcuts]
alt-F7 = { type = "set-render-device", dev.name = "dedicated" }
alt-F8 = { type = "set-render-device", dev.name = "integrated" }
```

## Hardware cursor

The `use-hardware-cursor` top-level setting controls whether the hardware cursor
plane is used. Disabling this forces software cursor rendering, which can be
useful for debugging.

```toml
use-hardware-cursor = true  # default
```

## Full reference

For the exhaustive list of all DRM device fields, match criteria, and related
types, see the [auto-generated specification](https://github.com/mahkoh/jay/blob/master/toml-spec/spec/spec.generated.md).