Module scene_parts 

Keyed parts of a shell scene section, so a small change inside a section damages that change’s bounds instead of the whole display.

The retained-damage producer proves a frame sparse by comparing each scene section with the previous frame’s; without parts, any difference inside the workspace (a caret, a peer’s cursor, a hover) made the whole section opaque to that proof. A part marks a stretch of a section’s draw commands with a key and the bounds those commands can paint, and every part boundary splits the section’s encoded streams into pieces, each belonging to the innermost part open across it. Comparing piece by piece then gives: every piece equal, the section is unchanged; only pieces of parts differ, damage is each changed part’s old and new bounds; a piece of the section itself differs, or the proof cannot be made, and the frame is dense.

Correctness rests on two facts: pixels outside every changed part’s bounds come from byte-identical commands in both frames (the sparse renderer re-renders the whole scene inside the damage, so blend layers above a part compose correctly), and a part’s commands are independent of what precedes them — the encoder dedups a transform or style against the last one encoded, so each boundary forces the next transform and style to be encoded again.

Only sections the producer registered (track) are split.

Structs

Begun

Whether a key was begun, for end_widget.

DamageHint

What changed in a part’s content between two generations of it, as the one who painted it knows: an embedded app’s own widget damage.

DrawBounds

Device-space bounds of everything a scene paints, for a caller that must know what lies over a region without rasterising the scene. Keep one: it retains glyph outlines across calls.

DrawnScroll

A scroll region a keyed widget drew this frame (Widget::primary_vertical_scroll).

Keyer

The code that writes widget keys, handed to key_widgets.

PartKey

Identifies one part among the parts of a section. Two frames’ parts are matched by key and position, so a key must name the same thing in both.

Presented

How a host presents a frame over the pixels of the one before: present_copies.

Recorded

Every tracked section’s parts from one finished Recording.

Recording

Records parts for the sections registered with track until finished.

SectionCopy

A copy a hinted part’s content made (DamageHint::copies), as a host presenting the section over its last frame must check it: what it moves, what the section draws over that content, and how it composites.

SectionDamage

damage_with_copies — where a section changed, and the copies that explain the rest.

SectionParts

The parts recorded for one section in one frame.

Enums

Unproven

Why two frames of a section cannot be compared piece by piece.

Functions

append

Append other, whose parts were recorded as parts (record), so that a tracked scene keeps them: each becomes a part of scene at the same place, its bounds carried through transform. Without parts everything other draws belongs to whatever part this append is in.

append_with

append for a caller that appends the recorded scene itself (with crate::backdrop::append_nested, say): append must append exactly that scene at transform.

begin

Begin a part keyed key around draws too long to pass to part as one closure; end closes it, under the same contract. A part left open gives the section no parts.

begin_frame

Start keying a frame: root widgets count from the first again. A host that keys widgets calls it before every frame it draws.

begin_item

Begin one item of a widget under key (item_key), standing at origin, for draws that cannot be one closure; end_widget ends it.

begin_widget

Begin widget’s draws: index is its place among its parent’s children, when the caller knows it (a container that skips children it does not draw must say it, or the children after them would take their keys). transform is the one it draws with. Writes nothing unless widgets are keyed.

culled

scene, drawn with parts, without every bounded part whose bounds wanted refuses, or None when no part is left out. Where the parts left out paint nothing, the result paints what scene does: a part’s commands depend on nothing before them ([boundary]), and only a part whose layers it pops itself is left out, so every layer around the rest is the same. A renderer’s work grows with every path a scene holds, wherever it lands, so a frame repainting a small damage renders only what can reach it.

damage

Damage, in section coordinates, between two frames of a section drawn with parts: the old and new bounds of every part whose commands changed (or what a hinted part’s hint says changed). Ok with no rects means the section is unchanged.

damage_with_copies

damage for a host that presents the section over the pixels of the frame it compares with and can move them: a hinted part whose hint follows on and carries copies (DamageHint::copies) damages its rects only, and each copy comes with what the section draws over it and how its content composites, which the host must check before making it (and otherwise repaint where it lands, SectionDamage::without_copies). bounds bounds the draws of the section outside every bounded part.

drawn_bounds

Where scene, drawn with parts (if it was), paints anything: inside a bounded part by that part’s bounds, anywhere else by its draw bounds. None when some of it cannot be bounded.

drawn_scrolls

The scroll regions of the widgets the last frame showed (retain_shown).

end

Close the part begin opened, with the bounds of what it painted.

end_hinted

Close the part begin opened as a hinted part: for a draw that knows what changed only once it has drawn (a widget notes its damage while drawing).

end_widget

End the draws begin_widget began.

hinted

Draw one part of a section with no bounds of its own: draw paints content whose change since an earlier frame hint describes. A change inside the part damages the hint’s rects when the hint follows on from the compared frame’s (same source and placement, the next generation). Otherwise, or with no hint, the change belongs to the enclosing part, and outside every bounded part it is not proven.

is_tracked

Whether scene is split into parts for the active recording.

item_key

The key a draw of something under the innermost open key gets: kind names the draw site and id tells its draws apart. For a widget that draws many items itself (an editor’s blocks, a list’s rows), so each item keeps an element of its own.

key_widgets

Have every widget this thread draws through the toolkit’s draw paths mark its draws with its key (begin_widget), with keyer’s code; None stops it. Off by default.

keyed

Draw one item of a widget under key (item_key), standing at origin. Writes no marks unless widgets are keyed.

keyer

The keying code: the one way to it.

keys_widgets

Whether widgets drawn on this thread mark their draws with their keys.

painted_key

The key widget’s draws carried in the frame keyed last, as the page names it (16 hex digits); None when it was not drawn keyed. The widget is matched by address and type, and nothing kept is dereferenced.

part

Draw one part of a section: bounds, in the section’s coordinates (the draw transform already applied), must cover every pixel draw can paint, shadows and antialiasing included. An empty bounds claims draw paints nothing; a part that then draws anything is treated as unbounded.

part_drawn

part for a draw that knows what it painted only once it has: draw returns the bounds, under the same contract.

present_copies

Decide which of a frame’s section copies (damage_with_copies) a host that keeps its target makes, and what it repaints around them. damage is every other change of the frame, in device pixels; above is where the scene draws over the section after it (later sections), in section coordinates; to_device maps section coordinates into the size target.

record

Record the parts of a scene drawn on its own (a retained scene a widget re-records only when it changes): the parts draw marks in scene, or None when they are not well nested. Any recording around this one is suspended while draw runs, so draw must paint only into scene.

retain_shown

Forget the scroll regions and widgets whose keys scene (a whole frame) no longer shows: what a cached subtree replayed into it keeps.

scroll_widget

Scroll the region scroll names to offset, in the widget’s own pixels, when the widget that drew it is still in root’s tree. Finds it by address and type, never through the address kept. Returns whether it was found.

skip_widget

Count a child left undrawn, so the siblings drawn after it without an index keep their keys.

track

Split scene at its parts’ boundaries for the active recording. The section must stay at its address until the recording finishes.