dusk/.claude/display-shader.md

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

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:

typedef union shadermaterial_u {
  shaderunlitmaterial_t unlit;
} shadermaterial_t;

shaderunlitmaterial_t typically holds a texture_t * and a tint colour. Check shaderunlitmaterial.h for the exact fields.

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:

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.