Mercurial

annotate infinite_canvas/docs/rendering.md @ 280:49e9e591c9bb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
author MrJuneJune <me@mrjunejune.com>
date Tue, 18 Aug 2026 19:14:53 -0700
parents 8d560f50ed4c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
278
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 # Rendering Surfaces
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 ## Choose the renderer by content
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 | Content | Entity type | Native | WebAssembly |
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6 | --- | --- | --- | --- |
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7 | Shapes, text, controls | regular `CANVAS_ENTITY_*` | Raylib | Raylib/WASM |
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 | Lucide icons | `CANVAS_ENTITY_LUCIDE_GALLERY` | Raylib line segments | Raylib/WASM line segments |
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9 | Image URL or file | `CANVAS_ENTITY_IMAGE` | CEF off-screen pixels uploaded to a Raylib texture | positioned `<img>` overlay |
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10 | Live web page | `CANVAS_ENTITY_WEB_CONTENT` | CEF off-screen pixels uploaded to a Raylib texture | positioned `<iframe>` overlay |
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 Do not route vector icons or ordinary components through CEF. They belong in
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 `Canvas_Draw_Entity()` so they inherit camera transforms, theme colors,
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 selection, dragging, pinning, and context behavior without another rendering
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 runtime.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 ## Raylib entities
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 `Canvas_Draw_World()` opens one `BeginMode2D()` camera and draws every retained
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 entity through `Canvas_Draw_Entity()`. Components such as buttons, dropdowns,
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 cards, calendars, tables, and switches are immediate Raylib draw calls backed
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 by state in `Canvas_Entity`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 The scene-array order is the z-order. The main frame interleaves each Raylib
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
25 entity layer with its native CEF/image texture, so a later button can genuinely
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26 draw over and receive input ahead of an earlier browser surface. Picking and
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 native browser input both resolve the same reverse scene order.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 The Lucide gallery follows the same path. The generator
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30 `tools/generate_lucide_data.mjs` downloads pinned Lucide 1.31.0 definitions,
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 flattens SVG paths and primitives into line segments, and writes
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32 `generated/lucide_data.h`. The gallery virtualizes rows: only cards fully inside
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 its visible body issue Raylib draw calls. Its Raylib search field filters icon
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34 names case-insensitively and resets the internal scroll offset when edited.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36 Regenerate after changing the pinned icon version:
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 ```bash
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 node infinite_canvas/tools/generate_lucide_data.mjs
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 ```
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 ## Native image and web surfaces
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 `web_surface_native.cc` maintains a pool of at most `CANVAS_MAX_WEB_VIEWS`
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45 off-screen CEF browsers. Visible image and web entities are reconciled by stable
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 entity ID. CEF paint callbacks fill arena-owned RGBA buffers; `Sync()` creates or
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 updates Raylib textures; `Draw()` composites those textures into the
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48 camera-derived screen bounds.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 Resolution follows displayed size in stable buckets and is capped. Off-screen
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 entities release their active pool slot, small background views receive lower
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52 frame rates, and the focused view receives the largest frame budget.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 When a web entity is selected, C reserves a fixed-screen-height toolbar above
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55 the page viewport. The reserved height and toolbar clip animate together so
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56 selection pushes the page down like an opening accordion and deselection pulls
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 it back up. Raylib draws the themed editable address field and Lucide
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58 navigation icons after that entity's CEF texture, preserving scene z-order.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
59 The URL editor retains its own draft, caret, selection, horizontal scroll, and
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60 clipboard focus; committing updates the entity URL, which triggers backend
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 navigation. CEF reports main-frame address changes and history availability
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62 back to the toolbar.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 CEF emulates the canvas `prefers-color-scheme` value and updates the page
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64 `color-scheme` when the canvas theme changes.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66 Images use a bundled `image-view.html` wrapper for `object-fit: contain`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67 Filesystem paths are resolved to `file://`; URLs remain URLs.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69 ## WebAssembly image and web surfaces
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 `web_surface_web.c` cannot composite cross-origin page pixels into WebGL, so it
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72 positions DOM overlays over the Raylib canvas. It creates `<img>` elements for
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 images and sandboxed `<iframe>` elements for live pages, converts Raylib screen
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74 coordinates to CSS coordinates, and removes overlays that are no longer
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 visible.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
76
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
77 Selected iframe entities use the same Raylib toolbar geometry and move the DOM
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
78 viewport below it. The iframe element receives the canvas `color-scheme`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
79 History navigation is best-effort because cross-origin iframe history and
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
80 address inspection remain browser-controlled; the displayed URL falls back to
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
81 the entity's configured URL.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
82
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
83 This is intentionally different from native. Shared scene semantics live in C;
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
84 the platform backend owns only presentation and input details.