# Display -- Shader, Material, and Display State

Source: `src/dusk/display/`

See also: `.claude/display-core.md`, `.claude/display-texture.md`

---

## Shader (`shader.h` + `shaderlist.h`)

Shaders are platform-abstracted. The current shader list is defined
in `shaderlist.h`. Currently only one shader is implemented:

| Enum | Description |
|------|-------------|
| `SHADER_LIST_SHADER_UNLIT` | Unlit / flat colour + texture shader |

```c
extern shaderlistdef_t SHADER_LIST_DEFS[SHADER_LIST_SHADER_COUNT];
// SHADER_LIST_DEFS[n].shader is the platform shader object.

// Bind a shader before drawing:
errorret_t shaderBind(shader_t *shader);

// Upload a mat4 uniform by name:
errorret_t shaderSetMatrix(shader_t *shader, const char_t *name, mat4 m);
```

Adding a new shader means adding an entry to `shaderlist.h`, providing
platform-specific vertex/fragment sources, and implementing the
corresponding material type in `shadermaterial_t`.

---

## Shader material (`shadermaterial.h`)

`shadermaterial_t` is a union over per-shader material structs.
Currently contains only the unlit material:

```c
typedef union shadermaterial_u {
  shaderunlitmaterial_t unlit;
} shadermaterial_t;
```

`shaderunlitmaterial_t` fields:

```c
typedef struct {
  color_t color;      // tint colour (multiplied with the texture sample)
  texture_t *texture; // NULL uses TEXTURE_WHITE (solid colour draw)
} shaderunlitmaterial_t;
```

The shader exposes uniforms `u_Proj`, `u_View`, `u_Model` (mat4),
`u_Texture` (sampler), and `u_Color` (vec4). They are uploaded via
`shaderUnlitSetMaterial(shader, material)`.

A global singleton `SHADER_UNLIT` is the live shader object;
`SHADER_UNLIT_DEFINITION` is its platform definition descriptor.

To use a shader material on a renderable entity:

1. Set `renderable.type = ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL`.
2. Set `renderable.data.material.shaderType` to the desired
   `shaderlistshadertype_t` value (e.g. `SHADER_LIST_SHADER_UNLIT`).
3. Fill in the corresponding union field:
   `renderable.data.material.material.unlit`.
4. Set `renderable.data.material.state.flags` for rasterizer state.

---

## Display state (`displaystate.h`)

`displaystate_t` controls per-draw rasterizer state flags:

```c
DISPLAY_STATE_FLAG_CULL        // back-face culling
DISPLAY_STATE_FLAG_DEPTH_TEST  // depth testing
DISPLAY_STATE_FLAG_BLEND       // alpha blending
```

Set flags via `data.material.state.flags` on the renderable's material.
The default for an uninitialised state is all flags clear (no culling,
no depth test, no blending). Most opaque geometry should set at least
`CULL | DEPTH_TEST`.