Document CultMath.Expr: design.md Expressions section, resolver README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-14 06:05:19 +02:00
commit defe2b80de
2 changed files with 41 additions and 0 deletions

View file

@ -834,6 +834,39 @@ interval, under the affine bound and under the oracle mask (one logarithmic
scale) and the transmittance. Its run: 4.23, 3.60 and 2.02 cells per ray on
average, 44 the most, mean transmittance 0.278.
## Expressions
`CultMath.Expr` holds a scalar SSA expression graph as a persisted value, a builder
for it, and a C# evaluator.
- **Graph (`ExprGraph`)**: a sealed immutable class. It has no name of its own; the
consumer record that holds it names it. Nodes are in topological order, an operand
names a lower node, and an edit builds a new graph. A persisted graph carries a
format version (1); one naming an unknown op, a newer format or a forward operand is
refused whole at decode. `ExprGraph.Create` is the one validator, run by the builder
and by decode.
- **Node**: its index in the topological order. The builder hash-conses identical
(op, operands, constant bits) nodes and drops nodes no output reaches, so one
expression always builds the same bytes; any rebuild may renumber nodes.
- **Port**: graph inputs vary per point, params are uniform per batch and carry a
default, outputs name a node. Names are `[A-Za-z_][A-Za-z0-9_]*`, unique per kind.
An op's operands are positional; a multi-result op (`cellular3`: nearest.xyzw,
edge.xyzw, id) is read only through `Pick`.
- **Op vocabulary**: one table (`ExprOps`), a stable string per op, append-only.
Vector arguments are decomposed operands: `snoise2`, `snoise3`, `cellular3`. An op
calls its CultMath function; a function's value change is a Breaking release note.
- **Evaluation**: `ExprEvaluator.Evaluate` runs the nodes in order through the table,
one IEEE single per op, so a result equals the direct composition of the same math
calls bit for bit. Params bind by name (`ExprBindings`): a missing name takes its
default and an unknown name is refused.
- **Stencils** are substitution at build time (`ExprBuilder.Substitute`, Fidget's
`remap_xyz`): N substitutions of the position inputs combined by ops give an ordinary
flat graph. There is no loop construct.
The MessagePack shape belongs to `GameCult.Caching.MessagePack` (`CultMathExprResolver`).
Interval, affine and gradient evaluation over the graph, bytecode, the HLSL
interpreter and pruning are not built.
## Rules
- Keep type names HLSL-shaped: `float2`, `float3`, `float4`, `float3x3`, and `math`.

View file

@ -10,6 +10,7 @@ format for the attribute-first `GameCult.Caching` stack.
- `CultDocumentResolver`
- `CultRecordRefFormatter<T>`
- `CultMathResolver`: the canonical component-array encoding of every public CultMath value type, part of the default resolver chain
- `CultMathExprResolver`: the canonical encoding of `CultMath.Expr.ExprGraph`, decoded through its validator, part of the default resolver chain
Cult document payloads serialize through `MessagePackSerializer` with the
options of the document's assembly (`CultDocumentMessagePackSerialization.OptionsFor`),
@ -83,6 +84,13 @@ refusal on write is a `JsonException` where System.Text.Json throws
`ArgumentException`. A consumer resolver or converter
registered ahead of these wins.
`CultMath.Expr.ExprGraph` is a class, not a value type, and has its own shape
(`CultMathExprResolver`, in the default chain): `[version, inputs, params, outputs, nodes]`,
with a param `[name, default float bits]`, an output `[name, node]` and a node
`[op name, operands, payload]`. Decoding runs the graph's one validator and refuses a
broken graph whole (an `ExprGraphException` naming the rule), so a consumer
`[CultDocument]` record with an `ExprGraph` field needs no registration. A nil graph is refused.
| Type | MessagePack | JSON |
| --- | --- | --- |
| `float2`, `double2`, `int2`, `bool2` | `[x, y]` | `{"x":..,"y":..}` |