2.5 KiB
Display -- Screen, Framebuffer, and Size Modes
Source: src/dusk/display/
See also: .claude/display-texture.md, .claude/display-shader.md
Display size modes
Two compile-time configurations exist:
Fixed size (DUSK_DISPLAY_WIDTH + DUSK_DISPLAY_HEIGHT)
The render resolution is constant. Set both defines at CMake configure
time. SCREEN.width and SCREEN.height are compile-time constants.
Dynamic size (DUSK_DISPLAY_SIZE_DYNAMIC)
The window can be resized (desktop targets). Instead of fixed defines,
set DUSK_DISPLAY_WIDTH_DEFAULT and DUSK_DISPLAY_HEIGHT_DEFAULT.
The screen system renders to an internal framebuffer at a logical
resolution and scales/letterboxes to the actual window.
Screen modes available only with DUSK_DISPLAY_SIZE_DYNAMIC:
| Mode | Behaviour |
|---|---|
SCREEN_MODE_BACKBUFFER |
Render directly to the window backbuffer |
SCREEN_MODE_FIXED_SIZE |
Fixed pixel dimensions; letterboxed |
SCREEN_MODE_ASPECT_RATIO |
Maintain aspect ratio at all cost |
SCREEN_MODE_FIXED_HEIGHT |
Fixed height; width expands/contracts |
SCREEN_MODE_FIXED_WIDTH |
Fixed width; height expands/contracts |
SCREEN_MODE_FIXED_VIEWPORT_HEIGHT |
Fixed height at higher resolution |
Configure via SCREEN.mode and the corresponding union field before
calling screenInit().
Framebuffer (framebuffer.h)
extern framebuffer_t FRAMEBUFFER_BACKBUFFER;
extern const framebuffer_t *FRAMEBUFFER_BOUND;
// Bind/unbind:
frameBufferBind(fb);
frameBufferUnbind();
// Clear (pass flag combination):
frameBufferClear(fb, FRAMEBUFFER_CLEAR_COLOR | FRAMEBUFFER_CLEAR_DEPTH);
// Dimensions of the currently bound framebuffer:
int32_t w = frameBufferGetWidth();
int32_t h = frameBufferGetHeight();
FRAMEBUFFER_BACKBUFFER is the window surface. Off-screen framebuffers
are used by the screen system when DUSK_DISPLAY_SIZE_DYNAMIC is on.
Screen (screen.h)
extern screen_t SCREEN;
// SCREEN.width, SCREEN.height -- logical render dimensions
// SCREEN.aspect -- width / height
// SCREEN.background -- clear colour
errorret_t screenInit();
errorret_t screenBind(); // call before rendering game content
errorret_t screenUnbind(); // call after game content, before UI
errorret_t screenRender(); // blit the internal framebuffer to the window
errorret_t screenDispose();
screenBind / screenUnbind / screenRender are called by the scene
system automatically each frame. Game code normally does not call them
directly -- use the JS render() hook instead.