RetainedSpans.h File Reference

Per-shape retained rasterization for the tiny-skia backend. More...

#include <cstdint>
#include <optional>
#include "donner/base/EcsRegistry.h"
#include "donner/base/FillRule.h"
#include "donner/base/Transform.h"
#include "tiny_skia/Geom.h"
#include "tiny_skia/Paint.h"
#include "tiny_skia/SpanCapture.h"
#include "tiny_skia/Stroke.h"

Include dependency graph for RetainedSpans.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	donner::svg::RetainedSpanKey
	Everything a captured blit sequence depends on, besides the shape's geometry. More...
struct	donner::svg::RetainedSpanSlot
	One retained fill or stroke pass of one shape. More...
struct	donner::svg::RetainedSpansComponent
	Retained rasterization output for one shape, attached to the entity its geometry came from. More...
struct	donner::svg::RetainedSpanDocumentState
	Document-wide state for retained coverage, stored in the registry context. More...
struct	donner::svg::RetainedSpanStats
	Counters describing what a renderer's retained coverage did, for tests and benchmarks. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.
namespace	donner::svg
	Donner SVG library, which can load, manipulate and render SVG files.

Functions
std::size_t	donner::svg::RetainedEntryBytes (const RetainedSpansComponent &entry)
	Returns everything an entry holds: recorded coverage, the paints kept beside it, and the entry itself.
void	donner::svg::EnsureRetainedSpanInvalidationWired (Registry &registry)
	Connects the resolved-path invalidation listener to registry, once per registry.
RetainedSpanDocumentState &	donner::svg::RetainedSpanStateFor (Registry &registry, std::size_t budgetBytes)
	Returns the document's retained-coverage state, creating it if needed.
void	donner::svg::ClearRetainedSpans (Registry &registry)
	Drops every retained entry in registry and resets its accounting.
void	donner::svg::EvictRetainedSpansToBudget (Registry &registry, std::uint64_t currentFrame)
	Evicts the coldest entries until the document is under budget.

Detailed Description

Per-shape retained rasterization for the tiny-skia backend.

Scan conversion is the expensive half of a shape draw, and its whole pixel effect is the sequence of blit calls it makes. Recording that sequence once and replaying it on later frames turns an unchanged shape into a blit-only draw. This file owns the storage for those recordings, the key that decides whether a recording still describes the draw the renderer is about to make, and the memory bound on how much a document may keep.

The correctness rule is one-directional: a recording may be discarded for any reason, but it may only be replayed when every input the recorded coverage depended on is unchanged. Keys therefore compare conservatively (bitwise float equality, patterns never equal), and every input that is re-supplied at replay rather than baked into the coverage (the paint the draw built its blitter from, the clip mask) is either part of the key or reproduced exactly.

---

Class Documentation

donner::svg::RetainedSpanStats

struct donner::svg::RetainedSpanStats

Counters describing what a renderer's retained coverage did, for tests and benchmarks.

Counts are per fill or stroke pass of a shape draw, and cover the frame most recently drawn. Draw kinds retention does not reach at all (text, images, layer composites) are not counted here at all, not even as bypassed.

Class Members
uint64_t	bypassedDraws = 0	Passes retention did not apply to. Draws whose recording was refused at replay, which then rasterized instead. A refusal is the surface-size guard doing its job, never a dropped shape.
uint64_t	capturedDraws = 0	Passes that rasterized and recorded their coverage.
bool	documentDisabled = false	Whether the document fell back to immediate mode.
uint64_t	evictions = 0	Entries evicted to stay under budget.
uint64_t	invalidatedDraws = 0	Captures that replaced a recording whose key changed.
size_t	liveBytes = 0	Bytes retained by the document at the end of the frame.
uint64_t	refusedReplays = 0
uint64_t	replayedDraws = 0	Passes served from retained coverage.
uint64_t	unrecordableDraws = 0	Draws that could not be recorded (a tiled surface, or a blit the packed record cannot hold). The pixels are painted regardless.