dusk/.claude/display-texture.md

Display -- Texture, Tileset, and Font

Source: src/dusk/display/

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

---

Texture (texture.h)

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.

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)

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.