# Display System Source: `src/dusk/display/` The display system is the rendering pipeline. It is abstracted across platforms via `displayplatform.h` — see [architecture.md](architecture.md) for the abstraction pattern. The current concrete backends are OpenGL (`src/duskgl/`) and GX/Dolphin (`src/duskdolphin/`). For the planned render-queue refactor (required for Saturn), see [display-refactor.md](display-refactor.md). --- ## Initialization order Within the display system, init must follow this order (enforced in `engine.c`): ``` displayInit → uiInit → uiTextboxInit ``` Within `displayInit`, the platform typically initialises: framebuffer → screen → shader list → textures → spritebatch → text system. --- ## `display_t` / `displaystate_t` `display_t DISPLAY` is the global display instance (type alias for `displayplatform_t`). `displaystate_t` carries per-draw-call render state flags: ```c DISPLAY_STATE_FLAG_CULL // face culling DISPLAY_STATE_FLAG_DEPTH_TEST // depth testing DISPLAY_STATE_FLAG_BLEND // alpha blending ``` Set state before drawing with `displaySetState(state)`. --- ## Screen (`display/screen/`) `screen_t SCREEN` manages the logical viewport that game content renders into. On dynamic-size platforms (Linux/SDL2) the screen can differ from the native window/framebuffer resolution. Screen modes: ``` SCREEN_MODE_BACKBUFFER — maps 1:1 to backbuffer SCREEN_MODE_FIXED_SIZE — fixed pixel dimensions SCREEN_MODE_ASPECT_RATIO — fixed aspect, scale to fit SCREEN_MODE_FIXED_HEIGHT — fixed height, width scales SCREEN_MODE_FIXED_WIDTH — fixed width, height scales SCREEN_MODE_FIXED_VIEWPORT_HEIGHT — fixed viewport height ``` The linux target defines `DUSK_DISPLAY_SCREEN_HEIGHT=240`, producing a 240p fixed-height viewport. Render loop usage: ```c screenBind(); // set up viewport, projection // ... draw game content ... screenUnbind(); screenRender(); // blit to backbuffer / current framebuffer ``` `SCREEN.width` / `SCREEN.height` are the logical dimensions used for world-to-screen math — always prefer these over the framebuffer dimensions. --- ## Framebuffer (`display/framebuffer/`) `framebuffer_t FRAMEBUFFER_BACKBUFFER` is the platform backbuffer. `FRAMEBUFFER_BOUND` points to the currently-bound framebuffer (or `NULL` for backbuffer). ```c frameBufferInitBackBuffer(); // called once at startup frameBufferBind(fb); // NULL → backbuffer frameBufferClear(FRAMEBUFFER_CLEAR_COLOR | FRAMEBUFFER_CLEAR_DEPTH, COLOR_BLACK); frameBufferGetWidth(fb) / frameBufferGetHeight(fb) / frameBufferGetAspect(fb); ``` On platforms with `DUSK_DISPLAY_SIZE_DYNAMIC`, off-screen framebuffers can be created with `frameBufferInit(fb, w, h)` and disposed with `frameBufferDispose(fb)`. Fixed-resolution platforms (PSP, GameCube) only ever use the backbuffer. --- ## Mesh (`display/mesh/`) `mesh_t` is a vertex buffer. The type is `meshplatform_t` (e.g. a VAO+VBO on GL, a GX display list on Dolphin). ```c meshInit(&mesh, MESH_PRIMITIVE_TYPE_TRIANGLES, vertexCount, verticesPtr); meshFlush(&mesh, offset, count); // upload CPU vertices → GPU meshDraw(&mesh, offset, count); // draw; pass -1 for count to draw all meshDispose(&mesh); ``` **Key distinction**: `meshFlush` uploads data to GPU memory; `meshDraw` issues the draw call. For static geometry (chunk meshes) you call `meshFlush` once on load, then `meshDraw` every frame. For dynamic geometry (spritebatch) you `meshFlush` + `meshDraw` each frame. `meshvertex_t` (`display/mesh/meshvertex.h`) contains: - `float_t uv[2]` — texture coordinates - `float_t pos[3]` — position - Optionally `color_t color` if `MESH_ENABLE_COLOR` is defined (off by default) Primitive mesh generators live alongside `mesh.h`: `quad.h`, `plane.h`, `cube.h`, `sphere.h`, `capsule.h`, `triprism.h`. --- ## Shader (`display/shader/`) `shader_t` is `shaderplatform_t` (GLSL program on GL, TEV state block on Dolphin). ```c shaderInit(&shader, &definition); shaderBind(&shader); shaderSetMatrix(&shader, "uModel", modelMat); shaderSetTexture(&shader, "uTexture", &texture); shaderSetColor(&shader, "uColor", COLOR_WHITE); shaderSetMaterial(&shader, &material); shaderDispose(&shader); ``` ### Shader list (`display/shader/shaderlist.h`) The engine maintains a small set of built-in shaders in `SHADER_LIST_DEFS[]`. Currently only one is defined: - `SHADER_LIST_SHADER_UNLIT` → `SHADER_UNLIT` — unlit textured/colored rendering, used for all world and entity drawing. `shaderListInit()` compiles/uploads all built-in shaders and sets shared projection/view matrices. Call once after display init. ### Materials (`display/shader/shadermaterial.h`) `shadermaterial_t` is a union of all shader-specific material structs. Currently only `shaderunlitmaterial_t`: ```c shadermaterial_t mat = { .unlit = { .color = COLOR_WHITE, .texture = &myTexture, // NULL for solid color } }; shaderSetMaterial(&SHADER_UNLIT, &mat); ``` --- ## Texture (`display/texture/`) ```c textureInit(&texture, width, height, format, data); textureDispose(&texture); ``` Width and height **must be powers of two** (asserted at init time). `textureformat_t` is `textureformatplatform_t`. Supported formats vary by platform; the common ones are `TEXTURE_FORMAT_RGBA` and `TEXTURE_FORMAT_PALETTE`. `texturedata_t` is a union: ```c // RGBA: data.rgbaColors = colorArray; // Paletted: data.paletted.indices = indexArray; data.paletted.palette = &palette; // palette color count must be power of two ``` **Built-in textures** (defined in `texture.c`, no asset loading needed): - `TEXTURE_WHITE` — 4×4 solid white - `TEXTURE_TEST` — 4×4 black/magenta checkerboard ### Palette (`display/texture/palette.h`) Up to `PALETTE_COUNT` (6) global palettes in `PALETTES[]`, each holding up to `PALETTE_COLOR_COUNT` (255) `color_t` entries. ### Tileset (`display/texture/tileset.h`) A tileset slices a texture into a grid of equal-sized tiles. Used by fonts and UI frames. The tileset does not own the texture — it references a `texture_t *`. --- ## SpriteBatch (`display/spritebatch/`) The primary 2D/billboard drawing primitive. Accumulates `spritebatchsprite_t` quads and flushes them in batches of `SPRITEBATCH_FLUSH_COUNT` (16) sprites at a time. ```c // Per frame: spriteBatchClear(); spriteBatchBuffer(sprites, count, &SHADER_UNLIT, material); // auto-flushes when batch full spriteBatchFlush(); // flush remaining // Low-level: write directly to an external mesh (for baking static geometry): spriteBatchBufferToMesh(sprites, count, vertices, verticesSize); ``` `spritebatchsprite_t`: ```c typedef struct { vec3 min, max; // 3D bounding box vec2 uvMin, uvMax; // texture region } spritebatchsprite_t; ``` The global `SPRITEBATCH` and its vertex backing array `SPRITEBATCH_VERTICES[]` are defined externally to the struct to satisfy alignment requirements on certain platforms. --- ## Text (`display/text/`) Text rendering uses `FONT_DEFAULT` (loaded during `textInit()`), which references a texture and a tileset. Characters start at ASCII `!` (`TEXT_CHAR_START`). ```c textDraw(x, y, "Hello", COLOR_WHITE, &FONT_DEFAULT); textMeasure("Hello", &FONT_DEFAULT, &outWidth, &outHeight); // Single-char sprite for manual layout: spritebatchsprite_t s = textGetSprite(pos, 'A', &FONT_DEFAULT); ``` `font_t` holds a `texture_t *` and a `tileset_t *` — both are owned by the asset system, not the font struct.