Add shape primitives and sprite flipping

[TomHoenderdos]

Summary

Adds vector shape primitives and sprite flipping to the display list, plus a rendering benchmark and opt-in LCD profiling.

{rounded_rect, X, Y, W, H, Radius, Color}
{line, X1, Y1, X2, Y2, Thickness, Color}
{circle, CX, CY, R, Color}
{ellipse, CX, CY, RX, RY, Color}
{arc, CX, CY, R, Thickness, StartDeg, EndDeg, Color}   % clockwise from StartDeg to EndDeg
{polygon, [{X, Y}, ...], Color}                        % even-odd, up to 256 points
{scaled_cropped_image, ..., [flip_x, flip_y], Img}     % or {flip_x, true}

Exact pixel rules, limits and validation are documented in docs/primitives.md.

Display list validation (#19) and the one-pass walk (#21) are merged; the SDL damage fix is in #20 and the per-row item walk in #22.

Commits

1. Add flip_x and flip_y to scaled_cropped_image
2. Add rounded_rect primitive: also adds the shape module (shape.c, integer-only geometry, exact scanline runs cached per row), the renderer hooks and tests/shapes.
3. Add circle primitive
4. Add ellipse primitive
5. Add line primitive
6. Add arc primitive
7. Add polygon primitive
8. Add rendering benchmark and LCD profiling: host benchmark and an opt-in -DATOMGL_PROFILE=1 log line (parse / draw / max line / spi wait / frame).

Each commit builds and passes tests/shapes (UBSan) and tests/items (ASan+UBSan) on its own.

Tested on hardware

ESP32-S3 badge, ST7789 320×240 RGB565 at 80 MHz SPI, ESP-IDF 5.5.2, running a racing game with 71–104 items per frame (road/kerb polygons, full-width rects, a scaled sprite, an arc, HUD text) with -DATOMGL_PROFILE=1, on the previous version of this branch. The draw time numbers from that run are in #22.

Other testing

• tests/shapes, tests/items (ASan+UBSan), tests/bench on the host, for every commit.
• This touches the same lines of dcs_lcd_display_driver.c and display_items.h as Walk only items that cover the current row #22; whichever is merged second will be rebased.
• On the previous version of this branch: randomized differential checks (valid rect/text/image scenes render byte-identical to main) and upstream CI reproduced locally in Docker (AtomVM release-0.6, IDF 5.4.3 and 5.5.2, esp32 and esp32s3, with and without ATOMGL_PROFILE).
• Not tested: the SDL plugin as a whole (it doesn't build against release-0.6 on main either, ufont_manager_register arity).

Compatibility

Existing display lists render the same; the previously ignored Opts of scaled_cropped_image now accepts flips, other entries are still ignored. BaseDisplayItem stays 56 bytes on ESP32; each shape item allocates its geometry separately.

🤖 Generated with Claude Code

[TomHoenderdos]

@bettio, tested this on the racer game and it works amazing :)

[bettio]

Let's start sorting this PR, would you mind extracting "display_items: Validate display list items" commit (6d59cb0) and the related tests: b0bfe1e and make a new PR just with those 2 commits?

[bettio]

So we are getting close and closer.

Here some action points:

1. Rebase on main. The only conflicts are two hunks that add the flip and shape cases to cmp_display_item(), which sdl: Fix plugin build and remove broken damage tracking #23 removed; drop them. Item comparison is moving to a shared display_diff module where shape_equal() and the flip fields will be compared.

2. Fold the per-item outside-run memo into shape_run(). The shape already caches its row, so the memo only saves a call and a switch, while it costs three fields in ShapeItemData, two helpers in display_items.h and the same remember/lookup dance in four renderers. With the gap check inside shape.c, the item holds just the pointer and each renderer's shape case shrinks to a few lines.

3. Transparent runs for every drawer. draw_x now carries a transparent_run down to the items below, but only shapes feed it; text, image and scaled image still return 0 and the items below get one pixel per call, so every background pixel of a label or a sprite costs a full draw_x round. Have those drawers report their transparent run the same way, and unify the contract on the return value (positive: pixels drawn, negative: transparent for that many pixels) so the shape drawer's out-parameter can go and draw_x has one rule. Measured on the host on top of the per-row lists of Walk only items that cover the current row #22, output identical on 2000 random scenes: a 25-label text UI 111 → 63 us/frame, ufont-style glyph images 106 → 56, text with no background 159 → 55, racer-like scene 53 → 40, sprites with holes about 1.3x (that run also changed the scaled stepping, which does not apply to your helper, so expect less there). Your call whether it is a last commit here or a follow-up stacked on this PR; it supersedes what I wrote in Walk only items that cover the current row #22 about doing it on our side.

4. display_items.h is becoming an implementation file. The flip/scaled row helpers are about 110 lines of inline math with a negative divisor for mirroring and an INT_MAX sentinel mode in ..._span(), and display_items_scaled_cropped_pixel() implements the same mapping a second time. Comments or a plainer representation, please. If you prefer, the flips commit could also become its own small PR so this one is shapes only.

5. Polygon parsing. The point count is known before the points are read, so they can be parsed straight into the shape allocation instead of a temporary array handed to shape_new_polygon_owned(), an API that exists only to free its input; that is one allocation less per polygon per update. Also consider a cap below 256 points: at 38 bytes per vertex a maximal polygon is close to 10 KB per item per frame, and nothing realistic needs it.

6. Diagnostics. Every shape failure logs "wrong arity, bad argument or out of memory", where the other primitives name the cause. Checking the arity first and saying so is trivial and keeps the error lines useful.

7. Arc segment arrays. seg_start[13] and seg_inside[12] are written at seg_count + 1 and seg_count after the loop, which is in bounds only because a row never has more than 6 inside/outside transitions (I checked by fuzzing and by exhaustive search over radii, thicknesses and angles). One entry of slack, or an assert, would make that explicit.

8. Nits. init_shape_item() has an unused ctx (new -Wextra warning on the host); new_polygon() checks malloc without IS_NULL_PTR/UNLIKELY; shape_contains() could take const; the rewritten scaled loops in sdl_display/display.c, mono_draw.c and epaper_draw.c kept (*pixels >> 24) next to the READ_32_UNALIGNED value, UBSan flags it with unaligned image data, use img_pixel; clang-format on the new test files.

9. Not blocking, worth a measurement. On the host, with the shape case present in draw_x, the existing primitives render 20-50% slower per draw_x call (removing only that case restores main's speed; neither jump tables, stack protector, inlining nor alignment explain it). On the device that would be roughly 1% of the draw time, so a before/after ATOMGL_PROFILE on a shape-free scene would settle it.