Files
faceclaw/app/graphics/display-list.md

117 lines
6.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TypeScript display lists
`GrayImage.drawDisplayList(list, x, y, width, height, depth)` retains a list alongside
the image's ordinary pixels. Existing frame submission (`prepareFrameDraws`) and
shell scene submission carry it to Kotlin. Bounds describe its footprint for plane
occlusion; draw coordinates are relative to its placement. Keep the list, its image
resources, and their pixel buffers immutable after submission.
```ts
import { DrawExpression as E } from './draw-expression';
import { DrawOp, type DisplayList } from './display-list';
const list: DisplayList = {
resources: [],
timeline: { token: animationId, startedAt: Date.now() },
calls: [{
op: DrawOp.ROUNDED_RECT,
x: E.progress(300).ease().lerp(E.f32(0), E.f32(100)).toInt(),
y: 0,
width: 40, height: 20, radius: 6,
background: 4, border: 15,
}],
};
frame.drawDisplayList(list, 20, 30, 140, 20, 0);
```
Supported calls:
- `ROUNDED_RECT`: literal or expression `x`/`y`, literal dimensions/radius, and
4-bit colors (0–15). Border 16 means no border. Fill takes the maximum of the
background color and existing pixels.
- `IMAGE`: a local resource index, integer `x`/`y`, and `transparent`. Transparent
images skip pixels quantized to zero. Resources have `width`, `height`, and
gray8 `pixels`; a baked `GrayImage` can be used directly.
- `RECT_COPY`: a local resource index, source rectangle and destination
`dx`/`dy`. Source x/y and `dx`/`dy` accept expressions (revision 29); the
source rectangle must stay inside the source at every time, or firmware
rejects the list. `SCREEN` reads the uncomposed frame; its source coordinates
are also relative to this list's placement. Each call may add its own `depth`
to the list's depth. A screen restore normally uses the negative of the list depth.
- `CLEAR` (revision 35 with a clip): fill with a 4-bit `color`. Under a clip it
fills just the clip rect, which is how to blank a region; without one it
fills the whole screen.
- `DRAWS` (bridge-only): replay glyph and icon draws offset by `x`/`y`, which
may be expressions. `records`/`count` come from glyph-wire's
`encodeReplayDraws(image.draws)`, which registers the rasters and returns null
unless every draw is a replayable glyph (atlas font, ASCII, ink inside the
line box) or plain image. Kotlin compiles them to firmware IMAGE calls on
ImageAtlas resources and TEXT runs on FontResourceAtlas fonts (one run per
line and color). `source` keeps the draws for software painting. If Kotlin
cannot resolve a record, the whole list draws nothing, so the frame's own
pixels show rather than content with a hole in it.
Any call may carry a `clip` (revision 35): a rect in list coordinates outside
which it draws nothing. It moves with the call's depth, like the call itself.
The firmware flag also nests (a clipped play-list call clips everything inside
it, intersected with the calls' own clips), but TS lists are inlined into the
root, so each call carries its own.
Kotlin allocates/cache-pins all image resources, resolves the local indices, applies
surface placement, and includes the calls in the root firmware display list. The
phone's existing display-list renderer consumes the same compiled calls. This uses
the current firmware protocol; no firmware update is needed for this bridge change.
## Expressions and time
`E.i32` and `E.f32` construct typed constants. Builders support arithmetic, min/max,
integer remainder, negation, explicit conversions, lerp, and the easing functions
in `ExprOp`. `ease()` defaults to smoothstep. Integers wrap at 32 bits; float
operations round to f32. The firmware's existing stack/error semantics apply.
Rounded-rectangle x/y and rect-copy source/destination coordinates accept
expressions. `E.progress(duration, delay)` stays 0 for the first `delay` ms of
the timeline, so one list can run motions that started at different times.
`maximum.time()` returns `min(milliseconds since PRESENT, maximum)`. The existing
45 ms repaint timer remains active while this is below maximum. `E.elapsed()` is
a bridge binding: Kotlin replaces it with the timeline's elapsed milliseconds when
building a new root list. It is a constant within that PRESENT, not a second clock.
`E.progress(durationMs)` combines the two and clamps to 0..1 so intervening frames
and PRESENTs continue an animation instead of restarting it.
Keep `timeline.token` and `timeline.startedAt` stable for an animation; use a new
token when restarting it. JS sends an elapsed duration, so JS and native clocks
need not share an epoch. Fingerprints include the token and expression code but
exclude the changing elapsed duration. Without a timeline, raw `time()` expressions
start at each PRESENT. Native compilation strips the bridge-only elapsed opcode.
`menu-selection-list.ts` authors both the rounded highlight and the transparent row
image using this API. `IconGrid` (app/ui/icon-grid.ts) animates a whole grid
this way: a clipped CLEAR of the grid box, the sliding highlight, then a DRAWS
of every row visible during the scroll, offset by the scroll expression. `menu-scroll-list.ts` authors a menu scroll or bounce: a
viewport-sized copy from a strip resource whose source y animates, then the
highlight. The bounce curve (`app/ui/menu-scroll-motion.ts`) needs no branches:
the easing ops clamp their input to 0..1, so `ease(t / p)` holds at 1 after the
peak and `ease((t - p) / (1 - p))` holds at 0 before it. Navigation eligibility, duration, and easing remain in
TypeScript. There is no animated-menu tag or menu animation policy in Kotlin.
## Bridge framing
Tag 7 is followed by a little-endian u32 byte length and a bounded body:
placement (i16 x/y, u16 width/height, i8 depth), timeline (u32 token/elapsed),
u16 resource count, gray8 images (u16 width/height followed by pixels), u16 call
count, then calls. Calls start with the opcode (bit 7 set when a clip follows)
and an i16 relative depth, then the clip if any (i16 x/y, u16 width/height);
operands otherwise use their fixed-width fields, except rounded x/y, rect-copy
x/y/dx/dy and DRAWS x/y which use extended varints. CLEAR is a u8 color. DRAWS
(opcode 32) is followed by a u16 record count and the records, in the frame
draw-buffer formats: glyph `[0][fontId u16][encoding u32][penX s16][lineY s16][value u8]`
and image `[1][imageId u32][x s16][y s16]`. Expressions use the firmware bytecode plus bridge-only
`ELAPSED = 128`. Resource indices are local to this record, never firmware IDs.
Rect-copy source x/y are signed here to permit relative SCREEN coordinates.
Limits: 256 images per record, 64 KiB per packed image, 4 MiB per bridge record,
4096 calls, and 900 input bytes per expression. Native validates the bound program
against the firmware's 1024-byte limit. The combined scene must also fit the
existing resource cache, root-list size, and VM stack limits.