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. Every part boundary splits the section’s encoded streams into pieces; a piece belongs to the innermost part open across it, or to the section itself. Comparing the previous and current frame 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, the parts are not the same keys in the same order, a changed part has no bounds, or anything cannot be proven: no authority, so the frame is dense.

Correctness rests on two facts. Pixels outside every changed part’s bounds are produced by byte-identical commands in both frames, so they cannot have changed (the sparse renderer re-renders the whole scene inside the damage, so blend layers and filters above a part compose correctly there). 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 of a tracked section forces the next transform and style to be encoded again.

Only sections the producer registered (track) are split; a part drawn into any other scene (a capture, a preview, a cached sub-scene) records nothing and changes no encoding.

Structs

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.

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.

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.

end

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

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.

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.

track

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