Render phase should auto-clear + auto-present; clear color configured declaratively #86

New issue

Closed

opened 2026-09-02 04:52:44 +02:00 by orkun · 1 comment

orkun commented

2026-09-02 04:52:44 +02:00

Owner

Games must manually call Screen.clear(color) at the top and Screen.show() at the bottom of every Render handler. Only the light system currently auto-presents ("the engine owns the flip for an ECS-lit frame").

Proposal: the Render phase auto-clears (to a configurable clear color set declaratively — a scene/world property or @ClearColor, not in the handler body) and auto-presents after Render handlers run, so games don't repeat clear/show boilerplate.

Games must manually call `Screen.clear(color)` at the top and `Screen.show()` at the bottom of every Render handler. Only the light system currently auto-presents ("the engine owns the flip for an ECS-lit frame"). Proposal: the Render phase auto-clears (to a configurable clear color set declaratively — a scene/world property or `@ClearColor`, not in the handler body) and auto-presents after Render handlers run, so games don't repeat clear/show boilerplate.

orkun referenced this issue from a commit

2026-09-02 06:10:47 +02:00

feat(render): #86 @ClearColor — Render phase auto-clears + auto-presents

orkun commented

2026-09-02 06:10:57 +02:00

Author

Owner

Shipped in d9287d6 (real implementation, tested — full suite 108/0, golden renders byte-identical, C-free bootstrap fixpoint intact).

@ClearColor(0xRRGGBB) declares the framebuffer clear colour, and the engine then owns the per-frame clear + flip: at the top of the Render phase it clears the framebuffer to the colour, and after all Render handlers run it presents the frame. A game's Render handler no longer repeats Screen.clear(color) / Screen.show(), and the clear colour is configured declaratively (an annotation), not in the handler body — exactly as the proposal asked.

Backward-compatible / opt-in: a program with no @ClearColor is byte-for-byte identical — it clears and presents itself, or (for an ECS-lit frame) the light system still owns the present. The clear/present emit is gated on the annotation flag.

Verified by examples/library/clear_color.ludic: a handler game with @ClearColor(0x102030) and a Render handler that draws a box but calls no Screen.clear/show; pixel readback after the frame confirms an undrawn pixel holds 0x102030 (so the engine cleared) and the box is present. Wired as a feat_case; docs page + inventory entry added.

Shipped in d9287d6 (real implementation, tested — full suite 108/0, golden renders byte-identical, C-free bootstrap fixpoint intact). **`@ClearColor(0xRRGGBB)`** declares the framebuffer clear colour, and the engine then owns the per-frame clear + flip: at the top of the Render phase it clears the framebuffer to the colour, and after all Render handlers run it presents the frame. A game's Render handler no longer repeats `Screen.clear(color)` / `Screen.show()`, and the clear colour is configured **declaratively** (an annotation), not in the handler body — exactly as the proposal asked. Backward-compatible / opt-in: a program with no `@ClearColor` is **byte-for-byte identical** — it clears and presents itself, or (for an ECS-lit frame) the light system still owns the present. The clear/present emit is gated on the annotation flag. Verified by `examples/library/clear_color.ludic`: a handler game with `@ClearColor(0x102030)` and a Render handler that draws a box but calls **no** Screen.clear/show; pixel readback after the frame confirms an undrawn pixel holds 0x102030 (so the engine cleared) and the box is present. Wired as a feat_case; docs page + inventory entry added.

orkun closed this issue

2026-09-02 06:10:57 +02:00