implements PLN-0120

This commit is contained in:
2026-06-16 05:46:13 +01:00
parent 67a629dbe4
commit 850ca8691b
6 changed files with 92 additions and 5 deletions
+44
View File
@@ -73,6 +73,24 @@ Color values in the runtime, HAL, host-facing framebuffer, and GFX ABI are
logical RGBA8888 values. RGB565 is not a supported runtime framebuffer,
palette, host presentation, or compatibility contract.
### Published owned frame
The canonical worker-published frame value is `OwnedRgba8888Frame`.
`OwnedRgba8888Frame` contains:
- the logical `FrameId`;
- render ownership metadata;
- width and height in pixels;
- stride in pixels;
- an owned `Vec<u32>` containing packed RGBA8888 pixels in canonical RGBA
channel order.
The pixel vector is owned by the published frame. Consumers may copy it into a
host upload buffer, retain it as the latest published frame, or repeat it for a
host redraw. Consumers MUST NOT interpret the frame as a native texture,
swapchain image, window handle, or host GPU resource.
---
## 3. Double Buffering
@@ -134,6 +152,11 @@ to the logical/runtime side before handoff, or to an owning service. They MUST
NOT require the render consumer to hold mutable VM, `Hardware`, `Gfx`, or
`FrameComposer` references.
Read-only resource APIs expose compact lookup by ID. They do not expose mutable
bank state, `Arc` ownership as part of the contract, copies of whole banks, or
snapshot payloads. The implementation may choose its internal sharing mechanism,
but the render boundary contract is ID-based read-only access.
Local host implementations may keep a concrete hardware object internally as a
platform implementation detail. That object is not part of the runtime-facing
render boundary; the boundary is the typed platform service set.
@@ -155,6 +178,12 @@ latest-wins semantics:
The consumer status is telemetry. It is not a semantic ACK to the VM.
The real render worker consumes owned `RenderSubmission` values from this
single-slot handoff and publishes owned `OwnedRgba8888Frame` values. The
producer path MUST remain non-blocking with respect to worker rasterization and
host present. A slow worker can cause replacement/drop telemetry, but it MUST
NOT create an unbounded queue or stall VM logical frame production.
### 4.4 Frame pacing
Game logical frames are paced by the runtime frame scheduler, not by render
@@ -170,6 +199,10 @@ sequential. The render consumer may repeat the last valid frame, and telemetry
records the overrun/repeat. The VM MUST NOT produce catch-up frames to skip
from frame `N` to frame `N+k`.
Repeating a frame means reusing the latest published `OwnedRgba8888Frame`
without recomposing, rerunning VM code, or consuming a new submission. Repeat
behavior is presentation cadence behavior, not guest-visible execution.
### 4.5 AppMode policy
Render execution policy is explicit by pipeline/AppMode:
@@ -231,6 +264,17 @@ Minimum render telemetry includes:
- last produced, consumed, presented, dropped, and error frame IDs;
- active render epoch.
### 4.8 Shutdown and typed failures
Render worker shutdown is bounded and observable. A shutdown request MUST
wake a waiting worker, discard pending submissions that will not be consumed,
and either join within the configured timeout or report a typed shutdown
failure.
Worker backend failures, sink publication failures, stale ownership discards,
panic capture, and shutdown timeout are typed render worker outcomes. They are
recorded through telemetry and diagnostics; they do not become VM-visible ACKs.
---
## 5. PROMETEU Graphical Structure