80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
---
|
|
id: PLN-0110
|
|
ticket: real-render-worker-establishment
|
|
title: Define Owned RGBA8888 Frame Contract
|
|
status: open
|
|
created: 2026-06-15
|
|
completed:
|
|
ref_decisions: [DEC-0033]
|
|
tags: [runtime, renderer, worker, hal, frame-contract]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0033` requires the worker to publish an owned RGBA8888 frame that is independent of native window APIs. This plan defines that shared HAL contract before any worker implementation depends on it.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0033`: Real Render Worker Contract.
|
|
|
|
## Alvo
|
|
|
|
Introduce `OwnedRgba8888Frame` in `prometeu-hal` as the canonical worker-to-host published frame type.
|
|
|
|
## Escopo
|
|
|
|
- Add the shared frame type to HAL.
|
|
- Include frame id, ownership/epoch metadata, dimensions, stride, and owned `Vec<u32>` RGBA8888 pixels.
|
|
- Add constructors and validation helpers that keep dimensions, stride, and pixel length coherent.
|
|
- Add unit tests for layout and validation.
|
|
|
|
## Fora de Escopo
|
|
|
|
- No worker thread.
|
|
- No host upload/present integration.
|
|
- No resource bank access.
|
|
- No spec updates beyond code-facing rustdoc if useful.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Add HAL frame module
|
|
|
|
**What:** Add `OwnedRgba8888Frame`.
|
|
**How:** Create a HAL module, likely `crates/console/prometeu-hal/src/owned_frame.rs` or equivalent, and export it from `lib.rs`.
|
|
**File(s):** `crates/console/prometeu-hal/src/lib.rs`, new HAL frame module.
|
|
|
|
### Step 2 - Define required fields
|
|
|
|
**What:** Encode the DEC-0033 frame contract.
|
|
**How:** Include `FrameId`, render ownership/epoch metadata compatible with `RenderSubmission`, `width`, `height`, `stride_pixels`, and `pixels: Vec<u32>`.
|
|
**File(s):** HAL frame module, existing render ownership types if reuse is needed.
|
|
|
|
### Step 3 - Add constructors and validation
|
|
|
|
**What:** Prevent malformed frame buffers from entering the worker-host boundary.
|
|
**How:** Add checked constructor(s) that reject zero dimensions, too-small stride, and pixel buffers shorter than `stride_pixels * height`.
|
|
**File(s):** HAL frame module.
|
|
|
|
### Step 4 - Add tests
|
|
|
|
**What:** Pin layout semantics.
|
|
**How:** Test valid construction, invalid stride, invalid pixel length, and that raw pixel values are preserved as RGBA8888 `u32`.
|
|
**File(s):** HAL frame module tests.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] `OwnedRgba8888Frame` is exported by `prometeu-hal`.
|
|
- [ ] The type contains `FrameId`, ownership/epoch, width, height, `stride_pixels`, and `Vec<u32>` pixels.
|
|
- [ ] Invalid dimensions/stride/pixel length cannot be silently accepted by checked constructors.
|
|
- [ ] No native host/window/pixels/winit/SDL type appears in the HAL frame contract.
|
|
|
|
## Tests / Validacao
|
|
|
|
- `cargo test -p prometeu-hal`
|
|
- `rg "OwnedRgba8888Frame" crates/console/prometeu-hal -n`
|
|
|
|
## Riscos
|
|
|
|
- Reusing native pixel terminology could blur the logical RGBA8888 contract.
|
|
- Overfitting the frame type to current desktop upload code would leak host details into HAL.
|