ryan
c1758efd3b
- Introduced `test_scenery_brick_preview.gd` to validate focused placement and CPU draw-cost for large brick walls. - Added `test_scenery_surface_cache.gd` to assess texture budget, visual equivalence, and cache invalidation. - Created `test_scenery_surface_preview.gd` to evaluate adaptive preview selection and placement behavior. - Implemented various helper functions to measure drawing performance and validate expected behaviors during tests. - Added unique identifiers for new test files to ensure proper tracking and management.
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# Scenery surface caching
|
||
|
||
`StageRectSurface` renders committed patterned scenery through reusable texture tiles.
|
||
Drawing previews use the adaptive lightweight renderer. Paint remains a single rectangle.
|
||
|
||
## Camera movement
|
||
|
||
Tiles use a fixed grid in the surface's local coordinates. Texture resolution changes in
|
||
powers of two, so adjacent wheel steps reuse existing tiles. Panning requests only newly
|
||
exposed tiles. Existing textures stay visible while missing tiles are prepared, with a
|
||
lightweight surface motif beneath them to prevent blank areas.
|
||
|
||
`StageSurfaceCache` keeps queued tiles as metadata. A shared queue creates and renders at
|
||
most one tile per process frame across all surfaces. It also retires at most two obsolete
|
||
render targets per frame. This avoids large allocations, vector rebuilds, and batches of
|
||
GPU resource releases during camera input.
|
||
|
||
Each tile has a 256 × 128 pixel core and a four pixel gutter. The gutter is cropped during
|
||
compositing to prevent seams. Each surface requests at most 192 visible tiles and retains
|
||
at most 224 tiles, evicting older unused entries. Half-resolution tiles retain full brick
|
||
texture and wood grain. Only quarter-resolution tiles and below omit fine texture, for
|
||
distant views. Brick and plank positions remain fixed. Detail can fill in progressively
|
||
after movement, including when returning from a distant view to a normal zoom level.
|
||
|
||
## Invalidation and coverage
|
||
|
||
Geometry, finish, tint, and motif-origin changes invalidate that surface's tiles. Camera
|
||
movement selects tiles without invalidating their artwork. Render targets belong to the
|
||
surface node; queued references are weak so deleted surfaces cannot keep jobs alive.
|
||
|
||
Fully opaque rectangular sibling surfaces can suppress artwork entirely hidden behind
|
||
them. Coverage checks account for transforms, draw order, and visibility. Transparent
|
||
surfaces, custom materials, differing relative-Z conventions, and Y-sorted parents disable
|
||
this optimization conservatively. Revealing a surface resumes its pending tiles.
|
||
|
||
## Verification
|
||
|
||
`tests/test_scenery_surface_cache.gd` checks rendered appearance against the direct vector
|
||
renderer, tile reuse and invalidation, the shared build limit, allocation and retention
|
||
bounds, and covered-surface behavior. Run it with a graphical Godot renderer for pixel
|
||
comparisons. The adaptive preview regressions remain in
|
||
`tests/test_scenery_surface_preview.gd` and `tests/test_scenery_brick_preview.gd`.
|