dtourolle
7421837c8a
Tool tabs need a taxonomy, and the taxonomy was the problem: a table in `ui/` mapping operation to tab breaks FR-DEV-3a, and a `group:` field risks what `ui-refinement.md` condemned `starts-group` for — the core deciding where the panel draws things. `Attribute` threads the needle. It says what an operation *is* — tone, colour, detail, optics, geometry, effect — which is the same category as `ParamKind` and squarely on the core's side of ARCH §4.3a's line. What is drawn, where it sits and whether it is visible stay the frontend's. There is no attribute for "the third tab", the enum's order is declaration order rather than screen order, and a frontend may render these as tabs, as headings, or ignore them. The payoff is that a tab strip can be *derived*: the groups are the attributes present in the capability list, so the interface names no operation and needs no table to keep in step. An operation joins the right group by declaring what it is, which is the one thing its author is well placed to say. Plural, because the tone curve is genuinely both — an RGB curve is tonal and the per-channel curves are chromatic, and filing it under one would hide it from half the people looking for it. Required and non-empty, enforced in `build.rs`, and the failure was checked by removing the line rather than assumed. An operation with no attribute is invisible to a panel that groups by them; a build that stops costs ten seconds, a control nobody can find costs more. The vocabulary is closed for the same reason: a typo would otherwise invent a category holding exactly one operation, which looks like a deliberate one until somebody counts. Six tests over the real chain, including the hand-written operations that `build.rs` never sees and so cannot check.
228 lines
9.3 KiB
Markdown
228 lines
9.3 KiB
Markdown
# Develop nodes
|
||
|
||
One file per operation. Adding a node to the pipeline is adding a file to this
|
||
directory — there is no list to extend, no shader to edit, and no UI change.
|
||
|
||
`../build.rs` compiles each declaration into Rust implementing
|
||
[`Operation`](../src/operation.rs), generated into `OUT_DIR`. The result is
|
||
indistinguishable downstream from a hand-written operation: the same
|
||
`&'static OpDescriptor`, the same fused-shader composition, the same sidecar
|
||
round-trip.
|
||
|
||
## `attributes:` — what the operation is about
|
||
|
||
Required, one or more of `tone`, `colour`, `detail`, `optics`, `geometry`,
|
||
`effect`. The build fails without it, and that is deliberate: an operation with
|
||
no attribute is invisible to an interface that groups by them, and a control
|
||
that silently does not exist is a worse failure than a build that stops.
|
||
|
||
**Say what the operation is, not where you want it drawn.** The core declares
|
||
capabilities; the frontend composes (ARCH §4.3a). `tone` means "this is about
|
||
lightness", not "put this in the second tab" — the interface is free to render
|
||
attributes as tabs, as headings, or not at all, and that choice may differ
|
||
between a tablet and a desktop without this file changing.
|
||
|
||
**Plural is normal.** The tone curve is `[tone, colour]` because an RGB curve
|
||
is tonal and the per-channel curves are chromatic; it appears wherever the
|
||
frontend decides that means. Reach for a second attribute when an operation
|
||
genuinely answers two questions, not to make it easier to find.
|
||
|
||
**The vocabulary is closed.** A typo is a build error rather than a new
|
||
category containing exactly one operation — which looks identical to a
|
||
deliberate new category until somebody notices the group with one control in
|
||
it.
|
||
|
||
## What you get for free
|
||
|
||
A node dropped in here arrives with:
|
||
|
||
- **Controls.** The develop panel builds them from the parameters' declared
|
||
kinds (FR-DEV-3c). It never learns the node's name.
|
||
- **A place in the chain**, from `order:`.
|
||
- **A place in the panel**, from `attributes:`. The interface groups by these
|
||
and names no operation, so a node arrives in the right group by saying what
|
||
it is rather than by anyone editing a list in `ui/`.
|
||
- **Persistence.** Parameters are ordinary scalars, so the sidecar writes them
|
||
with everything else.
|
||
- **Its tests**, compiled from `tests:` and run with `cargo test`.
|
||
- **Neutral-means-absent.** At its defaults the node contributes no code, no
|
||
uniform, and no branch to the generated shader.
|
||
|
||
## The shape of a file
|
||
|
||
```yaml
|
||
id: exposure # must match the filename
|
||
label: op.exposure # a localisation key, never a display string
|
||
order: 20 # where it sits in the chain
|
||
attributes: [tone] # what it is about; one or more, and required
|
||
|
||
doc: | # becomes the generated module's documentation
|
||
Exposure — a linear gain, expressed in stops.
|
||
placement: | # why it sits where it does; appears above the
|
||
A correction to capture. # entry in the generated chain
|
||
|
||
params:
|
||
exposure:
|
||
label: param.exposure
|
||
kind: stops
|
||
min: -5
|
||
max: 5
|
||
doc: | # optional prose, kept with the descriptor
|
||
±5 stops.
|
||
|
||
uniforms:
|
||
gain: exp2(exposure) # shorthand, or a mapping with `value:` and `doc:`
|
||
|
||
helpers: [luminance] # names from _helpers.yaml
|
||
define: # helpers this node alone needs
|
||
my_curve: |
|
||
fn my_curve(x: f32) -> f32 { return x; }
|
||
|
||
wgsl: | # `c` is linear RGB in and out
|
||
c = c * gain;
|
||
|
||
presentation: # optional; omit for one control per parameter
|
||
widgets: [tone_curve] # a hint, most preferred first
|
||
params: [exposure] # what that widget owns
|
||
|
||
tests:
|
||
- name: one_stop_is_a_doubling
|
||
why: The definition of a stop.
|
||
set: { exposure: 1 }
|
||
expect: { gain: 2.0 }
|
||
```
|
||
|
||
### Parameter kinds
|
||
|
||
| `kind` | Shape | Extra keys |
|
||
|---|---|---|
|
||
| `amount` | −100…100, neutral at 0 — the familiar photographic control | — |
|
||
| `stops` | exposure-like, in stops | `min`, `max` |
|
||
| `fraction` | 0…1 | `default` |
|
||
| `switch` | a toggle, neutral off | — |
|
||
| `enum` | one of a short, fixed list | `variants` |
|
||
| `scalar` | anything else | `min`, `max`, `default`, `unit`, `scale`, `precision` |
|
||
|
||
Reach for `amount` first. Writing its range out by hand in each node is how one
|
||
of them comes to disagree with the rest.
|
||
|
||
An `enum` names its choices as localisation keys, most-neutral first:
|
||
|
||
```yaml
|
||
params:
|
||
method:
|
||
label: param.method
|
||
kind: enum
|
||
variants: [param.method.fast, param.method.exact]
|
||
```
|
||
|
||
The value is the chosen **index**, carried as an `f32` like every other
|
||
parameter — so a uniform expression can use it (`method` is 0 or 1), the
|
||
sidecar stores it unchanged, and nothing along the way needed a second kind of
|
||
value. The default is always the first variant, so `reset` means what it means
|
||
everywhere else; if your neutral choice is not first, reorder the list rather
|
||
than reaching for a `default:`.
|
||
|
||
Two variants is the minimum. A one-entry list is a control the user cannot
|
||
change, and the build rejects it.
|
||
|
||
### Uniform expressions
|
||
|
||
Arithmetic (`+ - * /`), parentheses, numbers, this node's parameters, and:
|
||
`exp2` `log2` `exp` `sqrt` `abs` `floor` `ceil` `round` `pow` `min` `max`
|
||
`clamp` `mix`.
|
||
|
||
Compiled to Rust, so an unknown name or a wrong arity is a build error naming
|
||
the file and the key. Deliberately small: a node is a description, and letting
|
||
it name arbitrary Rust would make this a second, worse place to write code.
|
||
|
||
### Activity
|
||
|
||
By default a node is active exactly when some parameter has moved off its
|
||
default, which is the honest rule and the right one for nearly everything. A
|
||
node whose neutral is something else declares `active:` as an expression —
|
||
non-zero means active.
|
||
|
||
### Presentation
|
||
|
||
Optional, and absent from nearly every node: one control per parameter is the
|
||
right answer for a list of unrelated sliders, which is what most operations
|
||
are. Declare it when several parameters form **one** conceptual control.
|
||
|
||
```yaml
|
||
presentation:
|
||
widgets: [colour_wheel] # most preferred first
|
||
demand:
|
||
two_dimensional: true # dragged in x and y at once
|
||
precise_pointing: false # needs accuracy finer than a fingertip
|
||
params: [hue, strength] # what the widget owns, in its order
|
||
```
|
||
|
||
Widgets: `tone_curve`, `colour_wheel`, `crop_overlay`, `gradient_handle`,
|
||
`brush_mask`, `white_point`.
|
||
|
||
**It is a hint and only a hint.** The frontend walks `widgets` and takes the
|
||
first it both implements and can afford; if it implements none of them, or
|
||
cannot meet the `demand`, it renders the parameters as ordinary sliders and the
|
||
edit still works. So it is safe to name a widget nothing draws yet — the node
|
||
degrades to sliders rather than breaking. That fallback is also why every
|
||
parameter must stay an ordinary scalar: it is what there is to fall back *to*.
|
||
|
||
`demand` says what the widget inherently needs, never what the screen has.
|
||
There is deliberately no way to write a pixel width, a breakpoint or a platform
|
||
name here — those are the frontend's to decide, and a node that reasoned about
|
||
them would eventually be wrong about a display it never saw (ARCH §4.3a).
|
||
|
||
Parameters named in `params:` are claimed by the widget and not drawn
|
||
separately, so a typo would take a parameter out of both. The build checks each
|
||
name against the node's own `params:` and fails if it does not match.
|
||
|
||
### Tests
|
||
|
||
| Key | Asserts |
|
||
|---|---|
|
||
| `set` | parameter values to apply first; build fails if out of range |
|
||
| `expect` | uniform values, within 1e-5 |
|
||
| `expect_range` | a uniform lies in `[low, high]` |
|
||
| `expect_active` | whether the node reaches the shader |
|
||
| `expect_wgsl` | substrings the fragment must contain |
|
||
| `expect_helper_wgsl` | substrings a named helper must contain |
|
||
|
||
`why:` becomes a comment in the generated test. Use it — a test named for a
|
||
property should say what breaks without it.
|
||
|
||
## Hand-written nodes
|
||
|
||
Some operations are not four facts, and forcing them into this schema would
|
||
produce a worse language aimed at one caller. Those stay in
|
||
[`../src/ops/`](../src/ops/) and declare only their position here:
|
||
|
||
```yaml
|
||
id: tone_curve
|
||
order: 60
|
||
rust: ToneCurve
|
||
why_rust: |
|
||
Its neutral is a relationship between five points, not a set of values.
|
||
```
|
||
|
||
They still belong in this directory, because the pipeline's **order** is the
|
||
one thing a reader comes here to learn, and an order written half in YAML and
|
||
half in Rust would be worse than either alone.
|
||
|
||
Currently hand-written: `tone_curve` (a curve widget over five interpolated
|
||
points), `colour_mixer` (thirty-six faceted parameters from twelve computed hue
|
||
bands). `vignetting` is hand-written too but is not in the develop chain — it
|
||
carries lens-profile coefficients that are not parameters. `distortion` and
|
||
`aberration` are `Warp`s rather than operations: they rewrite coordinates
|
||
before sampling rather than transforming a colour after it.
|
||
|
||
## Errors
|
||
|
||
The build script reports failures by naming the key you got wrong, and exits
|
||
rather than panicking, so the message is the message and not a backtrace. It
|
||
refuses: a duplicate `order:`, a filename disagreeing with its `id:`, a default
|
||
outside its own range, a test value the graph would clamp before the node saw
|
||
it, a helper that does not define the function it names, an expression naming
|
||
something that is not a parameter, and a declared node whose name collides with
|
||
a file in `../src/ops/`.
|