# RenderWave shaders

RenderWave appears in **two distinct places** in Ultimate VJ, and they are easy to confuse:

1. **RenderWave shader sources** — a GPU shader that *is* the clip's image, supplying pixels upstream of
   effects. Reached from the **Shader Browser**.
2. **Kaleidoscope · RenderWave** — the single effect instance that runs through the RenderWave runtime.

## Shader sources

A clip using a RenderWave source gets its pixels from the GPU frame rather than from a media file
(`Sources/VJMac/ConsoleRenderer.swift:932-939`). Nothing else about the clip changes: it still has a
transform, effects, audio settings and its own transport.

### How they are discovered

Catalog metadata is read through a **compiled catalog library**: `libRenderWaveCatalogRuntime.dylib` in
`Contents/Frameworks`, or the path in the `ULTIMATEVJ_RENDERWAVE_CATALOG_PATH` environment variable.

- One catalog is loaded per process, so **switching catalogs requires restarting the app**.
- If no catalog is present you see *"RenderWave is unavailable. Saved shader settings are retained."*
- Each shader's compiled Metal library is `<metalFile>.metallib` under `RenderWaveRuntime/Shaders`.

### Applying one

**Shader Browser** → search → **Apply** (or double-click). Applying inserts the shader into the selected
slot and switches the Inspector to the **Source** tab.

The browser search matches display name, category or summary, and the grid shows name plus category.

### Controls

Each shader exposes controls of three kinds — `float`, `integer` and `toggle` — rendered as slider,
stepper and checkbox respectively. The **first six are inline**; the rest sit under a
**More controls** disclosure.

Uniforms available to a shader include TIME, RENDERSIZE, bpm, beat and bar phase, and `param1…param26`.

Catalog contract limits (these are enforced when the catalog is read):

| Constraint | Value |
|---|---|
| Schema / ABI major | 1 / 1 |
| Shaders per catalog | 1 … 256 |
| Default uniform values per shader | 1 … 26 |
| Controls per shader | 1 … 26 |
| Control values per frame | ≤ 256 |
| Uniform words | 42 (168 bytes) |

### Saving and reusing looks

**Extension `.uvjshader`**, default filename `Shader look.uvjshader`, maximum 1 MiB.

The payload is the shader **selection** — its values, version, source version, descriptor, any animation
drivers, and a preset name taken from the filename (truncated to 80 characters). Because each control row
offers the standard Animate editor, **animation travels inside the preset**.

A shader that is unavailable in this build is retained as opaque data with *"This shader is unavailable in
this build. Its preset data is retained."* — never substituted.

## The RenderWave effect

**Kaleidoscope · RenderWave** is the only effect kind routed through RenderWave
(`Sources/VJMac/ConsoleEffectStack.swift:41`). It needs a prepared GPU frame; without one its scope
renders black and reports *"RenderWave effects runtime is not prepared."*

## Not verified

- **How many shaders ship, and their names.** That depends on which catalog library is present at
  runtime, and no catalog file exists in the repository checkout — only the ABI header. The code permits
  1…256. Any specific count should be read from the Shader Browser's own `<n> shaders` line, which is
  generated from whatever catalog is installed.
- Which shaders are available in a given third-party catalog.