This commit is contained in:
+74
@@ -0,0 +1,74 @@
|
||||
---
|
||||
id: LSN-0031
|
||||
ticket: render-all-scene-cache-and-camera-integration
|
||||
title: Frame Composition Belongs Above the Render Backend
|
||||
created: 2026-04-18
|
||||
tags: [gfx, runtime, render, camera, scene, sprites, frame-composer]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
`DSC-0025` split canonical scene ownership from viewport caching and resolver policy, but the runtime still treated `Gfx.render_all()` as the operational frame entrypoint. That left scene binding, camera state, cache refresh, and sprite submission spread across the wrong layer.
|
||||
|
||||
`DSC-0026` completed the integration by making `FrameComposer` the owner of frame orchestration and reducing `Gfx` to a backend that consumes already prepared render state.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Frame Orchestration Must Not Live in the Backend
|
||||
|
||||
**What:**
|
||||
`FrameComposer.render_frame()` became the canonical frame service, while `Gfx.render_all()` was retired from the runtime-facing flow.
|
||||
|
||||
**Why:**
|
||||
The backend should execute composition, not decide scene binding, camera policy, cache refresh, or sprite lifecycle. Keeping those responsibilities above `Gfx` preserves a cleaner ownership model and avoids re-entangling policy with raster code.
|
||||
|
||||
**Trade-offs:**
|
||||
This adds an explicit orchestration layer between runtime callsites and the renderer, but the resulting boundaries are easier to evolve and test.
|
||||
|
||||
### Scene Binding, Camera, Cache, and Sprites Form One Operational Unit
|
||||
|
||||
**What:**
|
||||
`FrameComposer` owns:
|
||||
- active scene binding by bank id and shared scene reference;
|
||||
- camera coordinates in top-left world pixel space;
|
||||
- `SceneViewportCache` and `SceneViewportResolver`;
|
||||
- a frame-emission `SpriteController`.
|
||||
|
||||
**Why:**
|
||||
These concerns all define what a frame is. Splitting them across multiple owners would recreate stale-state bugs and make no-scene behavior ambiguous.
|
||||
|
||||
**Trade-offs:**
|
||||
The composer becomes a richer subsystem, but it carries policy in one place instead of leaking it into unrelated APIs.
|
||||
|
||||
### The World Path Must Stay Tile-Size Agnostic
|
||||
|
||||
**What:**
|
||||
The integrated frame path derives cache sizing, resolver math, and world-copy behavior from per-layer scene metadata instead of a hard-coded `16x16` assumption.
|
||||
|
||||
**Why:**
|
||||
The scene contract already allows canonical `8x8`, `16x16`, and `32x32` tile sizes. The frame service has to consume that contract faithfully or it becomes a hidden compatibility break.
|
||||
|
||||
**Trade-offs:**
|
||||
The integration and tests need to exercise more than the legacy default path, but the renderer no longer bakes in a false invariant.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Put frame policy in a dedicated orchestration layer and keep the renderer backend-oriented.
|
||||
- Treat scene binding, camera state, cache lifetime, and sprite submission as one cohesive frame model.
|
||||
- Refresh cache state inside the orchestrator before composition instead of letting the renderer discover refresh policy.
|
||||
- Prefer frame-emission sprite submission with internal ordering over caller-owned sprite slots.
|
||||
- Keep the no-scene path valid so world composition remains optional, not mandatory.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Leaving `render_all()` alive as a canonical path creates a fragile dual-service model.
|
||||
- Letting `Gfx` own cache refresh semantics collapses the boundary between policy and execution.
|
||||
- Requiring a scene for every frame quietly breaks sprite-only or fade-only operation.
|
||||
- Testing only `16x16` scenes hides regressions against valid `8x8` or `32x32` content.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Frame composition belongs in a subsystem that owns policy, not in the backend that draws pixels.
|
||||
- Scene binding, camera, cache, resolver, and sprite submission should converge under one frame owner.
|
||||
- No-scene rendering is part of the contract and should stay valid throughout integration work.
|
||||
- Tile-size assumptions must be derived from canonical scene metadata, never from renderer habit.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: LSN-0032
|
||||
ticket: frame-composer-public-syscall-surface
|
||||
title: Public ABI Must Follow the Canonical Service Boundary
|
||||
created: 2026-04-18
|
||||
tags: [gfx, runtime, syscall, abi, frame-composer, scene, camera, sprites]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
`DSC-0026` finished the internal migration to `FrameComposer` as the canonical frame-orchestration owner, but the public VM-facing ABI still exposed part of that behavior through legacy `gfx`-domain calls. That left the codebase with a mismatch between the real runtime ownership model and the surface visible to cartridges, tooling, and syscall declarations.
|
||||
|
||||
`DSC-0027` closed that gap by introducing the `composer.*` public domain and removing the old public sprite path.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Public Syscalls Must Expose the Real Owner
|
||||
|
||||
**What:**
|
||||
Scene binding, camera control, and sprite emission now live under `composer.*`, and the legacy public `gfx.set_sprite` path is gone.
|
||||
|
||||
**Why:**
|
||||
Once `FrameComposer` became the canonical orchestration service, keeping public orchestration under `gfx.*` would preserve the wrong mental model and encourage callers to treat the render backend as the owner of frame policy.
|
||||
|
||||
**Trade-offs:**
|
||||
This forces migration across ABI declarations, runtime dispatch, tests, and tooling, but it removes the long-term cost of a misleading public boundary.
|
||||
|
||||
### Domain-Specific Status Types Preserve Architectural Meaning
|
||||
|
||||
**What:**
|
||||
Mutating public composer operations return `ComposerOpStatus` instead of reusing backend-oriented status naming.
|
||||
|
||||
**Why:**
|
||||
Operational outcomes for scene binding or sprite emission are not backend-domain results. Reusing `GfxOpStatus` would blur the boundary that the migration was trying to make explicit.
|
||||
|
||||
**Trade-offs:**
|
||||
This adds one more status family to maintain, but it keeps the public ABI semantically aligned with the actual service contract.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Promote internal ownership changes into the public ABI as part of the same migration thread.
|
||||
- Use syscall domains to encode service boundaries, not just namespace aesthetics.
|
||||
- Remove obsolete public fallbacks completely when they preserve the wrong operational model.
|
||||
- Keep runtime dispatch, bytecode declarations, and tooling aligned so the public path is exercised end to end.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Leaving a legacy public syscall alive after the internal model changes creates a dual-contract system that is harder to remove later.
|
||||
- Migrating runtime dispatch without migrating declarations and tooling can leave hidden ABI drift in tests and generators.
|
||||
- Reusing backend-specific status names in the wrong domain quietly leaks old ownership assumptions into new APIs.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The public ABI should mirror the canonical service boundary, not historical implementation leftovers.
|
||||
- Namespace changes are architectural when they change who is responsible for a behavior.
|
||||
- Removing a legacy public entrypoint is often safer than preserving a compatibility shim that encodes the wrong model.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: LSN-0033
|
||||
ticket: deferred-overlay-and-primitive-composition
|
||||
title: Debug Primitives Should Be a Final Overlay, Not Part of Game Composition
|
||||
created: 2026-04-18
|
||||
tags: [gfx, runtime, render, frame-composer, overlay, primitives, hud, debug]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
After `FrameComposer.render_frame()` became the canonical game-frame entrypoint, immediate `gfx.*` primitive writes were no longer stable. Scene-backed composition could rebuild the framebuffer after `draw_text(...)` or other debug primitives had already written to it.
|
||||
|
||||
`DSC-0028` resolved that conflict by moving `gfx.*` primitives into a deferred overlay/debug stage outside `FrameComposer`, drained only after canonical game composition and fades are complete.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Debug Overlay Must Stay Outside the Canonical Game Pipeline
|
||||
|
||||
**What:**
|
||||
`FrameComposer` keeps ownership of canonical game composition, while debug/text/primitive commands are captured separately and drained later as a final overlay.
|
||||
|
||||
**Why:**
|
||||
Game composition and debug overlay have different purposes. The first must remain canonical and deterministic; the second must remain opportunistic, screen-space, and independent from scene or sprite semantics.
|
||||
|
||||
**Trade-offs:**
|
||||
The renderer needs a second deferred path, but the game pipeline no longer depends on transient debug state.
|
||||
|
||||
### Final Visual Ordering Matters More Than Immediate Writes
|
||||
|
||||
**What:**
|
||||
Overlay/debug commands are drained after scene composition, sprite composition, and fades, with parity between scene-bound and no-scene frame paths.
|
||||
|
||||
**Why:**
|
||||
The stable user-visible contract is that debug primitives appear on top. Immediate writes were only an implementation detail, and they stopped preserving that contract once frame composition became deferred and canonical.
|
||||
|
||||
**Trade-offs:**
|
||||
This changes primitive semantics from "write now" to "show at frame end," but it produces the behavior users actually rely on.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Separate canonical composition state from debug-overlay state even when both reuse the same raster backend.
|
||||
- Capture primitives as commands first, then drain them at the final stage where visual priority is unambiguous.
|
||||
- Preserve the same overlay semantics whether a scene is bound or not.
|
||||
- Keep implementation reuse internal while maintaining a clear semantic boundary in the public model.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating debug primitives as part of HUD or scene composition will eventually couple tooling/debug behavior to gameplay pipeline rules.
|
||||
- Draining overlay before fades or before final frame composition breaks the visible "always on top" contract.
|
||||
- Reusing `FrameComposer` storage for overlay state collapses the ownership split that prevents these bugs.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Immediate framebuffer writes are not a reliable contract once final composition is orchestrated elsewhere.
|
||||
- Debug primitives work best as a dedicated final overlay layer.
|
||||
- Ownership separation is what keeps debug behavior stable while the canonical render pipeline evolves.
|
||||
Reference in New Issue
Block a user