# 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`)

```c
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`)

```c
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.