FilterGraph.h File Reference

#include <algorithm>
#include <array>
#include <charconv>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <memory>
#include <optional>
#include <span>
#include <string_view>
#include <type_traits>
#include <variant>
#include <vector>
#include "donner/base/Box.h"
#include "donner/base/EcsRegistry_fwd.h"
#include "donner/base/Length.h"
#include "donner/base/RcString.h"
#include "donner/base/Transform.h"
#include "donner/css/Color.h"
#include "donner/svg/SVGDocumentHandle.h"
#include "donner/svg/components/animation/ContextualLengthRecipe.h"
#include "donner/svg/components/filter/FilterUnits.h"
#include "donner/svg/core/ColorInterpolationFilters.h"
#include "donner/svg/core/ImageRendering.h"
#include "donner/svg/core/PreserveAspectRatio.h"

Include dependency graph for FilterGraph.h:

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

Classes
struct	donner::svg::components::FilterInput
	Identifies the input to a filter primitive node. More...
struct	donner::svg::components::FilterInput::Previous
	The input is the output of the immediately preceding primitive (or SourceGraphic for the first primitive). More...
struct	donner::svg::components::FilterInput::Named
	The input is a named result from a prior primitive's result attribute. More...
struct	donner::svg::components::filter_primitive::GaussianBlur
	Parameters for feGaussianBlur. More...
struct	donner::svg::components::filter_primitive::Flood
	Parameters for feFlood. More...
struct	donner::svg::components::filter_primitive::Offset
	Parameters for feOffset. More...
struct	donner::svg::components::filter_primitive::Blend
	Parameters for feBlend. More...
struct	donner::svg::components::filter_primitive::Composite
	Parameters for feComposite. More...
struct	donner::svg::components::filter_primitive::ColorMatrix
	Parameters for feColorMatrix. More...
struct	donner::svg::components::filter_primitive::Merge
	Parameters for feMerge. Children are represented as additional inputs on the FilterNode. More...
struct	donner::svg::components::filter_primitive::DropShadow
	Parameters for feDropShadow. More...
struct	donner::svg::components::filter_primitive::ComponentTransfer
	Parameters for feComponentTransfer. More...
struct	donner::svg::components::filter_primitive::ComponentTransfer::Func
	A single channel's transfer function. More...
struct	donner::svg::components::filter_primitive::ConvolveMatrix
	Parameters for feConvolveMatrix. More...
struct	donner::svg::components::filter_primitive::Morphology
	Parameters for feMorphology. More...
struct	donner::svg::components::filter_primitive::Tile
	Parameters for feTile. More...
struct	donner::svg::components::filter_primitive::Turbulence
	Parameters for feTurbulence. More...
struct	donner::svg::components::filter_primitive::Image
	Parameters for feImage. More...
struct	donner::svg::components::filter_primitive::DisplacementMap
	Parameters for feDisplacementMap. More...
struct	donner::svg::components::filter_primitive::LightSource
	Light source parameters for lighting filter primitives. More...
struct	donner::svg::components::filter_primitive::DiffuseLighting
	Parameters for feDiffuseLighting. More...
struct	donner::svg::components::filter_primitive::SpecularLighting
	Parameters for feSpecularLighting. More...
struct	donner::svg::components::FilterNode
	A single node in the filter graph, representing one filter primitive. More...
struct	donner::svg::components::FilterGraph
	The complete filter graph for a <filter> element. More...
struct	donner::svg::components::GpuFilterWorkingSet
	Conservative resource layout for the live float filter execution strategy. More...
struct	donner::svg::components::FilterWorkMultiplier
	Computes one primitive's full-surface work multiplier without changing its validation rules. More...
struct	donner::svg::components::FilterStandardInputUsage
	Standard filter inputs that a graph reads, other than SourceGraphic. More...
struct	donner::svg::components::CpuTransientBufferCount
	Computes one CPU primitive's transient float-buffer demand. More...
class	donner::svg::components::FilterExecutionBudget
	Shared per-frame filter budget. More...
struct	donner::svg::components::FilterExecutionBudget::Reservation
	Successful preflight reservation made before allocating a filter capture surface. 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.
namespace	donner::svg::components
	Contains the implementation of the Donner ECS,.
namespace	donner::svg::components::filter_primitive
	Variant holding the parameters for each type of filter primitive.

Typedefs
using	donner::svg::components::FilterPrimitive
	Variant holding any filter primitive type.

Enumerations
enum class	donner::svg::components::FilterStandardInput : std::uint8_t {   donner::svg::components::SourceGraphic ,   donner::svg::components::SourceAlpha ,   donner::svg::components::FillPaint ,   donner::svg::components::StrokePaint }
	Standard named inputs available to filter primitives. More...
enum class	donner::svg::components::FilterMemoryModel : std::uint8_t {   donner::svg::components::CpuFloatNamedResults ,   donner::svg::components::GpuAllNodes }
	Intermediate-retention behavior used to estimate backend memory before filter execution. More...

Functions
double	donner::svg::components::filter_primitive::ConvolveKernelSum (std::span< const double > kernel)
	Sum an admitted convolution kernel with compensation for cancellation.
bool	donner::svg::components::filter_primitive::detail::ParseConvolveDecimalExponent (const char *begin, const char *end, int &power)
	Parses a scientific exponent, including the optional positive sign.
bool	donner::svg::components::filter_primitive::detail::AddConvolveDecimalDigits (std::span< const char > spelling, int power, int sign, std::span< std::int32_t > bins, int lowestPower)
	Adds signed significand digits to fixed decimal bins without rounding.
bool	donner::svg::components::filter_primitive::detail::AddConvolveDecimalCoefficient (double coefficient, std::span< std::int32_t > bins, int lowestPower)
	Adds the shortest round-trip decimal spelling of one finite coefficient.
bool	donner::svg::components::filter_primitive::ConvolveKernelHasDecimalZeroSum (std::span< const double > kernel)
	Tests exact cancellation of the coefficients' shortest round-trip decimal spellings.
double	donner::svg::components::filter_primitive::ConvolveKernelDefaultDivisor (std::span< const double > kernel)
	Resolves an omitted convolution divisor using decimal-zero fallback and compensated summation.
std::uint64_t	donner::svg::components::FilterPrimitivePayloadBytes (const FilterPrimitive &primitive)
	Dynamic numeric storage retained by one primitive payload.
bool	donner::svg::components::FilterGraphHasTurbulence (const FilterGraph &graph)
	Whether graph contains feTurbulence, whose noise both backends evaluate from raster pixel coordinates through only the linear part of the filter transform.
std::uint64_t	donner::svg::components::GpuFilterParameterAllocationBound (std::uint64_t requested)
	Bounds new fixed-block allocations, including a partially filled starting block.
bool	donner::svg::components::ComputeGpuFilterWorkingSet (const FilterGraph &graph, GpuFilterWorkingSet &result)
	Derives a byte-format-aware bound without allocating or changing the CPU filter model.
bool	donner::svg::components::AddFilterRecipeWork (const FilterNode &node, std::uint64_t executions, std::uint64_t &workUnits)
	Adds contextual-region sampling work for one node.
bool	donner::svg::components::AddFilterNodeWork (const FilterNode &node, std::uint64_t pixelCount, std::uint64_t executions, FilterMemoryModel memoryModel, std::uint64_t &workUnits)
	Adds one node's primitive work while preserving the established overflow checks.
bool	donner::svg::components::InitializeFilterWork (const FilterGraph &graph, std::uint64_t pixelCount, FilterMemoryModel memoryModel, std::uint64_t &workUnits)
	Initializes the work estimate, including CPU animated-region coverage scans.
FilterStandardInputUsage	donner::svg::components::StandardInputUsage (const FilterGraph &graph)
	Collects the standard inputs retained by a CPU filter execution.
std::uint64_t	donner::svg::components::CpuRetainedBuffers (const FilterGraph &graph)
	Computes the maximum live CPU float-buffer count across the graph.
bool	donner::svg::components::CpuFilterExecutionBytes (const FilterGraph &graph, std::uint64_t pixelCount, std::uint64_t workUnits, std::uint64_t &workUnitsOut, std::uint64_t &intermediateBytesOut)
	Finalizes the CPU intermediate-memory estimate.
bool	donner::svg::components::GpuFilterExecutionBytes (const FilterGraph &graph, std::uint64_t memoryPixels, std::uint64_t executions, std::uint64_t workUnits, std::uint64_t &workUnitsOut, std::uint64_t &intermediateBytesOut)
	Finalizes the GPU parameter, image, and texture-memory estimate.
bool	donner::svg::components::FilterGraphSizeIsValid (const FilterGraph &graph, std::uint64_t pixelCount)
	Validates graph and logical-surface limits before estimating any node work.
bool	donner::svg::components::FilterMemoryRequestIsValid (std::uint64_t memoryPixels, std::uint64_t executions)
	Validates retained-surface and repeated-execution dimensions.
bool	donner::svg::components::FilterGraphExecutionCost (const FilterGraph &graph, std::uint64_t pixelCount, FilterMemoryModel memoryModel, std::uint64_t &workUnitsOut, std::uint64_t &intermediateBytesOut, std::uint64_t memoryPixels=UINT64_MAX, std::uint64_t executions=1)
	Estimate a filter graph's aggregate execution cost for a pixel surface.
bool	donner::svg::components::FilterGraphFitsExecutionBudget (const FilterGraph &graph, std::uint64_t pixelCount, FilterMemoryModel memoryModel)
	Return whether one filter graph fits the execution budget for a pixel surface.

Variables
constexpr double	donner::svg::components::kMaximumFilterOffset = 4096.0
	Maximum accepted user-space filter offset magnitude.
constexpr double	donner::svg::components::kMaximumFilterStdDeviation = 256.0
	Maximum accepted user-space blur standard deviation.
constexpr double	donner::svg::components::kMaximumFilterMorphologyRadius = 256.0
	Maximum accepted user-space morphology radius.
constexpr int	donner::svg::components::kMaximumFilterPixelOffset = 4096
	Maximum filter offset after conversion to device pixels.
constexpr int	donner::svg::components::kMaximumFilterPixelRadius = 256
	Maximum blur standard deviation or morphology radius after conversion to device pixels.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterMorphologyPassesPerAxis = 9
	Geode decomposes morphology into shader passes whose per-axis radius is at most 31.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterMorphologyWorkMultiplier
	Bound for aggregate morphology work after splitting a large radius into shader passes.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterMorphologyRetainedBuffers
	Bound for temporary buffers retained by a multi-pass morphology execution.
constexpr int	donner::svg::components::kMaximumFilterSurfaceDimension = 4096
	Maximum dimension of a filter-specific intermediate surface.
constexpr std::size_t	donner::svg::components::kMaximumFilterSurfacePixels = 12 * 1024 * 1024
	Maximum pixel area of a filter-specific intermediate surface.
constexpr std::size_t	donner::svg::components::kMaximumFilterGraphNodes = 32
	Maximum number of primitives retained in one computed filter graph.
constexpr std::size_t	donner::svg::components::kMaximumFilterMergeInputs = 16
	Maximum number of inputs composited by one feMerge primitive.
constexpr std::size_t	donner::svg::components::kMaximumFilterTableValues = 1024
	Maximum number of samples accepted for one feComponentTransfer channel table.
constexpr std::size_t	donner::svg::components::kMaximumFilterColorMatrixValues = 20
	Maximum numeric payload accepted for feColorMatrix (the 5-by-4 matrix form).
constexpr int	donner::svg::components::kMaximumFilterConvolveOrder = 64
	Maximum convolve order on either axis and aggregate kernel payload.
constexpr std::size_t	donner::svg::components::kMaximumFilterKernelValues
	Maximum number of coefficients accepted by an feConvolveMatrix kernel.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterWorkUnits = 256ULL * 1024 * 1024
	Maximum aggregate pixel operations accepted for one filter execution.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterFrameWorkUnits = 512ULL * 1024 * 1024
	Maximum aggregate pixel operations accepted across one rendered frame.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterIntermediateBytes = 256ULL * 1024 * 1024
	Maximum estimated bytes retained by filter intermediates during one execution.
constexpr std::uint64_t	donner::svg::components::kMaximumFilterFrameBytes = 256ULL * 1024 * 1024
	Maximum filter memory reserved across one frame, including RGBA capture surfaces.
constexpr double	donner::svg::components::kMaximumFilterTurbulenceFrequency = 1024.0
	Maximum accepted feTurbulence base-frequency magnitude.
constexpr double	donner::svg::components::kMaximumFilterTurbulenceSeed = 2147483646.0
	Maximum accepted feTurbulence seed magnitude (Park-Miller modulus minus one).
constexpr int	donner::svg::components::kMaximumFilterTurbulenceOctaves = 16
	Maximum accepted feTurbulence octave count.
constexpr std::uint64_t	donner::svg::components::kGpuFilterParameterBlockBytes = 64 * 1024
	Minimum allocation of each persistent parameter arena.
constexpr std::uint64_t	donner::svg::components::kGpuFilterTransferTableBytes = 2 * 4096 * sizeof(float)
	Two 4096-entry float transfer tables retained by the filter engine.

---

Class Documentation

donner::svg::components::filter_primitive::Flood

struct donner::svg::components::filter_primitive::Flood

Parameters for feFlood.

Class Members
Color	floodColor {css::RGBA(0, 0, 0, 0xFF)}	Flood color (default: black).
double	floodOpacity = 1.0	Flood opacity (default: 1).

donner::svg::components::filter_primitive::Offset

struct donner::svg::components::filter_primitive::Offset

Parameters for feOffset.

Class Members
double	dx = 0.0	Horizontal offset.
double	dy = 0.0	Vertical offset.

donner::svg::components::filter_primitive::Merge

struct donner::svg::components::filter_primitive::Merge

Parameters for feMerge. Children are represented as additional inputs on the FilterNode.

donner::svg::components::filter_primitive::DropShadow

struct donner::svg::components::filter_primitive::DropShadow

Parameters for feDropShadow.

Class Members
double	dx = 2.0	Horizontal offset.
double	dy = 2.0	Vertical offset.
Color	floodColor {css::RGBA(0, 0, 0, 0xFF)}	Shadow color (default: black).
double	floodOpacity = 1.0	Shadow opacity (default: 1).
double	stdDeviationX = 2.0	Blur standard deviation X.
double	stdDeviationY = 2.0	Blur standard deviation Y.

donner::svg::components::filter_primitive::ComponentTransfer::Func

struct donner::svg::components::filter_primitive::ComponentTransfer::Func

A single channel's transfer function.

Class Members
double	amplitude = 1.0	Amplitude (for gamma).
double	exponent = 1.0	Exponent (for gamma).
double	intercept = 0.0	Intercept (for linear).
double	offset = 0.0	Offset (for gamma).
double	slope = 1.0	Slope (for linear).
vector< double >	tableValues	Table values (for table/discrete).
FuncType	type = FuncType::Identity	Function type.

donner::svg::components::filter_primitive::Tile

struct donner::svg::components::filter_primitive::Tile

Parameters for feTile.

donner::svg::components::filter_primitive::DiffuseLighting

struct donner::svg::components::filter_primitive::DiffuseLighting

Parameters for feDiffuseLighting.

Class Members
double	diffuseConstant = 1.0	Diffuse reflection constant.
optional< LightSource >	light	Light source (from child element).
Color	lightingColor {css::RGBA(0xFF, 0xFF, 0xFF, 0xFF)}	Light color (default: white).
double	surfaceScale = 1.0	Height of surface.

donner::svg::components::filter_primitive::SpecularLighting

struct donner::svg::components::filter_primitive::SpecularLighting

Parameters for feSpecularLighting.

Class Members
optional< LightSource >	light	Light source (from child element).
Color	lightingColor {css::RGBA(0xFF, 0xFF, 0xFF, 0xFF)}	Light color (default: white).
double	specularConstant = 1.0	Specular reflection constant.
double	specularExponent = 1.0	Specular exponent (1..128).
double	surfaceScale = 1.0	Height of surface.

donner::svg::components::GpuFilterWorkingSet

struct donner::svg::components::GpuFilterWorkingSet

Conservative resource layout for the live float filter execution strategy.

Class Members
uint64_t	floatTextures = 0
uint64_t	imageBytes = 0
uint64_t	runtimeUniformBytes = 0
uint64_t	standaloneBufferBytes = 0
uint64_t	uniformBytes = 0

donner::svg::components::FilterStandardInputUsage

struct donner::svg::components::FilterStandardInputUsage

Standard filter inputs that a graph reads, other than SourceGraphic.

Class Members
bool	fillPaint = false	Some node reads FillPaint.
bool	sourceAlpha = false	Some node reads SourceAlpha.
bool	strokePaint = false	Some node reads StrokePaint.

donner::svg::components::FilterExecutionBudget::Reservation

struct donner::svg::components::FilterExecutionBudget::Reservation

Successful preflight reservation made before allocating a filter capture surface.

Class Members
bool	active = false
uint64_t	captureBytes = 0
FilterMemoryModel	memoryModel = FilterMemoryModel::CpuFloatNamedResults

Function Documentation

AddConvolveDecimalCoefficient()

bool donner::svg::components::filter_primitive::detail::AddConvolveDecimalCoefficient ( double coefficient, std::span< std::int32_t > bins, int lowestPower )

inline

Adds the shortest round-trip decimal spelling of one finite coefficient.

Parameters

coefficient	Value to accumulate.
bins	Fixed decimal sum storage.
lowestPower	Power represented by the first bin.

Returns

Whether conversion and accumulation succeeded; false for nonfinite input.

AddConvolveDecimalDigits()

bool donner::svg::components::filter_primitive::detail::AddConvolveDecimalDigits ( std::span< const char > spelling, int power, int sign, std::span< std::int32_t > bins, int lowestPower )

inline

Adds signed significand digits to fixed decimal bins without rounding.

Parameters

spelling	Signless significand, optionally containing a decimal point.
power	Power of the first digit.
sign	Coefficient sign, either -1 or 1.
bins	Fixed sum storage.
lowestPower	Power represented by the first bin.

Returns

Whether all digits and powers were supported.

ParseConvolveDecimalExponent()

bool donner::svg::components::filter_primitive::detail::ParseConvolveDecimalExponent ( const char * begin, const char * end, int & power )

inline

Parses a scientific exponent, including the optional positive sign.

Parameters

begin	First exponent character.
end	One past the exponent.
power	Receives the parsed exponent.

Returns

Whether every character was parsed.