# Display -- Texture, Tileset, and Font

Source: `src/dusk/display/`

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

---

## Texture (`texture.h`)

```c
extern texture_t TEXTURE_WHITE;  // 4x4 opaque white; always available

errorret_t textureInit(
  texture_t *texture,
  int32_t width,
  int32_t height,
  textureformat_t format,
  texturedata_t data
);
errorret_t textureDispose(texture_t *texture);
```

`textureformat_t` and `texture_t` are platform aliases
(`textureformatplatform_t`, `textureplatform_t`). On OpenGL targets
the format maps to GL texture format constants.

`texturedata_t` is a union:
- `.paletted.indices` + `.paletted.palette` -- for paletted formats
- `.rgbaColors` -- for RGBA formats

### Texture rules

- Dimensions must be powers of two on PSP and GameCube/Wii. Use
  `mathNextPowTwo` from `util/math.h` if needed.
- Texture upload must happen on the main thread. In the asset loader,
  this means `loadSync` (not `loadAsync`).
- `TEXTURE_WHITE` is always available without loading; use it as a
  placeholder or for untextured geometry.

---

## Tileset (`tileset.h`)

A tileset subdivides a texture into a uniform grid of tiles.

```c
typedef struct {
  uint16_t tileWidth, tileHeight;
  uint16_t tileCount;
  uint16_t columns, rows;
  vec2 uv;   // UV size per tile (pre-computed from grid dimensions)
} tileset_t;

// Get UV rect for a tile by index:
void tilesetTileGetUV(
  const tileset_t *ts, uint16_t tileIndex, vec4 outUV
);

// Get UV rect for a tile by grid position:
void tilesetPositionGetUV(
  const tileset_t *ts, uint16_t column, uint16_t row, vec4 outUV
);
```

`outUV` is `{u, v, u2, v2}` in normalised [0, 1] texture space.

Tilesets are loaded from `.dtf` binary files via
`ASSET_LOADER_TYPE_TILESET`. The DTF format stores tile width/height,
grid dimensions, and per-tile UV offsets (magic + version header).

---

## Font (`font.h`)

```c
typedef struct {
  texture_t *texture;
  tileset_t *tileset;
} font_t;
```

A font is a tileset-backed texture atlas where each tile is a character
glyph. No heap allocation -- both pointers are owned by the caller.
Character lookup is by glyph index into the tileset grid. Rendering is
handled by the spritebatch system using the tileset UV helpers.