Repository navigation
[M2-PAR-01] Parallax layers - #79
Merged
Merged
Conversation
…et, UV scroll (FR-2.3)
NEW laige::render::ParallaxLayers<Backend> (header-only, templated over
the SimMath backends — the presentation.h pattern): the named
background/midground/foreground layer model of FR-2.3.
Model — a layer is a WORLD-SPACE RECTANGLE (one texture — the Image
source — or one tilemap — the Tilemap source, the M2-TILE-02 hook,
data-only here) whose content position at camera position p is the
EXACT formula (pinned by tests, bit-exact for dyadic values):
worldOffset(p) = factor * (p - center) + offset
factor in [0, 1] (one source of truth): 0 = fixed in world space
(maximum parallax, a close-by background), 1 = fixed on screen (no
parallax, the sky layer); center = the reference camera position
(default the world origin); offset = the world-space offset at
p = center. Everything is world space (PRD §4, RENDER-006); the
camera position is the presentation-side input (ARCH-009).
Render order (documented — background first) — the layer quads carry
the M2-ISO-01 key's LAYER field (engine-owned, G-R11): the presets are
kParallaxDepthLayerBackground = -2, kParallaxDepthLayerMidground = -1,
kIsoDepthGroundLayer = 0 (the ground), kParallaxDepthLayerForeground
= +1; a custom layer picks any value in the M2-ISO-01 domain
[-512, +511]. WITHIN a shared (atlas, material, blend) group the layer
field dominates the key — background quads sort before every ground
object and foreground quads after it, whatever the quads' v
(engine-guaranteed). ACROSS groups the draw order is the batcher's
group order (ascending (atlas, material, blend), RENDER-003) — the
scene's SET-UP assigns the layers' atlas ids background-below /
foreground-above the world content (the M2-TILE-01 convention).
UV scroll (auto or manual) — each layer carries a CURRENT UV OFFSET in
[0, 1)^2. Manual: setUvOffset (any finite value, wrapped to [0, 1)^2).
Auto: advanceScrolls() advances by scrollSpeed (UV units PER FRAME per
axis — frames are the presentation pace; frame-rate independence is
the caller's concern, the M2-CAM-01 lerp precedent), once per frame,
before the declarations. The WRAP is exact at the texture boundary:
wrap(x) = x - floor(x) (1.0 -> exactly 0.0; -0.25 -> exactly 0.75). A
scrolled layer renders through the 2 x 2 wrap split (one SpriteItem
carries one UV rect — no wrap): up to four quads per layer (q00, q10,
q01, q11; an empty-range quad is skipped), one draw call per layer
group (FR-2.1, RENDER-001).
Semantics — one owner (the sim/scene-owner thread; the M2-GL-02
cull/batch stage owns the render-side declaration); sim-phase writes /
render-phase reads (CONC-001); ARCH-009 headless-buildable,
presentation-only (never sim state, never replay state); no per-frame
allocation (FR-2.2 — the 1000-frame zero-allocation proof);
setLayer validates first-failure-wins (a rejection leaves the slot
unchanged + one rate-limited parallax/layer_invalid warn with the
failing field — LOG-004); the happy paths log nothing (LOG-002/003).
Tests — NEW tests/laige-render/parallax_tests.cpp (CTest entry
'parallax' = the step's Verify command; 12 tests / 6 suites, no GL —
runs in every tree): the create/stopped-state matrix; the setLayer
validation matrix (15 rejections with pinned warn fields, domain
edges, the Tilemap size/uv not validated, state-unchanged-on-rejection,
replace + scroll-reset); the EXACT offset formula (hand-computed
dyadic goldens, both backends agree; factor-0.3 linearity within
tolerance); the auto/manual UV scroll with the EXACT wrap at the
texture boundary; the golden declare (the 4-layer + ground scene,
camera (10,6), both backends: the 5 quads pinned field-by-field, the
hand-computed 32-bit keys (with the 2^21 base) against the
independent M2-ISO-01 oracle, the group draw order, the
layer-dominance orderings, cross-frame determinism); the scrolled
split (full/half/un-scrolled: 4/2/1 quads, the world rects tile the
rectangle exactly, the atlas sub-rect mapping, the offset layer, the
frameCounts pin); the frame protocol (built frame / stopped batcher /
stopped registry / disabled + tilemap-hook skips); the 1000-frame
zero-allocation loop.
Docs — NEW docs/api/parallax.md (the API table, the model + the exact
formula, the render-order section, the UV scroll + the 2 x 2 split
table, ownership/threading, the DOC-004 Performance section, the
misuse warnings, the performant example); docs/README.md index entry;
the module README status paragraph; docs/concepts/coordinates.md
(NEW section 4.10 + the section 5 conversion row + the section 6
render-order summary + the Related link); the stale 'land with
M2-PAR-01' references updated (iso_depth_key.md, iso_depth_table.md,
tilemap.md, the tilemap.h comment).
API surface — laige-api.json regenerated LAST (1265 -> 1315 symbols,
39 -> 40 headers: the 2 enums, ParallaxLayerDef + 16 fields + the
field-wise operator== (a defaulted == would be deleted — SpriteUvRect
has no operator==), ParallaxLayers + Options + 13 public members, the
6 kParallax* constants). Additive only.
Budget — no standalone budgets.json entry (the count stays 16 — the
BudgetHarnessTable.LoadsTheRepoBudgetsFile pin): the per-frame declare
cost is PART of the composite 50k render-CPU budget (PRD section 8.1,
sprites_50k_cpu — M2-PERF-01 measures the reference scene with the
parallax layers included; the M2-SCENE-01 reference scene has 3
parallax layers within the 50k-sprite / <=30-draw-call budget).
Local verification — all six local trees warning-clean + full ctest
green: build 113/113, build-clang 113/113, build-release 102/102,
build-shared 113/113, build-asan 110/110, build-tsan 110/110 (the prior
counts +1 each — the new 'parallax' entry); ctest -R parallax green
(12/12); api-real-tree / api-check-fresh / include-lint /
determinism-lint green.
… pull_request event)
…ntees the float overload of std::floor; std::floorf is not guaranteed in std — the CI 'Determinism check' job's libstdc++ does not expose it)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
M2-PAR-01 · Parallax layers (FR-2.3)
The named background/midground/foreground layer model: parallax factor (0..1), world-space offset, UV scroll (auto or manual), blend — all rendered through the sprite batcher (S-5).
laige::render::ParallaxLayers<Backend>(header-only, templated over the SimMath backends) — the layer registry with the bounded slot table + the per-frame protocol.worldOffset(p) = factor * (p - center) + offset— pinned bit-exactly for dyadic values, both backends.wrap(x) = x - floor(x)— 1.0 → exactly 0.0), rendered through the 2×2 wrap split (one SpriteItem carries one UV rect — no wrap): up to 4 quads per layer, one draw call per layer group.declareTo; size/uv not validated).parallax/layer_invalidwarn per rejected def.parallax— 12 tests / 6 suites, no GL (12/12 green;ctest -R parallax= the step's Verify).docs/api/parallax.md; coordinates.md §4.10 + §5/§6 rows; module README; docs index; stale refs in iso_depth_key/iso_depth_table/tilemap updated.laige-api.jsonregenerated last (1265 → 1315 symbols, 39 → 40 headers).budgets.jsonentry (count stays 16) — the per-frame declare cost is part of the composite 50k render-CPU budget (M2-PERF-01; the M2-SCENE-01 reference scene has 3 parallax layers within the 50k-sprite / ≤30-draw-call budget).Roadmap board: M2 17/33 → 18/33, total 63/194 → 64/194; box checked; change-log row added. CI: one P0 OS per PR — Linux lane on the default event + the ci:windows lane (MSVC audit of the new header-only template — C4267/C4244 precedent).