amenui
en·中 github ↗ v0.0.1
01文档 02组件 03实验室 04作品
en·中github ↗
×

文档 / 概念 / 设计 / 1.12 帧时间读数和分辨率预算 文档 / 概念 / 设计 /

1.12 帧时间读数和分辨率预算

03.28

本页只有英文。

The readout (the first item of the top bar's Performance menu, or F2; Look::overlay): the annotation layer draws a block above the material in Departure Mono 11 px (on the page background at 0.92 opacity), in the corner Look::overlay_at names (Corner::BottomRight by default), Look::overlay_inset ([12, 12] px) in from its edges. When the block there would cover text to read, it moves on clockwise to the first corner where it covers none (Ui::legible_ink, Ui::overlay_box); when every corner covers some, it stays in the asked one:

text
F2 frames       58/s  drawn 1234 skipped 56
ms               last    avg    max
update+layout    0.42   0.50   2.10
scene build      0.80   0.91   3.02
gpu submit       1.20   1.13   4.00
total            ...
instances 1234  particles 0  glyph atlas 12%
layouts 12  shaped 345  views 40
quality 0.5 auto  WebGL2  dpr 2

The data (src/perf.rs, no GPU): Perf.pending is the time spent since the last frame, added to by the runtime. update+layout is update, view and layout (timing the outermost send / relayout, minus the scene building inside it); scene build is paint and finish (building instances, animation, corner marks, annotations); the renderer's CPU time in draw from the start to the last queue.submit is gpu submit; then Perf::frame records the three as one frame (keeping only the last two seconds). Perf::summary(now) gives the frames drawn in the last second and each item's last / mean / max in ms. Time comes from perf::now_ms(): performance.now() on the web, Instant natively. There are also work counters (Counters: layouts, parley layouts, view calls, scenes), used by tests too. The backend name and device pixel ratio are filled in by the host (Perf::backend: WebGPU, WebGL2, Vulkan, Metal). While the readout is open it wakes every 0.5 s to refresh, so the frame count falls to 0 at rest; when closed it doesn't wake. On the web the readout's on / detailed / off state is kept in localStorage (amenui.readout, every read and write in try / catch so it runs as usual when storage is unavailable; readout(), set_readout(v)); natively it isn't kept.

The resolution budget (Look::quality: 1, 0.75, 0.5, or 0 = automatic). The screen-space shading stage can first draw into an image at q times the resolution (lo, ceil(width × q) × ceil(height × q), in the frame's format): fs_material uses p = frag × (1 / q) (qual.x), so pixel centers of the small image land on full-resolution coordinates and lengths, pitches and sampling in the material functions don't change. Then the full-resolution fs_material_up decides per pixel:

  • Pixels at rest (rest_at(p): on a picture pic_k(p) = 0; elsewhere kt(p) < 0.02, no burst, lens < 0.02) are recomputed by the material at full resolution (shade(p)). For materials that equal plain at rest, that just reads the coverage buffer; for materials with a look of their own at rest (dottr's ground, smudgr's grain, near), their resting look is at full resolution too. So a still page is identical pixel for pixel to q = 1, and text is always sharp.
  • Loose pixels take lo's bilinearly filtered colour. Loose things (marks, scattered dots, carved cuts) are changing anyway, and half resolution doesn't show, so the cost drops to q².

Pixels at rest are not shaded in lo; they only write 1 into alpha (loose pixels are shaded and write 0). The full-resolution pass takes one bilinear sample of lo: with alpha > 0 (a resting cell nearby) it recomputes with shade(p) here, otherwise it uses the sampled colour. So the edges of loose areas stay sharp, and the rest test runs once over q² of the pixels.

A material pass for one material (Renderer::specialise): shade dispatches on each pixel's material (an override's, else the global one), so its pipeline holds every material's branch, which a GPU runs with fewer pixels at once. A frame with one built-in global material and no instance overriding it (in the scene or drawn into a plate since it was cleared) draws the material pass (fs_material, both the full and the reduced one) with a pipeline of its own made with the WGSL override constant MAT set to that material, and fs_material_up and fs_trace too; eff_mat then returns MAT. The passes are made ahead, from the renderer's render::SPECIALISE_AFTER (2nd) frame drawn, one a frame after the frame is sent (WebGPU's createRenderPipelineAsync is not reached through wgpu): the global material's pass and upsample, then the passes for each material of the page (below), the page's materials being every override its elements have, drawn or hidden (Scene::mats: a word waiting for a morph in a material of its own), then the trace passes once a scroll's trace has been shaded. Each is kept by material, so a page that changes its global material and back, or shows an override and hides it, makes nothing again. A frame whose pass is not made yet, and any with a material from source, draws with the pass for any material (the readout's spec no (warming)). While a morph's tiles fly, the frame's materials include both its ends' (the tiles show the word's material). The frames are the same pixel for pixel (tests/specialise.rs). Offscreen, on the CPU rasteriser, specialise is None: compiling another pass costs more there than it saves. An override in the global material is not one. A page of several built-in materials (up to render::GATED_MAX, 4: the gallery's plain chrome round cells in their own) gets a pass for each, made ahead as above (the material passes and their upsamples, then their trace passes), with MAT set and the override constant ONLY: every pixel finds its material as the pass for any finds it (where a scroll holds the rows to a lattice, at the row it reads), and the pass for MAT draws only the pixels of MAT (shade_new discards the rest), so each box is drawn once per material and each pixel by one pass, and the frame is the frame of the pass for any, byte for byte (tests/specialise.rs: at rest, loose and scrolled fast). The readout says spec each dottr+plain+charr. For measuring what the pass for any material costs against one material's (an A/B on one page, on the device), Renderer::spec_force: Some(true) makes the global material's pass from the next frame and uses it even over overrides (their pixels are then drawn in the global material), Some(false) never makes it nor uses one already made, nor the passes for each material; the readout says which (spec yes …, spec no (forced off)).

lo is drawn only when the loose area is large enough: Ui::loose_estimate(now, lens_radius) estimates the share of the window that may be loose (1 with fronts, condensing, morphs or flows; otherwise the sum of the areas of instances with static looseness, bursts, the lens on pictures and compare wipes). Below LO_MIN_AREA = 0.15 there is a single full-resolution pass: for one lens or one held control, the extra pass costs more than it saves. Particles in flight always count as large. Renderer::always_lo lets acceptance force lo.

Automatic (perf::AutoQuality): the level goes by the intervals between frames, since what is slow is often the GPU, whose time is not measured on the web (on an M1 the CPU's share of a 67 ms scroll frame was about 10 %, so a CPU-time rule never stepped). The display frame is the 10th percentile of the last second's intervals, never under 4 ms; an interval over 250 ms is a pause, not a frame. Only frames drawn while something moves count (scrolling, or a loose area of at least LO_MIN_AREA): one level down (1 → 0.75 → 0.5) when the 95th percentile of the last 30 of them is above 1.5 display frames or 20 ms, whichever is less; one level up after 2 s of them with no missed frame and every frame's CPU cost under 60 % of the display frame. The level is kept for the session. Offscreen it does not move (Renderer::govern). The readout says "quality 0.75 auto".

Scrolling under the automatic level (Fable's ruling; render::SOFT_SCROLL): only with Look::quality at 0 (automatic) and the level below 1, the scroll areas (Field::scrolls) are shaded in lo while a scroll offset has changed within ui::SOFT_STOP = 0.1 s, from the first frame that scrolls; no fixed level ever softens scrolling. The level is no lower than the material's floor (render::soft_floor): 0.75 for charr, halftonr, carvr, glitchr, scribblr, smudgr (its grain is shaded with the rest, not in the full-resolution pass) and a material from source; 0.5 for plain, near and dottr. Marks keep their pitch and place in screen pixels (the reduced pass samples the full frame's coordinates): only edges soften, and the upscale is the bilinear read, with no sharpening. The ink stays at full resolution: a reduced texel whose ink around it (±0.75 / q + 0.5 px, centre and four diagonals) is not all the same, in coverage or a glyph's tone over a shape, is marked at rest, so glyphs, strokes of 2 px or less, focus corners and the edges of panels and the chrome are shaded in the full-resolution pass; the annotation layer and overlays are drawn after the material and never reduced. Once it stops, Ui::needs_frame asks for one more frame (Ui::soft_drawn says the last one was softened) and that frame is drawn sharp everywhere. Softening stands down on a frame that can move the last one (dirty::Move, §1.19): that frame shades only the strip that scrolled in and what changed, sharp, which costs less than any reduced pass; a softened frame, and the sharp one after it, are drawn whole. The real costs of scrolling are there (the move, the per-pixel cost of shade); 0.5 is the fallback.

Acceptance: tests/perf.rs (the level steps down on slow intervals while something moves and never at rest, a missed frame restarts the wait up, costly frames do not raise it, last-second statistics, F2 and the menu open the readout and its text is in the annotation layer, it wakes every 0.5 s while open); tests/stage_scale.rs (a scroll area softens while it scrolls and nothing outside it does, a fixed level never softens, the frame due after it stops is sharp, a frame that moves the last one is not softened); check item 12: under every material at rest, q = 0.5 (with lo forced) and q = 1 are identical pixel for pixel and body text equals plain (with item 5's tolerance), with a control: once loosened, the two resolutions can be told apart. Frame times on llvmpipe (relative comparison only) are in §9.

Look::overlay_keep keeps the readout in overlay_at's corner even where it covers text to read (for a page whose own text fills every corner); by default it moves on clockwise to the next clear corner. In a narrow window the readout wraps at its two-space field breaks to fit between overlay_inset and 12 px from the window's other side, so at 390 px wide every number stays in the window (tests/render.rs).