Document CultMath.Expr: design.md Expressions section, resolver README
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
dc302a96a7
commit
defe2b80de
2 changed files with 41 additions and 0 deletions
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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":..}` |
|
||||
|
|
|
|||
Loading…
Reference in a new issue