# Window and Viewport Internals

## Purpose

Explain how virtual resolution, window size, viewport mode, and resize updates
interact in runtime rendering.

## Core files

- `packages/mini-arcade-core/src/mini_arcade_core/runtime/window/window_adapter.py`
- `packages/mini-arcade-core/src/mini_arcade_core/engine/render/viewport.py`
- `packages/mini-arcade-core/src/mini_arcade_core/engine/render/passes/world.py`
- `packages/mini-arcade-core/src/mini_arcade_core/engine/render/passes/ui.py`

## Virtual vs window resolution

- virtual resolution:
  simulation/render space (`virtual_w`, `virtual_h`)
- window resolution:
  presentation size (`window_w`, `window_h`)

`set_virtual_resolution(w, h)` updates virtual canvas and recomputes viewport
scale/offset for current window size.

## Viewport modes

`ViewportMode.FIT`:

- `scale = min(window_w/virtual_w, window_h/virtual_h)`
- full virtual frame visible
- letterbox/pillarbox bars may appear

`ViewportMode.FILL`:

- `scale = max(window_w/virtual_w, window_h/virtual_h)`
- fills window
- virtual frame is cropped on one axis

## Viewport state fields

`ViewportState` includes:

- virtual size
- window size
- mode
- scale
- viewport rectangle (`viewport_w`, `viewport_h`, `offset_x`, `offset_y`)

Offsets can be negative in `FILL` mode.

## Resize propagation

1. backend emits `WINDOWRESIZED`
2. loop hook calls `window.on_window_resized(w, h)`
3. adapter updates logical/drawable sizes
4. viewport recomputes scale/offset
5. render passes consume updated viewport on next frame

## World pass vs UI pass

World pass:

- applies viewport transform and virtual clipping
- use for gameplay/world entities

UI pass:

- clears viewport transform and clip
- use for screen-space overlays/layout

This separation is the basis for responsive reflow on resize.

## Tutorial references

- `docs/source/tutorials/window/virtual_resolution_basics.md`
- `docs/source/tutorials/window/fit_vs_fill.md`
- `docs/source/tutorials/window/resize_reflow.md`