donner::svg::compositor::ComplexityBucketer Class Reference

Phase 2.5 producer that pre-chunks a document into a small number of layers based on per-subtree rasterization cost. More...

#include "donner/svg/compositor/ComplexityBucketer.h"

Public Member Functions
	ComplexityBucketer (ComplexityBucketerConfig config={})
	ComplexityBucketer (const ComplexityBucketer &)=delete
ComplexityBucketer &	operator= (const ComplexityBucketer &)=delete
	ComplexityBucketer (ComplexityBucketer &&) noexcept=default
ComplexityBucketer &	operator= (ComplexityBucketer &&) noexcept=default
void	reconcile (Registry &registry)
	Recompute the bucket partition for the current document state.
void	clear ()
	Drop all held bucket hints. Callers use this when the registry is being reset (e.g. CompositorController::resetAllLayers) so stale bucket assignments don't linger into the rebuilt document.
void	releaseAllHintsNoClean ()
	Like clear(), but releases each hint's registry pointer first so the dtor becomes a no-op. Used from CompositorController::resetAll Layers after setDocument has replaced the entity space — the old CompositorHintComponents are already gone, and registry.valid() on the rebuilt registry would SIGSEGV against the stale entity IDs.
void	rebuildForReplacedDocument (Registry &newRegistry)
	Rebuild the bucket hint set against a new entity space after a structurally-identical setDocument. Mirror of MandatoryHint Detector::rebuildForReplacedDocument — release the stale hints without touching the old entity ids, then run reconcile on the new registry. Because the bucketer's decisions are a pure function of the render-tree shape + complexity costs, a structurally-equal document produces the identical bucket set keyed on the new ids.
const ComplexityBucketerStats &	stats () const
const ComplexityBucketerConfig &	config () const

Detailed Description

Phase 2.5 producer that pre-chunks a document into a small number of layers based on per-subtree rasterization cost.

Runs at document load and on structural rebuild (both callers control when; this class is stateless between calls other than its held hints).

Algorithm (see 0025-composited_rendering.md § Complexity Bucketing):

1. Walk RenderingInstanceView in draw order. The first entity is the document root; skip it as a candidate (we never bucket the whole document).
2. Identify direct children of the root by advancing past each child's subtree (subtreeInfo.lastRenderedEntity). Each direct child is a candidate; its cost is computed from the subtree walk: cost = 1 per entity + filterPenalty * has_filter + maskPenalty * has_mask summed across the subtree.
3. Sort candidates by cost descending, ties broken by entity id ascending (deterministic).
4. Publish ComplexityBucket hints for the top targetBucketCount - reservedSlots candidates.

Restricting candidates to top-level root children sidesteps the deferred-pop correctness concern: by construction, top-level children have no isolation / clip / filter / mask ancestor (other than the root itself), so bucketing them cannot split a group that must stay atomic.

v1 simplifications (tracked for Phase 2.5 followups):

• Cost walk does NOT perform bbox overlap rejection. Two candidates with visually overlapping subtrees may both be bucketed. Correctness is preserved (the resolver composes layers in order); optimality may suffer for pathological documents.
• Candidates are limited to top-level root children. Deeper cost peaks (e.g., a deeply-nested <g> with many filter children) are not promoted in v1 — they'd require a deferred-pop walk we're deferring.
• Each reconcile recomputes from scratch. No incremental update on partial mutations.

Held hints map (bucketHints_) is non-copyable, movable. The RAII pattern ensures dropped entries clean up their CompositorHintComponent entries.

Member Function Documentation

reconcile()

void donner::svg::compositor::ComplexityBucketer::reconcile

(

Registry &

registry

)

Recompute the bucket partition for the current document state.

Intended to be called on document load and when RenderTreeState::needsFullRebuild is true. Publishes new ComplexityBucket hints, drops stale ones, and updates stats. Idempotent on unchanged input.

---

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

• donner/svg/compositor/ComplexityBucketer.h