82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
# 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.
|