Module scroll_copy 

Scrolling by copying the pixels that stay on screen.

A scroll moves every pixel of a scroller’s content, so damage alone repaints its whole viewport on every frame of a scroll. When the content moved by a pure translation since the frame the host last presented, most of those pixels are already in the host’s retained target, one delta away.

A scroller says so from its collect_damage (offer) instead of damaging its viewport: where its content paints, how far it moved, and what it paints over its content that does not move with it (a scroll bar, an edge fade). A host that keeps the last frame’s pixels collects damage inside accepting; any other host gets the viewport damage as before, because offer answers false there.

The host plans each offer (plan) against the tree it just drew: the copy is clipped by every ancestor’s child clip and kept to whole device pixels; a delta that is not a whole number of them, or a scroller drawn under another transform than the window’s, is refused. What may paint over or under the content without moving with it is damage (the scroller’s overlays, every other widget whose box reaches into the viewport, the edges of every ancestor and of every frame holding the viewport); damage a copy reads is carried to where the copy lands (carry) and what the copy exposed is repainted. The renderer copies first (encode_copies, or copy_pixels on a CPU canvas), then rasterizes the damage.

A relayout’s moves are checked against the offers (moves_besides): content that moved by its scroller’s delta is the copy’s; content that came, went or stayed put (a long list mounting rows, a pinned title) is damage; anything else that moved makes the host repaint as it would without copies.

Structs

Around

What a scroller that keeps its rows’ scenes (Painted) paints besides them, which must be as it was for any reuse: its box, and what it paints there that does not scroll and is not a piece of its own (a header, a focus ring).

CopyPlan

What a host does with a frame’s offers, in device pixels: the copies, in order; the damage they add where something does not move with the content (each copy’s overlays, a refused offer’s viewport), which the host carries along with the rest of its damage (carry); and what the copies exposed, repainted as it is.

CopyScratch

A target’s scratch space for copies within it, which a copy cannot do in place: WebGPU refuses a copy whose source and destination are the same texture’s same subresource. Each copy moves through it in bands of at most BAND rows, so it holds a band, not a viewport.

DeviceCopy

One planned copy within a host’s retained target, in device pixels: the source rectangle, and how far it moves.

HostCopies

While held, every crate::app::EmbeddedApp drawn on this thread is drawn for a host that presents each frame over the pixels it last presented and can move them, as crate::app::EmbeddedApp::set_accepts_scroll_copies says; an app that learned so keeps handing out copies, which a host that cannot make them repaints where they land.

MovedRegion

A copy as a host that composites the target elsewhere sees it: the rectangle it reads and how far it moves it, in the coordinates of the scene the target is drawn into (an embedded app’s region in a desktop section), before that scene is rasterised.

Painted

A piece’s paint as the scene it drew, drawn where the piece stands in the content unscrolled, so a piece a scroll only moved encodes the same. Two compare equal when they encode alike (vello::Scene::encoding_eq).

Piece

One piece of what a scroller paints: a line, a page, a caret. rect is where it paints with the content unscrolled (on screen plus the scroll), or on screen for a piece that does not move with the content; paint fingerprints its pixels, or is the scene that painted them (Painted).

ScrollOffer

A scroller’s claim that, since the frame its host last presented, its content moved by a pure translation within an unchanged viewport.

Showing

A scroller’s frame as most scrollers describe it (Shown).

ShownFrames

The frame being drawn and the frame on screen, as noted.

Enums

Since

How the frame being drawn differs from the one on screen.

Constants

EFFECT_REACH

How far outside its layout box a widget may paint: anti-aliasing, a shadow, a hover lift. The native window grows every widget’s damage by as much, in logical pixels.

Traits

Shown

One frame of a scroller, as a later frame compares it.

Functions

accepting

Run collect (a widget tree’s collect_damage) with scroll copies accepted, and return what the scrollers in it offered instead of damaging their viewports. Only a host that presents over its last frame’s pixels and copies each planned offer (plan, encode_copies) may call it.

carried

Where copies take the pixels rects cover (device pixels): each piece of a rect a copy reads, one delta away.

carry

Add to damage (device pixels, where a frame differs from the last in place) where copies take what it covers: a pixel that changed in place and that a copy moves lands, stale, one delta away. Everything but what the copies exposed goes through here, the overlays the plan found included.

copy_pixels

Apply copies to pixels, a width-pixel-wide RGBA8 image whose rows are stride bytes apart, in order. Returns false, changing nothing, when a copy would leave the image.

drawing_into_cache

Record draw into a cache its caller then appends with transform (a container that draws its children at the identity into a retained scene): a scroller drawn inside learns where its content lands on screen (on_screen).

encode_copies

Record copies within texture, in order, each through scratch. Returns false, recording nothing, when a copy would leave the texture: the caller must then repaint the target whole.

host_copies

Whether the host drawing now copies (HostCopies).

host_device_scale

How many pixels of the target of the host drawing now one unit of its scene is (HostCopies::begin_scaled); 1 outside any.

marks_over_copies

Add to damage what marks painted over a window’s content without moving with it, and unseen by the planner (collaborators’ pointers and names), cost its copies (device pixels, as each would be repainted): the target holds the marks of the frame on screen (shown), which a copy moves with the content, stale, one delta away; and this frame’s marks (painted) must be repainted wherever a copy wrote under them. Where a mark changed in place is the frame’s other damage, carried with it (carry).

offer

From a scroller’s collect_damage: offer to have its host copy what of its content stays on screen. viewport is where the content paints, delta how far it moved on screen since the frame the host last presented, and overlays what the scroller paints over its content that does not move with it, all in logical pixels; transform is the one its content landed on screen with this frame (on_screen). The scroller must still damage whatever inside its content changed besides moving.

on_screen

Where transform, the one a widget draws with, lands on screen: through every cache being recorded around it.

piece_key

A stable key for a piece named name (a row’s identity, a bar).

plan

Plan offers against the trees under roots just drawn (the app’s, then any the window draws beside it, such as History’s toolbar), at scale device pixels per logical pixel, for a width × height target: each becomes a copy and the damage around it, or, when it cannot be copied exactly, damage over its whole viewport.

plan_scaled

plan for a window drawn at drawn_scale scene pixels per logical pixel into a host target of device_per_scene pixels per scene pixel (an app drawn into a desktop’s logical scene, shown at 200 %): the plan is in those device pixels, for a width × height target of them.

Type Aliases

PaintedFrames

The frames of a scroller that keeps its rows’ scenes (a table, a tree).