feat(render): #86 @ClearColor — Render phase auto-clears + auto-presents
All checks were successful
bootstrap / cfree-fixpoint (push) Successful in 23s
ci / build-and-test (push) Successful in 2m18s
commit-lint / conventional-commits (push) Successful in 4s
docs / build-and-deploy (push) Successful in 28s

@ClearColor(0xRRGGBB) declares the framebuffer clear colour, so the engine
owns the per-frame clear and flip: the Render phase clears to the colour at
the top and presents after the handlers run. Games drop the repeated
Screen.clear(color)/Screen.show() boilerplate, and the colour is configured
declaratively (an annotation) rather than in the handler body. Opt-in and
backward-compatible: a program with no @ClearColor is byte-for-byte identical
(it clears/presents itself, or the light system owns the present).

Parser reads @ClearColor(int) into g_clear_color/g_has_clear_color;
emit_game_main emits rt_clear before and rt_present after the Render phase,
gated on the flag. Example clear_color (pixel-readback verified — an undrawn
pixel holds the clear colour, proving the engine cleared), docs page +
inventory entry. Full suite 108/0, goldens byte-identical, fixpoint holds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-09-02 07:10:44 +03:00
parent bccd26fb29
commit d9287d6b1d
8 changed files with 18108 additions and 17936 deletions

View file

@ -0,0 +1,23 @@
---
id: annot-clearcolor
name: "@ClearColor"
category: annotations
kind: annotation
tokens: "@ClearColor"
sig: "@ClearColor(0xRRGGBB) handler Draw phase Render { … }"
tip: Declare a clear colour so the Render phase auto-clears + auto-presents for you.
order: 62
---
<code>@ClearColor(N)</code> declares the framebuffer clear colour (a <code>0x00RRGGBB</code> integer) so the engine owns the per-frame clear and present: at the top of the Render phase it clears the framebuffer to <code>N</code>, and after all Render handlers run it presents the frame — so a game's Render handler carries no <code>Screen.clear</code> / <code>Screen.show</code> boilerplate, and the colour is configured declaratively rather than written in the handler body. It is opt-in: a program with no <code>@ClearColor</code> is byte-for-byte identical (it clears and presents itself, or the light system owns the present). Place it on the program's Render handler (or any declaration — it is program-wide).
```ludic
program ClearColorDemo {
property Tag { n: int = 0 }
model P { Tag }
@ClearColor(0x102030)
handler Draw phase Render {
Screen.fill_rectangle(10, 10, 4, 4, 0xffffff)
}
}
```