donner::svg::RendererDriver Class Reference

Backend-agnostic renderer driver that prepares documents for rendering and emits drawing commands through a RendererInterface implementation. More...

#include "donner/svg/renderer/RendererDriver.h"

Classes
struct	SecurityStats
	Optional diagnostics for structured fuzzers and embedders auditing rejected preparation. More...
struct	TextPreparationStats
	CPU preparation work performed by this driver, for text-effect regression tests. More...
struct	EntityRangeBoundsOptions
	Controls visibility and transform handling when computing an entity range's bounds. More...

Public Member Functions
TextPreparationStats	textPreparationStatsForTesting () const
	Cumulative text preparation work for this driver's lifetime.
	RendererDriver (RendererInterface &renderer, bool verbose=false, SecurityStats *securityStats=nullptr, std::shared_ptr< components::StyleResourceBudget > externalUseStyleWork=nullptr)
	Create a renderer driver that will forward traversal output to the given backend implementation.
void	draw (SVGDocument &document)
	Render the given SVGDocument using the configured backend.
void	draw (SVGDocument &document, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas)
	Render the given SVGDocument into viewport after applying surfaceFromCanvas to every canvas-space draw command.
bool	drawInterruptibly (SVGDocument &document, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas, const std::function< bool()> &shouldCancel)
	Prepare and render a document while polling shouldCancel between rendered entities.
RenderSnapshot	captureRenderSnapshot (SVGDocument &document)
	Capture an immutable render snapshot from the given SVGDocument.
void	draw (const RenderSnapshot &snapshot)
	Replay an already-captured render snapshot into the configured backend.
void	drawEntityRange (Registry &registry, Entity firstEntity, Entity lastEntity, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas)
	Render a range of entities from an already-prepared document's render tree.
bool	drawEntityRangeInterruptibly (Registry &registry, Entity firstEntity, Entity lastEntity, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas, const std::function< bool()> &shouldCancel)
	Render a prepared entity range while polling shouldCancel between shapes.
void	drawEntityRangeIntoCurrentFrame (Registry &registry, Entity firstEntity, Entity lastEntity, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas)
	Render a range of entities into the renderer's already-active frame.
bool	drawUnderEntityMaskIntoCurrentFrame (Registry &registry, Entity maskedEntity, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas, const std::function< bool()> &drawContent)
	Draw caller-supplied content under one entity's mask, into the renderer's already-active frame.
void	drawDocumentIntoCurrentFrame (SVGDocument &document, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas)
	Prepare and draw a whole document into the renderer's already-open frame, using the same main-entity selection as drawInterruptibly (traversal order, offscreen feImage shadow entities excluded).
void	setConservativeEarlyLeafCulling (bool enabled)
	Skip fully off-viewport path leaves before resolving paint and clip resources. Enabled only for bounded damage renders after their caller rules out nonlocal effects in the owner tree.
std::optional< Box2d >	computeEntityRangeBounds (Registry &registry, Entity firstEntity, Entity lastEntity, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas)
	Compute the canvas-space bounding box of every pixel a subsequent drawEntityRange(registry, firstEntity, lastEntity, viewport, baseTransform) call would write to.
std::optional< Box2d >	computeEntityRangeBounds (Registry &registry, Entity firstEntity, Entity lastEntity, const RenderViewport &viewport, const Transform2d &surfaceFromCanvas, EntityRangeBoundsOptions options)
	Compute conservative range bounds with explicit clipping and mask policy; no value requires full-canvas fallback.
RendererBitmap	takeSnapshot () const
	Capture a snapshot from the underlying backend after rendering.

Static Public Attributes
static constexpr std::size_t	kMaximumPreparedFilterGraphs
	Aggregate limits for frame-wide filter graph preparation and feImage snapshots.
static constexpr std::size_t	kMaximumPreparedFilterNodes
	Maximum filter nodes admitted during render preparation.
static constexpr std::uint64_t	kMaximumPreparedFilterImageBytes
	Maximum decoded filter-image bytes admitted during preparation.
static constexpr std::uint64_t	kMaximumPreparedFilterMaterializationBytes
	Maximum filter materialization bytes admitted during preparation.
static constexpr std::uint64_t	kMaximumPreparedFilterPayloadBytes
	Maximum retained filter payload bytes admitted during preparation.
static constexpr std::size_t	kMaximumPreparedFilterShadowEntities
	Maximum shadow entities admitted for prepared filter content.
static constexpr std::size_t	kMaximumClipGeometryPaths = 1024
	Clip-path shapes copied per frame.
static constexpr RendererTextMaterializationBudget::Cost	kClipGeometryCopyLimits
	Per-frame limits on clip-path geometry copies, independent of the text budget's.

Detailed Description

Backend-agnostic renderer driver that prepares documents for rendering and emits drawing commands through a RendererInterface implementation.

---

Class Documentation

donner::svg::RendererDriver::SecurityStats

struct donner::svg::RendererDriver::SecurityStats

Optional diagnostics for structured fuzzers and embedders auditing rejected preparation.

Class Members
bool	clipGeometryCopyRejected = false
size_t	clipGeometryPathsPreflighted = 0
size_t	filterPreparationAttempts = 0
bool	filterPreparationRejected = false
Stats	nestedFontResources
size_t	preparedFilterGraphs = 0
uint64_t	preparedFilterImageBytes = 0
uint64_t	preparedFilterMaterializationBytes = 0
size_t	preparedFilterNodes = 0
uint64_t	preparedFilterPayloadBytes = 0
size_t	preparedFilterShadowEntities = 0

donner::svg::RendererDriver::TextPreparationStats

struct donner::svg::RendererDriver::TextPreparationStats

CPU preparation work performed by this driver, for text-effect regression tests.

Class Members
size_t	fullElementStylePasses = 0	Full text-root layout/style preparations across rendered frames.
size_t	spanStyleVisits = 0	Span entries visited while resolving renderer-facing paints and decoration.

donner::svg::RendererDriver::EntityRangeBoundsOptions

struct donner::svg::RendererDriver::EntityRangeBoundsOptions

Controls visibility and transform handling when computing an entity range's bounds.

Class Members
bool	allowMaskSuperset = false	A mask can remove source pixels but cannot expand their geometric extent. When enabled, accumulate the unmasked geometry as a conservative upper bound instead of giving up.
bool	clipToCanvas = true	Ordinary scene tiles are bounded by the current raster viewport. A selected drag tile may retain geometry outside it so those pixels can move into view without another raster pass.

Constructor & Destructor Documentation

RendererDriver()

donner::svg::RendererDriver::RendererDriver ( RendererInterface & renderer, bool verbose = false, SecurityStats * securityStats = nullptr, std::shared_ptr< components::StyleResourceBudget > externalUseStyleWork = nullptr )

explicit

Create a renderer driver that will forward traversal output to the given backend implementation.

Parameters

renderer	Backend receiving prepared draw calls.
verbose	Whether to emit diagnostic warnings.
securityStats	Optional preparation diagnostics destination.
externalUseStyleWork	Optional shared owner-frame work admission context. Current-frame callers share one fresh context for every backend beginFrame/endFrame pair; persistent drivers must establish an OwnerScope on that context or be reconstructed for the next frame.

Member Function Documentation

captureRenderSnapshot()

RenderSnapshot donner::svg::RendererDriver::captureRenderSnapshot ( SVGDocument & document )

nodiscard

Capture an immutable render snapshot from the given SVGDocument.

Snapshot capture prepares the live render tree under document access, then records backend-agnostic draw commands that can be replayed after access is released.

Parameters

document

Document to snapshot.

computeEntityRangeBounds() [1/2]

std::optional< Box2d > donner::svg::RendererDriver::computeEntityRangeBounds ( Registry & registry, Entity firstEntity, Entity lastEntity, const RenderViewport & viewport, const Transform2d & surfaceFromCanvas )

nodiscard

Compute the canvas-space bounding box of every pixel a subsequent drawEntityRange(registry, firstEntity, lastEntity, viewport, baseTransform) call would write to.

Runs the same entity traversal as drawEntityRange but with a bounds-accumulating visitor; no side effects on the renderer or registry.

The bounds include the effect of:

• Per-entity transforms (including the base transform).
• Filter regions (via computeFilterRegion; the filter's output rectangle is taken as the entity subtree's contribution).
• Stroke widths on stroked paths (expanded by strokeWidth / 2 plus a miter margin).
• Isolated layers - child bounds accumulate into the parent.
• Clip-rects (intersect, shrink only).

Returns std::nullopt when:

• The range is empty / renders nothing.
• Any entity uses a bound-expander the visitor doesn't yet model precisely (text, markers, masks, patterns). Callers must treat nullopt as "fall back to full-canvas render", NOT as "empty segment".

Safe to call on a RendererDriver whose renderer holds persistent state - the traversal never invokes renderer methods.

computeEntityRangeBounds() [2/2]

std::optional< Box2d > donner::svg::RendererDriver::computeEntityRangeBounds ( Registry & registry, Entity firstEntity, Entity lastEntity, const RenderViewport & viewport, const Transform2d & surfaceFromCanvas, EntityRangeBoundsOptions options )

nodiscard

Compute conservative range bounds with explicit clipping and mask policy; no value requires full-canvas fallback.

Parameters

registry	Registry containing the prepared render tree.
firstEntity	First entity in the traversal range.
lastEntity	Last entity in the traversal range.
viewport	Viewport for the bounds calculation.
surfaceFromCanvas	Transform from canvas to destination-surface coordinates.
options	Clipping and conservative-mask policies.

draw() [1/2]

void donner::svg::RendererDriver::draw

(

const RenderSnapshot &

snapshot

)

Replay an already-captured render snapshot into the configured backend.

Parameters

snapshot

Snapshot to render.

draw() [2/2]

void donner::svg::RendererDriver::draw	(	SVGDocument &	document,
		const RenderViewport &	viewport,
		const Transform2d &	surfaceFromCanvas )

Render the given SVGDocument into viewport after applying surfaceFromCanvas to every canvas-space draw command.

This is used by editor-style camera rendering: SVG layout can still use the document's semantic full canvas, while the backend only allocates the visible output surface.

Parameters

document	Document to render.
viewport	Output viewport for the backend frame.
surfaceFromCanvas	Transform from document canvas coordinates to the output surface.

drawDocumentIntoCurrentFrame()

void donner::svg::RendererDriver::drawDocumentIntoCurrentFrame	(	SVGDocument &	document,
		const RenderViewport &	viewport,
		const Transform2d &	surfaceFromCanvas )

Prepare and draw a whole document into the renderer's already-open frame, using the same main-entity selection as drawInterruptibly (traversal order, offscreen feImage shadow entities excluded).

Use this instead of deriving an entity range by hand: a range computed from a different ordering can cross drawEntityRange's first/last walk and unbalance layer bookkeeping.

The caller owns beginFrame/endFrame and holds the document's write access.

Parameters

document	Document to draw; prepared for rendering by this call.
viewport	Viewport for the active render pass.
surfaceFromCanvas	Transform that maps canvas coords to the active render surface.

drawEntityRange()

void donner::svg::RendererDriver::drawEntityRange	(	Registry &	registry,
		Entity	firstEntity,
		Entity	lastEntity,
		const RenderViewport &	viewport,
		const Transform2d &	surfaceFromCanvas )

Render a range of entities from an already-prepared document's render tree.

The document must have been prepared via RendererUtils::prepareDocumentForRendering() before calling this method.

Parameters

registry	The registry containing the prepared render tree.
firstEntity	First entity in the range to render (inclusive).
lastEntity	Last entity in the range to render (inclusive).
viewport	Viewport for the render pass.
surfaceFromCanvas	Transform that maps canvas coords to the render surface (Translate(-topLeft) for tight-bounded compositor segments, identity for full-canvas layers/segments). Named with destFromSource convention; composed with each entity's worldFromEntityTransform as worldFromEntityTransform * surfaceFromCanvas (donner's left-first operator*: "apply entity-to-canvas, then canvas-to-surface").

drawEntityRangeInterruptibly()

bool donner::svg::RendererDriver::drawEntityRangeInterruptibly ( Registry & registry, Entity firstEntity, Entity lastEntity, const RenderViewport & viewport, const Transform2d & surfaceFromCanvas, const std::function< bool()> & shouldCancel )

nodiscard

Render a prepared entity range while polling shouldCancel between shapes.

The renderer frame is always balanced and ended before this method returns. A cancelled partial frame is safe to discard, which lets editor workers release their document guard without waiting for an entire complex compositor segment to finish.

Returns

True when the complete range was rendered, false when cancellation stopped traversal.

drawEntityRangeIntoCurrentFrame()

void donner::svg::RendererDriver::drawEntityRangeIntoCurrentFrame	(	Registry &	registry,
		Entity	firstEntity,
		Entity	lastEntity,
		const RenderViewport &	viewport,
		const Transform2d &	surfaceFromCanvas )

Render a range of entities into the renderer's already-active frame.

This is the current-frame form of drawEntityRange: the caller owns RendererInterface::beginFrame() / endFrame(), and this method only emits the entity-range draw commands. It is used by the compositor when an immediate-mode span should be drawn directly into the composition render target instead of first being rasterized into an offscreen tile.

Parameters

registry	The registry containing the prepared render tree.
firstEntity	First entity in the range to render (inclusive).
lastEntity	Last entity in the range to render (inclusive).
viewport	Viewport for the active render pass.
surfaceFromCanvas	Transform that maps canvas coords to the active render surface.

drawInterruptibly()

bool donner::svg::RendererDriver::drawInterruptibly ( SVGDocument & document, const RenderViewport & viewport, const Transform2d & surfaceFromCanvas, const std::function< bool()> & shouldCancel )

nodiscard

Prepare and render a document while polling shouldCancel between rendered entities.

The document write guard and renderer frame are always balanced before this method returns. A cancelled partial frame is safe for a background worker to discard.

Returns

True when the complete document rendered, false when cancellation stopped work.

drawUnderEntityMaskIntoCurrentFrame()

bool donner::svg::RendererDriver::drawUnderEntityMaskIntoCurrentFrame ( Registry & registry, Entity maskedEntity, const RenderViewport & viewport, const Transform2d & surfaceFromCanvas, const std::function< bool()> & drawContent )

nodiscard

Draw caller-supplied content under one entity's mask, into the renderer's already-active frame.

Replays the mask pass the entity would get in a range draw: the mask region, the mask content and its coverage mode. Between RendererInterface::transitionMaskToContent() and RendererInterface::popMask() it calls drawContent with the renderer transform reset to identity, so the callback draws in surface pixels. The entity's own opacity, blend mode, clip-path and filter are not applied; callers use this only for entities whose mask is their sole compositing context.

Parameters

registry	The registry containing the prepared render tree.
maskedEntity	Entity whose RenderingInstanceComponent carries the mask.
viewport	Viewport for the active render pass.
surfaceFromCanvas	Transform that maps canvas coords to the active render surface.
drawContent	Draws the masked content; returns false if any draw failed.

Returns

False, with nothing drawn, when the entity has no renderable mask; otherwise the result of drawContent.

Member Data Documentation

kClipGeometryCopyLimits

RendererTextMaterializationBudget::Cost donner::svg::RendererDriver::kClipGeometryCopyLimits

staticconstexpr

Initial value:

{
      .uniqueOutlines = kMaximumClipGeometryPaths,
      .commands = 4 * 1024 * 1024,
      .points = 8 * 1024 * 1024,
      .bytes = 64ULL * 1024 * 1024,
      .decodeWork = 64 * 1024 * 1024}

Per-frame limits on clip-path geometry copies, independent of the text budget's.

kMaximumPreparedFilterGraphs

std::size_t donner::svg::RendererDriver::kMaximumPreparedFilterGraphs

staticconstexpr

Initial value:

=
      RendererFilterPreparationBudget::kMaximumGraphs

Aggregate limits for frame-wide filter graph preparation and feImage snapshots.

kMaximumPreparedFilterImageBytes

std::uint64_t donner::svg::RendererDriver::kMaximumPreparedFilterImageBytes

staticconstexpr

Initial value:

=
      RendererFilterPreparationBudget::kMaximumImageBytes

Maximum decoded filter-image bytes admitted during preparation.

kMaximumPreparedFilterMaterializationBytes

std::uint64_t donner::svg::RendererDriver::kMaximumPreparedFilterMaterializationBytes

staticconstexpr

Initial value:

=
      RendererFilterPreparationBudget::kMaximumMaterializationBytes

Maximum filter materialization bytes admitted during preparation.

kMaximumPreparedFilterNodes

std::size_t donner::svg::RendererDriver::kMaximumPreparedFilterNodes

staticconstexpr

Initial value:

=
      RendererFilterPreparationBudget::kMaximumNodes

Maximum filter nodes admitted during render preparation.

kMaximumPreparedFilterPayloadBytes

std::uint64_t donner::svg::RendererDriver::kMaximumPreparedFilterPayloadBytes

staticconstexpr

Initial value:

=
      RendererFilterPreparationBudget::kMaximumPayloadBytes

Maximum retained filter payload bytes admitted during preparation.

kMaximumPreparedFilterShadowEntities

std::size_t donner::svg::RendererDriver::kMaximumPreparedFilterShadowEntities

staticconstexpr

Initial value:

=
      RendererFilterPreparationBudget::kMaximumShadowEntities

Maximum shadow entities admitted for prepared filter content.

---

The documentation for this class was generated from the following file:

• donner/svg/renderer/RendererDriver.h