116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# Display -- Text Rendering
|
|
|
|
Source: `src/dusk/display/text/`
|
|
|
|
See also: `.claude/display-spritebatch.md`, `.claude/display-texture.md`
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Text rendering is layered on top of the SpriteBatch. Each character
|
|
maps to a glyph tile in a bitmap font atlas; `textDraw` builds the
|
|
corresponding `spritebatchsprite_t` values and pushes them to the
|
|
global `SPRITEBATCH`. The caller is responsible for flushing the batch.
|
|
|
|
---
|
|
|
|
## Font type (`font.h`)
|
|
|
|
```c
|
|
typedef struct {
|
|
texture_t *texture; // glyph atlas texture
|
|
tileset_t *tileset; // grid describing glyph size + UV layout
|
|
} font_t;
|
|
```
|
|
|
|
Both pointers are caller-owned. The text system does not allocate or
|
|
free them.
|
|
|
|
```c
|
|
extern font_t FONT_DEFAULT;
|
|
```
|
|
|
|
`FONT_DEFAULT` is the engine's built-in bitmap font. It is initialised
|
|
during `textInit()` and available for the engine lifetime.
|
|
|
|
---
|
|
|
|
## Character range
|
|
|
|
```c
|
|
#define TEXT_CHAR_START '!' // ASCII 33
|
|
```
|
|
|
|
The glyph atlas begins at `'!'` (ASCII 33). Characters below this value
|
|
-- space, control characters -- are handled specially:
|
|
|
|
- `' '` (space) advances the cursor by one tile width without drawing.
|
|
- Characters below `TEXT_CHAR_START` other than space are skipped.
|
|
|
|
---
|
|
|
|
## API (`text.h`)
|
|
|
|
```c
|
|
// Initialises the text system and FONT_DEFAULT.
|
|
errorret_t textInit(void);
|
|
|
|
// Disposes of the text system.
|
|
errorret_t textDispose(void);
|
|
|
|
// Draw a null-terminated string at (x, y) in screen/world space.
|
|
// Pushes sprites to SPRITEBATCH. Caller must call spriteBatchFlush()
|
|
// after all text has been drawn.
|
|
errorret_t textDraw(
|
|
const float_t x,
|
|
const float_t y,
|
|
const char_t *text,
|
|
const color_t color,
|
|
font_t *font
|
|
);
|
|
|
|
// Measure the bounding box of a string without drawing it.
|
|
void textMeasure(
|
|
const char_t *text,
|
|
const font_t *font,
|
|
int32_t *outWidth,
|
|
int32_t *outHeight
|
|
);
|
|
|
|
// Low-level: build a single glyph sprite at position pos.
|
|
// Returns a spritebatchsprite_t ready for spriteBatchBuffer.
|
|
spritebatchsprite_t textGetSprite(
|
|
const vec2 pos,
|
|
const char_t c,
|
|
const font_t *font
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## Typical usage
|
|
|
|
```c
|
|
// Inside a render callback:
|
|
errorChain(textDraw(10.0f, 10.0f, "Hello", COLOR_WHITE, &FONT_DEFAULT));
|
|
errorChain(spriteBatchFlush());
|
|
```
|
|
|
|
If you are also drawing UI frames or other sprites in the same pass,
|
|
batch all the `textDraw` and `spriteBatchBuffer` calls first, then call
|
|
`spriteBatchFlush()` once at the end.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Text coordinates are in the same space as the scene render (screen
|
|
space for UI, or world space if placed in the scene).
|
|
- `textMeasure` returns pixel dimensions based on the font's
|
|
`tileset.tileWidth` and `tileset.tileHeight`. Use it to centre or
|
|
right-align text before drawing.
|
|
- For UI-attached text (dialogue, labels), prefer the `uitextbox_t`
|
|
system which handles word-wrap and paging automatically
|
|
(see `.claude/ui.md`).
|