|
|
Donner SVG 0.8.0-pre
SVG editor and embeddable C++20 engine.
|
Typed, immutable expression nodes for the donner::gpu::shader IR.
More...
#include <cstdint>#include <memory>#include <ostream>#include <span>#include <string>#include <string_view>#include <variant>#include <vector>#include "donner/base/RcString.h"#include "donner/gpu/shader/IrType.h"#include "donner/gpu/shader/ShaderResult.h"Classes | |
| class | donner::gpu::shader::IrExpr |
| A typed, immutable IR expression handle. More... | |
| struct | donner::gpu::shader::IrExpr::RefInfo |
| One name reference found inside an expression tree (see collectRefs). More... | |
| struct | donner::gpu::shader::IrExpr::Node |
| Internal storage for IrExpr nodes; public for the factory, serialization, and emitter implementations only. More... | |
Namespaces | |
| namespace | donner |
| Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css. | |
Enumerations | |
| enum class | donner::gpu::shader::BinaryOp : uint8_t { Add , Sub , Mul , Div , Mod , Lt , Le , Gt , Ge , Eq , Ne , And , Or , Shr } |
| Binary operators. More... | |
| enum class | donner::gpu::shader::BuiltinFn : uint8_t { Abs , Min , Max , Clamp , Saturate , Fract , Sqrt , Sin , Cos , Length , Dot , Normalize , Fwidth , Round , Sign , Floor , Pow , Select , Any , All , TextureSample , TextureLoad , TextureDimensions , Ceil , Exp } |
| Builtin functions callable from IR (the program-supported subset; everything else is rejected). More... | |
| enum class | donner::gpu::shader::RefKind : uint8_t { Param , Let , Var , Constant , Resource } |
| What a name reference refers to; determines mutability and serialization. More... | |
Functions | |
| std::ostream & | donner::gpu::shader::operator<< (std::ostream &os, BinaryOp value) |
| Ostream output operator, e.g. add. | |
| std::string_view | donner::gpu::shader::BuiltinFnName (BuiltinFn fn) |
| The builtin's spelling. | |
| std::ostream & | donner::gpu::shader::operator<< (std::ostream &os, BuiltinFn value) |
| Ostream output operator, e.g. clamp. | |
| std::ostream & | donner::gpu::shader::operator<< (std::ostream &os, RefKind value) |
| Ostream output operator, e.g. var. | |
| IrExpr | donner::gpu::shader::LiteralF32 (float value) |
| f32 literal. | |
| IrExpr | donner::gpu::shader::LiteralI32 (int32_t value) |
| i32 literal. | |
| IrExpr | donner::gpu::shader::LiteralU32 (uint32_t value) |
| u32 literal. | |
| IrExpr | donner::gpu::shader::LiteralBool (bool value) |
| bool literal. | |
| IrExpr | donner::gpu::shader::MakeRef (RefKind kind, const RcString &name, const IrType &type) |
| Named reference; normally produced by the function/module builders, which guarantee the name exists with the given type. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Add (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="add") |
| lhs + rhs for matching numeric scalar/vector types. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Sub (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="sub") |
| lhs - rhs for matching numeric scalar/vector types. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Mul (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="mul") |
| lhs * rhs: matching numeric scalar/vector types, vector*scalar, scalar*vector, mat4x4f*vec4f, or mat4x4f*mat4x4f (required by the solid-fill vertex stage, which composes the per-instance matrix with the MVP). | |
| ShaderResult< IrExpr > | donner::gpu::shader::Mod (const IrExpr &lhs, const IrExpr &rhs, const RcString &label=RcString()) |
| lhs / rhs for matching numeric scalar/vector types. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Div (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="div") |
| ShaderResult< IrExpr > | donner::gpu::shader::Lt (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="lt") |
| Every comparison below takes two operands of the same type, and both may be scalars or vectors: a scalar comparison yields bool, a vector comparison compares componentwise and yields a bool vector of the same size, which is how WGSL, MSL, and SPIR-V all define it. Any and All reduce such a vector back to a single bool. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Le (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="le") |
| lhs <= rhs componentwise; yields bool or a bool vector. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Gt (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="gt") |
| lhs > rhs componentwise; yields bool or a bool vector. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Ge (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="ge") |
| lhs >= rhs componentwise; yields bool or a bool vector. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Eq (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="eq") |
| lhs == rhs componentwise for matching scalars or vectors; yields bool or a bool vector. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Ne (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="ne") |
| lhs != rhs componentwise for matching scalars or vectors; yields bool or a bool vector. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Shr (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="shr") |
| lhs >> rhs, a logical shift right on matching-size u32 scalars or vectors. | |
| ShaderResult< IrExpr > | donner::gpu::shader::And (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="and") |
| lhs && rhs for bools. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Or (const IrExpr &lhs, const IrExpr &rhs, const RcString &label="or") |
| lhs || rhs for bools. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Not (const IrExpr &operand, const RcString &label="not") |
| !operand for bool. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Neg (const IrExpr &operand, const RcString &label="neg") |
| -operand for f32/i32 scalars and vectors (u32 has no unary minus). | |
| ShaderResult< IrExpr > | donner::gpu::shader::Member (const IrExpr &base, const RcString &memberName, const RcString &label="member") |
| Struct member access base.member. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Swizzle (const IrExpr &base, std::string_view components, const RcString &label="swizzle") |
| Vector swizzle base.xy (components from xyzw, 1-4 of them, within the vector size). | |
| ShaderResult< IrExpr > | donner::gpu::shader::Index (const IrExpr &base, const IrExpr &index, const RcString &label="index") |
| Indexing base[index] for sized arrays, runtime arrays, and vectors, with an i32/u32 index. | |
| ShaderResult< IrExpr > | donner::gpu::shader::ConstructVector (const IrType &target, std::vector< IrExpr > args, const RcString &label="construct") |
| Vector constructor: vecN<T>(...) from scalars and smaller vectors of element type T totaling exactly N components, or a single scalar splat. | |
| ShaderResult< IrExpr > | donner::gpu::shader::ConstructMat2x2f (std::vector< IrExpr > columns, const RcString &label=RcString()) |
| mat2x2<f32> constructor from two vec2<f32> columns. | |
| ShaderResult< IrExpr > | donner::gpu::shader::ConstructMat4x4f (std::vector< IrExpr > columns, const RcString &label="mat4x4f") |
| Matrix constructor: mat4x4f(c0, c1, c2, c3) from four vec4f columns. | |
| ShaderResult< IrExpr > | donner::gpu::shader::Convert (const IrType &target, const IrExpr &value, const RcString &label="convert") |
| Scalar or vector element-type conversion, e.g. | |
| ShaderResult< IrExpr > | donner::gpu::shader::CallBuiltin (BuiltinFn fn, std::vector< IrExpr > args, const RcString &label="call") |
| Builtin function call by enum. | |
| ShaderResult< IrExpr > | donner::gpu::shader::CallBuiltinNamed (std::string_view name, std::vector< IrExpr > args, const RcString &label="call") |
| Builtin function call by name; unknown names fail closed. | |
| IrExpr | donner::gpu::shader::MakeCallUser (const RcString &name, const IrType &returnType, std::vector< IrExpr > args) |
| User-defined function call; normally produced by the function builder, which checks the signature against the module's registered functions. | |
Typed, immutable expression nodes for the donner::gpu::shader IR.
Every expression is type-checked at construction: the factory functions return ShaderResult and fail closed on ill-typed operands, unknown swizzles, bad constructor arity, indexing of non-indexable types, and unknown builtin functions. Expression values are cheap immutable handles; sharing a subexpression is sharing, not mutation.
| struct donner::gpu::shader::IrExpr::RefInfo |
One name reference found inside an expression tree (see collectRefs).
| Class Members | ||
|---|---|---|
| RefKind | kind | What the name refers to. |
| RcString | name | Referenced name. |
| IrType | type | Type the reference was created with. |
| struct donner::gpu::shader::IrExpr::Node |
Internal storage for IrExpr nodes; public for the factory, serialization, and emitter implementations only.
| Class Members | ||
|---|---|---|
| BinaryOp | binaryOp = BinaryOp::Add | Binary payload. |
| BuiltinFn | builtin = BuiltinFn::Abs | Builtin payload. |
| vector< IrExpr > | children | Operands, in order. |
| Kind | kind = Kind::Literal | Node kind. |
| variant< bool, int32_t, uint32_t, float > | literal = 0.0f | Literal payload. |
| bool | mutableLvalue = false | Assignable access chain. |
| RcString | name | Ref/member/callee name. |
| RefKind | refKind = RefKind::Let | Ref payload. |
| string | swizzle | Swizzle components. |
| IrType | type = IrType::F32() | Result type. |
| UnaryOp | unaryOp = UnaryOp::Neg | Unary payload. |
|
strong |
|
strong |
Builtin functions callable from IR (the program-supported subset; everything else is rejected).
Sign, Floor, and Pow take f32 scalars and f32 vectors and return the shape they were given. Their semantics are stated here because callers depend on them:
All three reject integers, so a caller cannot reach a lowering that differs per backend.
|
strong |
| ShaderResult< IrExpr > donner::gpu::shader::Add | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "add" ) |
lhs + rhs for matching numeric scalar/vector types.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::And | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "and" ) |
lhs && rhs for bools.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| std::string_view donner::gpu::shader::BuiltinFnName | ( | BuiltinFn | fn | ) |
The builtin's spelling.
WGSL, MSL, and the IR's own serialization all use it, because every builtin in scope is named identically in both target languages.
| fn | Builtin to name. |
| ShaderResult< IrExpr > donner::gpu::shader::CallBuiltin | ( | BuiltinFn | fn, |
| std::vector< IrExpr > | args, | ||
| const RcString & | label = "call" ) |
Builtin function call by enum.
| fn | Builtin to call. |
| args | Call arguments. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::CallBuiltinNamed | ( | std::string_view | name, |
| std::vector< IrExpr > | args, | ||
| const RcString & | label = "call" ) |
Builtin function call by name; unknown names fail closed.
| name | Builtin name, e.g. "clamp". |
| args | Call arguments. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::ConstructMat2x2f | ( | std::vector< IrExpr > | columns, |
| const RcString & | label = RcString() ) |
mat2x2<f32> constructor from two vec2<f32> columns.
| columns | Exactly two vec2<f32> columns, in column-major order. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::ConstructMat4x4f | ( | std::vector< IrExpr > | columns, |
| const RcString & | label = "mat4x4f" ) |
Matrix constructor: mat4x4f(c0, c1, c2, c3) from four vec4f columns.
| columns | The four column vectors. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::ConstructVector | ( | const IrType & | target, |
| std::vector< IrExpr > | args, | ||
| const RcString & | label = "construct" ) |
Vector constructor: vecN<T>(...) from scalars and smaller vectors of element type T totaling exactly N components, or a single scalar splat.
| target | Vector type to construct. |
| args | Constructor arguments. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Convert | ( | const IrType & | target, |
| const IrExpr & | value, | ||
| const RcString & | label = "convert" ) |
Scalar or vector element-type conversion, e.g.
f32(x), u32(x), vec2i(vec2f). The target must be a numeric scalar or vector; vector conversions require matching component counts, and a numeric scalar argument may also convert to a vector by splat (e.g. vec2i(0)).
| target | Conversion target type. |
| value | Value to convert. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Eq | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "eq" ) |
lhs == rhs componentwise for matching scalars or vectors; yields bool or a bool vector.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Ge | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "ge" ) |
lhs >= rhs componentwise; yields bool or a bool vector.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Gt | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "gt" ) |
lhs > rhs componentwise; yields bool or a bool vector.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Index | ( | const IrExpr & | base, |
| const IrExpr & | index, | ||
| const RcString & | label = "index" ) |
Indexing base[index] for sized arrays, runtime arrays, and vectors, with an i32/u32 index.
| base | Indexable expression. |
| index | Index expression. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Le | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "le" ) |
lhs <= rhs componentwise; yields bool or a bool vector.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| IrExpr donner::gpu::shader::LiteralBool | ( | bool | value | ) |
bool literal.
| value | Literal value. |
| IrExpr donner::gpu::shader::LiteralF32 | ( | float | value | ) |
f32 literal.
| value | Literal value. |
| IrExpr donner::gpu::shader::LiteralI32 | ( | int32_t | value | ) |
i32 literal.
| value | Literal value. |
| IrExpr donner::gpu::shader::LiteralU32 | ( | uint32_t | value | ) |
u32 literal.
| value | Literal value. |
| ShaderResult< IrExpr > donner::gpu::shader::Lt | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "lt" ) |
Every comparison below takes two operands of the same type, and both may be scalars or vectors: a scalar comparison yields bool, a vector comparison compares componentwise and yields a bool vector of the same size, which is how WGSL, MSL, and SPIR-V all define it. Any and All reduce such a vector back to a single bool.
The ordered comparisons (Lt, Le, Gt, Ge) additionally require numeric operands, since bool has no ordering. Eq and Ne do not: comparing two bools, or two bool vectors, is meaningful and allowed. lhs < rhs componentwise; yields bool or a bool vector.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| IrExpr donner::gpu::shader::MakeCallUser | ( | const RcString & | name, |
| const IrType & | returnType, | ||
| std::vector< IrExpr > | args ) |
User-defined function call; normally produced by the function builder, which checks the signature against the module's registered functions.
| name | Callee name. |
| returnType | Callee return type. |
| args | Call arguments (already checked against the signature). |
Named reference; normally produced by the function/module builders, which guarantee the name exists with the given type.
| kind | What the name refers to. |
| name | Referenced name. |
| type | Type of the referenced value. |
| ShaderResult< IrExpr > donner::gpu::shader::Member | ( | const IrExpr & | base, |
| const RcString & | memberName, | ||
| const RcString & | label = "member" ) |
Struct member access base.member.
| base | Struct-typed expression. |
| memberName | Member to access. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Mod | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = RcString() ) |
lhs / rhs for matching numeric scalar/vector types.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. Integer remainder lhs % rhs. |
| lhs | Left operand (i32 or u32 scalar). |
| rhs | Right operand (same type as lhs). |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Mul | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "mul" ) |
lhs * rhs: matching numeric scalar/vector types, vector*scalar, scalar*vector, mat4x4f*vec4f, or mat4x4f*mat4x4f (required by the solid-fill vertex stage, which composes the per-instance matrix with the MVP).
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Ne | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "ne" ) |
lhs != rhs componentwise for matching scalars or vectors; yields bool or a bool vector.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Neg | ( | const IrExpr & | operand, |
| const RcString & | label = "neg" ) |
-operand for f32/i32 scalars and vectors (u32 has no unary minus).
| operand | Operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Not | ( | const IrExpr & | operand, |
| const RcString & | label = "not" ) |
!operand for bool.
| operand | Operand. |
| label | Diagnostic label. |
| std::ostream & donner::gpu::shader::operator<< | ( | std::ostream & | os, |
| BinaryOp | value ) |
Ostream output operator, e.g. add.
| os | Output stream. |
| value | Value to output. |
| std::ostream & donner::gpu::shader::operator<< | ( | std::ostream & | os, |
| BuiltinFn | value ) |
Ostream output operator, e.g. clamp.
| os | Output stream. |
| value | Value to output. |
| std::ostream & donner::gpu::shader::operator<< | ( | std::ostream & | os, |
| RefKind | value ) |
Ostream output operator, e.g. var.
| os | Output stream. |
| value | Value to output. |
| ShaderResult< IrExpr > donner::gpu::shader::Or | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "or" ) |
lhs || rhs for bools.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Shr | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "shr" ) |
lhs >> rhs, a logical shift right on matching-size u32 scalars or vectors.
Unsigned only: an arithmetic shift of a signed value is a different instruction on every backend, and nothing in the shader set shifts a signed value. There is no left-shift sibling for the same reason - no shader uses one, and an operator with no caller has no execution test that would catch it being emitted wrong.
| lhs | Value to shift. |
| rhs | Shift amount, u32 of the same shape as lhs. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Sub | ( | const IrExpr & | lhs, |
| const IrExpr & | rhs, | ||
| const RcString & | label = "sub" ) |
lhs - rhs for matching numeric scalar/vector types.
| lhs | Left operand. |
| rhs | Right operand. |
| label | Diagnostic label. |
| ShaderResult< IrExpr > donner::gpu::shader::Swizzle | ( | const IrExpr & | base, |
| std::string_view | components, | ||
| const RcString & | label = "swizzle" ) |
Vector swizzle base.xy (components from xyzw, 1-4 of them, within the vector size).
| base | Vector-typed expression. |
| components | Swizzle string, e.g. "xy". |
| label | Diagnostic label. |