pngine 2.2.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -0
- package/dist/core.mjs +4 -4
- package/dist/dev.mjs +1 -1
- package/dist/mini-no-audio.mjs +1 -1
- package/dist/mini.mjs +1 -1
- package/dist/viewer.mjs +1 -1
- package/package.json +7 -7
- package/schema/pngine.sjon +921 -413
- package/src/core.js +10 -5
- package/src/descriptor-decode.js +5 -1
- package/src/gpu-resource-pass-commands.js +42 -6
- package/src/gpu.js +45 -20
- package/src/init-core.js +6 -0
- package/src/init.js +48 -31
- package/src/mini.js +30 -9
- package/src/viewer-init.js +24 -16
- package/src/worker-core.js +47 -15
- package/src/worker-prefetch.js +7 -2
- package/wasm/pngine-compiler.wasm +0 -0
- package/wasm/pngine.wasm +0 -0
package/schema/pngine.sjon
CHANGED
|
@@ -1,31 +1,36 @@
|
|
|
1
|
-
; PNGine WebGPU schema
|
|
1
|
+
; PNGine WebGPU schema.
|
|
2
2
|
;
|
|
3
3
|
; Single source of truth for what a PNGine `.sjon` document may contain. The
|
|
4
|
-
; compiler (`src/dsl_sjon/Compiler.zig`)
|
|
5
|
-
;
|
|
4
|
+
; compiler (`src/dsl_sjon/Compiler.zig`) preloads this manifest once
|
|
5
|
+
; (`sjon.preloadSchema`) and hands it to every `Host.validateDocument`, so
|
|
6
|
+
; the user document parses at offset 0 and the data forms below are validated
|
|
6
7
|
; against this plugin with no filesystem (works on wasm32-freestanding). It is
|
|
7
8
|
; `@embedFile`'d via the `pngine_schema` build import and feeds the web editor's
|
|
8
9
|
; TS / JSON-Schema export.
|
|
9
10
|
;
|
|
10
|
-
;
|
|
11
|
-
;
|
|
12
|
-
; `
|
|
13
|
-
;
|
|
14
|
-
; imageBitmap, MRT/blend/MSAA and `(pass …)` land in later Phase 2 sub-waves.
|
|
11
|
+
; It grew in phases (the core forms first, then shapes, textures, depth/stencil
|
|
12
|
+
; and indexed draws, then samplers, imageBitmap, MRT/blend/MSAA, queries, copies
|
|
13
|
+
; and `(pass …)`); every one of those is here now, and 3.0.0 re-shaped the
|
|
14
|
+
; whole file against the WebGPU IDL.
|
|
15
15
|
;
|
|
16
|
-
; ---- Defaults policy
|
|
16
|
+
; ---- Defaults policy — three DISTINCT notions, never conflated ----
|
|
17
17
|
; 1. Schema `:default V` is a PNGine OPINION. On key absence SJON materializes V
|
|
18
18
|
; into the effective view (→ HostResult.materialized_defaults), so the emitter
|
|
19
19
|
; always bakes a concrete value into the bytecode. Use it where PNGine commits
|
|
20
|
-
; to a value even when WebGPU has none
|
|
21
|
-
;
|
|
20
|
+
; to a value even when WebGPU has none. Note this is NOT a licence to default
|
|
21
|
+
; a REQUIRED member: `load-op` used to be the example here, and it was the
|
|
22
|
+
; wrong one — WebGPU requires loadOp precisely so the author states it, and
|
|
23
|
+
; 3.0.0 made it required here too.
|
|
22
24
|
; 2. A key with NO `:default`, left absent, defers to WebGPU's OWN spec default at
|
|
23
25
|
; runtime — the emitter writes nothing and PNGine invents nothing.
|
|
24
26
|
; 3. js_codegen's omit-when-default (`--html`) is a SIZE ENCODING, not a semantic
|
|
25
27
|
; source: it may drop a descriptor field ONLY when the emitted value equals
|
|
26
28
|
; WebGPU's spec default (e.g. a buffer-binding offset 0 / size = rest-of-buffer),
|
|
27
29
|
; leaning on WebGPU to refill it identically. A materialized OPINION that differs
|
|
28
|
-
; from the WebGPU default (
|
|
30
|
+
; from the WebGPU default (a pass-lowered sampler's `linear` filters, or an
|
|
31
|
+
; authored `:default` on a key whose IDL default is something else) is
|
|
32
|
+
; NEVER omitted. (loadOp/storeOp/clearValue used to be the example: they
|
|
33
|
+
; are required / default-less since 3.0.0.)
|
|
29
34
|
(plugin :name pngine :version "0.1.0"
|
|
30
35
|
|
|
31
36
|
; ---- numeric refinements ----
|
|
@@ -38,13 +43,65 @@
|
|
|
38
43
|
; silently wraps it, and SJON's exporter emits the branded `U32` TS alias so the
|
|
39
44
|
; editor gets real per-field GPU types. Repr checks literals only — expressions
|
|
40
45
|
; (`:size (* NUM 4 4)`) and define-refs are evaluated later, untouched here.
|
|
41
|
-
|
|
46
|
+
;
|
|
47
|
+
; ---- the `x` / `x-value` pair ----
|
|
48
|
+
; Every numeric kind here comes in two: `x-value` carries the bounds and the
|
|
49
|
+
; repr, and `x` is `(scalar-or-ref-shape :base x-value :ref define-ref)` — a
|
|
50
|
+
; literal, a bounded expression, or a bare `(define …)` name. KEYS NAME `x`.
|
|
51
|
+
; The pair is `count` / `count-value`'s, applied to the rest: a number slot
|
|
52
|
+
; is "literal | expression | checked reference" everywhere, because an author
|
|
53
|
+
; who can write `:vertex-count NUM_PARTICLES` and not `:size NUM_PARTICLES`
|
|
54
|
+
; is looking at an accident, not a rule.
|
|
55
|
+
;
|
|
56
|
+
; This could not be written until SJON's union reporting changed. A `scalar-or-ref`
|
|
57
|
+
; desugars to a union, and a union that matched nothing used to report only
|
|
58
|
+
; its ALTERNATIVE NAMES — so adding the reference arm would have retired every
|
|
59
|
+
; bound below it: `:max-anisotropy 32` would have said "no alternative
|
|
60
|
+
; matched: anisotropy-value | define-ref" where it used to name 1..16. SJON
|
|
61
|
+
; reports the arm the value's SHAPE selected, so the bounds still speak. The
|
|
62
|
+
; three inline tests in Compiler.zig are the ratchet.
|
|
63
|
+
;
|
|
64
|
+
; Two numeric slots have no `define-ref` arm, and neither is an oversight:
|
|
65
|
+
; `write-mask` (its symbol arm is the closed member set `all`) and a
|
|
66
|
+
; `(wasm-call :args […])` element (`wasm-arg`, whose symbol arm is the
|
|
67
|
+
; builtin set `canvas-width` …). A third alternative would put a bare name
|
|
68
|
+
; within reach of TWO arms, and SJON's rule declines to guess between them —
|
|
69
|
+
; the slot would lose the report it just gained. A constant is written
|
|
70
|
+
; `(* MASK 1)` / `(* SCALE 1)` there.
|
|
71
|
+
(value-kind :name byte-count-value
|
|
42
72
|
:description "Non-negative integer byte size / offset / stride."
|
|
43
73
|
:underlying number
|
|
44
74
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
45
75
|
:unit (unit-shape :reject true)
|
|
46
76
|
:repr (repr-shape :type u32))
|
|
47
|
-
(value-kind :name
|
|
77
|
+
(value-kind :name byte-count
|
|
78
|
+
:description "Byte size / offset / stride: a literal, a bounded expression, or a bare (define …) reference."
|
|
79
|
+
:underlying scalar-or-ref
|
|
80
|
+
:scalar-or-ref (scalar-or-ref-shape :base byte-count-value :ref define-ref))
|
|
81
|
+
; WebGPU's alignment rules on byte offsets and sizes, as `:multiple-of`
|
|
82
|
+
; bounds (SJON 1.2.0). Like every numeric-bounds, these judge a LITERAL; an
|
|
83
|
+
; expression (`:offset (* N 4)`) is evaluated by the emitter, untouched here.
|
|
84
|
+
(value-kind :name byte-count-4-aligned-value
|
|
85
|
+
:description "Byte offset / size that WebGPU requires to be a multiple of 4."
|
|
86
|
+
:underlying number
|
|
87
|
+
:numeric (numeric-bounds :min 0 :integer true :multiple-of 4)
|
|
88
|
+
:unit (unit-shape :reject true)
|
|
89
|
+
:repr (repr-shape :type u32))
|
|
90
|
+
(value-kind :name byte-count-4-aligned
|
|
91
|
+
:description "A 4-aligned byte offset / size: a literal, a bounded expression, or a bare (define …) reference."
|
|
92
|
+
:underlying scalar-or-ref
|
|
93
|
+
:scalar-or-ref (scalar-or-ref-shape :base byte-count-4-aligned-value :ref define-ref))
|
|
94
|
+
(value-kind :name byte-count-256-aligned-value
|
|
95
|
+
:description "Byte offset that WebGPU requires to be a multiple of 256."
|
|
96
|
+
:underlying number
|
|
97
|
+
:numeric (numeric-bounds :min 0 :integer true :multiple-of 256)
|
|
98
|
+
:unit (unit-shape :reject true)
|
|
99
|
+
:repr (repr-shape :type u32))
|
|
100
|
+
(value-kind :name byte-count-256-aligned
|
|
101
|
+
:description "A 256-aligned byte offset: a literal, a bounded expression, or a bare (define …) reference."
|
|
102
|
+
:underlying scalar-or-ref
|
|
103
|
+
:scalar-or-ref (scalar-or-ref-shape :base byte-count-256-aligned-value :ref define-ref))
|
|
104
|
+
(value-kind :name pool-size-value
|
|
48
105
|
:description "Ping-pong pool size (1..255). The ceiling is the wire's: the
|
|
49
106
|
pool index is a byte everywhere it is encoded, so a larger pool
|
|
50
107
|
cannot be addressed. Bounds a LITERAL; the emitter re-checks the
|
|
@@ -53,24 +110,99 @@
|
|
|
53
110
|
:numeric (numeric-bounds :min 1 :max 255 :integer true)
|
|
54
111
|
:unit (unit-shape :reject true)
|
|
55
112
|
:repr (repr-shape :type u32))
|
|
56
|
-
(value-kind :name
|
|
113
|
+
(value-kind :name pool-size
|
|
114
|
+
:description "Ping-pong pool size: a literal, a bounded expression, or a bare (define …) reference."
|
|
115
|
+
:underlying scalar-or-ref
|
|
116
|
+
:scalar-or-ref (scalar-or-ref-shape :base pool-size-value :ref define-ref))
|
|
117
|
+
(value-kind :name binding-index-value
|
|
57
118
|
:description "Non-negative binding / group / pool index. The PNGB wire stores these as u8, so 255 is the ceiling (WebGPU's own maxBindingsPerBindGroup default is 1000, but PNGine's uniform table and descriptor encoding are byte-indexed)."
|
|
58
119
|
:underlying number
|
|
59
120
|
:numeric (numeric-bounds :min 0 :max 255 :integer true)
|
|
60
121
|
:unit (unit-shape :reject true)
|
|
61
122
|
:repr (repr-shape :type u32))
|
|
123
|
+
(value-kind :name binding-index
|
|
124
|
+
:description "Binding / group / pool index: a literal, a bounded expression, or a bare (define …) reference."
|
|
125
|
+
:underlying scalar-or-ref
|
|
126
|
+
:scalar-or-ref (scalar-or-ref-shape :base binding-index-value :ref define-ref))
|
|
62
127
|
(value-kind :name count-value
|
|
63
128
|
:description "Non-negative integer draw / dispatch count (literals + expressions)."
|
|
64
129
|
:underlying number
|
|
65
130
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
66
131
|
:unit (unit-shape :reject true)
|
|
67
132
|
:repr (repr-shape :type u32))
|
|
68
|
-
; A count may also be a bare
|
|
69
|
-
;
|
|
133
|
+
; A count may also be a bare `(define …)` reference, e.g.
|
|
134
|
+
; `:instance-count NUM_PARTICLES`. The reference half is a cross-ref to the
|
|
135
|
+
; define form (SJON 1.2.0 `scalar-or-ref-shape :ref`), so a misspelt constant is
|
|
136
|
+
; a located `union_no_branch_matched` at validation — it used to be an
|
|
137
|
+
; unlocated "emit failed" from the emitter's env lookup. The emitter still
|
|
138
|
+
; resolves the symbol through its expr env; the schema only guarantees the
|
|
139
|
+
; name exists.
|
|
140
|
+
(value-kind :name define-ref
|
|
141
|
+
:description "Reference to a declared (define :name …) constant."
|
|
142
|
+
:underlying symbol
|
|
143
|
+
:cross-ref (cross-ref :target define))
|
|
144
|
+
; The unbounded real: the element kind of every numeric vector (clear
|
|
145
|
+
; colors, blend constants, float lists) and, since 3.0.0, the
|
|
146
|
+
; `(define …)` value. No bounds to keep, but the unit reject stays — `:base
|
|
147
|
+
; number` (the primitive shortcut) took `1f` and the reader used its
|
|
148
|
+
; magnitude, one reading of the `1.0f` defect the scalar slots close.
|
|
149
|
+
;
|
|
150
|
+
; On `(define :value …)` the rule holds in full: a constant is a real, negative
|
|
151
|
+
; and fractional allowed, and the SLOT that reads it decides integrality and
|
|
152
|
+
; range at use — `0.5` is `:vertex-count`'s located reject and legal in
|
|
153
|
+
; `:clear-value`. The reference arm lets a constant name another constant,
|
|
154
|
+
; declared before or after it; the emitter resolves the set document-wide
|
|
155
|
+
; and refuses a cycle with a span.
|
|
156
|
+
(value-kind :name real-value
|
|
157
|
+
:description "An unbounded real literal: negative and fractional allowed; a unit suffix is rejected."
|
|
158
|
+
:underlying number
|
|
159
|
+
:unit (unit-shape :reject true))
|
|
160
|
+
(value-kind :name real
|
|
161
|
+
:description "An unbounded real: a literal, a bounded expression, or a bare (define …) reference."
|
|
162
|
+
:underlying scalar-or-ref
|
|
163
|
+
:scalar-or-ref (scalar-or-ref-shape :base real-value :ref define-ref))
|
|
70
164
|
(value-kind :name count
|
|
71
165
|
:description "Draw / dispatch count: a literal, a bounded expression, or a bare (define …) reference."
|
|
72
|
-
:underlying
|
|
73
|
-
:
|
|
166
|
+
:underlying scalar-or-ref
|
|
167
|
+
:scalar-or-ref (scalar-or-ref-shape :base count-value :ref define-ref))
|
|
168
|
+
; ---- the domain names ----
|
|
169
|
+
; `count` names a draw / dispatch count and `byte-count` names bytes; a slot
|
|
170
|
+
; that is neither — a sample count, a query index or count, a stencil
|
|
171
|
+
; reference or clear value, a pixel rect, a texel origin, a pool offset — is
|
|
172
|
+
; the general `u32`, and a bitmask is `mask32` (hex literals read as the
|
|
173
|
+
; number they spell: `0xFF` is 255, `pngine inspect` shows the decimal). Same
|
|
174
|
+
; bounds and repr as `count`; the name says the domain, and the exported
|
|
175
|
+
; `.d.ts` alias follows it.
|
|
176
|
+
(value-kind :name u32-value
|
|
177
|
+
:description "Non-negative integer that rides the wire as u32."
|
|
178
|
+
:underlying number
|
|
179
|
+
:numeric (numeric-bounds :min 0 :integer true)
|
|
180
|
+
:unit (unit-shape :reject true)
|
|
181
|
+
:repr (repr-shape :type u32))
|
|
182
|
+
(value-kind :name u32
|
|
183
|
+
:description "A non-negative integer: a literal, a bounded expression, or a bare (define …) reference."
|
|
184
|
+
:underlying scalar-or-ref
|
|
185
|
+
:scalar-or-ref (scalar-or-ref-shape :base u32-value :ref define-ref))
|
|
186
|
+
(value-kind :name query-count-value
|
|
187
|
+
:description "Number of queries in a (query-set …): an integer in [1, 4096] (GPUQuerySetDescriptor.count's createQuerySet bound)."
|
|
188
|
+
:underlying number
|
|
189
|
+
:numeric (numeric-bounds :min 1 :max 4096 :integer true)
|
|
190
|
+
:unit (unit-shape :reject true)
|
|
191
|
+
:repr (repr-shape :type u32))
|
|
192
|
+
(value-kind :name query-count
|
|
193
|
+
:description "Query-set size: a literal, a bounded expression, or a bare (define …) reference, at most 4096."
|
|
194
|
+
:underlying scalar-or-ref
|
|
195
|
+
:scalar-or-ref (scalar-or-ref-shape :base query-count-value :ref define-ref))
|
|
196
|
+
(value-kind :name mask32-value
|
|
197
|
+
:description "32-bit bitmask (0..0xFFFFFFFF); a hex literal reads as the number it spells."
|
|
198
|
+
:underlying number
|
|
199
|
+
:numeric (numeric-bounds :min 0 :integer true)
|
|
200
|
+
:unit (unit-shape :reject true)
|
|
201
|
+
:repr (repr-shape :type u32))
|
|
202
|
+
(value-kind :name mask32
|
|
203
|
+
:description "A 32-bit bitmask: a literal (hex welcome), a bounded expression, or a bare (define …) reference."
|
|
204
|
+
:underlying scalar-or-ref
|
|
205
|
+
:scalar-or-ref (scalar-or-ref-shape :base mask32-value :ref define-ref))
|
|
74
206
|
; A WebGPU device-limit value. Non-negative integer, u32-range in the schema
|
|
75
207
|
; (the PNGB wire carries u64 for forward-compat). Passed VERBATIM to
|
|
76
208
|
; requiredLimits at device creation — an unsatisfiable request fails loud there
|
|
@@ -81,53 +213,108 @@
|
|
|
81
213
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
82
214
|
:unit (unit-shape :reject true)
|
|
83
215
|
:repr (repr-shape :type u32))
|
|
84
|
-
(value-kind :name
|
|
85
|
-
:description "
|
|
216
|
+
(value-kind :name device-limit
|
|
217
|
+
:description "A WebGPU device limit: a literal, a bounded expression, or a bare (define …) reference."
|
|
218
|
+
:underlying scalar-or-ref
|
|
219
|
+
:scalar-or-ref (scalar-or-ref-shape :base device-limit-value :ref define-ref))
|
|
220
|
+
(value-kind :name unorm-value
|
|
221
|
+
:description "A float in [0,1] (the depth clear value)."
|
|
86
222
|
:underlying number
|
|
87
223
|
:numeric (numeric-bounds :min 0 :max 1)
|
|
88
224
|
:unit (unit-shape :reject true)
|
|
89
225
|
:repr (repr-shape :type f32))
|
|
226
|
+
(value-kind :name unorm
|
|
227
|
+
:description "A float in [0,1] (the depth clear value): a literal, a bounded expression, or a bare (define …) reference."
|
|
228
|
+
:underlying scalar-or-ref
|
|
229
|
+
:scalar-or-ref (scalar-or-ref-shape :base unorm-value :ref define-ref))
|
|
230
|
+
; WebGPU's three bias terms are two different types, and conflating them cost
|
|
231
|
+
; this schema a value: `GPUDepthBiasValue` is a `long` (signed 32-bit) while
|
|
232
|
+
; `depthBiasSlopeScale` / `depthBiasClamp` are floats. One `f32`-repr kind for
|
|
233
|
+
; all three let `:depth-bias -1` through the schema and into a u32 read, which
|
|
234
|
+
; dropped it silently (webgpu_wireframe's wireframe pass layered over the solid
|
|
235
|
+
; one by exactly that -1, and shipped without it).
|
|
236
|
+
(value-kind :name depth-bias-int-value
|
|
237
|
+
:description "Constant depth bias: a signed integer (GPUDepthBiasValue is a long)."
|
|
238
|
+
:underlying number
|
|
239
|
+
:numeric (numeric-bounds :integer true)
|
|
240
|
+
:unit (unit-shape :reject true)
|
|
241
|
+
:repr (repr-shape :type i32))
|
|
242
|
+
(value-kind :name depth-bias-int
|
|
243
|
+
:description "Constant depth bias: a literal, a bounded expression, or a bare (define …) reference."
|
|
244
|
+
:underlying scalar-or-ref
|
|
245
|
+
:scalar-or-ref (scalar-or-ref-shape :base depth-bias-int-value :ref define-ref))
|
|
90
246
|
(value-kind :name depth-bias-value
|
|
91
|
-
:description "Depth bias
|
|
247
|
+
:description "Depth bias slope-scale / clamp: a real."
|
|
92
248
|
:underlying number
|
|
93
249
|
:unit (unit-shape :reject true)
|
|
94
250
|
:repr (repr-shape :type f32))
|
|
95
|
-
(value-kind :name
|
|
251
|
+
(value-kind :name depth-bias
|
|
252
|
+
:description "Depth bias slope-scale / clamp: a literal, a bounded expression, or a bare (define …) reference."
|
|
253
|
+
:underlying scalar-or-ref
|
|
254
|
+
:scalar-or-ref (scalar-or-ref-shape :base depth-bias-value :ref define-ref))
|
|
255
|
+
(value-kind :name lod-clamp-value
|
|
96
256
|
:description "Sampler mip level-of-detail clamp (non-negative real; WebGPU defaults lodMinClamp 0, lodMaxClamp 32)."
|
|
97
257
|
:underlying number
|
|
98
258
|
:numeric (numeric-bounds :min 0)
|
|
99
259
|
:unit (unit-shape :reject true)
|
|
100
260
|
:repr (repr-shape :type f32))
|
|
261
|
+
(value-kind :name lod-clamp
|
|
262
|
+
:description "Sampler LOD clamp: a literal, a bounded expression, or a bare (define …) reference."
|
|
263
|
+
:underlying scalar-or-ref
|
|
264
|
+
:scalar-or-ref (scalar-or-ref-shape :base lod-clamp-value :ref define-ref))
|
|
101
265
|
(value-kind :name anisotropy-value
|
|
102
266
|
:description "Sampler max anisotropy (integer in [1,16]; values > 1 require linear mag/min/mipmap filters)."
|
|
103
267
|
:underlying number
|
|
104
268
|
:numeric (numeric-bounds :min 1 :max 16 :integer true)
|
|
105
269
|
:unit (unit-shape :reject true)
|
|
106
270
|
:repr (repr-shape :type u32))
|
|
271
|
+
(value-kind :name anisotropy
|
|
272
|
+
:description "Sampler max anisotropy: a literal, a bounded expression, or a bare (define …) reference."
|
|
273
|
+
:underlying scalar-or-ref
|
|
274
|
+
:scalar-or-ref (scalar-or-ref-shape :base anisotropy-value :ref define-ref))
|
|
275
|
+
; Digit-leading spellings (`1d`, `2d-array`) lex as unit-bearing numbers; SJON
|
|
276
|
+
; 1.2.0 lets a symbol member-set declare them and matches on the parsed
|
|
277
|
+
; (magnitude, unit) pair, so the value reaches the emitter as a
|
|
278
|
+
; `number_with_unit` node, not a symbol — read it with `Reader.memberSpelling`
|
|
279
|
+
; and map through `values.textureDimensionCode` / `viewDimensionCode`
|
|
280
|
+
; (`Emitter.dimensionCode`), never `Reader.symbol` (which returns null on it).
|
|
107
281
|
(value-kind :name texture-dimension
|
|
108
|
-
:description "GPUTextureDimension as
|
|
109
|
-
:underlying
|
|
110
|
-
:
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
282
|
+
:description "GPUTextureDimension, spelled as the WebGPU spec spells it: 1d, 2d (default), 3d."
|
|
283
|
+
:underlying symbol
|
|
284
|
+
:members (member-set
|
|
285
|
+
(member :name 1d :description "One-dimensional texture.")
|
|
286
|
+
(member :name 2d :description "Two-dimensional texture (the default); with a third :size element > 1 it is a 2d array.")
|
|
287
|
+
(member :name 3d :description "Three-dimensional (volume) texture; the third :size element is its slice count.")))
|
|
288
|
+
(value-kind :name subresource-count-value
|
|
289
|
+
:description "Positive integer texture subresource count (≥ 1) — mip levels or array/3d layers. Absent: a texture allocates 1; a texture view exposes every level/layer from its base."
|
|
115
290
|
:underlying number
|
|
116
291
|
:numeric (numeric-bounds :min 1 :integer true)
|
|
117
292
|
:unit (unit-shape :reject true)
|
|
118
293
|
:repr (repr-shape :type u32))
|
|
119
|
-
(value-kind :name subresource-
|
|
294
|
+
(value-kind :name subresource-count
|
|
295
|
+
:description "Texture subresource count: a literal, a bounded expression, or a bare (define …) reference."
|
|
296
|
+
:underlying scalar-or-ref
|
|
297
|
+
:scalar-or-ref (scalar-or-ref-shape :base subresource-count-value :ref define-ref))
|
|
298
|
+
(value-kind :name subresource-index-value
|
|
120
299
|
:description "Zero-based texture subresource index (≥ 0) — a texture view's base mip level or base array layer. Defaults to 0. (subresource-count is ≥ 1; a base index is ≥ 0.)"
|
|
121
300
|
:underlying number
|
|
122
301
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
123
302
|
:unit (unit-shape :reject true)
|
|
124
303
|
:repr (repr-shape :type u32))
|
|
304
|
+
(value-kind :name subresource-index
|
|
305
|
+
:description "Texture subresource index: a literal, a bounded expression, or a bare (define …) reference."
|
|
306
|
+
:underlying scalar-or-ref
|
|
307
|
+
:scalar-or-ref (scalar-or-ref-shape :base subresource-index-value :ref define-ref))
|
|
125
308
|
(value-kind :name view-dimension
|
|
126
|
-
:description "GPUTextureViewDimension as
|
|
127
|
-
:underlying
|
|
128
|
-
:
|
|
129
|
-
|
|
130
|
-
|
|
309
|
+
:description "GPUTextureViewDimension, spelled as the WebGPU spec spells it: 1d, 2d, 2d-array, cube, cube-array, 3d."
|
|
310
|
+
:underlying symbol
|
|
311
|
+
:members (member-set
|
|
312
|
+
(member :name 1d :description "One-dimensional view (texture_1d).")
|
|
313
|
+
(member :name 2d :description "Two-dimensional view (texture_2d) — the default.")
|
|
314
|
+
(member :name 2d-array :description "Array of 2d layers (texture_2d_array).")
|
|
315
|
+
(member :name cube :description "Cube map — six 2d layers (texture_cube).")
|
|
316
|
+
(member :name cube-array :description "Array of cube maps — 6·N layers (texture_cube_array).")
|
|
317
|
+
(member :name 3d :description "Volume view (texture_3d).")))
|
|
131
318
|
(value-kind :name texture-aspect
|
|
132
319
|
:description "GPUTextureAspect — which aspect(s) of a depth/stencil texture a view exposes."
|
|
133
320
|
:underlying symbol
|
|
@@ -157,10 +344,6 @@
|
|
|
157
344
|
:description "Reference to a declared (compute-pipeline :name …)."
|
|
158
345
|
:underlying symbol
|
|
159
346
|
:cross-ref (cross-ref :target compute-pipeline))
|
|
160
|
-
(value-kind :name wasm-call-ref
|
|
161
|
-
:description "Reference to a declared (wasm-call :name …)."
|
|
162
|
-
:underlying symbol
|
|
163
|
-
:cross-ref (cross-ref :target wasm-call))
|
|
164
347
|
(value-kind :name bind-group-ref
|
|
165
348
|
:description "Reference to a declared (bind-group :name …)."
|
|
166
349
|
:underlying symbol
|
|
@@ -173,20 +356,35 @@
|
|
|
173
356
|
:description "Reference to a declared (queue :name …)."
|
|
174
357
|
:underlying symbol
|
|
175
358
|
:cross-ref (cross-ref :target queue))
|
|
176
|
-
(value-kind :name render-pass-ref
|
|
177
|
-
:description "Reference to a declared (render-pass :name …)."
|
|
178
|
-
:underlying symbol
|
|
179
|
-
:cross-ref (cross-ref :target render-pass))
|
|
180
359
|
(value-kind :name compute-pass-ref
|
|
181
360
|
:description "Reference to a declared (compute-pass :name …), including one lowered from (init …) sugar."
|
|
182
361
|
:underlying symbol
|
|
183
362
|
:cross-ref (cross-ref :target compute-pass))
|
|
184
|
-
;
|
|
185
|
-
;
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
363
|
+
; `pipeline-ref` = `(cross-ref :target [render-pipeline compute-pipeline])`
|
|
364
|
+
; lived here until the descriptor cut. Its ONE consumer was the bind-group's
|
|
365
|
+
; `:layout-pipeline`, and `bind-group-layout-spec` below is the same group
|
|
366
|
+
; plus `bind-group-layout` — so the render/compute one-namespace property
|
|
367
|
+
; that closed the shared-namespace hole is unchanged, and keeping both meant two buckets over
|
|
368
|
+
; overlapping target sets reporting ONE collision twice.
|
|
369
|
+
;
|
|
370
|
+
; A bind group's `:layout` names the layout it is built against: a pipeline's
|
|
371
|
+
; auto-derived layout, or an explicit (bind-group-layout …). One key, because
|
|
372
|
+
; GPUBindGroupDescriptor.layout is one member — it was two mutually
|
|
373
|
+
; exclusive keys and an exactly-one group.
|
|
374
|
+
;
|
|
375
|
+
; A TARGET GROUP (`:target [a b c]`), never a union of ref kinds. A union
|
|
376
|
+
; resolves first-match while the emitter's tables are separate id spaces, so a
|
|
377
|
+
; render-pipeline and a bind-group-layout sharing a name would resolve one way
|
|
378
|
+
; here and bind the other downstream — the same hole, closed for `pipeline-ref`
|
|
379
|
+
; and `frame-step` the same way on 2026-08-17. As a group the three forms are
|
|
380
|
+
; ONE namespace: the collision is a `duplicate_cross_ref_target` at the second
|
|
381
|
+
; declaration, so a reference here resolves to exactly one form by
|
|
382
|
+
; construction, and the emitter's "did it resolve to a pipeline?" test is a
|
|
383
|
+
; lookup in its own tables rather than a guess.
|
|
384
|
+
(value-kind :name bind-group-layout-spec
|
|
385
|
+
:description "The layout a bind group is built against: a render-/compute-pipeline whose auto-layout it targets, or an explicit (bind-group-layout …). One namespace across the three."
|
|
386
|
+
:underlying symbol
|
|
387
|
+
:cross-ref (cross-ref :target [render-pipeline compute-pipeline bind-group-layout]))
|
|
190
388
|
|
|
191
389
|
; ---- runtime builtin data sources (write-buffer :data) ----
|
|
192
390
|
(value-kind :name builtin-data-source
|
|
@@ -194,18 +392,27 @@
|
|
|
194
392
|
:underlying symbol
|
|
195
393
|
:members (member-set
|
|
196
394
|
(member :name pngine-inputs :description "16 B: time, canvasWidth, canvasHeight, aspect (all f32).")
|
|
197
|
-
(member :name scene-time-inputs :description "12 B: time, canvasWidth, canvasHeight (all f32) — the first 12 bytes of pngine-inputs. True scene timing is
|
|
395
|
+
(member :name scene-time-inputs :description "12 B: time, canvasWidth, canvasHeight (all f32) — the first 12 bytes of pngine-inputs. True scene timing is not modelled yet.")
|
|
198
396
|
(member :name pointer-inputs :description "48 B: x, y, clickX, clickY, dx, dy, buttons, pressure, modifiers, scrollX, scrollY, _pad (all f32).")))
|
|
397
|
+
; The two ref arms are ONE cross-ref target group, never a union of two ref
|
|
398
|
+
; kinds: a union resolves first-match while the emitter looks the name up in
|
|
399
|
+
; separate id tables. A group gives one namespace — a
|
|
400
|
+
; `(data …)` and a `(wasm-call …)` that share a name collide at the second
|
|
401
|
+
; declaration, so "which table" is decided by the document, not by arm order.
|
|
402
|
+
(value-kind :name data-or-wasm-ref
|
|
403
|
+
:description "Reference to a declared (data :name …) or (wasm-call :name …). One namespace across the two."
|
|
404
|
+
:underlying symbol
|
|
405
|
+
:cross-ref (cross-ref :target [data wasm-call]))
|
|
199
406
|
(value-kind :name write-buffer-source
|
|
200
|
-
:description "write-buffer :data source: a runtime builtin or a (
|
|
407
|
+
:description "write-buffer :data source: a runtime builtin, a (data …) reference, or a (wasm-call …) whose result is written each frame."
|
|
201
408
|
:underlying union
|
|
202
|
-
:union (union-shape :alternatives [builtin-data-source data-ref]))
|
|
409
|
+
:union (union-shape :alternatives [builtin-data-source data-or-wasm-ref]))
|
|
203
410
|
|
|
204
|
-
;
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
411
|
+
; `byte-size` was `[byte-count data-ref]` — a union whose ref arm meant "size
|
|
412
|
+
; this buffer from that data without filling it". Every corpus use of it also
|
|
413
|
+
; carried `:mapped-at-creation <the same data>`, naming one thing twice, and
|
|
414
|
+
; `:data` sizes the buffer now. The arm is gone; a buffer's `:size` is a byte
|
|
415
|
+
; count.
|
|
209
416
|
|
|
210
417
|
; ---- enums ----
|
|
211
418
|
(value-kind :name buffer-usage
|
|
@@ -220,8 +427,8 @@
|
|
|
220
427
|
(member :name copy-src :description "Source of copy operations.")
|
|
221
428
|
(member :name indirect :description "Holds indirect draw/dispatch arguments.")
|
|
222
429
|
(member :name query-resolve :description "Receives resolve-query-set results.")
|
|
223
|
-
(member :name map-read :description "Mappable for CPU readback.")
|
|
224
|
-
(member :name map-write :description "Mappable for CPU upload (write).")))
|
|
430
|
+
(member :name map-read :description "Mappable for CPU readback; combines with copy-dst and nothing else.")
|
|
431
|
+
(member :name map-write :description "Mappable for CPU upload (write); combines with copy-src and nothing else.")))
|
|
225
432
|
(value-kind :name primitive-topology
|
|
226
433
|
:description "GPUPrimitiveTopology — how vertices are assembled into primitives."
|
|
227
434
|
:underlying symbol
|
|
@@ -304,8 +511,7 @@
|
|
|
304
511
|
; Follows `entry-point`: a free symbol naming something inside opaque WGSL,
|
|
305
512
|
; which the EMITTER cross-checks against reflection. SJON cannot check it —
|
|
306
513
|
; the override declarations live inside a `:code` string the validator does
|
|
307
|
-
; not parse
|
|
308
|
-
; that would change that, and why it is blocked upstream).
|
|
514
|
+
; not parse.
|
|
309
515
|
(value-kind :name override-name
|
|
310
516
|
:description "A WGSL `override` identifier, as written in the shader. An @id(N)-annotated override is still named by its identifier here — pngine resolves the value at compile time, so the numeric id never reaches a runtime."
|
|
311
517
|
:underlying symbol)
|
|
@@ -317,6 +523,10 @@
|
|
|
317
523
|
:description "The value to specialise a WGSL `override` with: an integer or real literal, or a bounded expression over (define …) constants. A bool override takes 0 or 1."
|
|
318
524
|
:underlying number
|
|
319
525
|
:unit (unit-shape :reject true))
|
|
526
|
+
(value-kind :name override-number
|
|
527
|
+
:description "An override's value: a literal, a bounded expression, or a bare (define …) reference."
|
|
528
|
+
:underlying scalar-or-ref
|
|
529
|
+
:scalar-or-ref (scalar-or-ref-shape :base override-value :ref define-ref))
|
|
320
530
|
(value-kind :name layout-mode
|
|
321
531
|
:description "Pipeline layout mode: auto derives bind-group layouts from the WGSL."
|
|
322
532
|
:underlying symbol
|
|
@@ -389,9 +599,16 @@
|
|
|
389
599
|
:description "Reference to a declared (query-set :name …)."
|
|
390
600
|
:underlying symbol
|
|
391
601
|
:cross-ref (cross-ref :target query-set))
|
|
392
|
-
(value-kind :name timestamp-writes-item :underlying form :heads (head-set :names [timestamp-writes]))
|
|
393
602
|
; Heads admitted positionally inside an (occlusion-query …) bracket.
|
|
394
|
-
|
|
603
|
+
; Every draw WebGPU brackets, at least one — the bracket is a plain
|
|
604
|
+
; begin/draws/end sequence, and it admits the indirect pair the wire has
|
|
605
|
+
; always allowed.
|
|
606
|
+
(value-kind :name occlusion-draw-item :underlying form :heads (head-set
|
|
607
|
+
:min-children 1
|
|
608
|
+
(head :name draw)
|
|
609
|
+
(head :name draw-indexed)
|
|
610
|
+
(head :name draw-indirect)
|
|
611
|
+
(head :name draw-indexed-indirect)))
|
|
395
612
|
|
|
396
613
|
; ---- Phase 2a: textures, shape generators, depth/stencil, indexed draws ----
|
|
397
614
|
(value-kind :name texture-ref
|
|
@@ -472,6 +689,38 @@
|
|
|
472
689
|
:underlying symbol
|
|
473
690
|
:members (member-set
|
|
474
691
|
(member :name canvas :description "Track the canvas size at runtime (resizes with it).")))
|
|
692
|
+
; One dimension of a GPUExtent3D. `:min 1`, not `:min 0`: a zero-texel
|
|
693
|
+
; dimension is invalid GPU in every direction, and the keys this replaces
|
|
694
|
+
; (`:width`/`:height`, typed `byte-count`) accepted 0 and encoded it.
|
|
695
|
+
(value-kind :name extent-value
|
|
696
|
+
:description "One dimension of a GPUExtent3D, in texels (at least 1)."
|
|
697
|
+
:underlying number
|
|
698
|
+
:numeric (numeric-bounds :min 1 :integer true)
|
|
699
|
+
:unit (unit-shape :reject true)
|
|
700
|
+
:repr (repr-shape :type u32))
|
|
701
|
+
(value-kind :name extent
|
|
702
|
+
:description "One GPUExtent3D dimension: a literal, a bounded expression, or a bare (define …) reference."
|
|
703
|
+
:underlying scalar-or-ref
|
|
704
|
+
:scalar-or-ref (scalar-or-ref-shape :base extent-value :ref define-ref))
|
|
705
|
+
; GPUExtent3D's sequence form: [w], [w h], [w h d]. The missing dimensions are
|
|
706
|
+
; WebGPU's own defaults (height 1, depthOrArrayLayers 1), not pngine's — which
|
|
707
|
+
; is why they are absent rather than materialized (see the defaults policy at
|
|
708
|
+
; the top of this file). A vector, because a sequence of scalars is a vector;
|
|
709
|
+
; three keys, because it was three keys.
|
|
710
|
+
(value-kind :name extent3
|
|
711
|
+
:description "Texture size as [width], [width height], or [width height depth-or-array-layers]; the missing dimensions default to 1."
|
|
712
|
+
:underlying vector
|
|
713
|
+
:vector (vector-shape :element extent :min-len 1 :max-len 3))
|
|
714
|
+
; GPUTextureDescriptor.size is ONE required member, so it is one required key
|
|
715
|
+
; over the three things a pngine texture may be sized by. Three
|
|
716
|
+
; different underlyings — vector, symbol member, cross-ref — so the union
|
|
717
|
+
; cannot be ambiguous. `texture-size-mode` precedes `image-bitmap-ref` because
|
|
718
|
+
; both are symbols and `canvas` must be read as the mode; the emitter's
|
|
719
|
+
; reserved-name check keeps a form from claiming the name.
|
|
720
|
+
(value-kind :name texture-size
|
|
721
|
+
:description "Texture size: an [w h d] extent, `canvas` to track the canvas, or an (image-bitmap …) to take the decoded image's size."
|
|
722
|
+
:underlying union
|
|
723
|
+
:union (union-shape :alternatives [extent3 texture-size-mode image-bitmap-ref]))
|
|
475
724
|
(value-kind :name index-format
|
|
476
725
|
:description "GPUIndexFormat — byte width of index-buffer entries."
|
|
477
726
|
:underlying symbol
|
|
@@ -549,7 +798,9 @@
|
|
|
549
798
|
(member :name decrement-clamp :description "Decrement, clamping at 0.")
|
|
550
799
|
(member :name increment-wrap :description "Increment, wrapping to 0 past the maximum.")
|
|
551
800
|
(member :name decrement-wrap :description "Decrement, wrapping to the maximum below 0.")))
|
|
552
|
-
(value-kind :name depth-stencil-section :underlying form :heads (head-set
|
|
801
|
+
(value-kind :name depth-stencil-section :underlying form :heads (head-set
|
|
802
|
+
(head :name stencil-front :max 1)
|
|
803
|
+
(head :name stencil-back :max 1)))
|
|
553
804
|
|
|
554
805
|
; ---- Phase 2d: MRT / MSAA / advanced render state ----
|
|
555
806
|
; A render-pass attachment view: the canvas (context-current-texture) or a
|
|
@@ -594,16 +845,34 @@
|
|
|
594
845
|
:numeric (numeric-bounds :min 0 :max 15 :integer true)
|
|
595
846
|
:unit (unit-shape :reject true)
|
|
596
847
|
:repr (repr-shape :type u32))
|
|
848
|
+
; The symbol half used to be the PRIMITIVE `symbol`, which accepts any
|
|
849
|
+
; spelling: `:write-mask everything` validated, and the emitter's "any
|
|
850
|
+
; non-numeric means all channels" fallback wrote 0xF — a target the author
|
|
851
|
+
; believed was masked rendered every channel, with no diagnostic anywhere.
|
|
852
|
+
; One member, closed.
|
|
853
|
+
(value-kind :name write-mask-symbol
|
|
854
|
+
:description "The one symbolic write mask: all (every channel, WebGPU's GPUColorWrite.ALL = 15)."
|
|
855
|
+
:underlying symbol
|
|
856
|
+
:members (member-set :values [all]))
|
|
857
|
+
; A `(scalar-or-ref-shape …)` rather than a hand-written `(union-shape …)` of
|
|
858
|
+
; the same two kinds, and the difference is the diagnostic: SJON's arm report
|
|
859
|
+
; is gated on the scalar-or-ref flag (a hand-written union keeps the collapsed
|
|
860
|
+
; report, deliberately — its alternatives may legitimately overlap). Spelled
|
|
861
|
+
; this way, `:write-mask MASK` says `all` is the only symbol it takes; spelled
|
|
862
|
+
; as a union it said "no alternative matched: write-mask-value |
|
|
863
|
+
; write-mask-symbol". `:ref` need not be a cross-ref kind — the meta-schema
|
|
864
|
+
; defines it as "a symbolic reference", and a closed member set is one.
|
|
597
865
|
(value-kind :name write-mask
|
|
598
866
|
:description "Color write mask: an integer bitmask (R=1 G=2 B=4 A=8) or the symbol all (15). Emitter-resolved."
|
|
599
|
-
:underlying
|
|
600
|
-
:
|
|
867
|
+
:underlying scalar-or-ref
|
|
868
|
+
:scalar-or-ref (scalar-or-ref-shape :base write-mask-value :ref write-mask-symbol))
|
|
601
869
|
|
|
602
870
|
; ---- explicit bind-group-layout (uniform_access feature) ----
|
|
603
|
-
; A
|
|
604
|
-
; visibility +
|
|
605
|
-
;
|
|
606
|
-
;
|
|
871
|
+
; A `(bind-group-layout …)` declares the binding layout explicitly (per-entry
|
|
872
|
+
; visibility + one resource sub-form: buffer / sampler / texture /
|
|
873
|
+
; storage-texture) instead of inferring it from a pipeline's auto-layout.
|
|
874
|
+
; visibility is a shader-stage set the emitter ORs into the WebGPU descriptor
|
|
875
|
+
; mask (vertex 0x01 / fragment 0x02 / compute 0x04).
|
|
607
876
|
(value-kind :name visibility
|
|
608
877
|
:description "GPUShaderStage — a shader stage that may access the binding."
|
|
609
878
|
:underlying symbol
|
|
@@ -629,14 +898,38 @@
|
|
|
629
898
|
:description "Reference to a declared (pipeline-layout :name …)."
|
|
630
899
|
:underlying symbol
|
|
631
900
|
:cross-ref (cross-ref :target pipeline-layout))
|
|
901
|
+
; GPUPipelineDescriptorBase.layout is ONE required member of type
|
|
902
|
+
; `GPUPipelineLayout | "auto"`, so it is ONE key. It was two keys and
|
|
903
|
+
; an exclusive-group, which said the same thing in three places and let the
|
|
904
|
+
; exported types describe a shape WebGPU does not have.
|
|
905
|
+
; `layout-mode` comes FIRST in the union: SJON tries alternatives in order, so
|
|
906
|
+
; `auto` is matched as the mode before it could ever be read as a name — which
|
|
907
|
+
; is what reserves it (`(pipeline-layout :name auto)` is rejected by the
|
|
908
|
+
; emitter's reserved-name check).
|
|
909
|
+
(value-kind :name pipeline-layout-spec
|
|
910
|
+
:description "GPUPipelineDescriptorBase.layout: auto (derive from the WGSL), or an explicit (pipeline-layout …)."
|
|
911
|
+
:underlying union
|
|
912
|
+
:union (union-shape :alternatives [layout-mode pipeline-layout-ref]))
|
|
632
913
|
; Positional sub-form heads for the explicit bind-group-layout: an (entry …)
|
|
633
|
-
; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms
|
|
914
|
+
; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms:
|
|
634
915
|
; declared inline under their parent form and resolved LOCAL-FIRST, so the
|
|
635
916
|
; natural names `entry`/`buffer` shadow within scope — no collision with the
|
|
636
917
|
; global `entry` (render-pipeline stage) or `buffer` (top-level resource) forms.
|
|
637
918
|
; Extends to local (sampler …)/(texture …) resources later.
|
|
638
919
|
(value-kind :name bgl-entry-item :underlying form :heads (head-set :names [entry]))
|
|
639
|
-
|
|
920
|
+
; Exactly ONE resource per entry (GPUBindGroupLayoutEntry). Both levels are
|
|
921
|
+
; stated on purpose. `:min-children 1 :max-children 1` (SJON after 1.2.0)
|
|
922
|
+
; counts the WHOLE set — the half per-head bounds cannot express, and what the
|
|
923
|
+
; emitter's `requireOneOf` used to carry. The per-head `:max 1`s are then
|
|
924
|
+
; arithmetically redundant, and kept for their diagnostic: the set yields to
|
|
925
|
+
; the head, so two `(buffer …)` report "at most one `buffer`" (the line to
|
|
926
|
+
; delete) rather than the set's weaker "too many resources".
|
|
927
|
+
(value-kind :name bgl-resource :underlying form :heads (head-set
|
|
928
|
+
:min-children 1 :max-children 1
|
|
929
|
+
(head :name buffer :max 1)
|
|
930
|
+
(head :name sampler :max 1)
|
|
931
|
+
(head :name texture :max 1)
|
|
932
|
+
(head :name storage-texture :max 1)))
|
|
640
933
|
; The three non-buffer resource kinds. Each symbol member IS its WebGPU spelling,
|
|
641
934
|
; so the emitter passes it into the descriptor JSON verbatim (like buffer-binding-type).
|
|
642
935
|
(value-kind :name canvas-alpha-mode
|
|
@@ -644,7 +937,7 @@
|
|
|
644
937
|
:underlying symbol
|
|
645
938
|
:members (member-set
|
|
646
939
|
(member :name opaque :description "Alpha is ignored; the canvas composites as opaque (the WebGPU spec default; cheaper, no fringe on colored pages).")
|
|
647
|
-
(member :name premultiplied :description "Color values are premultiplied by alpha and blend with the page
|
|
940
|
+
(member :name premultiplied :description "Color values are premultiplied by alpha and blend with the page, so a transparent clear lets the page show through. Never a default: an absent (canvas …) form is opaque, as the IDL says.")))
|
|
648
941
|
(value-kind :name sampler-binding-type
|
|
649
942
|
:description "GPUSamplerBindingType — how a sampler binding is exposed to WGSL."
|
|
650
943
|
:underlying symbol
|
|
@@ -676,24 +969,27 @@
|
|
|
676
969
|
:string-bounds (string-bounds :format path))
|
|
677
970
|
|
|
678
971
|
; ---- vectors ----
|
|
679
|
-
(value-kind :name float-list :underlying vector :vector (vector-shape :element
|
|
972
|
+
(value-kind :name float-list :underlying vector :vector (vector-shape :element real))
|
|
680
973
|
; Viewport: the two shapes the emitter accepts — a 5-element rect is invalid.
|
|
681
974
|
(value-kind :name viewport-rect4
|
|
682
975
|
:description "Viewport [x y w h]; minDepth/maxDepth default to 0 and 1."
|
|
683
|
-
:underlying vector :vector (vector-shape :element
|
|
976
|
+
:underlying vector :vector (vector-shape :element real :len 4))
|
|
684
977
|
(value-kind :name viewport-rect6
|
|
685
978
|
:description "Viewport [x y w h minDepth maxDepth]; depths in [0,1]."
|
|
686
|
-
:underlying vector :vector (vector-shape :element
|
|
979
|
+
:underlying vector :vector (vector-shape :element real :len 6))
|
|
687
980
|
(value-kind :name viewport-rect
|
|
688
981
|
:description "Viewport rectangle: [x y w h] or [x y w h minDepth maxDepth]."
|
|
689
982
|
:underlying union
|
|
690
983
|
:union (union-shape :alternatives [viewport-rect4 viewport-rect6]))
|
|
984
|
+
; Integer pixels / texels / indices: `u32` elements (a literal, a bounded
|
|
985
|
+
; expression, or a bare (define …) reference — non-negative integer), where
|
|
986
|
+
; `real` used to let `[0.5 0 1 1.25]` through to be truncated.
|
|
691
987
|
(value-kind :name pixel-rect
|
|
692
988
|
:description "Rectangle [x y w h] in integer pixels."
|
|
693
|
-
:underlying vector :vector (vector-shape :element
|
|
989
|
+
:underlying vector :vector (vector-shape :element u32 :len 4))
|
|
694
990
|
(value-kind :name origin3
|
|
695
|
-
:description "Copy origin [x y z] in texels; z is the destination array layer / depth slice (default 0)."
|
|
696
|
-
:underlying vector :vector (vector-shape :element
|
|
991
|
+
:description "Copy origin [x y z] in integer texels; z is the destination array layer / depth slice (default 0)."
|
|
992
|
+
:underlying vector :vector (vector-shape :element u32 :max-len 3))
|
|
697
993
|
; A buffer/texture with zero usage flags is invalid GPU — require >= 1 (else the
|
|
698
994
|
; reader emits a buffer with no usage and no diagnostic). `:min-len 1`.
|
|
699
995
|
(value-kind :name usage-list
|
|
@@ -702,13 +998,13 @@
|
|
|
702
998
|
; RGBA clear: exactly 4 components (else a 3-element color silently gets alpha 0).
|
|
703
999
|
(value-kind :name clear-color
|
|
704
1000
|
:description "RGBA clear color: exactly 4 components."
|
|
705
|
-
:underlying vector :vector (vector-shape :element
|
|
1001
|
+
:underlying vector :vector (vector-shape :element real :len 4))
|
|
706
1002
|
; RGBA blend-constant: exactly 4 float components, used by the `constant` /
|
|
707
1003
|
; `one-minus-constant` blend factors (setBlendConstant). Same shape as
|
|
708
1004
|
; clear-color; named separately so the description reads for its own role.
|
|
709
1005
|
(value-kind :name blend-constant-color
|
|
710
1006
|
:description "RGBA blend constant: exactly 4 float components (the `constant` blend factor's value)."
|
|
711
|
-
:underlying vector :vector (vector-shape :element
|
|
1007
|
+
:underlying vector :vector (vector-shape :element real :len 4))
|
|
712
1008
|
(value-kind :name buffer-ref-list
|
|
713
1009
|
:description "Declared (buffer …) names, bound to vertex slots 0..N in order."
|
|
714
1010
|
:underlying vector :vector (vector-shape :element buffer-ref))
|
|
@@ -716,7 +1012,7 @@
|
|
|
716
1012
|
:description "Declared (bind-group …) names, set at @group 0..N in order."
|
|
717
1013
|
:underlying vector :vector (vector-shape :element bind-group-ref))
|
|
718
1014
|
(value-kind :name bind-group-layout-ref-list
|
|
719
|
-
:description "Declared (bind-group-layout …) names composing a pipeline layout at @group 0..N in order."
|
|
1015
|
+
:description "Declared (bind-group-layout …) names composing a pipeline layout at @group 0..N in order. At least one — a pngine opinion (WebGPU allows an empty list); an empty pipeline layout is `:layout auto` over a shader with no bindings."
|
|
720
1016
|
:underlying vector :vector (vector-shape :element bind-group-layout-ref :min-len 1))
|
|
721
1017
|
(value-kind :name render-bundle-ref-list
|
|
722
1018
|
:description "Declared (render-bundle …) names replayed by a pass."
|
|
@@ -736,72 +1032,187 @@
|
|
|
736
1032
|
(value-kind :name compute-pass-ref-list
|
|
737
1033
|
:description "Declared (compute-pass …) / (init …) names, run in order."
|
|
738
1034
|
:underlying vector :vector (vector-shape :element compute-pass-ref :max-len 2048))
|
|
739
|
-
; One frame step
|
|
1035
|
+
; One frame step. The three forms share ONE namespace (SJON 1.2.0 multi-target
|
|
1036
|
+
; cross-ref): a pass and a queue with the same :name is a
|
|
1037
|
+
; `duplicate_cross_ref_target` at the declaration, so a step can never be
|
|
1038
|
+
; ambiguous. (It used to be a union tried in order, while the emitter kept
|
|
1039
|
+
; one table for both pass kinds — a collision silently dropped the render pass.)
|
|
740
1040
|
(value-kind :name frame-step
|
|
741
|
-
:description "One frame step: a render-pass, compute-pass, or queue name."
|
|
742
|
-
:underlying
|
|
743
|
-
:
|
|
1041
|
+
:description "One frame step: a render-pass, compute-pass, or queue name (one namespace across the three)."
|
|
1042
|
+
:underlying symbol
|
|
1043
|
+
:cross-ref (cross-ref :target [render-pass compute-pass queue]))
|
|
744
1044
|
(value-kind :name frame-step-list
|
|
745
1045
|
:description "Passes and queues run every frame, in order."
|
|
746
1046
|
:underlying vector :vector (vector-shape :element frame-step :max-len 2048))
|
|
1047
|
+
; `:min-len 1` because count 0 is not "no color targets" on the wire — it is
|
|
1048
|
+
; the frozen legacy sentinel meaning "substitute the preferred canvas format"
|
|
1049
|
+
; (docs/abi.md §6.5), which is exactly the fabrication 3.0.0 removes.
|
|
1050
|
+
; A depth-only bundle is legal WebGPU and this descriptor cannot express it;
|
|
1051
|
+
; saying so is better than accepting `[]` and encoding the canvas guess.
|
|
747
1052
|
(value-kind :name texture-format-list
|
|
748
|
-
:description "Color target formats a (render-bundle …) is recorded against."
|
|
749
|
-
:underlying vector :vector (vector-shape :element texture-format))
|
|
1053
|
+
:description "Color target formats a (render-bundle …) is recorded against (at least one)."
|
|
1054
|
+
:underlying vector :vector (vector-shape :element texture-format :min-len 1))
|
|
750
1055
|
(value-kind :name data-file-list
|
|
751
|
-
:description "WASM file paths whose data segments become D0, D1, … storage buffers."
|
|
1056
|
+
:description "WASM file paths (a pass's :file) whose data segments become D0, D1, … storage buffers."
|
|
752
1057
|
:underlying vector :vector (vector-shape :element file-path))
|
|
753
1058
|
(value-kind :name offset-list
|
|
754
1059
|
:description "Integer offset list (e.g. per-entry ping-pong pool offsets)."
|
|
755
|
-
:underlying vector :vector (vector-shape :element
|
|
1060
|
+
:underlying vector :vector (vector-shape :element u32))
|
|
756
1061
|
(value-kind :name shape-format-list
|
|
757
1062
|
:description "Vertex layout of generated shape data, as ordered attribute specifiers."
|
|
758
1063
|
:underlying vector :vector (vector-shape :element shape-format))
|
|
759
1064
|
(value-kind :name texture-usage-list
|
|
760
1065
|
:description "Texture usage flags (at least one)."
|
|
761
1066
|
:underlying vector :vector (vector-shape :element texture-usage :min-len 1))
|
|
1067
|
+
; GPUExtent3D's sequence rule again, one form over: [x], [x y], [x y z], the
|
|
1068
|
+
; missing dimensions WebGPU's own default of 1. Vector-only — the
|
|
1069
|
+
; alternative was a union with a bare `:workgroups 64` beside `[16 16 1]`,
|
|
1070
|
+
; which would leave the grammar with exactly one member that has two shapes
|
|
1071
|
+
; while texture `:size 512` stays illegal.
|
|
1072
|
+
;
|
|
1073
|
+
; The element is `count` — a literal, a bounded expression, or a bare
|
|
1074
|
+
; `(define …)` name — since 3.0.0 (`[WG 1 1]` works; it used to
|
|
1075
|
+
; be `count-value`, literals and expressions only, because the element
|
|
1076
|
+
; reader resolved no symbols, §307).
|
|
762
1077
|
(value-kind :name dispatch-size
|
|
763
|
-
:description "
|
|
764
|
-
:underlying vector :vector (vector-shape :element count-
|
|
1078
|
+
:description "Compute dispatch in workgroups as [x], [x y] or [x y z]; the missing dimensions default to 1. Elements are literals, expressions, or (define …) names."
|
|
1079
|
+
:underlying vector :vector (vector-shape :element count :min-len 1 :max-len 3))
|
|
765
1080
|
; `(wasm-call …)` args: the emitter encodes a type tag per arg (+ 4 value bytes for
|
|
766
1081
|
; literals); the legacy spells the builtins `canvas.width`/etc.
|
|
1082
|
+
; Same closure as `write-mask`, one form over: the symbol half was the
|
|
1083
|
+
; primitive, so `:args [canvas-widht]` validated and reached an emitter check
|
|
1084
|
+
; that had to exist because the schema could not say the four names. The
|
|
1085
|
+
; emitter's map is still the authority on the ENCODING; the schema is
|
|
1086
|
+
; the authority on the spelling, and the two are pinned together by
|
|
1087
|
+
; `values.mapWasmArgType` (a member the map does not know is `internal:`).
|
|
1088
|
+
(value-kind :name wasm-arg-builtin
|
|
1089
|
+
:description "A runtime value the player fills in before each (wasm-call …)."
|
|
1090
|
+
:underlying symbol
|
|
1091
|
+
:members (member-set
|
|
1092
|
+
(member :name canvas-width :description "Canvas width in physical pixels.")
|
|
1093
|
+
(member :name canvas-height :description "Canvas height in physical pixels.")
|
|
1094
|
+
(member :name time-total :description "Seconds since playback started.")
|
|
1095
|
+
(member :name time-delta :description "Seconds since the previous frame.")))
|
|
767
1096
|
(value-kind :name wasm-arg
|
|
768
1097
|
:description "WASM call argument: a numeric literal, or a runtime builtin the player fills each frame (canvas-width, canvas-height, time-total, time-delta)."
|
|
769
|
-
:underlying union :union (union-shape :alternatives [
|
|
1098
|
+
:underlying union :union (union-shape :alternatives [wasm-arg-builtin number]))
|
|
770
1099
|
(value-kind :name wasm-arg-list
|
|
771
1100
|
:description "Arguments passed to a (wasm-call …) function each frame."
|
|
772
1101
|
:underlying vector :vector (vector-shape :element wasm-arg))
|
|
773
1102
|
|
|
774
1103
|
; ---- positional head-sets ----
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
;
|
|
779
|
-
;
|
|
780
|
-
;
|
|
781
|
-
(value-kind :name
|
|
782
|
-
|
|
783
|
-
|
|
1104
|
+
; Per-head `:min`/`:max` (SJON 1.2.0) carry the IDL's cardinality: a
|
|
1105
|
+
; GPURenderPipelineDescriptor has exactly one vertex stage and at most one of
|
|
1106
|
+
; each other state; a compute pipeline has exactly one compute stage. Below
|
|
1107
|
+
; the floor is `positional_missing` (on the parent), above the ceiling
|
|
1108
|
+
; `positional_too_many` (on the extra child) — both located, at validation.
|
|
1109
|
+
; Until 1.3 these were unenforced or hand-checked in the emitter.
|
|
1110
|
+
(value-kind :name pipeline-section :underlying form :heads (head-set
|
|
1111
|
+
(head :name vertex :min 1 :max 1)
|
|
1112
|
+
(head :name fragment :max 1)
|
|
1113
|
+
(head :name primitive :max 1)
|
|
1114
|
+
(head :name depth-stencil :max 1)
|
|
1115
|
+
(head :name multisample :max 1)))
|
|
1116
|
+
; A stage's module and entry point are SCALARS, so they are keys; what
|
|
1117
|
+
; is left positional is the stage's sequences — `GPUVertexState.buffers`
|
|
1118
|
+
; and `GPUFragmentState.targets`, spliced in directly with no wrapper form.
|
|
1119
|
+
(value-kind :name vertex-section :underlying form :heads (head-set
|
|
1120
|
+
(head :name vertex-buffer)
|
|
1121
|
+
(head :name constant)))
|
|
1122
|
+
; `:min 1` on `target` is a deliberate PNGine narrowing of
|
|
1123
|
+
; GPUFragmentState.targets, which WebGPU lets be empty (a depth-only fragment
|
|
1124
|
+
; stage). Removing the wrapper costed as "zero targets becomes legal" — but
|
|
1125
|
+
; pngine has no runtime that honours it: wgpu_native_gpu's
|
|
1126
|
+
; pipeline decoder substitutes ONE BGRA8Unorm target when the list is empty,
|
|
1127
|
+
; and gpu.js passes the empty list through, so the two backends would build
|
|
1128
|
+
; DIFFERENT pipelines from the same document. That is exactly the fabrication
|
|
1129
|
+
; 3.0.0 set out to remove, so the floor stays until a backend can
|
|
1130
|
+
; express a depth-only stage. It also closes a hole the wrapper left open:
|
|
1131
|
+
; `(targets)` with no children validated and reached the same fabrication.
|
|
1132
|
+
(value-kind :name fragment-section :underlying form :heads (head-set
|
|
1133
|
+
(head :name target :min 1)
|
|
1134
|
+
(head :name constant)))
|
|
1135
|
+
; One stage per compute pipeline, spelled as a form like the other two. The
|
|
1136
|
+
; schema used to argue the flat `:module`/`:entry` shape was natural
|
|
1137
|
+
; here; it is the same GPUProgrammableStage the vertex and fragment stages
|
|
1138
|
+
; carry, and one rule that holds everywhere beats three shapes that each read
|
|
1139
|
+
; well alone.
|
|
1140
|
+
(value-kind :name compute-pipeline-section :underlying form :heads (head-set
|
|
1141
|
+
(head :name compute :min 1 :max 1)))
|
|
1142
|
+
(value-kind :name compute-section :underlying form :heads (head-set :names [constant]))
|
|
784
1143
|
(value-kind :name attribute-item :underlying form :heads (head-set :names [attribute]))
|
|
785
|
-
(value-kind :name
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
1144
|
+
(value-kind :name target-section :underlying form :heads (head-set
|
|
1145
|
+
(head :name blend :max 1)))
|
|
1146
|
+
; GPUBlendState requires BOTH components — `(blend (color …))` alone used to
|
|
1147
|
+
; validate and die on the GPU.
|
|
1148
|
+
(value-kind :name blend-section :underlying form :heads (head-set
|
|
1149
|
+
(head :name color :min 1 :max 1)
|
|
1150
|
+
(head :name alpha :min 1 :max 1)))
|
|
1151
|
+
(value-kind :name render-pass-section :underlying form :heads (head-set
|
|
1152
|
+
(head :name color-attachment)
|
|
1153
|
+
(head :name depth-stencil-attachment :max 1)
|
|
1154
|
+
(head :name draw)
|
|
1155
|
+
(head :name draw-indexed)
|
|
1156
|
+
(head :name draw-indirect)
|
|
1157
|
+
(head :name draw-indexed-indirect)
|
|
1158
|
+
(head :name timestamp-writes :max 1)
|
|
1159
|
+
(head :name occlusion-query)))
|
|
789
1160
|
(value-kind :name bind-entry-item :underlying form :heads (head-set :names [entry]))
|
|
790
1161
|
(value-kind :name queue-action :underlying form :heads (head-set :names [write-buffer copy-texture-to-texture copy-external-image-to-texture resolve-query-set copy-buffer-to-buffer]))
|
|
1162
|
+
; Both texture copies take exactly one endpoint of each kind. The heads
|
|
1163
|
+
; are shared but the FORMS are not — each copy declares its own slot-local
|
|
1164
|
+
; `source`/`destination`, resolved local-first, so `(source :image …)` under
|
|
1165
|
+
; one is not `(source :texture …)` under the other.
|
|
1166
|
+
(value-kind :name copy-endpoints-section :underlying form :heads (head-set
|
|
1167
|
+
(head :name source :min 1 :max 1)
|
|
1168
|
+
(head :name destination :min 1 :max 1)))
|
|
1169
|
+
; A compute pass issues at least one command: a pass that dispatches
|
|
1170
|
+
; nothing is always an authoring slip. WebGPU has no such rule — this is
|
|
1171
|
+
; pngine's opinion, and it is one line of schema rather than an emitter check.
|
|
1172
|
+
; Unbounded per head: several dispatches in one pass is legal WebGPU.
|
|
1173
|
+
(value-kind :name compute-pass-command :underlying form :heads (head-set
|
|
1174
|
+
:min-children 1
|
|
1175
|
+
(head :name dispatch)
|
|
1176
|
+
(head :name dispatch-indirect)))
|
|
1177
|
+
; A bundle records EXACTLY ONE draw, and only a direct one. Not an opinion:
|
|
1178
|
+
; the create_render_bundle descriptor carries a single `drawType` byte with
|
|
1179
|
+
; two values, decoded that way by gpu.js, the native backend and the reference
|
|
1180
|
+
; dispatcher alike. `draw-indirect` in a bundle, and a second draw, arrive
|
|
1181
|
+
; when that descriptor does.
|
|
1182
|
+
(value-kind :name render-bundle-command :underlying form :heads (head-set
|
|
1183
|
+
:min-children 1
|
|
1184
|
+
:max-children 1
|
|
1185
|
+
(head :name draw :max 1)
|
|
1186
|
+
(head :name draw-indexed :max 1)))
|
|
791
1187
|
; `(data …)` generators: a positional sub-form whose head selects a procedural shape
|
|
792
1188
|
; (cube/sphere/…) or `wasm-data` (a WASM function that returns the vertex bytes).
|
|
793
|
-
|
|
1189
|
+
; At most ONE per (data …) — one byte source, nine spellings. Per-head bounds
|
|
1190
|
+
; say "at most one of each"; "at most one across the nine" is the ceiling over
|
|
1191
|
+
; the SET (SJON after 1.2.0 — it replaced the emitter's `requireOneOf`).
|
|
1192
|
+
; `:max-children` with no floor, since a (data … :float32 […]) / (data …
|
|
1193
|
+
; :file …) carries no generator at all.
|
|
1194
|
+
(value-kind :name data-shape-section :underlying form :heads (head-set
|
|
1195
|
+
:max-children 1
|
|
1196
|
+
(head :name cube :max 1)
|
|
1197
|
+
(head :name plane :max 1)
|
|
1198
|
+
(head :name sphere :max 1)
|
|
1199
|
+
(head :name torus :max 1)
|
|
1200
|
+
(head :name truncated-cone :max 1)
|
|
1201
|
+
(head :name cylinder :max 1)
|
|
1202
|
+
(head :name teapot :max 1)
|
|
1203
|
+
(head :name dragon :max 1)
|
|
1204
|
+
(head :name wasm-data :max 1)))
|
|
794
1205
|
|
|
795
1206
|
; =====================================================================
|
|
796
|
-
; Top-level forms
|
|
1207
|
+
; Top-level forms
|
|
797
1208
|
; =====================================================================
|
|
798
1209
|
|
|
799
1210
|
(form :name define
|
|
800
|
-
:description "Named numeric constant
|
|
1211
|
+
:description "Named numeric constant, usable in every numeric slot and vector element as a bare name or inside a bounded expression."
|
|
801
1212
|
(key :name name :type symbol
|
|
802
|
-
:description "Constant name, referenced from numeric
|
|
803
|
-
(key :name value :type
|
|
804
|
-
:description "
|
|
1213
|
+
:description "Constant name, referenced from numeric slots, vector elements and expressions.")
|
|
1214
|
+
(key :name value :type real
|
|
1215
|
+
:description "The constant's value: a real (negative and fractional allowed), a bounded expression, or another constant's name — the slot that reads the constant decides integrality and range."))
|
|
805
1216
|
|
|
806
1217
|
; Authored WebGPU device requiredLimits. Optional singleton (declare at most
|
|
807
1218
|
; once, no :name). Each present key raises the corresponding GPUSupportedLimits
|
|
@@ -812,116 +1223,126 @@
|
|
|
812
1223
|
; WebGPU GPUSupportedLimits members (kebab here → camelCase on the wire).
|
|
813
1224
|
(form :name limits
|
|
814
1225
|
:description "Authored WebGPU device requiredLimits (optional singleton)."
|
|
815
|
-
(key :name max-texture-dimension-1d :type device-limit
|
|
1226
|
+
(key :name max-texture-dimension-1d :type device-limit :optional true
|
|
816
1227
|
:description "Max width of a 1D texture (default 8192).")
|
|
817
|
-
(key :name max-texture-dimension-2d :type device-limit
|
|
1228
|
+
(key :name max-texture-dimension-2d :type device-limit :optional true
|
|
818
1229
|
:description "Max width/height of a 2D texture (default 8192).")
|
|
819
|
-
(key :name max-texture-dimension-3d :type device-limit
|
|
1230
|
+
(key :name max-texture-dimension-3d :type device-limit :optional true
|
|
820
1231
|
:description "Max width/height/depth of a 3D texture (default 2048).")
|
|
821
|
-
(key :name max-texture-array-layers :type device-limit
|
|
1232
|
+
(key :name max-texture-array-layers :type device-limit :optional true
|
|
822
1233
|
:description "Max array layers of a 2D texture (default 256).")
|
|
823
|
-
(key :name max-bind-groups :type device-limit
|
|
1234
|
+
(key :name max-bind-groups :type device-limit :optional true
|
|
824
1235
|
:description "Max simultaneous bind groups (default 4).")
|
|
825
|
-
(key :name max-bind-groups-plus-vertex-buffers :type device-limit
|
|
1236
|
+
(key :name max-bind-groups-plus-vertex-buffers :type device-limit :optional true
|
|
826
1237
|
:description "Max bind groups + vertex buffers combined (default 24).")
|
|
827
|
-
(key :name max-bindings-per-bind-group :type device-limit
|
|
1238
|
+
(key :name max-bindings-per-bind-group :type device-limit :optional true
|
|
828
1239
|
:description "Max bindings in a single bind group (default 1000).")
|
|
829
|
-
(key :name max-dynamic-uniform-buffers-per-pipeline-layout :type device-limit
|
|
1240
|
+
(key :name max-dynamic-uniform-buffers-per-pipeline-layout :type device-limit :optional true
|
|
830
1241
|
:description "Max dynamic-offset uniform buffers per pipeline layout (default 8).")
|
|
831
|
-
(key :name max-dynamic-storage-buffers-per-pipeline-layout :type device-limit
|
|
1242
|
+
(key :name max-dynamic-storage-buffers-per-pipeline-layout :type device-limit :optional true
|
|
832
1243
|
:description "Max dynamic-offset storage buffers per pipeline layout (default 4).")
|
|
833
|
-
(key :name max-sampled-textures-per-shader-stage :type device-limit
|
|
1244
|
+
(key :name max-sampled-textures-per-shader-stage :type device-limit :optional true
|
|
834
1245
|
:description "Max sampled textures per shader stage (default 16).")
|
|
835
|
-
(key :name max-samplers-per-shader-stage :type device-limit
|
|
1246
|
+
(key :name max-samplers-per-shader-stage :type device-limit :optional true
|
|
836
1247
|
:description "Max samplers per shader stage (default 16).")
|
|
837
|
-
(key :name max-storage-buffers-per-shader-stage :type device-limit
|
|
1248
|
+
(key :name max-storage-buffers-per-shader-stage :type device-limit :optional true
|
|
838
1249
|
:description "Max storage buffers per shader stage (default 8).")
|
|
839
|
-
(key :name max-storage-buffers-in-vertex-stage :type device-limit
|
|
1250
|
+
(key :name max-storage-buffers-in-vertex-stage :type device-limit :optional true
|
|
840
1251
|
:description "Max storage buffers in the vertex stage (compat split-stage limit; default 8).")
|
|
841
|
-
(key :name max-storage-buffers-in-fragment-stage :type device-limit
|
|
1252
|
+
(key :name max-storage-buffers-in-fragment-stage :type device-limit :optional true
|
|
842
1253
|
:description "Max storage buffers in the fragment stage (compat split-stage limit; default 8).")
|
|
843
|
-
(key :name max-storage-textures-per-shader-stage :type device-limit
|
|
1254
|
+
(key :name max-storage-textures-per-shader-stage :type device-limit :optional true
|
|
844
1255
|
:description "Max storage textures per shader stage (default 4).")
|
|
845
|
-
(key :name max-storage-textures-in-vertex-stage :type device-limit
|
|
1256
|
+
(key :name max-storage-textures-in-vertex-stage :type device-limit :optional true
|
|
846
1257
|
:description "Max storage textures in the vertex stage (compat split-stage limit; default 4).")
|
|
847
|
-
(key :name max-storage-textures-in-fragment-stage :type device-limit
|
|
1258
|
+
(key :name max-storage-textures-in-fragment-stage :type device-limit :optional true
|
|
848
1259
|
:description "Max storage textures in the fragment stage (compat split-stage limit; default 4).")
|
|
849
|
-
(key :name max-
|
|
1260
|
+
(key :name max-immediate-size :type device-limit :optional true
|
|
1261
|
+
:description "Max size in bytes of a pipeline's immediate-data range; must be a multiple of 4 (default 64).")
|
|
1262
|
+
(key :name max-uniform-buffers-per-shader-stage :type device-limit :optional true
|
|
850
1263
|
:description "Max uniform buffers per shader stage (default 12).")
|
|
851
|
-
(key :name max-uniform-buffer-binding-size :type device-limit
|
|
1264
|
+
(key :name max-uniform-buffer-binding-size :type device-limit :optional true
|
|
852
1265
|
:description "Max bound range of a uniform buffer in bytes (default 65536).")
|
|
853
|
-
(key :name max-storage-buffer-binding-size :type device-limit
|
|
1266
|
+
(key :name max-storage-buffer-binding-size :type device-limit :optional true
|
|
854
1267
|
:description "Max bound range of a storage buffer in bytes (default 134217728).")
|
|
855
|
-
(key :name min-uniform-buffer-offset-alignment :type device-limit
|
|
1268
|
+
(key :name min-uniform-buffer-offset-alignment :type device-limit :optional true
|
|
856
1269
|
:description "Required alignment of a dynamic uniform buffer offset (default 256).")
|
|
857
|
-
(key :name min-storage-buffer-offset-alignment :type device-limit
|
|
1270
|
+
(key :name min-storage-buffer-offset-alignment :type device-limit :optional true
|
|
858
1271
|
:description "Required alignment of a dynamic storage buffer offset (default 256).")
|
|
859
|
-
(key :name max-vertex-buffers :type device-limit
|
|
1272
|
+
(key :name max-vertex-buffers :type device-limit :optional true
|
|
860
1273
|
:description "Max vertex buffers in a render pipeline (default 8).")
|
|
861
|
-
(key :name max-buffer-size :type device-limit
|
|
1274
|
+
(key :name max-buffer-size :type device-limit :optional true
|
|
862
1275
|
:description "Max size of a buffer in bytes (default 268435456).")
|
|
863
|
-
(key :name max-vertex-attributes :type device-limit
|
|
1276
|
+
(key :name max-vertex-attributes :type device-limit :optional true
|
|
864
1277
|
:description "Max vertex attributes across all buffers (default 16).")
|
|
865
|
-
(key :name max-vertex-buffer-array-stride :type device-limit
|
|
1278
|
+
(key :name max-vertex-buffer-array-stride :type device-limit :optional true
|
|
866
1279
|
:description "Max stride of a vertex buffer in bytes (default 2048).")
|
|
867
|
-
(key :name max-inter-stage-shader-variables :type device-limit
|
|
1280
|
+
(key :name max-inter-stage-shader-variables :type device-limit :optional true
|
|
868
1281
|
:description "Max inter-stage shader variables (default 16).")
|
|
869
|
-
(key :name max-color-attachments :type device-limit
|
|
1282
|
+
(key :name max-color-attachments :type device-limit :optional true
|
|
870
1283
|
:description "Max color attachments in a render pass (default 8).")
|
|
871
|
-
(key :name max-color-attachment-bytes-per-sample :type device-limit
|
|
1284
|
+
(key :name max-color-attachment-bytes-per-sample :type device-limit :optional true
|
|
872
1285
|
:description "Max total bytes per sample across color attachments (default 32).")
|
|
873
|
-
(key :name max-compute-workgroup-storage-size :type device-limit
|
|
1286
|
+
(key :name max-compute-workgroup-storage-size :type device-limit :optional true
|
|
874
1287
|
:description "Max var<workgroup> storage in bytes (default 16384).")
|
|
875
|
-
(key :name max-compute-invocations-per-workgroup :type device-limit
|
|
1288
|
+
(key :name max-compute-invocations-per-workgroup :type device-limit :optional true
|
|
876
1289
|
:description "Max x*y*z of a compute @workgroup_size (default 256).")
|
|
877
|
-
(key :name max-compute-workgroup-size-x :type device-limit
|
|
1290
|
+
(key :name max-compute-workgroup-size-x :type device-limit :optional true
|
|
878
1291
|
:description "Max X of a compute @workgroup_size (default 256).")
|
|
879
|
-
(key :name max-compute-workgroup-size-y :type device-limit
|
|
1292
|
+
(key :name max-compute-workgroup-size-y :type device-limit :optional true
|
|
880
1293
|
:description "Max Y of a compute @workgroup_size (default 256).")
|
|
881
|
-
(key :name max-compute-workgroup-size-z :type device-limit
|
|
1294
|
+
(key :name max-compute-workgroup-size-z :type device-limit :optional true
|
|
882
1295
|
:description "Max Z of a compute @workgroup_size (default 64).")
|
|
883
|
-
(key :name max-compute-workgroups-per-dimension :type device-limit
|
|
1296
|
+
(key :name max-compute-workgroups-per-dimension :type device-limit :optional true
|
|
884
1297
|
:description "Max dispatchWorkgroups count per dimension (default 65535)."))
|
|
885
1298
|
|
|
886
1299
|
(form :name canvas
|
|
887
1300
|
:description "Canvas presentation configuration (optional singleton). Carried as a
|
|
888
1301
|
header flag, consumed by the JS runtime at context.configure() before
|
|
889
|
-
the executor runs. Form absent →
|
|
890
|
-
|
|
1302
|
+
the executor runs. Form absent → opaque, as
|
|
1303
|
+
GPUCanvasConfiguration.alphaMode. Write (canvas :alpha-mode
|
|
1304
|
+
premultiplied) for a canvas the page shows through.
|
|
891
1305
|
Native --frame renders offscreen and ignores it. viewFormats/
|
|
892
|
-
colorSpace/toneMapping are
|
|
893
|
-
chained header table, the 3 reserved header bytes
|
|
894
|
-
by the device-limits offset
|
|
895
|
-
(key :name alpha-mode :type canvas-alpha-mode :default
|
|
896
|
-
:description "GPUCanvasConfiguration.alphaMode — opaque or premultiplied
|
|
1306
|
+
colorSpace/toneMapping are not modelled: anything list-shaped
|
|
1307
|
+
needs a chained header table, and the 3 reserved header bytes
|
|
1308
|
+
are consumed by the device-limits offset."
|
|
1309
|
+
(key :name alpha-mode :type canvas-alpha-mode :default opaque
|
|
1310
|
+
:description "GPUCanvasConfiguration.alphaMode — opaque (the default) or premultiplied, which lets the page behind the canvas show through wherever the rendered alpha is below 1."))
|
|
897
1311
|
|
|
898
1312
|
(form :name shader-module
|
|
899
1313
|
:description "A named WGSL module. The source is opaque text to SJON."
|
|
900
1314
|
(key :name name :type symbol
|
|
901
|
-
:description "Module name referenced by pipeline
|
|
1315
|
+
:description "Module name referenced by a pipeline stage's :module key.")
|
|
902
1316
|
(key :name code :type string
|
|
903
|
-
:description "WGSL source text
|
|
1317
|
+
:description "WGSL source text, kept verbatim (a triple-quoted string's indentation is part of the shader)."))
|
|
904
1318
|
|
|
905
1319
|
(form :name data
|
|
906
1320
|
:description "Binary data: an inline float32 array, a positional shape sub-form
|
|
907
|
-
(cube/teapot/…) the emitter expands to vertex bytes, or a `:
|
|
1321
|
+
(cube/teapot/…) the emitter expands to vertex bytes, or a `:file`
|
|
908
1322
|
image file the emitter reads from disk and embeds as
|
|
909
1323
|
[mime_len][mime][bytes] (consumed by an image-bitmap)."
|
|
910
1324
|
:positional data-shape-section
|
|
911
1325
|
(key :name name :type symbol
|
|
912
|
-
:description "Data name referenced by buffer :
|
|
1326
|
+
:description "Data name referenced by buffer :data / :index-of and image-bitmap :data.")
|
|
913
1327
|
(key :name float32 :type float-list :optional true
|
|
914
1328
|
:description "Inline float32 array embedded little-endian in the payload.")
|
|
915
|
-
(key :name
|
|
1329
|
+
(key :name file :type file-path :optional true
|
|
916
1330
|
:description "Image file path (relative to the source file) embedded as [mime_len][mime][bytes]; decoded at runtime via createImageBitmap.")
|
|
917
1331
|
(key :name mime :type string :optional true
|
|
918
|
-
:description "MIME type stored with the :
|
|
1332
|
+
:description "MIME type stored with the :file bytes (e.g. image/png); default application/octet-stream. Ignored when there is no :file.")
|
|
1333
|
+
; One source per (data …): the inline array OR the file (both used to
|
|
1334
|
+
; validate and the file won in silence). The third source, a
|
|
1335
|
+
; positional generator, is a head-set the group cannot count against; the
|
|
1336
|
+
; emitter refuses a generator beside either key, and a (data …) with none.
|
|
1337
|
+
(exclusive-group :cardinality at-most-one
|
|
1338
|
+
(alt :keys [float32])
|
|
1339
|
+
(alt :keys [file])))
|
|
919
1340
|
|
|
920
1341
|
(form :name image-bitmap
|
|
921
|
-
:description "A decoded image created from a (data … :
|
|
1342
|
+
:description "A decoded image created from a (data … :file …) entry. Copied into a texture via a (copy-external-image-to-texture …) queue action."
|
|
922
1343
|
(key :name name :type symbol)
|
|
923
|
-
(key :name
|
|
924
|
-
:description "The (data … :
|
|
1344
|
+
(key :name data :type data-ref
|
|
1345
|
+
:description "The (data … :file …) entry holding the encoded image bytes."))
|
|
925
1346
|
|
|
926
1347
|
; ---- shape sub-forms (positional children of `(data …)`) ----
|
|
927
1348
|
; `:open true` so generator-specific numeric config (segments, rings, radius,
|
|
@@ -954,36 +1375,28 @@
|
|
|
954
1375
|
|
|
955
1376
|
(form :name wasm-data
|
|
956
1377
|
:description "Static WASM data generator (positional child of (data …)): the module's :func is called once at buffer-create time and its returned bytes fill the buffer via mappedAtCreation."
|
|
957
|
-
(key :name
|
|
958
|
-
:description "WASM file path relative to the source file
|
|
1378
|
+
(key :name file :type file-path
|
|
1379
|
+
:description "WASM file path relative to the source file.")
|
|
959
1380
|
(key :name func :type symbol
|
|
960
1381
|
:description "Exported function called once to produce the bytes.")
|
|
961
1382
|
(key :name returns :type string
|
|
962
1383
|
:description "Return type → byte count (e.g. array<f32,360> → 1440)."))
|
|
963
1384
|
|
|
964
1385
|
(form :name texture
|
|
965
|
-
:description "GPU texture. `:size
|
|
966
|
-
|
|
967
|
-
sequential ping-pong ids."
|
|
1386
|
+
:description "GPU texture. `:size` is an [w h d] extent, `canvas` to track the
|
|
1387
|
+
canvas size at runtime, or an (image-bitmap …) to take the decoded
|
|
1388
|
+
image's size. `pool` creates N sequential ping-pong ids."
|
|
968
1389
|
(key :name name :type symbol)
|
|
969
|
-
(key :name size :type texture-size
|
|
970
|
-
:description "
|
|
971
|
-
(key :name size-from :type image-bitmap-ref :optional true
|
|
972
|
-
:description "Take width/height from a decoded (image-bitmap …) at runtime (mutually exclusive with :size).")
|
|
973
|
-
(key :name width :type byte-count :optional true
|
|
974
|
-
:description "Texel width (when not sized by :size canvas or :size-from).")
|
|
975
|
-
(key :name height :type byte-count :optional true
|
|
976
|
-
:description "Texel height (when not sized by :size canvas or :size-from).")
|
|
1390
|
+
(key :name size :type texture-size
|
|
1391
|
+
:description "Texel size: [w], [w h] or [w h d]; canvas to track the canvas; or an (image-bitmap …) to size from a decoded image.")
|
|
977
1392
|
(key :name format :type texture-format
|
|
978
1393
|
:description "Texel format of the texture.")
|
|
979
1394
|
(key :name usage :type texture-usage-list
|
|
980
1395
|
:description "Allowed texture usages (at least one).")
|
|
981
|
-
(key :name sample-count :type
|
|
1396
|
+
(key :name sample-count :type u32 :optional true
|
|
982
1397
|
:description "Samples per texel: 1 (default) or 4 (MSAA). >1 requires render-attachment usage and a resolve-target on the pass.")
|
|
983
1398
|
(key :name dimension :type texture-dimension :optional true
|
|
984
|
-
:description "Texture dimensionality:
|
|
985
|
-
(key :name depth-or-array-layers :type subresource-count :optional true
|
|
986
|
-
:description "GPUExtent3D depthOrArrayLayers: slice count of a 3d texture or layer count of a 2d array (default 1).")
|
|
1399
|
+
:description "Texture dimensionality: 1d, 2d (default), or 3d. A 3d texture needs a third :size element; sampling 1d/3d/array textures needs a matching texture view.")
|
|
987
1400
|
(key :name mip-level-count :type subresource-count :optional true
|
|
988
1401
|
:description "GPUTextureDescriptor.mipLevelCount — number of mip levels to allocate (default 1). Levels beyond what's written stay uninitialized until generated.")
|
|
989
1402
|
(key :name pool :type pool-size :optional true
|
|
@@ -1000,8 +1413,8 @@
|
|
|
1000
1413
|
(key :name name :type symbol)
|
|
1001
1414
|
(key :name texture :type texture-ref
|
|
1002
1415
|
:description "Source texture this view aliases.")
|
|
1003
|
-
(key :name
|
|
1004
|
-
:description "How the view is addressed:
|
|
1416
|
+
(key :name dimension :type view-dimension :optional true
|
|
1417
|
+
:description "How the view is addressed (GPUTextureViewDescriptor.dimension): 1d, 2d, 2d-array, cube, cube-array or 3d. Must match the WGSL binding (texture_2d_array, texture_3d, …). Default: inferred from the texture.")
|
|
1005
1418
|
(key :name aspect :type texture-aspect :optional true
|
|
1006
1419
|
:description "Which aspect(s) of a depth/stencil texture the view exposes (default all).")
|
|
1007
1420
|
(key :name base-mip-level :type subresource-index :optional true
|
|
@@ -1021,20 +1434,20 @@
|
|
|
1021
1434
|
indexed shape's (teapot/dragon) index data — avoids a synthetic
|
|
1022
1435
|
`_indices` data symbol the SJON cross-ref validator can't resolve."
|
|
1023
1436
|
(key :name name :type symbol)
|
|
1024
|
-
(key :name size :type byte-
|
|
1025
|
-
:description "Size in bytes: an integer, a bounded expression like (* NUM 4 4), or a (
|
|
1437
|
+
(key :name size :type byte-count :optional true
|
|
1438
|
+
:description "Size in bytes: an integer, a bounded expression like (* NUM 4 4), or a bare (define …) name. Optional only when :data, :index-of or :file supplies the size instead.")
|
|
1026
1439
|
(key :name usage :type usage-list
|
|
1027
|
-
:description "Allowed buffer usages (at least one).")
|
|
1440
|
+
:description "Allowed buffer usages (at least one). A mappable buffer is host memory the GPU may only copy in or out of: map-read pairs with copy-dst, map-write with copy-src, and neither combines with anything else.")
|
|
1028
1441
|
(key :name pool :type pool-size :optional true
|
|
1029
1442
|
:description "Create N sequential buffer ids for ping-pong (actual id = base + (frame + offset) % N).")
|
|
1030
|
-
(key :name
|
|
1031
|
-
:description "(data …) whose bytes fill the buffer at creation via mappedAtCreation.")
|
|
1443
|
+
(key :name data :type data-ref :optional true
|
|
1444
|
+
:description "(data …) whose bytes fill the buffer at creation via mappedAtCreation, and size it when :size is absent.")
|
|
1032
1445
|
(key :name index-of :type data-ref :optional true
|
|
1033
|
-
:description "Source size, initial bytes, and index-format (uint16/uint32) from an indexed shape's (teapot/dragon) index companion.")
|
|
1446
|
+
:description "Source size, initial bytes, and index-format (uint16/uint32) from an indexed shape's (teapot/dragon) index companion. Beside :data it wins: the index data sizes and fills the buffer, and :data is only length-checked, never written.")
|
|
1034
1447
|
(key :name index-format :type index-format :optional true
|
|
1035
1448
|
:description "Index format (uint16/uint32) when the buffer is bound as a pass's :index-buffer without an :index-of source (e.g. GPU-generated indices).")
|
|
1036
|
-
(key :name
|
|
1037
|
-
:description "WASM file path (relative to the source file); its l/s/gen exports supply size + initial bytes — size comes from the WASM, not :size. Synthesized by pngine/pass-v1 for `(pass … :
|
|
1449
|
+
(key :name file :type file-path :optional true
|
|
1450
|
+
:description "WASM file path (relative to the source file); its l/s/gen exports supply size + initial bytes — size comes from the WASM, not :size. Synthesized by pngine/pass-v1 for `(pass … :file …)` buffers."))
|
|
1038
1451
|
|
|
1039
1452
|
; Emitter packs a [type:u8][count:u16-LE] descriptor blob → create_query_set.
|
|
1040
1453
|
(form :name query-set
|
|
@@ -1042,11 +1455,12 @@
|
|
|
1042
1455
|
(key :name name :type symbol)
|
|
1043
1456
|
(key :name type :type query-type
|
|
1044
1457
|
:description "What each query measures: occlusion or timestamp.")
|
|
1045
|
-
(key :name count :type count
|
|
1046
|
-
:description "Number of queries in the set (
|
|
1458
|
+
(key :name count :type query-count
|
|
1459
|
+
:description "Number of queries in the set, 1 to 4096 (the createQuerySet bound)."))
|
|
1047
1460
|
|
|
1048
1461
|
(form :name queue
|
|
1049
|
-
:description "Queue
|
|
1462
|
+
:description "Queue actions (write-buffer, copy-buffer-to-buffer, copy-texture-to-texture,
|
|
1463
|
+
copy-external-image-to-texture, resolve-query-set) run in order by the
|
|
1050
1464
|
frames that reference it."
|
|
1051
1465
|
:positional queue-action
|
|
1052
1466
|
(key :name name :type symbol))
|
|
@@ -1055,68 +1469,91 @@
|
|
|
1055
1469
|
:description "Queue op: write bytes into a buffer before/within a frame (GPUQueue.writeBuffer)."
|
|
1056
1470
|
(key :name buffer :type buffer-ref
|
|
1057
1471
|
:description "Destination buffer (needs copy-dst usage).")
|
|
1058
|
-
(key :name offset :type byte-count :default 0
|
|
1472
|
+
(key :name offset :type byte-count-4-aligned :default 0
|
|
1059
1473
|
:description "Byte offset into the destination (WebGPU requires a multiple of 4).")
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
(alt :keys [data])
|
|
1067
|
-
(alt :keys [data-from-wasm])))
|
|
1474
|
+
; One key for one member. `:data-from-wasm` was a second spelling of
|
|
1475
|
+
; the same slot, distinguished only by which kind of name it took — so the
|
|
1476
|
+
; document said twice what the widened union now says once, and the
|
|
1477
|
+
; exclusive-group existed to stop an author saying both.
|
|
1478
|
+
(key :name data :type write-buffer-source
|
|
1479
|
+
:description "Source: a (data …) ref, a (wasm-call …) whose result is written each frame, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pointer-inputs (48B)."))
|
|
1068
1480
|
|
|
1481
|
+
; Both ends of a copy are dictionaries in the IDL
|
|
1482
|
+
; (GPUTexelCopyTextureInfo / GPUCopyExternalImageSourceInfo), so they are
|
|
1483
|
+
; child forms, and their members are that form's keys: `:mip-level` and
|
|
1484
|
+
; `:origin` describe the DESTINATION subresource, not the copy. The flat
|
|
1485
|
+
; `:source X :texture Y` spelling is retired rather than kept as a second one.
|
|
1486
|
+
; Their heads are SLOT-LOCAL: `source` carries a texture under one copy
|
|
1487
|
+
; and an image under the other, and neither is a global form.
|
|
1488
|
+
;
|
|
1489
|
+
; There is no `:size`: pngine copies the whole source, which is what both
|
|
1490
|
+
; runtimes do today. A key the bytecode cannot carry would validate and be
|
|
1491
|
+
; dropped in silence — the texture→texture opcode encodes the two texture
|
|
1492
|
+
; ids and nothing else (`wire_schema` L_2V); the external-image opcode encodes
|
|
1493
|
+
; the bitmap id, the texture id and the destination mip level + origin
|
|
1494
|
+
; (L_COPY_EXT_IMG). Neither carries a size. It arrives when the opcode does.
|
|
1069
1495
|
(form :name copy-texture-to-texture
|
|
1070
1496
|
:description "Queue op: GPU texture→texture copy. context-current-texture names the canvas; otherwise a (texture …) name."
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
:
|
|
1497
|
+
:positional copy-endpoints-section
|
|
1498
|
+
(form :name source
|
|
1499
|
+
:description "Copy source (GPUTexelCopyTextureInfo)."
|
|
1500
|
+
(key :name texture :type attachment-view
|
|
1501
|
+
:description "Source texture: context-current-texture or a (texture …) name."))
|
|
1502
|
+
(form :name destination
|
|
1503
|
+
:description "Copy destination (GPUTexelCopyTextureInfo)."
|
|
1504
|
+
(key :name texture :type attachment-view
|
|
1505
|
+
:description "Destination texture: context-current-texture or a (texture …) name.")))
|
|
1075
1506
|
|
|
1076
1507
|
(form :name copy-external-image-to-texture
|
|
1077
1508
|
:description "Queue op: upload a decoded image (image-bitmap) into a texture. mip-level / origin default to 0 per the WebGPU spec."
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
:
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1509
|
+
:positional copy-endpoints-section
|
|
1510
|
+
(form :name source
|
|
1511
|
+
:description "Copy source (GPUCopyExternalImageSourceInfo)."
|
|
1512
|
+
(key :name image :type image-bitmap-ref
|
|
1513
|
+
:description "The decoded (image-bitmap …) to upload."))
|
|
1514
|
+
(form :name destination
|
|
1515
|
+
:description "Copy destination (GPUCopyExternalImageDestInfo)."
|
|
1516
|
+
(key :name texture :type texture-ref
|
|
1517
|
+
:description "Destination texture (needs copy-dst usage).")
|
|
1518
|
+
(key :name mip-level :type subresource-index :optional true
|
|
1519
|
+
:description "Destination mip level (default 0).")
|
|
1520
|
+
(key :name origin :type origin3 :optional true
|
|
1521
|
+
:description "Destination origin [x y z] in texels (default [0 0 0]; z selects the array layer / depth slice).")))
|
|
1086
1522
|
|
|
1087
1523
|
(form :name resolve-query-set
|
|
1088
1524
|
:description "Queue op: copy resolved query results from a query set into a buffer (GPUCommandEncoder.resolveQuerySet)."
|
|
1089
1525
|
(key :name query-set :type query-set-ref
|
|
1090
1526
|
:description "The query set to resolve.")
|
|
1091
|
-
(key :name first-query :type
|
|
1527
|
+
(key :name first-query :type u32 :default 0
|
|
1092
1528
|
:description "Index of the first query to resolve.")
|
|
1093
|
-
(key :name query-count :type
|
|
1529
|
+
(key :name query-count :type u32
|
|
1094
1530
|
:description "Number of queries to resolve; each resolves to 8 bytes.")
|
|
1095
1531
|
(key :name destination :type buffer-ref
|
|
1096
1532
|
:description "Destination buffer; must have query-resolve usage.")
|
|
1097
|
-
(key :name destination-offset :type byte-count :default 0
|
|
1533
|
+
(key :name destination-offset :type byte-count-256-aligned :default 0
|
|
1098
1534
|
:description "Byte offset into the destination (WebGPU requires a multiple of 256)."))
|
|
1099
1535
|
|
|
1100
1536
|
(form :name copy-buffer-to-buffer
|
|
1101
1537
|
:description "Queue op: GPU buffer→buffer copy (e.g. resolved queries → a map-read readback buffer)."
|
|
1102
1538
|
(key :name source :type buffer-ref
|
|
1103
1539
|
:description "Source buffer (needs copy-src usage).")
|
|
1104
|
-
(key :name source-offset :type byte-count :default 0
|
|
1540
|
+
(key :name source-offset :type byte-count-4-aligned :default 0
|
|
1105
1541
|
:description "Byte offset into the source (multiple of 4).")
|
|
1106
1542
|
(key :name destination :type buffer-ref
|
|
1107
1543
|
:description "Destination buffer (needs copy-dst usage).")
|
|
1108
|
-
(key :name destination-offset :type byte-count :default 0
|
|
1544
|
+
(key :name destination-offset :type byte-count-4-aligned :default 0
|
|
1109
1545
|
:description "Byte offset into the destination (multiple of 4).")
|
|
1110
|
-
(key :name size :type byte-count
|
|
1546
|
+
(key :name size :type byte-count-4-aligned
|
|
1111
1547
|
:description "Bytes to copy (multiple of 4)."))
|
|
1112
1548
|
|
|
1113
|
-
; The legacy nests `module={ url=… }`; SJON flattens to `:
|
|
1114
|
-
;
|
|
1549
|
+
; The legacy nests `module={ url=… }`; SJON flattens to `:file` — `url`
|
|
1550
|
+
; promised fetching the descriptor never did, and the kind is `file-path`,
|
|
1551
|
+
; "relative to the document".
|
|
1115
1552
|
(form :name wasm-call
|
|
1116
|
-
:description "A runtime WASM call: load the module at :
|
|
1553
|
+
:description "A runtime WASM call: load the module at :file, call :func with :args each frame; a (write-buffer :data <name>) writes the result into a buffer."
|
|
1117
1554
|
(key :name name :type symbol)
|
|
1118
|
-
(key :name
|
|
1119
|
-
:description "WASM file path relative to the source file (modules deduped by
|
|
1555
|
+
(key :name file :type file-path
|
|
1556
|
+
:description "WASM file path relative to the source file (modules deduped by path).")
|
|
1120
1557
|
(key :name func :type symbol
|
|
1121
1558
|
:description "Exported function to call at frame time.")
|
|
1122
1559
|
(key :name returns :type string
|
|
@@ -1126,30 +1563,32 @@
|
|
|
1126
1563
|
|
|
1127
1564
|
(form :name bind-group
|
|
1128
1565
|
:description "Bind group. `pool` + per-entry `ping-pong` drive ping-pong. The
|
|
1129
|
-
layout is a pipeline's auto-layout
|
|
1130
|
-
(bind-group-layout …)
|
|
1131
|
-
(schema-enforced via the exclusive-group below)."
|
|
1566
|
+
layout is a pipeline's auto-layout or an explicit
|
|
1567
|
+
(bind-group-layout …) — one required :layout key naming either."
|
|
1132
1568
|
:positional bind-entry-item
|
|
1133
1569
|
(key :name name :type symbol)
|
|
1134
|
-
(key :name layout
|
|
1135
|
-
:description "The
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1570
|
+
(key :name layout :type bind-group-layout-spec
|
|
1571
|
+
:description "The layout this group is built against: a pipeline (its auto-derived layout) or an explicit (bind-group-layout …).")
|
|
1572
|
+
; `:group` is `@group(N)` in the WGSL — the word WebGPU and WGSL both use,
|
|
1573
|
+
; and it pairs with the entries' `:binding` the way the shader spells them.
|
|
1574
|
+
; It was `:layout-index`, which named the mechanism rather than the
|
|
1575
|
+
; thing. Meaningful for the PIPELINE arm only: that arm resolves the layout
|
|
1576
|
+
; as `pipeline.getBindGroupLayout(:group)`, while an explicit
|
|
1577
|
+
; (bind-group-layout …) IS the layout and the index selects nothing. The
|
|
1578
|
+
; emitter warns rather than rejects — the value is still encoded, so a
|
|
1579
|
+
; document that states it keeps compiling byte-identically.
|
|
1580
|
+
(key :name group :type binding-index :default 0
|
|
1581
|
+
:description "Which @group index of the pipeline's layout this group binds (spec baseline < 4). Ignored when :layout names an explicit (bind-group-layout …).")
|
|
1140
1582
|
(key :name pool :type pool-size :optional true
|
|
1141
1583
|
:description "Create N sequential bind-group ids for ping-pong selection.")
|
|
1142
|
-
;
|
|
1143
|
-
; (bind-group-layout …). Declarative replacement for the emit-time check.
|
|
1144
|
-
(exclusive-group :cardinality exactly-one
|
|
1145
|
-
(alt :keys [layout-pipeline])
|
|
1146
|
-
(alt :keys [bind-group-layout]))
|
|
1147
|
-
; Slot-local (F8) entry form: `(entry :binding N :buffer|:sampler|:texture R)`.
|
|
1584
|
+
; Slot-local entry form: `(entry :binding N :buffer|:sampler|:texture|:texture-view R)`.
|
|
1148
1585
|
; Resolved LOCAL-FIRST under bind-group, so this `entry` is distinct from the
|
|
1149
|
-
;
|
|
1586
|
+
; bind-group-layout's entry. (A global `entry` stand-in used to sit above
|
|
1587
|
+
; this form so `:lowering :produces` could name the head; SJON since 1.5 makes
|
|
1588
|
+
; `:produces` resolve slot-local heads and the stand-in is gone.)
|
|
1150
1589
|
(form :name entry
|
|
1151
|
-
:description "One bind-group entry: binding → buffer | sampler | texture resource
|
|
1152
|
-
(exactly one of :buffer/:sampler/:texture, schema-enforced)."
|
|
1590
|
+
:description "One bind-group entry: binding → buffer | sampler | texture | texture-view resource
|
|
1591
|
+
(exactly one of :buffer/:sampler/:texture/:texture-view, schema-enforced)."
|
|
1153
1592
|
(key :name binding :type binding-index
|
|
1154
1593
|
:description "Binding slot matching @binding(N) in the WGSL.")
|
|
1155
1594
|
(key :name buffer :type buffer-ref :optional true
|
|
@@ -1160,9 +1599,11 @@
|
|
|
1160
1599
|
:description "Bind a (texture …) at this slot via its default 2d view.")
|
|
1161
1600
|
(key :name texture-view :type texture-view-ref :optional true
|
|
1162
1601
|
:description "Bind an explicit (texture-view …) at this slot — for 1d/3d/array/cube sampling.")
|
|
1163
|
-
(
|
|
1602
|
+
; `:requires [buffer]` (SJON 1.2.0): a slice on a sampler/texture entry is a
|
|
1603
|
+
; located `dependent_key_missing` at validation, not an emitter reject.
|
|
1604
|
+
(key :name offset :type byte-count :optional true :requires [buffer]
|
|
1164
1605
|
:description "GPUBufferBinding.offset — byte offset of the bound slice into :buffer (default 0; requires :buffer; must lie inside the declared buffer size — checked at compile time). Dynamic-offset alignment rules apply (uniform 256, storage 256 by default).")
|
|
1165
|
-
(key :name size :type byte-count :optional true
|
|
1606
|
+
(key :name size :type byte-count :optional true :requires [buffer]
|
|
1166
1607
|
:description "GPUBufferBinding.size — byte size of the bound slice (default: the rest of :buffer from :offset; requires :buffer; :offset + :size must fit the declared buffer size — checked at compile time).")
|
|
1167
1608
|
(key :name ping-pong :type binding-index :optional true
|
|
1168
1609
|
:description "Pool offset for this entry: actual id = base + (frame + offset) % pool.")
|
|
@@ -1173,31 +1614,14 @@
|
|
|
1173
1614
|
(alt :keys [texture])
|
|
1174
1615
|
(alt :keys [texture-view]))))
|
|
1175
1616
|
|
|
1176
|
-
; Head-resolution target for the `(bind-group-layout entry (storage-texture …))`
|
|
1177
|
-
; slot-local form below. WebGPU has no standalone storage-texture resource (a
|
|
1178
|
-
; storage texture is a (texture … :usage [storage-binding])); this global form
|
|
1179
|
-
; exists only so the `bgl-resource` head-set resolves `storage-texture` to a form,
|
|
1180
|
-
; exactly as `buffer`/`sampler`/`texture` resolve to their global resource forms.
|
|
1181
|
-
; It has no emitter phase — never walked at top level — so the real fields live in
|
|
1182
|
-
; the slot-local form; this one just satisfies the head lookup.
|
|
1183
|
-
(form :name storage-texture
|
|
1184
|
-
:description "Storage-texture layout resource (authored inside (bind-group-layout entry …), not at top level)."
|
|
1185
|
-
(key :name name :type symbol :optional true)
|
|
1186
|
-
(key :name format :type texture-format :optional true
|
|
1187
|
-
:description "Texel format of the storage texture.")
|
|
1188
|
-
(key :name access :type storage-texture-access :optional true
|
|
1189
|
-
:description "Access mode (default write-only).")
|
|
1190
|
-
(key :name view-dimension :type view-dimension :optional true
|
|
1191
|
-
:description "View dimension (default 2d)."))
|
|
1192
|
-
|
|
1193
1617
|
; ---- explicit bind-group-layout (uniform_access) ----
|
|
1194
1618
|
; → create_bind_group_layout (opcode 0x06), emitted between samplers and
|
|
1195
1619
|
; pipelines (the legacy phase position). Buffer, sampler, texture, and storage-
|
|
1196
|
-
; texture bindings are modeled. Entries and their resource are SLOT-LOCAL
|
|
1197
|
-
;
|
|
1620
|
+
; texture bindings are modeled. Entries and their resource are SLOT-LOCAL
|
|
1621
|
+
; forms: `(entry …)` and its nested `(buffer|sampler|texture|storage-texture …)`,
|
|
1198
1622
|
; resolved local-first so the natural names don't collide with the global forms.
|
|
1199
1623
|
(form :name bind-group-layout
|
|
1200
|
-
:description "Explicit binding layout (per-entry visibility + resource type)
|
|
1624
|
+
:description "Explicit binding layout (per-entry visibility + resource type) named by a (bind-group … :layout …) instead of a pipeline's auto-layout."
|
|
1201
1625
|
:positional bgl-entry-item
|
|
1202
1626
|
(key :name name :type symbol)
|
|
1203
1627
|
(form :name entry
|
|
@@ -1207,13 +1631,13 @@
|
|
|
1207
1631
|
:description "Binding slot matching @binding(N) in the WGSL.")
|
|
1208
1632
|
(key :name visibility :type visibility-list
|
|
1209
1633
|
:description "Shader stages that may access this binding (ORed into the WebGPU mask: vertex 0x1, fragment 0x2, compute 0x4).")
|
|
1210
|
-
; Nested slot-local
|
|
1634
|
+
; Nested slot-local resource form: `(buffer :type T)`. Resolved
|
|
1211
1635
|
; local-first under the layout entry, distinct from the global `buffer`.
|
|
1212
1636
|
(form :name buffer
|
|
1213
1637
|
:description "Buffer resource of a layout entry."
|
|
1214
|
-
(key :name type :type buffer-binding-type
|
|
1215
|
-
:description "How the buffer is exposed to WGSL: uniform, storage, or read-only-storage."))
|
|
1216
|
-
; Non-buffer resources (
|
|
1638
|
+
(key :name type :type buffer-binding-type :optional true
|
|
1639
|
+
:description "How the buffer is exposed to WGSL: uniform, storage, or read-only-storage (WebGPU default: uniform)."))
|
|
1640
|
+
; Non-buffer resources (slot-local, like buffer). Their WebGPU-shape sub-
|
|
1217
1641
|
; objects flow verbatim through gpu.js/--html; native's create_bind_group_layout
|
|
1218
1642
|
; parser reads each field string-for-string.
|
|
1219
1643
|
(form :name sampler
|
|
@@ -1225,7 +1649,7 @@
|
|
|
1225
1649
|
(key :name sample-type :type texture-sample-type :optional true
|
|
1226
1650
|
:description "Sample type of the bound texture (default float).")
|
|
1227
1651
|
(key :name view-dimension :type view-dimension :optional true
|
|
1228
|
-
:description "View dimension:
|
|
1652
|
+
:description "View dimension: 1d, 2d, 2d-array, cube, cube-array or 3d (default 2d).")
|
|
1229
1653
|
(key :name multisampled :type boolean :optional true
|
|
1230
1654
|
:description "Whether the binding is a multisampled texture (default false)."))
|
|
1231
1655
|
(form :name storage-texture
|
|
@@ -1240,24 +1664,24 @@
|
|
|
1240
1664
|
; ---- explicit pipeline-layout ----
|
|
1241
1665
|
; → create_pipeline_layout (opcode 0x07), emitted between bind-group-layouts and
|
|
1242
1666
|
; pipelines. Composes N (bind-group-layout …) into a GPUPipelineLayout that a
|
|
1243
|
-
; (render-pipeline …)/(compute-pipeline …)
|
|
1244
|
-
;
|
|
1667
|
+
; (render-pipeline …)/(compute-pipeline …) names in `:layout` instead of
|
|
1668
|
+
; `auto` (deriving from the WGSL). This is the only way to bind @group 0..N to
|
|
1245
1669
|
; DIFFERENT explicit layouts (auto derives a single implicit layout per pipeline).
|
|
1246
1670
|
(form :name pipeline-layout
|
|
1247
|
-
:description "Explicit pipeline layout: an ordered list of (bind-group-layout …) at @group 0..N.
|
|
1671
|
+
:description "Explicit pipeline layout: an ordered list of (bind-group-layout …) at @group 0..N. Named by a pipeline's :layout key in place of auto."
|
|
1248
1672
|
(key :name name :type symbol)
|
|
1249
1673
|
(key :name bind-group-layouts :type bind-group-layout-ref-list
|
|
1250
1674
|
:description "The (bind-group-layout …) forms at @group 0, 1, … in order."))
|
|
1251
1675
|
|
|
1252
1676
|
(form :name sampler
|
|
1253
|
-
:description "GPU sampler.
|
|
1677
|
+
:description "GPU sampler. Defaults match GPUSamplerDescriptor: filters nearest, address-mode clamp-to-edge."
|
|
1254
1678
|
(key :name name :type symbol)
|
|
1255
|
-
(key :name mag-filter :type filter-mode :default
|
|
1256
|
-
:description "Magnification filter — sampling when one texel covers many pixels.
|
|
1257
|
-
(key :name min-filter :type filter-mode :default
|
|
1258
|
-
:description "Minification filter — sampling when many texels cover one pixel.
|
|
1679
|
+
(key :name mag-filter :type filter-mode :default nearest
|
|
1680
|
+
:description "Magnification filter — sampling when one texel covers many pixels. Default nearest, as GPUSamplerDescriptor.magFilter; write :mag-filter linear for smoothing.")
|
|
1681
|
+
(key :name min-filter :type filter-mode :default nearest
|
|
1682
|
+
:description "Minification filter — sampling when many texels cover one pixel. Default nearest, as GPUSamplerDescriptor.minFilter; write :min-filter linear for smoothing.")
|
|
1259
1683
|
(key :name address-mode :type address-mode :optional true
|
|
1260
|
-
:description "Addressing for texture coordinates outside [0,1], applied to all three axes
|
|
1684
|
+
:description "Addressing for texture coordinates outside [0,1], applied to all three axes. A PNGine shorthand for the IDL's three separate keys, and like them it defaults to clamp-to-edge. Per-axis :address-mode-u/v/w override it.")
|
|
1261
1685
|
(key :name address-mode-u :type address-mode :optional true
|
|
1262
1686
|
:description "Addressing for the U (S) axis; overrides :address-mode for this axis.")
|
|
1263
1687
|
(key :name address-mode-v :type address-mode :optional true
|
|
@@ -1265,12 +1689,12 @@
|
|
|
1265
1689
|
(key :name address-mode-w :type address-mode :optional true
|
|
1266
1690
|
:description "Addressing for the W (R) axis; overrides :address-mode for this axis (3D / cube sampling).")
|
|
1267
1691
|
(key :name mipmap-filter :type filter-mode :optional true
|
|
1268
|
-
:description "Filter applied between mip levels (only visible with a mipmapped texture).")
|
|
1692
|
+
:description "Filter applied between mip levels (only visible with a mipmapped texture). Default nearest, as GPUSamplerDescriptor.mipmapFilter; :max-anisotropy above 1 requires linear here as well as on :mag-filter and :min-filter.")
|
|
1269
1693
|
(key :name lod-min-clamp :type lod-clamp :optional true
|
|
1270
1694
|
:description "Minimum mip level of detail the sampler will use (default 0).")
|
|
1271
1695
|
(key :name lod-max-clamp :type lod-clamp :optional true
|
|
1272
1696
|
:description "Maximum mip level of detail the sampler will use (default 32).")
|
|
1273
|
-
(key :name max-anisotropy :type anisotropy
|
|
1697
|
+
(key :name max-anisotropy :type anisotropy :optional true
|
|
1274
1698
|
:description "Maximum anisotropy for filtering; values > 1 require linear mag/min/mipmap filters.")
|
|
1275
1699
|
(key :name compare :type compare-function :optional true
|
|
1276
1700
|
:description "Comparison function — makes this a comparison sampler (e.g. depth shadow sampling)."))
|
|
@@ -1279,38 +1703,48 @@
|
|
|
1279
1703
|
; (via EmittedForm positional children), so the render-pipeline descriptor has
|
|
1280
1704
|
; one path.
|
|
1281
1705
|
(form :name render-pipeline
|
|
1282
|
-
:description "GPU render pipeline. Positional (
|
|
1706
|
+
:description "GPU render pipeline. Positional (vertex …)(fragment …)(primitive …)(depth-stencil …)(multisample …) sections mirror GPURenderPipelineDescriptor."
|
|
1283
1707
|
:positional pipeline-section
|
|
1284
1708
|
(key :name name :type symbol)
|
|
1285
|
-
|
|
1286
|
-
|
|
1709
|
+
; GPUPipelineDescriptorBase.layout: required, and ONE member — see
|
|
1710
|
+
; `pipeline-layout-spec`.
|
|
1711
|
+
(key :name layout :type pipeline-layout-spec
|
|
1712
|
+
:description "auto to derive the bind-group layouts from the WGSL, or a declared (pipeline-layout …)."))
|
|
1287
1713
|
|
|
1288
|
-
; compute-pipeline is flat (no positional sections) — natural, not a workaround:
|
|
1289
|
-
; a compute pipeline is just module + entry, with no vertex/fragment stages to
|
|
1290
|
-
; nest. The `pngine/init-v1` hook emits one; the flat kvpair shape is correct
|
|
1291
|
-
; as-is (the positional-slot limitation it once worked around was lifted in SJON
|
|
1292
|
-
; 2026-06, but compute-pipeline never needed positional children anyway).
|
|
1293
1714
|
(form :name compute-pipeline
|
|
1294
|
-
:description "GPU compute pipeline:
|
|
1715
|
+
:description "GPU compute pipeline: one positional (compute …) stage naming the WGSL module and its @compute entry point."
|
|
1295
1716
|
:positional compute-pipeline-section
|
|
1296
1717
|
(key :name name :type symbol)
|
|
1297
|
-
(key :name
|
|
1298
|
-
:description "
|
|
1299
|
-
(key :name entry :type entry-point :optional true
|
|
1300
|
-
:description "Entry-point function name (defaults to the module's sole @compute fn).")
|
|
1301
|
-
(key :name pipeline-layout :type pipeline-layout-ref :optional true
|
|
1302
|
-
:description "An explicit (pipeline-layout …) instead of auto-deriving the layout from the WGSL."))
|
|
1718
|
+
(key :name layout :type pipeline-layout-spec
|
|
1719
|
+
:description "auto to derive the bind-group layouts from the WGSL, or a declared (pipeline-layout …)."))
|
|
1303
1720
|
|
|
1304
|
-
; ----
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1721
|
+
; ---- pipeline stage sub-forms (source-authored + hook-emitted) ----
|
|
1722
|
+
; All three are GPUProgrammableStage: a required module, an optional entry
|
|
1723
|
+
; point, and per-stage `(constant …)` overrides. `(module …)`/`(entry …)` were
|
|
1724
|
+
; positional atom forms until this cut — a scalar member of a dictionary is a
|
|
1725
|
+
; key, and spelling it as a form meant two global heads existed for no
|
|
1726
|
+
; reason but the grammar.
|
|
1308
1727
|
(form :name vertex
|
|
1309
|
-
:description "Vertex stage:
|
|
1310
|
-
:positional vertex-section
|
|
1728
|
+
:description "Vertex stage (GPUVertexState): the module + entry point, one (vertex-buffer …) per bound vertex slot, and (constant …) overrides."
|
|
1729
|
+
:positional vertex-section
|
|
1730
|
+
(key :name module :type module-ref
|
|
1731
|
+
:description "The (shader-module …) holding the @vertex entry.")
|
|
1732
|
+
(key :name entry :type entry-point :optional true
|
|
1733
|
+
:description "Entry-point function name (defaults to the module's sole @vertex fn)."))
|
|
1311
1734
|
(form :name fragment
|
|
1312
|
-
:description "Fragment stage:
|
|
1313
|
-
:positional fragment-section
|
|
1735
|
+
:description "Fragment stage (GPUFragmentState): the module + entry point, one (target …) per color attachment, and (constant …) overrides."
|
|
1736
|
+
:positional fragment-section
|
|
1737
|
+
(key :name module :type module-ref
|
|
1738
|
+
:description "The (shader-module …) holding the @fragment entry.")
|
|
1739
|
+
(key :name entry :type entry-point :optional true
|
|
1740
|
+
:description "Entry-point function name (defaults to the module's sole @fragment fn)."))
|
|
1741
|
+
(form :name compute
|
|
1742
|
+
:description "Compute stage (GPUProgrammableStage): the module + @compute entry point of a (compute-pipeline …), and (constant …) overrides."
|
|
1743
|
+
:positional compute-section
|
|
1744
|
+
(key :name module :type module-ref
|
|
1745
|
+
:description "The (shader-module …) holding the @compute entry.")
|
|
1746
|
+
(key :name entry :type entry-point :optional true
|
|
1747
|
+
:description "Entry-point function name (defaults to the module's sole @compute fn)."))
|
|
1314
1748
|
; Authored per STAGE, mirroring WebGPU's GPUProgrammableStage.constants and
|
|
1315
1749
|
; the per-entry-point reflection — but RESOLVED per module, because pngine
|
|
1316
1750
|
; specialises the shader text at compile time instead of passing a constants
|
|
@@ -1320,39 +1754,68 @@
|
|
|
1320
1754
|
:description "Specialise a WGSL `override` with a compile-time value. The declaration becomes a `const` in the shipped shader, so the value participates in const-folding and dead-code elimination — an unused branch leaves the payload entirely."
|
|
1321
1755
|
(key :name name :type override-name
|
|
1322
1756
|
:description "The WGSL `override` identifier this value is for.")
|
|
1323
|
-
(key :name value :type override-
|
|
1757
|
+
(key :name value :type override-number
|
|
1324
1758
|
:description "The value. Must fit the override's declared WGSL type: a fractional value for a u32/i32 override, or anything but 0/1 for a bool, is rejected."))
|
|
1325
1759
|
(form :name primitive
|
|
1326
|
-
:description "Primitive assembly state
|
|
1327
|
-
|
|
1760
|
+
:description "Primitive assembly state (GPUPrimitiveState). Mirror the source: omit the whole form when unauthored."
|
|
1761
|
+
; `:default triangle-list` is REQUIRED here, and it is the one default in
|
|
1762
|
+
; this file the emitter deliberately does not bake. A `(variant …)` needs a
|
|
1763
|
+
; discriminant it can resolve — SJON answers `missing_discriminant_key` when
|
|
1764
|
+
; the key is neither authored nor defaulted — while a default is MATERIALIZED
|
|
1765
|
+
; into the effective view, which the defaults policy at the top of this file
|
|
1766
|
+
; says the emitter bakes. Both hold: the schema defaults the key so the
|
|
1767
|
+
; variant below resolves, and `appendPrimitive` emits `topology` only when
|
|
1768
|
+
; `authorNode` says the author wrote it, so a document that omits it still
|
|
1769
|
+
; ships no topology (measured: +27 bytes on the one corpus document that
|
|
1770
|
+
; omits it). The value is WebGPU's own default, so the two readings agree —
|
|
1771
|
+
; a list topology, which reads no strip index format.
|
|
1772
|
+
;
|
|
1773
|
+
; `:strip-index-format` is the conditional key `(variant …)` exists for, and
|
|
1774
|
+
; SJON's manifest spec uses this exact rule as its worked example. It could
|
|
1775
|
+
; not be written until SJON 1.5: WebGPU reads stripIndexFormat for TWO
|
|
1776
|
+
; topologies (triangle-strip and line-strip) and a key belonged to one
|
|
1777
|
+
; variant (`variant_key_collision`). `(variant :when [a b])` is that fix,
|
|
1778
|
+
; so the rule is the schema's now and the emitter's
|
|
1779
|
+
; `checkStripIndexFormat` is gone. Under a list topology the key does not
|
|
1780
|
+
; exist: `unknown_key`, located, at validation.
|
|
1781
|
+
:discriminant topology
|
|
1782
|
+
(key :name topology :type primitive-topology :optional true :default triangle-list
|
|
1783
|
+
:description "How vertices assemble into primitives (WebGPU default: triangle-list). Selects whether :strip-index-format exists: WebGPU reads a strip index format only for triangle-strip and line-strip.")
|
|
1328
1784
|
(key :name cull-mode :type cull-mode :optional true
|
|
1329
1785
|
:description "Which faces are discarded (WebGPU default: none).")
|
|
1330
1786
|
(key :name front-face :type front-face :optional true
|
|
1331
1787
|
:description "Winding that counts as front-facing (WebGPU default: ccw).")
|
|
1332
|
-
(key :name strip-index-format :type index-format :optional true
|
|
1333
|
-
:description "Index byte-width (uint16/uint32) for indexed strip draws; WebGPU requires it only when draw-indexed uses a strip topology (triangle-strip/line-strip).")
|
|
1334
1788
|
(key :name unclipped-depth :type boolean :optional true
|
|
1335
|
-
:description "Disable depth clipping (clamp fragments to [0,1] instead of discarding them); needs the depth-clip-control device feature (WebGPU default: false).")
|
|
1336
|
-
|
|
1337
|
-
|
|
1789
|
+
:description "Disable depth clipping (clamp fragments to [0,1] instead of discarding them); needs the depth-clip-control device feature (WebGPU default: false).")
|
|
1790
|
+
(variant :when [triangle-strip line-strip]
|
|
1791
|
+
(key :name strip-index-format :type index-format :optional true
|
|
1792
|
+
:description "Index byte-width (uint16/uint32) for indexed strip draws. WebGPU reads it only under a strip topology, which is why it is declared here and is an unknown key anywhere else; it becomes REQUIRED once a (draw-indexed …) runs this pipeline (that half crosses pipeline and pass, so it stays the emitter's).")))
|
|
1793
|
+
; The emitter emits only authored keys (mirroring the legacy
|
|
1794
|
+
; property-by-property JSON build), but "optional + default-free" is NOT the
|
|
1795
|
+
; rule this form follows any more: `:format` is required, and
|
|
1796
|
+
; `:depth-write-enabled` / `:depth-compare` become required from the format's
|
|
1797
|
+
; aspects, which only the emitter can see.
|
|
1338
1798
|
(form :name depth-stencil
|
|
1339
1799
|
:description "Depth/stencil pipeline state. Positional (stencil-front …)/(stencil-back …) carry per-face stencil state."
|
|
1340
1800
|
:positional depth-stencil-section
|
|
1341
|
-
|
|
1342
|
-
|
|
1801
|
+
; REQUIRED, matching GPUDepthStencilState.format. Every other key here is
|
|
1802
|
+
; genuinely optional; this one only looked optional because the form was
|
|
1803
|
+
; built "optional + default-free by construction" without checking the IDL.
|
|
1804
|
+
(key :name format :type texture-format
|
|
1805
|
+
:description "Format of the depth/stencil attachment this pipeline renders to; a depth or stencil format, never a colour one.")
|
|
1343
1806
|
(key :name depth-write-enabled :type boolean :optional true
|
|
1344
|
-
:description "Whether fragments write their depth value.")
|
|
1807
|
+
:description "Whether fragments write their depth value. Required once :format has a depth aspect (the IDL gives it no default); optional only because a stencil-only pipeline omits it.")
|
|
1345
1808
|
(key :name depth-compare :type compare-function :optional true
|
|
1346
|
-
:description "Comparison the depth test applies (fragment depth vs stored depth).")
|
|
1347
|
-
(key :name depth-bias :type depth-bias-
|
|
1809
|
+
:description "Comparison the depth test applies (fragment depth vs stored depth). Required once the pipeline writes depth, or a stencil face states a :depth-fail-op other than keep.")
|
|
1810
|
+
(key :name depth-bias :type depth-bias-int :optional true
|
|
1348
1811
|
:description "Constant bias added to fragment depth — shadow maps / depth pre-pass (triangles only).")
|
|
1349
|
-
(key :name depth-bias-slope-scale :type depth-bias
|
|
1812
|
+
(key :name depth-bias-slope-scale :type depth-bias :optional true
|
|
1350
1813
|
:description "Bias that scales with the triangle's depth slope (triangles only).")
|
|
1351
|
-
(key :name depth-bias-clamp :type depth-bias
|
|
1814
|
+
(key :name depth-bias-clamp :type depth-bias :optional true
|
|
1352
1815
|
:description "Maximum magnitude of the total depth bias (0 = unclamped).")
|
|
1353
|
-
(key :name stencil-read-mask :type
|
|
1816
|
+
(key :name stencil-read-mask :type mask32 :optional true
|
|
1354
1817
|
:description "Bitmask ANDed with stencil values for tests (spec default 0xFFFFFFFF).")
|
|
1355
|
-
(key :name stencil-write-mask :type
|
|
1818
|
+
(key :name stencil-write-mask :type mask32 :optional true
|
|
1356
1819
|
:description "Bitmask ANDed with stencil writes (spec default 0xFFFFFFFF)."))
|
|
1357
1820
|
; Same key set for front/back; the head selects which face the emitter writes.
|
|
1358
1821
|
(form :name stencil-front
|
|
@@ -1377,28 +1840,16 @@
|
|
|
1377
1840
|
:description "Applied when both stencil and depth tests pass."))
|
|
1378
1841
|
(form :name multisample
|
|
1379
1842
|
:description "Multisample pipeline state (MSAA)."
|
|
1380
|
-
(key :name count :type
|
|
1381
|
-
:description "Samples per pixel: 1 or 4; must match the attachment textures' sample-count.")
|
|
1382
|
-
(key :name mask :type
|
|
1843
|
+
(key :name count :type u32 :optional true
|
|
1844
|
+
:description "Samples per pixel: 1 or 4; must match the attachment textures' sample-count. Absent defers to WebGPU's 1 — a (multisample …) carrying only :mask or :alpha-to-coverage-enabled is legal.")
|
|
1845
|
+
(key :name mask :type mask32 :optional true
|
|
1383
1846
|
:description "Sample coverage bitmask (spec default 0xFFFFFFFF).")
|
|
1384
1847
|
(key :name alpha-to-coverage-enabled :type boolean :optional true
|
|
1385
|
-
:description "Fragment alpha generates the coverage mask
|
|
1386
|
-
(form :name module
|
|
1387
|
-
:description "The (shader-module …) this stage executes."
|
|
1388
|
-
:positional module-ref)
|
|
1389
|
-
(form :name entry
|
|
1390
|
-
:description "Entry-point function name within the stage's module."
|
|
1391
|
-
:positional entry-point)
|
|
1392
|
-
(form :name topology
|
|
1393
|
-
:description "How vertices assemble into primitives (WebGPU default: triangle-list)."
|
|
1394
|
-
:positional primitive-topology)
|
|
1395
|
-
(form :name buffers
|
|
1396
|
-
:description "Vertex input layout: one (vertex-buffer …) per bound vertex buffer slot."
|
|
1397
|
-
:positional buffers-item)
|
|
1848
|
+
:description "Fragment alpha generates the coverage mask. Requires :count above 1, a (fragment …) stage, and a first (target …) whose format has an alpha channel to derive the mask from."))
|
|
1398
1849
|
(form :name vertex-buffer
|
|
1399
1850
|
:description "Layout of one vertex buffer slot: stride + step mode + (attribute …) children."
|
|
1400
1851
|
:positional attribute-item
|
|
1401
|
-
(key :name array-stride :type byte-count
|
|
1852
|
+
(key :name array-stride :type byte-count-4-aligned
|
|
1402
1853
|
:description "Bytes between consecutive elements; multiple of 4 (spec baseline limit 2048).")
|
|
1403
1854
|
(key :name step-mode :type step-mode :optional true
|
|
1404
1855
|
:description "Advance per vertex or per instance (WebGPU default: vertex)."))
|
|
@@ -1410,9 +1861,6 @@
|
|
|
1410
1861
|
:description "Byte offset of the attribute within one element.")
|
|
1411
1862
|
(key :name format :type vertex-format
|
|
1412
1863
|
:description "Wire format of the attribute data."))
|
|
1413
|
-
(form :name targets
|
|
1414
|
-
:description "Color targets of the fragment stage: one (target …) per attachment."
|
|
1415
|
-
:positional targets-item)
|
|
1416
1864
|
(form :name target
|
|
1417
1865
|
:description "One color target: format plus optional (blend …) state and write mask."
|
|
1418
1866
|
:positional target-section
|
|
@@ -1421,32 +1869,32 @@
|
|
|
1421
1869
|
(key :name write-mask :type write-mask :optional true
|
|
1422
1870
|
:description "Channel write mask: bitmask R=1 G=2 B=4 A=8, or all (15; the WebGPU default)."))
|
|
1423
1871
|
(form :name blend
|
|
1424
|
-
:description "Blend state of a color target: (color …) and (alpha …) components."
|
|
1872
|
+
:description "Blend state of a color target: (color …) and (alpha …) components. Only on a blendable target format — never a uint or sint one."
|
|
1425
1873
|
:positional blend-section)
|
|
1426
1874
|
(form :name color
|
|
1427
1875
|
:description "Blend component for RGB: out.rgb = operation(src.rgb * src-factor, dst.rgb * dst-factor)."
|
|
1428
|
-
(key :name src-factor :type blend-factor
|
|
1429
|
-
:description "Multiplier on the fragment's color (WebGPU default: one).")
|
|
1430
|
-
(key :name dst-factor :type blend-factor
|
|
1431
|
-
:description "Multiplier on the attachment's color (WebGPU default: zero).")
|
|
1876
|
+
(key :name src-factor :type blend-factor :optional true
|
|
1877
|
+
:description "Multiplier on the fragment's color (WebGPU default: one). Emitted only when authored.")
|
|
1878
|
+
(key :name dst-factor :type blend-factor :optional true
|
|
1879
|
+
:description "Multiplier on the attachment's color (WebGPU default: zero). Emitted only when authored.")
|
|
1432
1880
|
(key :name operation :type blend-operation :optional true
|
|
1433
1881
|
:description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
|
|
1434
1882
|
(form :name alpha
|
|
1435
1883
|
:description "Blend component for alpha: out.a = operation(src.a * src-factor, dst.a * dst-factor)."
|
|
1436
|
-
(key :name src-factor :type blend-factor
|
|
1437
|
-
:description "Multiplier on the fragment's alpha (WebGPU default: one).")
|
|
1438
|
-
(key :name dst-factor :type blend-factor
|
|
1439
|
-
:description "Multiplier on the attachment's alpha (WebGPU default: zero).")
|
|
1884
|
+
(key :name src-factor :type blend-factor :optional true
|
|
1885
|
+
:description "Multiplier on the fragment's alpha (WebGPU default: one). Emitted only when authored.")
|
|
1886
|
+
(key :name dst-factor :type blend-factor :optional true
|
|
1887
|
+
:description "Multiplier on the attachment's alpha (WebGPU default: zero). Emitted only when authored.")
|
|
1440
1888
|
(key :name operation :type blend-operation :optional true
|
|
1441
1889
|
:description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
|
|
1442
1890
|
|
|
1443
1891
|
; ---- render / compute pass ----
|
|
1444
1892
|
(form :name render-pass
|
|
1445
|
-
:description "GPU render pass: (color-attachment …)/(depth-attachment …) targets, a pipeline, bound resources, and (draw
|
|
1893
|
+
:description "GPU render pass: (color-attachment …)/(depth-stencil-attachment …) targets, a pipeline, bound resources, and its commands — the four draws (draw / draw-indexed / draw-indirect / draw-indexed-indirect), (occlusion-query …) brackets and one (timestamp-writes …). At least one attachment, of either kind — a pass writes somewhere."
|
|
1446
1894
|
:positional render-pass-section
|
|
1447
1895
|
(key :name name :type symbol)
|
|
1448
1896
|
(key :name occlusion-query-set :type query-set-ref :optional true
|
|
1449
|
-
:description "The (query-set :type occlusion) that (occlusion-query …) brackets in this pass write into.")
|
|
1897
|
+
:description "The (query-set :type occlusion) that (occlusion-query …) brackets in this pass write into. Required once the pass holds a bracket; optional only because a pass may hold none.")
|
|
1450
1898
|
(key :name pipeline :type render-pipeline-ref :optional true
|
|
1451
1899
|
:description "The render pipeline this pass draws with. Omit for a pass that only replays :execute-bundles (the bundle records it).")
|
|
1452
1900
|
(key :name vertex-buffers :type buffer-ref-list :optional true
|
|
@@ -1459,7 +1907,7 @@
|
|
|
1459
1907
|
:description "Bind groups set at @group 0..N in order.")
|
|
1460
1908
|
(key :name bind-groups-pool-offsets :type offset-list :optional true
|
|
1461
1909
|
:description "Per-group ping-pong offsets into each group's pool.")
|
|
1462
|
-
(key :name stencil-reference :type
|
|
1910
|
+
(key :name stencil-reference :type u32 :optional true
|
|
1463
1911
|
:description "Reference value used by stencil compare and the replace operation.")
|
|
1464
1912
|
(key :name blend-constant :type blend-constant-color :optional true
|
|
1465
1913
|
:description "[r g b a] blend constant (setBlendConstant); the value the `constant`/`one-minus-constant` blend factors multiply by. Defaults to [0 0 0 0] when unset.")
|
|
@@ -1468,8 +1916,17 @@
|
|
|
1468
1916
|
(key :name scissor-rect :type pixel-rect :optional true
|
|
1469
1917
|
:description "[x y w h] in integer pixels; fragments outside are discarded.")
|
|
1470
1918
|
(key :name execute-bundles :type render-bundle-ref-list :optional true
|
|
1471
|
-
:description "Replay pre-recorded (render-bundle …) forms instead of an inline pipeline/draw."))
|
|
1919
|
+
:description "Replay pre-recorded (render-bundle …) forms instead of an inline pipeline/draw. Each bundle's declared color formats, depth/stencil format and sample count must equal this pass's, which WebGPU derives from its attachments' textures."))
|
|
1472
1920
|
|
|
1921
|
+
; NOT `:discriminant load-op`, though `:clear-value` is exactly the
|
|
1922
|
+
; conditional key `(variant …)` is for (WebGPU IGNORES a clearValue
|
|
1923
|
+
; beside `load`, so a document that states one is stating something inert).
|
|
1924
|
+
; SJON's variant rule is positional — the discriminant kvpair must be written
|
|
1925
|
+
; BEFORE any variant-only key, in both walkers — and the corpus spells
|
|
1926
|
+
; `:clear-value [0 0 0 1] :load-op clear` in all 234 of its colour
|
|
1927
|
+
; attachments. Adopting the variant means a key-ORDER rule inside a form,
|
|
1928
|
+
; which is not something WebGPU has and not something a 1:1 mapping should
|
|
1929
|
+
; invent; the check is the emitter's instead, with the same span.
|
|
1473
1930
|
(form :name color-attachment
|
|
1474
1931
|
:description "One color target of a render pass."
|
|
1475
1932
|
(key :name view :type attachment-view
|
|
@@ -1477,30 +1934,53 @@
|
|
|
1477
1934
|
(key :name resolve-target :type attachment-view :optional true
|
|
1478
1935
|
:description "Receives the resolved single-sample output when :view is multisampled.")
|
|
1479
1936
|
(key :name clear-value :type clear-color :optional true
|
|
1480
|
-
:description "RGBA the attachment is cleared to when load-op is clear (
|
|
1481
|
-
|
|
1937
|
+
:description "RGBA the attachment is cleared to when load-op is clear (WebGPU default: transparent black). Stating one beside `:load-op load` is an error — WebGPU would ignore it.")
|
|
1938
|
+
; REQUIRED, matching GPURenderPassColorAttachment.loadOp/storeOp. WebGPU has
|
|
1939
|
+
; no default for either: a pass that does not say whether it clears or loads
|
|
1940
|
+
; is a pass whose contents depend on what happened to be in the texture, and
|
|
1941
|
+
; the spec makes the author decide. PNGine defaulted them to clear/store,
|
|
1942
|
+
; which is right often enough that the one time it is wrong reads as a
|
|
1943
|
+
; rendering bug.
|
|
1944
|
+
(key :name load-op :type load-op
|
|
1482
1945
|
:description "clear to :clear-value, or load the existing contents.")
|
|
1483
|
-
(key :name store-op :type store-op
|
|
1946
|
+
(key :name store-op :type store-op
|
|
1484
1947
|
:description "store the pass result, or discard it."))
|
|
1485
1948
|
|
|
1486
1949
|
; Non-default load/store ops emit a preceding set_pass_depth_stencil_ops
|
|
1487
1950
|
; (matches the legacy path).
|
|
1488
|
-
|
|
1951
|
+
; `depthStencilAttachment` is the IDL's word, and the form has carried
|
|
1952
|
+
; stencil keys since it was written — `depth-attachment` named half of it.
|
|
1953
|
+
; `:depth-load-op` / `:depth-store-op` no longer carry PNGine defaults
|
|
1954
|
+
; (clear/store) — that half stands. Making them
|
|
1955
|
+
; unconditionally REQUIRED, as the first cut did, was wrong in the other
|
|
1956
|
+
; direction: WebGPU requires the depth pair only when the VIEW's format has a
|
|
1957
|
+
; depth aspect, and FORBIDS it otherwise, so a `stencil8` attachment became
|
|
1958
|
+
; unwritable. The requirement is conditional on a format the schema cannot
|
|
1959
|
+
; reach, so it is the emitter's, in both directions and for both aspects.
|
|
1960
|
+
;
|
|
1961
|
+
; `:depth-clear-value` is the emitter's, for the same positional reason the colour
|
|
1962
|
+
; attachment records: GPURenderPassDepthStencilAttachment gives
|
|
1963
|
+
; depthClearValue no default at all, so a `clear` without one baked a PNGine
|
|
1964
|
+
; 1.0 — the single number in a depth pass that decides whether anything is
|
|
1965
|
+
; visible. Required-when-clearing needs a `(variant :when clear …)`, which
|
|
1966
|
+
; needs `:depth-load-op` written before `:depth-clear-value` in every
|
|
1967
|
+
; document. The emitter says it instead, with a span on the attachment.
|
|
1968
|
+
(form :name depth-stencil-attachment
|
|
1489
1969
|
:description "Depth/stencil target of a render pass."
|
|
1490
1970
|
(key :name view :type texture-ref
|
|
1491
1971
|
:description "The depth/stencil (texture …) this pass tests/writes against.")
|
|
1492
1972
|
(key :name depth-clear-value :type unorm :optional true
|
|
1493
|
-
:description "Depth cleared to when depth-load-op is clear
|
|
1494
|
-
(key :name depth-load-op :type load-op :
|
|
1495
|
-
:description "clear depth to :depth-clear-value, or load the existing depth.")
|
|
1496
|
-
(key :name depth-store-op :type store-op :
|
|
1497
|
-
:description "store the resulting depth, or discard it.")
|
|
1498
|
-
(key :name stencil-clear-value :type
|
|
1973
|
+
:description "Depth cleared to when depth-load-op is clear, in [0,1]. Required when it clears — WebGPU has no default for it — and rejected beside `:depth-load-op load`.")
|
|
1974
|
+
(key :name depth-load-op :type load-op :optional true
|
|
1975
|
+
:description "clear depth to :depth-clear-value, or load the existing depth. Required when the view's format has a depth aspect, and rejected when it has none.")
|
|
1976
|
+
(key :name depth-store-op :type store-op :optional true
|
|
1977
|
+
:description "store the resulting depth, or discard it. Required when the view's format has a depth aspect, and rejected when it has none.")
|
|
1978
|
+
(key :name stencil-clear-value :type u32 :optional true
|
|
1499
1979
|
:description "Stencil cleared to when stencil-load-op is clear.")
|
|
1500
1980
|
(key :name stencil-load-op :type load-op :optional true
|
|
1501
|
-
:description "clear stencil to :stencil-clear-value, or load the existing stencil.")
|
|
1981
|
+
:description "clear stencil to :stencil-clear-value, or load the existing stencil. Required when the view's format has a stencil aspect, and rejected when it has none.")
|
|
1502
1982
|
(key :name stencil-store-op :type store-op :optional true
|
|
1503
|
-
:description "store the resulting stencil, or discard it."))
|
|
1983
|
+
:description "store the resulting stencil, or discard it. Required when the view's format has a stencil aspect, and rejected when it has none."))
|
|
1504
1984
|
|
|
1505
1985
|
(form :name draw
|
|
1506
1986
|
:description "Non-indexed draw call."
|
|
@@ -1522,7 +2002,7 @@
|
|
|
1522
2002
|
(key :name first-index :type count :default 0
|
|
1523
2003
|
:description "Offset into the index buffer, in indices.")
|
|
1524
2004
|
(key :name base-vertex :type count :default 0
|
|
1525
|
-
:description "Added to each index before vertex lookup
|
|
2005
|
+
:description "Added to each index before vertex lookup. Signed in WebGPU; pngine carries a u32 and rejects a negative value.")
|
|
1526
2006
|
(key :name first-instance :type count :default 0
|
|
1527
2007
|
:description "First instance index."))
|
|
1528
2008
|
|
|
@@ -1530,73 +2010,95 @@
|
|
|
1530
2010
|
:description "Non-indexed indirect draw: the GPUDrawIndirectArgs (4×u32: vertex-count, instance-count, first-vertex, first-instance) are read from :buffer at :offset, typically written by a compute pass. No index buffer needed."
|
|
1531
2011
|
(key :name buffer :type buffer-ref
|
|
1532
2012
|
:description "Buffer holding the indirect args (needs indirect usage).")
|
|
1533
|
-
(key :name offset :type byte-count :default 0
|
|
1534
|
-
:description "Byte offset of the args within :buffer."))
|
|
2013
|
+
(key :name offset :type byte-count-4-aligned :default 0
|
|
2014
|
+
:description "Byte offset of the args within :buffer (a multiple of 4, as WebGPU requires of indirectOffset)."))
|
|
1535
2015
|
|
|
1536
2016
|
(form :name draw-indexed-indirect
|
|
1537
2017
|
:description "Indexed indirect draw: the GPUDrawIndexedIndirectArgs (5×u32) are read from :buffer at :offset, typically written by a compute pass. Requires the pass's :index-buffer."
|
|
1538
2018
|
(key :name buffer :type buffer-ref
|
|
1539
2019
|
:description "Buffer holding the indirect args (needs indirect usage).")
|
|
1540
|
-
(key :name offset :type byte-count :default 0
|
|
1541
|
-
:description "Byte offset of the args within :buffer."))
|
|
2020
|
+
(key :name offset :type byte-count-4-aligned :default 0
|
|
2021
|
+
:description "Byte offset of the args within :buffer (a multiple of 4, as WebGPU requires of indirectOffset)."))
|
|
1542
2022
|
|
|
1543
2023
|
; Emitted as a pre-pass set_pass_timestamp_writes (before begin_render_pass).
|
|
2024
|
+
; GPURenderPassTimestampWrites, keys spelled as the IDL spells them. The
|
|
2025
|
+
; two indices are baked (`:default 0` / `:default 1`) where the IDL
|
|
2026
|
+
; leaves them optional with NO default — "write only the end" is not
|
|
2027
|
+
; expressible because the opcode carries two u32s and no absent marker. A
|
|
2028
|
+
; PNGine opinion, ledgered in the conformance harness; the absent-index
|
|
2029
|
+
; capability and the compute-pass timestamp-writes the IDL also has are not
|
|
2030
|
+
; expressible here yet.
|
|
1544
2031
|
(form :name timestamp-writes
|
|
1545
2032
|
:description "Record GPU timestamps at pass start/end into a (query-set :type timestamp)."
|
|
1546
2033
|
(key :name query-set :type query-set-ref
|
|
1547
2034
|
:description "The timestamp query set written into.")
|
|
1548
|
-
(key :name
|
|
1549
|
-
:description "Query index written at pass start.")
|
|
1550
|
-
(key :name end :type
|
|
1551
|
-
:description "Query index written at pass end."))
|
|
2035
|
+
(key :name beginning-of-pass-write-index :type u32 :default 0
|
|
2036
|
+
:description "Query index written at pass start (PNGine bakes 0; the IDL leaves it absent = not written).")
|
|
2037
|
+
(key :name end-of-pass-write-index :type u32 :default 1
|
|
2038
|
+
:description "Query index written at pass end (PNGine bakes 1; the IDL leaves it absent = not written)."))
|
|
1552
2039
|
|
|
1553
2040
|
(form :name occlusion-query
|
|
1554
2041
|
:description "Bracket one or more draws in an occlusion query: the GPU counts samples passing depth/stencil into the pass's :occlusion-query-set at :query-index."
|
|
1555
2042
|
:positional occlusion-draw-item
|
|
1556
|
-
(key :name query-index :type
|
|
2043
|
+
(key :name query-index :type u32 :default 0
|
|
1557
2044
|
:description "Index within the pass's occlusion query set."))
|
|
1558
2045
|
|
|
2046
|
+
; A dispatch is a COMMAND, and commands are forms — the same shape the
|
|
2047
|
+
; render pass has used for `(draw …)` all along. It was three keys with a
|
|
2048
|
+
; precedence rule between them (`:dispatch-indirect` beat `:dispatch` beat
|
|
2049
|
+
; `:dispatch-workgroups`), which is what a writer had to know to read a pass
|
|
2050
|
+
; that stated two. Several dispatches per pass are legal WebGPU and now
|
|
2051
|
+
; expressible; a pass with none is not a pass, which is the head-set's
|
|
2052
|
+
; `:min-children 1` — a pngine opinion, not an IDL rule.
|
|
1559
2053
|
(form :name compute-pass
|
|
1560
|
-
:description "GPU compute pass: a compute pipeline + bind groups + one dispatch."
|
|
2054
|
+
:description "GPU compute pass: a compute pipeline + bind groups + one or more (dispatch …) commands."
|
|
2055
|
+
:positional compute-pass-command
|
|
1561
2056
|
(key :name name :type symbol)
|
|
1562
2057
|
(key :name pipeline :type compute-pipeline-ref
|
|
1563
2058
|
:description "The compute pipeline this pass dispatches.")
|
|
1564
2059
|
(key :name bind-groups :type bind-group-ref-list :optional true
|
|
1565
2060
|
:description "Bind groups set at @group 0..N in order.")
|
|
1566
2061
|
(key :name bind-groups-pool-offsets :type offset-list :optional true
|
|
1567
|
-
:description "Per-group ping-pong offsets into each group's pool.")
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
|
|
1573
|
-
:description "Indirect dispatch: the workgroup counts (3×u32) are read from this buffer at :dispatch-indirect-offset, typically written by an earlier compute pass. Takes precedence over :dispatch / :dispatch-workgroups.")
|
|
1574
|
-
(key :name dispatch-indirect-offset :type byte-count :default 0
|
|
1575
|
-
:description "Byte offset of the dispatch args within :dispatch-indirect."))
|
|
2062
|
+
:description "Per-group ping-pong offsets into each group's pool."))
|
|
2063
|
+
|
|
2064
|
+
(form :name dispatch
|
|
2065
|
+
:description "Compute dispatch command (GPUComputePassEncoder.dispatchWorkgroups)."
|
|
2066
|
+
(key :name workgroups :type dispatch-size
|
|
2067
|
+
:description "Workgroup counts as [x], [x y] or [x y z]; the missing dimensions default to 1. Each element is a literal, an expression like (ceil (/ NUM 64)), or a bare (define …) name."))
|
|
1576
2068
|
|
|
2069
|
+
(form :name dispatch-indirect
|
|
2070
|
+
:description "Indirect compute dispatch: the workgroup counts (3×u32) are read from :buffer at :offset, typically written by an earlier compute pass."
|
|
2071
|
+
(key :name buffer :type buffer-ref
|
|
2072
|
+
:description "Buffer holding the dispatch args (needs indirect usage).")
|
|
2073
|
+
(key :name offset :type byte-count-4-aligned :default 0
|
|
2074
|
+
:description "Byte offset of the args within :buffer (a multiple of 4, as WebGPU requires of indirectOffset)."))
|
|
2075
|
+
|
|
2076
|
+
; The recorded draw is a `(draw …)` / `(draw-indexed …)` CHILD — the same two
|
|
2077
|
+
; forms a render pass issues, with the same keys. It was `:draw N`
|
|
2078
|
+
; beside `:instance-count M`, a third spelling of a draw that could not say
|
|
2079
|
+
; `:first-vertex`, and `:draw-indexed N` which could say nothing else at all.
|
|
1577
2080
|
(form :name render-bundle
|
|
1578
|
-
:description "Pre-recorded reusable draw sequence (pipeline + buffers + bind groups + one draw), replayed via a render-pass's :execute-bundles."
|
|
2081
|
+
:description "Pre-recorded reusable draw sequence (pipeline + buffers + bind groups + one (draw …)), replayed via a render-pass's :execute-bundles."
|
|
2082
|
+
:positional render-bundle-command
|
|
1579
2083
|
(key :name name :type symbol)
|
|
1580
|
-
(key :name pipeline :type render-pipeline-ref
|
|
1581
|
-
:description "Pipeline recorded into the bundle (the executing pass omits its own).")
|
|
1582
|
-
|
|
1583
|
-
|
|
2084
|
+
(key :name pipeline :type render-pipeline-ref
|
|
2085
|
+
:description "Pipeline recorded into the bundle (the executing pass omits its own). Required: a bundle's descriptor is its own layout, and a draw with no pipeline is invalid WebGPU.")
|
|
2086
|
+
; REQUIRED, matching GPURenderPassLayout.colorFormats. A bundle is validated
|
|
2087
|
+
; against the layout it declares, so an unstated list is not a shorthand —
|
|
2088
|
+
; it is a claim the runtime has to invent, and every runtime invented the
|
|
2089
|
+
; canvas format.
|
|
2090
|
+
(key :name color-formats :type texture-format-list
|
|
2091
|
+
:description "Color attachment formats the bundle is recorded against. Each must be a color format, and the list must equal both the :pipeline's color targets and the replaying pass's color attachments.")
|
|
1584
2092
|
(key :name depth-stencil-format :type texture-format :optional true
|
|
1585
|
-
:description "Depth/stencil format the bundle is recorded against.")
|
|
1586
|
-
(key :name sample-count :type
|
|
1587
|
-
:description "Sample count the bundle is recorded against.")
|
|
2093
|
+
:description "Depth/stencil format the bundle is recorded against. Must be a depth or stencil format, and must be present exactly when the :pipeline declares a (depth-stencil …) and the replaying pass has a (depth-stencil-attachment …).")
|
|
2094
|
+
(key :name sample-count :type u32 :optional true
|
|
2095
|
+
:description "Sample count the bundle is recorded against (default 1). Must equal the :pipeline's (multisample :count …) and the sample count of the replaying pass's attachment textures.")
|
|
1588
2096
|
(key :name vertex-buffers :type buffer-ref-list :optional true
|
|
1589
2097
|
:description "Buffers bound to vertex slots 0..N in order.")
|
|
1590
2098
|
(key :name bind-groups :type bind-group-ref-list :optional true
|
|
1591
2099
|
:description "Bind groups set at @group 0..N in order.")
|
|
1592
2100
|
(key :name index-buffer :type buffer-ref :optional true
|
|
1593
|
-
:description "Index buffer when the bundle draws indexed.")
|
|
1594
|
-
(key :name draw :type count :optional true
|
|
1595
|
-
:description "Record a non-indexed draw of this many vertices.")
|
|
1596
|
-
(key :name draw-indexed :type count :optional true
|
|
1597
|
-
:description "Record an indexed draw of this many indices.")
|
|
1598
|
-
(key :name instance-count :type count :optional true
|
|
1599
|
-
:description "Instances for the recorded :draw."))
|
|
2101
|
+
:description "Index buffer when the bundle draws indexed."))
|
|
1600
2102
|
|
|
1601
2103
|
(form :name frame
|
|
1602
2104
|
:description "Frame program: what runs each frame, in order."
|
|
@@ -1611,15 +2113,21 @@
|
|
|
1611
2113
|
; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
|
|
1612
2114
|
(form :name init
|
|
1613
2115
|
:description "One-shot compute init of a storage buffer (first frame only)."
|
|
2116
|
+
; `entry` here is the bind-group's SLOT-LOCAL entry, and it resolves through
|
|
2117
|
+
; the dummy global `(entry …)` form declared beside bind-group — see the
|
|
2118
|
+
; comment there. It used to resolve through the render-pipeline stage's
|
|
2119
|
+
; `(entry …)`, by accident.
|
|
1614
2120
|
:lowering (lowering :hook pngine/init-v1
|
|
1615
|
-
:produces [compute-pipeline bind-group entry compute-pass])
|
|
2121
|
+
:produces [compute-pipeline compute bind-group entry compute-pass dispatch])
|
|
1616
2122
|
(key :name name :type symbol)
|
|
1617
2123
|
(key :name buffer :type buffer-ref
|
|
1618
2124
|
:description "The storage buffer the init compute writes (bound at @binding 0).")
|
|
1619
|
-
(key :name
|
|
2125
|
+
(key :name module :type module-ref
|
|
1620
2126
|
:description "The (shader-module …) holding the @compute init entry.")
|
|
1621
|
-
(
|
|
1622
|
-
|
|
2127
|
+
; Same shape as the `(dispatch :workgroups …)` this lowers to. Sugar is
|
|
2128
|
+
; spelled like what it expands into, so a change binds both or neither.
|
|
2129
|
+
(key :name workgroups :type dispatch-size
|
|
2130
|
+
:description "Workgroup counts as [x], [x y] or [x y z]. Read at lowering time through the lowering env: literals, bounded expressions over (define …) constants, e.g. [(ceil (/ NUM 64))], or a bare (define …) name."))
|
|
1623
2131
|
|
|
1624
2132
|
; =====================================================================
|
|
1625
2133
|
; `(pass …)` sugar — container-lowered by pngine/pass-v1 (Phase 2f)
|
|
@@ -1637,14 +2145,14 @@
|
|
|
1637
2145
|
:description "One `(pass …)`: a fullscreen fragment (or compute) shader-art stage.
|
|
1638
2146
|
The hook detects features from the WGSL (pngine/pointer/feedback)."
|
|
1639
2147
|
(key :name name :type symbol)
|
|
1640
|
-
(key :name code :type string
|
|
1641
|
-
:description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers).")
|
|
2148
|
+
(key :name code :type string
|
|
2149
|
+
:description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers). Required — the hook always refused its absence.")
|
|
1642
2150
|
(key :name feedback :type boolean :optional true
|
|
1643
2151
|
:description "Ping-pong texture pair for feedback; the previous frame is readable as prev_<name>.")
|
|
1644
2152
|
(key :name init :type string :optional true
|
|
1645
2153
|
:description "One-shot WGSL compute source run on the first frame only.")
|
|
1646
|
-
(key :name
|
|
1647
|
-
:description "WASM file paths → D0, D1, … storage buffers; the hook injects var<storage, read> D{i}: array<f32>."))
|
|
2154
|
+
(key :name file :type data-file-list :optional true
|
|
2155
|
+
:description "WASM file paths (relative to the document) → D0, D1, … storage buffers; the hook injects var<storage, read> D{i}: array<f32>. The same :file every other file-on-disk key spells."))
|
|
1648
2156
|
|
|
1649
2157
|
(form :name pass-graph
|
|
1650
2158
|
:description "Container of (pass …) children lowered as a unit so resource ids
|
|
@@ -1652,7 +2160,7 @@
|
|
|
1652
2160
|
:open true
|
|
1653
2161
|
:positional pass-item
|
|
1654
2162
|
:lowering (lowering :hook pngine/pass-v1
|
|
1655
|
-
:produces [shader-module buffer texture sampler bind-group
|
|
1656
|
-
render-pipeline vertex fragment
|
|
2163
|
+
:produces [shader-module buffer texture sampler bind-group entry
|
|
2164
|
+
render-pipeline vertex fragment target
|
|
1657
2165
|
render-pass color-attachment draw frame
|
|
1658
|
-
compute-pipeline compute-pass queue write-buffer])))
|
|
2166
|
+
compute-pipeline compute compute-pass dispatch queue write-buffer])))
|