docs: add book

book/src/configuration/gpu.md

@@ -0,0 +1,293 @@
+# 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).