pngine 2.0.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/LICENSE +121 -0
- package/README.md +27 -10
- package/dist/core.mjs +4 -4
- package/dist/dev.d.ts +16 -0
- package/dist/dev.mjs +1 -1
- package/dist/index.cjs +1 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.mjs +1 -0
- package/dist/mini-no-audio.mjs +1 -1
- package/dist/mini.mjs +1 -1
- package/dist/viewer.d.ts +16 -0
- package/dist/viewer.mjs +1 -1
- package/package.json +17 -9
- package/schema/pngine.sjon +973 -425
- package/src/anim.js +78 -13
- package/src/core.js +10 -5
- package/src/descriptor-decode.js +5 -1
- package/src/dev.js +1 -1
- package/src/gpu-queue-commands.js +29 -11
- package/src/gpu-resource-pass-commands.js +115 -21
- package/src/gpu-stats.js +57 -0
- package/src/gpu.js +239 -47
- package/src/init-core.js +118 -26
- package/src/init.js +89 -55
- package/src/mini.js +213 -96
- package/src/viewer-init.js +44 -34
- package/src/viewer.js +1 -1
- package/src/worker-core.js +162 -17
- package/src/worker-prefetch.js +21 -3
- package/src/worker-viewer.js +0 -1
- package/wasm/pngine-compiler.wasm +0 -0
- package/wasm/pngine.wasm +0 -0
package/schema/pngine.sjon
CHANGED
|
@@ -1,32 +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 (
|
|
29
|
-
;
|
|
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.)
|
|
30
34
|
(plugin :name pngine :version "0.1.0"
|
|
31
35
|
|
|
32
36
|
; ---- numeric refinements ----
|
|
@@ -39,36 +43,166 @@
|
|
|
39
43
|
; silently wraps it, and SJON's exporter emits the branded `U32` TS alias so the
|
|
40
44
|
; editor gets real per-field GPU types. Repr checks literals only — expressions
|
|
41
45
|
; (`:size (* NUM 4 4)`) and define-refs are evaluated later, untouched here.
|
|
42
|
-
|
|
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
|
|
43
72
|
:description "Non-negative integer byte size / offset / stride."
|
|
44
73
|
:underlying number
|
|
45
74
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
46
75
|
:unit (unit-shape :reject true)
|
|
47
76
|
:repr (repr-shape :type u32))
|
|
48
|
-
(value-kind :name
|
|
49
|
-
:description "
|
|
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."
|
|
50
86
|
:underlying number
|
|
51
|
-
:numeric (numeric-bounds :min
|
|
87
|
+
:numeric (numeric-bounds :min 0 :integer true :multiple-of 4)
|
|
52
88
|
:unit (unit-shape :reject true)
|
|
53
89
|
:repr (repr-shape :type u32))
|
|
54
|
-
(value-kind :name
|
|
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
|
|
105
|
+
:description "Ping-pong pool size (1..255). The ceiling is the wire's: the
|
|
106
|
+
pool index is a byte everywhere it is encoded, so a larger pool
|
|
107
|
+
cannot be addressed. Bounds a LITERAL; the emitter re-checks the
|
|
108
|
+
expression spelling (`:pool (* 100 3)`), which repr cannot see."
|
|
109
|
+
:underlying number
|
|
110
|
+
:numeric (numeric-bounds :min 1 :max 255 :integer true)
|
|
111
|
+
:unit (unit-shape :reject true)
|
|
112
|
+
:repr (repr-shape :type u32))
|
|
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
|
|
55
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)."
|
|
56
119
|
:underlying number
|
|
57
120
|
:numeric (numeric-bounds :min 0 :max 255 :integer true)
|
|
58
121
|
:unit (unit-shape :reject true)
|
|
59
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))
|
|
60
127
|
(value-kind :name count-value
|
|
61
128
|
:description "Non-negative integer draw / dispatch count (literals + expressions)."
|
|
62
129
|
:underlying number
|
|
63
130
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
64
131
|
:unit (unit-shape :reject true)
|
|
65
132
|
:repr (repr-shape :type u32))
|
|
66
|
-
; A count may also be a bare
|
|
67
|
-
;
|
|
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))
|
|
68
164
|
(value-kind :name count
|
|
69
165
|
:description "Draw / dispatch count: a literal, a bounded expression, or a bare (define …) reference."
|
|
70
|
-
:underlying
|
|
71
|
-
:
|
|
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))
|
|
72
206
|
; A WebGPU device-limit value. Non-negative integer, u32-range in the schema
|
|
73
207
|
; (the PNGB wire carries u64 for forward-compat). Passed VERBATIM to
|
|
74
208
|
; requiredLimits at device creation — an unsatisfiable request fails loud there
|
|
@@ -79,53 +213,108 @@
|
|
|
79
213
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
80
214
|
:unit (unit-shape :reject true)
|
|
81
215
|
:repr (repr-shape :type u32))
|
|
82
|
-
(value-kind :name
|
|
83
|
-
: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)."
|
|
84
222
|
:underlying number
|
|
85
223
|
:numeric (numeric-bounds :min 0 :max 1)
|
|
86
224
|
:unit (unit-shape :reject true)
|
|
87
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))
|
|
88
246
|
(value-kind :name depth-bias-value
|
|
89
|
-
:description "Depth bias
|
|
247
|
+
:description "Depth bias slope-scale / clamp: a real."
|
|
90
248
|
:underlying number
|
|
91
249
|
:unit (unit-shape :reject true)
|
|
92
250
|
:repr (repr-shape :type f32))
|
|
93
|
-
(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
|
|
94
256
|
:description "Sampler mip level-of-detail clamp (non-negative real; WebGPU defaults lodMinClamp 0, lodMaxClamp 32)."
|
|
95
257
|
:underlying number
|
|
96
258
|
:numeric (numeric-bounds :min 0)
|
|
97
259
|
:unit (unit-shape :reject true)
|
|
98
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))
|
|
99
265
|
(value-kind :name anisotropy-value
|
|
100
266
|
:description "Sampler max anisotropy (integer in [1,16]; values > 1 require linear mag/min/mipmap filters)."
|
|
101
267
|
:underlying number
|
|
102
268
|
:numeric (numeric-bounds :min 1 :max 16 :integer true)
|
|
103
269
|
:unit (unit-shape :reject true)
|
|
104
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).
|
|
105
281
|
(value-kind :name texture-dimension
|
|
106
|
-
:description "GPUTextureDimension as
|
|
107
|
-
:underlying
|
|
108
|
-
:
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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."
|
|
113
290
|
:underlying number
|
|
114
291
|
:numeric (numeric-bounds :min 1 :integer true)
|
|
115
292
|
:unit (unit-shape :reject true)
|
|
116
293
|
:repr (repr-shape :type u32))
|
|
117
|
-
(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
|
|
118
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.)"
|
|
119
300
|
:underlying number
|
|
120
301
|
:numeric (numeric-bounds :min 0 :integer true)
|
|
121
302
|
:unit (unit-shape :reject true)
|
|
122
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))
|
|
123
308
|
(value-kind :name view-dimension
|
|
124
|
-
:description "GPUTextureViewDimension as
|
|
125
|
-
:underlying
|
|
126
|
-
:
|
|
127
|
-
|
|
128
|
-
|
|
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).")))
|
|
129
318
|
(value-kind :name texture-aspect
|
|
130
319
|
:description "GPUTextureAspect — which aspect(s) of a depth/stencil texture a view exposes."
|
|
131
320
|
:underlying symbol
|
|
@@ -155,10 +344,6 @@
|
|
|
155
344
|
:description "Reference to a declared (compute-pipeline :name …)."
|
|
156
345
|
:underlying symbol
|
|
157
346
|
:cross-ref (cross-ref :target compute-pipeline))
|
|
158
|
-
(value-kind :name wasm-call-ref
|
|
159
|
-
:description "Reference to a declared (wasm-call :name …)."
|
|
160
|
-
:underlying symbol
|
|
161
|
-
:cross-ref (cross-ref :target wasm-call))
|
|
162
347
|
(value-kind :name bind-group-ref
|
|
163
348
|
:description "Reference to a declared (bind-group :name …)."
|
|
164
349
|
:underlying symbol
|
|
@@ -171,20 +356,35 @@
|
|
|
171
356
|
:description "Reference to a declared (queue :name …)."
|
|
172
357
|
:underlying symbol
|
|
173
358
|
:cross-ref (cross-ref :target queue))
|
|
174
|
-
(value-kind :name render-pass-ref
|
|
175
|
-
:description "Reference to a declared (render-pass :name …)."
|
|
176
|
-
:underlying symbol
|
|
177
|
-
:cross-ref (cross-ref :target render-pass))
|
|
178
359
|
(value-kind :name compute-pass-ref
|
|
179
360
|
:description "Reference to a declared (compute-pass :name …), including one lowered from (init …) sugar."
|
|
180
361
|
:underlying symbol
|
|
181
362
|
:cross-ref (cross-ref :target compute-pass))
|
|
182
|
-
;
|
|
183
|
-
;
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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]))
|
|
188
388
|
|
|
189
389
|
; ---- runtime builtin data sources (write-buffer :data) ----
|
|
190
390
|
(value-kind :name builtin-data-source
|
|
@@ -192,18 +392,27 @@
|
|
|
192
392
|
:underlying symbol
|
|
193
393
|
:members (member-set
|
|
194
394
|
(member :name pngine-inputs :description "16 B: time, canvasWidth, canvasHeight, aspect (all f32).")
|
|
195
|
-
(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.")
|
|
196
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]))
|
|
197
406
|
(value-kind :name write-buffer-source
|
|
198
|
-
: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."
|
|
199
408
|
:underlying union
|
|
200
|
-
:union (union-shape :alternatives [builtin-data-source data-ref]))
|
|
409
|
+
:union (union-shape :alternatives [builtin-data-source data-or-wasm-ref]))
|
|
201
410
|
|
|
202
|
-
;
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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.
|
|
207
416
|
|
|
208
417
|
; ---- enums ----
|
|
209
418
|
(value-kind :name buffer-usage
|
|
@@ -218,8 +427,8 @@
|
|
|
218
427
|
(member :name copy-src :description "Source of copy operations.")
|
|
219
428
|
(member :name indirect :description "Holds indirect draw/dispatch arguments.")
|
|
220
429
|
(member :name query-resolve :description "Receives resolve-query-set results.")
|
|
221
|
-
(member :name map-read :description "Mappable for CPU readback.")
|
|
222
|
-
(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.")))
|
|
223
432
|
(value-kind :name primitive-topology
|
|
224
433
|
:description "GPUPrimitiveTopology — how vertices are assembled into primitives."
|
|
225
434
|
:underlying symbol
|
|
@@ -299,6 +508,25 @@
|
|
|
299
508
|
(value-kind :name entry-point
|
|
300
509
|
:description "Shader entry-point function name (a WGSL @vertex/@fragment/@compute fn)."
|
|
301
510
|
:underlying symbol)
|
|
511
|
+
; Follows `entry-point`: a free symbol naming something inside opaque WGSL,
|
|
512
|
+
; which the EMITTER cross-checks against reflection. SJON cannot check it —
|
|
513
|
+
; the override declarations live inside a `:code` string the validator does
|
|
514
|
+
; not parse.
|
|
515
|
+
(value-kind :name override-name
|
|
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."
|
|
517
|
+
:underlying symbol)
|
|
518
|
+
; Deliberately NOT :repr-tagged. A constant's width is whatever its WGSL
|
|
519
|
+
; `override` declares (f32/u32/i32/bool), which the schema cannot see; the
|
|
520
|
+
; emitter type-checks the value against the reflected type instead. A repr
|
|
521
|
+
; tag here would be a guess that rejects valid documents.
|
|
522
|
+
(value-kind :name override-value
|
|
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."
|
|
524
|
+
:underlying number
|
|
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))
|
|
302
530
|
(value-kind :name layout-mode
|
|
303
531
|
:description "Pipeline layout mode: auto derives bind-group layouts from the WGSL."
|
|
304
532
|
:underlying symbol
|
|
@@ -371,9 +599,16 @@
|
|
|
371
599
|
:description "Reference to a declared (query-set :name …)."
|
|
372
600
|
:underlying symbol
|
|
373
601
|
:cross-ref (cross-ref :target query-set))
|
|
374
|
-
(value-kind :name timestamp-writes-item :underlying form :heads (head-set :names [timestamp-writes]))
|
|
375
602
|
; Heads admitted positionally inside an (occlusion-query …) bracket.
|
|
376
|
-
|
|
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)))
|
|
377
612
|
|
|
378
613
|
; ---- Phase 2a: textures, shape generators, depth/stencil, indexed draws ----
|
|
379
614
|
(value-kind :name texture-ref
|
|
@@ -454,6 +689,38 @@
|
|
|
454
689
|
:underlying symbol
|
|
455
690
|
:members (member-set
|
|
456
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]))
|
|
457
724
|
(value-kind :name index-format
|
|
458
725
|
:description "GPUIndexFormat — byte width of index-buffer entries."
|
|
459
726
|
:underlying symbol
|
|
@@ -531,7 +798,9 @@
|
|
|
531
798
|
(member :name decrement-clamp :description "Decrement, clamping at 0.")
|
|
532
799
|
(member :name increment-wrap :description "Increment, wrapping to 0 past the maximum.")
|
|
533
800
|
(member :name decrement-wrap :description "Decrement, wrapping to the maximum below 0.")))
|
|
534
|
-
(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)))
|
|
535
804
|
|
|
536
805
|
; ---- Phase 2d: MRT / MSAA / advanced render state ----
|
|
537
806
|
; A render-pass attachment view: the canvas (context-current-texture) or a
|
|
@@ -576,16 +845,34 @@
|
|
|
576
845
|
:numeric (numeric-bounds :min 0 :max 15 :integer true)
|
|
577
846
|
:unit (unit-shape :reject true)
|
|
578
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.
|
|
579
865
|
(value-kind :name write-mask
|
|
580
866
|
:description "Color write mask: an integer bitmask (R=1 G=2 B=4 A=8) or the symbol all (15). Emitter-resolved."
|
|
581
|
-
:underlying
|
|
582
|
-
:
|
|
867
|
+
:underlying scalar-or-ref
|
|
868
|
+
:scalar-or-ref (scalar-or-ref-shape :base write-mask-value :ref write-mask-symbol))
|
|
583
869
|
|
|
584
870
|
; ---- explicit bind-group-layout (uniform_access feature) ----
|
|
585
|
-
; A
|
|
586
|
-
; visibility +
|
|
587
|
-
;
|
|
588
|
-
;
|
|
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).
|
|
589
876
|
(value-kind :name visibility
|
|
590
877
|
:description "GPUShaderStage — a shader stage that may access the binding."
|
|
591
878
|
:underlying symbol
|
|
@@ -611,14 +898,38 @@
|
|
|
611
898
|
:description "Reference to a declared (pipeline-layout :name …)."
|
|
612
899
|
:underlying symbol
|
|
613
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]))
|
|
614
913
|
; Positional sub-form heads for the explicit bind-group-layout: an (entry …)
|
|
615
|
-
; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms
|
|
914
|
+
; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms:
|
|
616
915
|
; declared inline under their parent form and resolved LOCAL-FIRST, so the
|
|
617
916
|
; natural names `entry`/`buffer` shadow within scope — no collision with the
|
|
618
917
|
; global `entry` (render-pipeline stage) or `buffer` (top-level resource) forms.
|
|
619
918
|
; Extends to local (sampler …)/(texture …) resources later.
|
|
620
919
|
(value-kind :name bgl-entry-item :underlying form :heads (head-set :names [entry]))
|
|
621
|
-
|
|
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)))
|
|
622
933
|
; The three non-buffer resource kinds. Each symbol member IS its WebGPU spelling,
|
|
623
934
|
; so the emitter passes it into the descriptor JSON verbatim (like buffer-binding-type).
|
|
624
935
|
(value-kind :name canvas-alpha-mode
|
|
@@ -626,7 +937,7 @@
|
|
|
626
937
|
:underlying symbol
|
|
627
938
|
:members (member-set
|
|
628
939
|
(member :name opaque :description "Alpha is ignored; the canvas composites as opaque (the WebGPU spec default; cheaper, no fringe on colored pages).")
|
|
629
|
-
(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.")))
|
|
630
941
|
(value-kind :name sampler-binding-type
|
|
631
942
|
:description "GPUSamplerBindingType — how a sampler binding is exposed to WGSL."
|
|
632
943
|
:underlying symbol
|
|
@@ -658,24 +969,27 @@
|
|
|
658
969
|
:string-bounds (string-bounds :format path))
|
|
659
970
|
|
|
660
971
|
; ---- vectors ----
|
|
661
|
-
(value-kind :name float-list :underlying vector :vector (vector-shape :element
|
|
972
|
+
(value-kind :name float-list :underlying vector :vector (vector-shape :element real))
|
|
662
973
|
; Viewport: the two shapes the emitter accepts — a 5-element rect is invalid.
|
|
663
974
|
(value-kind :name viewport-rect4
|
|
664
975
|
:description "Viewport [x y w h]; minDepth/maxDepth default to 0 and 1."
|
|
665
|
-
:underlying vector :vector (vector-shape :element
|
|
976
|
+
:underlying vector :vector (vector-shape :element real :len 4))
|
|
666
977
|
(value-kind :name viewport-rect6
|
|
667
978
|
:description "Viewport [x y w h minDepth maxDepth]; depths in [0,1]."
|
|
668
|
-
:underlying vector :vector (vector-shape :element
|
|
979
|
+
:underlying vector :vector (vector-shape :element real :len 6))
|
|
669
980
|
(value-kind :name viewport-rect
|
|
670
981
|
:description "Viewport rectangle: [x y w h] or [x y w h minDepth maxDepth]."
|
|
671
982
|
:underlying union
|
|
672
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.
|
|
673
987
|
(value-kind :name pixel-rect
|
|
674
988
|
:description "Rectangle [x y w h] in integer pixels."
|
|
675
|
-
:underlying vector :vector (vector-shape :element
|
|
989
|
+
:underlying vector :vector (vector-shape :element u32 :len 4))
|
|
676
990
|
(value-kind :name origin3
|
|
677
|
-
:description "Copy origin [x y z] in texels; z is the destination array layer / depth slice (default 0)."
|
|
678
|
-
: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))
|
|
679
993
|
; A buffer/texture with zero usage flags is invalid GPU — require >= 1 (else the
|
|
680
994
|
; reader emits a buffer with no usage and no diagnostic). `:min-len 1`.
|
|
681
995
|
(value-kind :name usage-list
|
|
@@ -684,13 +998,13 @@
|
|
|
684
998
|
; RGBA clear: exactly 4 components (else a 3-element color silently gets alpha 0).
|
|
685
999
|
(value-kind :name clear-color
|
|
686
1000
|
:description "RGBA clear color: exactly 4 components."
|
|
687
|
-
:underlying vector :vector (vector-shape :element
|
|
1001
|
+
:underlying vector :vector (vector-shape :element real :len 4))
|
|
688
1002
|
; RGBA blend-constant: exactly 4 float components, used by the `constant` /
|
|
689
1003
|
; `one-minus-constant` blend factors (setBlendConstant). Same shape as
|
|
690
1004
|
; clear-color; named separately so the description reads for its own role.
|
|
691
1005
|
(value-kind :name blend-constant-color
|
|
692
1006
|
:description "RGBA blend constant: exactly 4 float components (the `constant` blend factor's value)."
|
|
693
|
-
:underlying vector :vector (vector-shape :element
|
|
1007
|
+
:underlying vector :vector (vector-shape :element real :len 4))
|
|
694
1008
|
(value-kind :name buffer-ref-list
|
|
695
1009
|
:description "Declared (buffer …) names, bound to vertex slots 0..N in order."
|
|
696
1010
|
:underlying vector :vector (vector-shape :element buffer-ref))
|
|
@@ -698,79 +1012,207 @@
|
|
|
698
1012
|
:description "Declared (bind-group …) names, set at @group 0..N in order."
|
|
699
1013
|
:underlying vector :vector (vector-shape :element bind-group-ref))
|
|
700
1014
|
(value-kind :name bind-group-layout-ref-list
|
|
701
|
-
: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."
|
|
702
1016
|
:underlying vector :vector (vector-shape :element bind-group-layout-ref :min-len 1))
|
|
703
1017
|
(value-kind :name render-bundle-ref-list
|
|
704
1018
|
:description "Declared (render-bundle …) names replayed by a pass."
|
|
705
1019
|
:underlying vector :vector (vector-shape :element render-bundle-ref))
|
|
1020
|
+
; Every list below runs ONCE PER FRAME, so its length multiplies per-frame GPU
|
|
1021
|
+
; work directly. `:max-len 2048` on all three is the command-buffer budget: the
|
|
1022
|
+
; cheapest step that emits anything is a compute pass (begin 1B + set_pipeline
|
|
1023
|
+
; 3B + dispatch 13B + end 1B = 18B), so ~3,640 steps alone exhaust the 64 KB
|
|
1024
|
+
; buffer — and past that the stream TEARS rather than truncates (cmd_count
|
|
1025
|
+
; counts commands whose operand bytes were dropped). 2048 sits below that with
|
|
1026
|
+
; headroom and is 25x the longest list in the corpus (82, webgpu_bitonic_sort).
|
|
1027
|
+
; Mirrored by Emitter.MAX_FRAME_STEPS for the queue-action count, which is
|
|
1028
|
+
; positional and so has no schema length to bound.
|
|
706
1029
|
(value-kind :name queue-ref-list
|
|
707
1030
|
:description "Declared (queue …) names, run in order."
|
|
708
|
-
:underlying vector :vector (vector-shape :element queue-ref))
|
|
1031
|
+
:underlying vector :vector (vector-shape :element queue-ref :max-len 2048))
|
|
709
1032
|
(value-kind :name compute-pass-ref-list
|
|
710
1033
|
:description "Declared (compute-pass …) / (init …) names, run in order."
|
|
711
|
-
:underlying vector :vector (vector-shape :element compute-pass-ref))
|
|
712
|
-
; One frame step
|
|
1034
|
+
:underlying vector :vector (vector-shape :element compute-pass-ref :max-len 2048))
|
|
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.)
|
|
713
1040
|
(value-kind :name frame-step
|
|
714
|
-
:description "One frame step: a render-pass, compute-pass, or queue name."
|
|
715
|
-
:underlying
|
|
716
|
-
:
|
|
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]))
|
|
717
1044
|
(value-kind :name frame-step-list
|
|
718
1045
|
:description "Passes and queues run every frame, in order."
|
|
719
|
-
:underlying vector :vector (vector-shape :element frame-step))
|
|
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.
|
|
720
1052
|
(value-kind :name texture-format-list
|
|
721
|
-
:description "Color target formats a (render-bundle …) is recorded against."
|
|
722
|
-
: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))
|
|
723
1055
|
(value-kind :name data-file-list
|
|
724
|
-
: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."
|
|
725
1057
|
:underlying vector :vector (vector-shape :element file-path))
|
|
726
1058
|
(value-kind :name offset-list
|
|
727
1059
|
:description "Integer offset list (e.g. per-entry ping-pong pool offsets)."
|
|
728
|
-
:underlying vector :vector (vector-shape :element
|
|
1060
|
+
:underlying vector :vector (vector-shape :element u32))
|
|
729
1061
|
(value-kind :name shape-format-list
|
|
730
1062
|
:description "Vertex layout of generated shape data, as ordered attribute specifiers."
|
|
731
1063
|
:underlying vector :vector (vector-shape :element shape-format))
|
|
732
1064
|
(value-kind :name texture-usage-list
|
|
733
1065
|
:description "Texture usage flags (at least one)."
|
|
734
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).
|
|
735
1077
|
(value-kind :name dispatch-size
|
|
736
|
-
:description "
|
|
737
|
-
:underlying vector :vector (vector-shape :element count-
|
|
738
|
-
;
|
|
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))
|
|
1080
|
+
; `(wasm-call …)` args: the emitter encodes a type tag per arg (+ 4 value bytes for
|
|
739
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.")))
|
|
740
1096
|
(value-kind :name wasm-arg
|
|
741
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)."
|
|
742
|
-
:underlying union :union (union-shape :alternatives [
|
|
1098
|
+
:underlying union :union (union-shape :alternatives [wasm-arg-builtin number]))
|
|
743
1099
|
(value-kind :name wasm-arg-list
|
|
744
1100
|
:description "Arguments passed to a (wasm-call …) function each frame."
|
|
745
1101
|
:underlying vector :vector (vector-shape :element wasm-arg))
|
|
746
1102
|
|
|
747
1103
|
; ---- positional head-sets ----
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
(
|
|
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]))
|
|
753
1143
|
(value-kind :name attribute-item :underlying form :heads (head-set :names [attribute]))
|
|
754
|
-
(value-kind :name
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
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)))
|
|
758
1160
|
(value-kind :name bind-entry-item :underlying form :heads (head-set :names [entry]))
|
|
759
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]))
|
|
760
|
-
;
|
|
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)))
|
|
1187
|
+
; `(data …)` generators: a positional sub-form whose head selects a procedural shape
|
|
761
1188
|
; (cube/sphere/…) or `wasm-data` (a WASM function that returns the vertex bytes).
|
|
762
|
-
|
|
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)))
|
|
763
1205
|
|
|
764
1206
|
; =====================================================================
|
|
765
|
-
; Top-level forms
|
|
1207
|
+
; Top-level forms
|
|
766
1208
|
; =====================================================================
|
|
767
1209
|
|
|
768
1210
|
(form :name define
|
|
769
|
-
: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."
|
|
770
1212
|
(key :name name :type symbol
|
|
771
|
-
:description "Constant name, referenced from numeric
|
|
772
|
-
(key :name value :type
|
|
773
|
-
: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."))
|
|
774
1216
|
|
|
775
1217
|
; Authored WebGPU device requiredLimits. Optional singleton (declare at most
|
|
776
1218
|
; once, no :name). Each present key raises the corresponding GPUSupportedLimits
|
|
@@ -778,121 +1220,131 @@
|
|
|
778
1220
|
; device().requestDevice({requiredLimits}); an unsatisfiable value fails loud at
|
|
779
1221
|
; device creation. Also feeds compile-time validation — e.g. raising
|
|
780
1222
|
; :max-compute-workgroup-size-x unlocks @workgroup_size(512). Names are the exact
|
|
781
|
-
; WebGPU GPUSupportedLimits members (kebab here → camelCase on the wire).
|
|
1223
|
+
; WebGPU GPUSupportedLimits members (kebab here → camelCase on the wire).
|
|
782
1224
|
(form :name limits
|
|
783
1225
|
:description "Authored WebGPU device requiredLimits (optional singleton)."
|
|
784
|
-
(key :name max-texture-dimension-1d :type device-limit
|
|
1226
|
+
(key :name max-texture-dimension-1d :type device-limit :optional true
|
|
785
1227
|
:description "Max width of a 1D texture (default 8192).")
|
|
786
|
-
(key :name max-texture-dimension-2d :type device-limit
|
|
1228
|
+
(key :name max-texture-dimension-2d :type device-limit :optional true
|
|
787
1229
|
:description "Max width/height of a 2D texture (default 8192).")
|
|
788
|
-
(key :name max-texture-dimension-3d :type device-limit
|
|
1230
|
+
(key :name max-texture-dimension-3d :type device-limit :optional true
|
|
789
1231
|
:description "Max width/height/depth of a 3D texture (default 2048).")
|
|
790
|
-
(key :name max-texture-array-layers :type device-limit
|
|
1232
|
+
(key :name max-texture-array-layers :type device-limit :optional true
|
|
791
1233
|
:description "Max array layers of a 2D texture (default 256).")
|
|
792
|
-
(key :name max-bind-groups :type device-limit
|
|
1234
|
+
(key :name max-bind-groups :type device-limit :optional true
|
|
793
1235
|
:description "Max simultaneous bind groups (default 4).")
|
|
794
|
-
(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
|
|
795
1237
|
:description "Max bind groups + vertex buffers combined (default 24).")
|
|
796
|
-
(key :name max-bindings-per-bind-group :type device-limit
|
|
1238
|
+
(key :name max-bindings-per-bind-group :type device-limit :optional true
|
|
797
1239
|
:description "Max bindings in a single bind group (default 1000).")
|
|
798
|
-
(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
|
|
799
1241
|
:description "Max dynamic-offset uniform buffers per pipeline layout (default 8).")
|
|
800
|
-
(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
|
|
801
1243
|
:description "Max dynamic-offset storage buffers per pipeline layout (default 4).")
|
|
802
|
-
(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
|
|
803
1245
|
:description "Max sampled textures per shader stage (default 16).")
|
|
804
|
-
(key :name max-samplers-per-shader-stage :type device-limit
|
|
1246
|
+
(key :name max-samplers-per-shader-stage :type device-limit :optional true
|
|
805
1247
|
:description "Max samplers per shader stage (default 16).")
|
|
806
|
-
(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
|
|
807
1249
|
:description "Max storage buffers per shader stage (default 8).")
|
|
808
|
-
(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
|
|
809
1251
|
:description "Max storage buffers in the vertex stage (compat split-stage limit; default 8).")
|
|
810
|
-
(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
|
|
811
1253
|
:description "Max storage buffers in the fragment stage (compat split-stage limit; default 8).")
|
|
812
|
-
(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
|
|
813
1255
|
:description "Max storage textures per shader stage (default 4).")
|
|
814
|
-
(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
|
|
815
1257
|
:description "Max storage textures in the vertex stage (compat split-stage limit; default 4).")
|
|
816
|
-
(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
|
|
817
1259
|
:description "Max storage textures in the fragment stage (compat split-stage limit; default 4).")
|
|
818
|
-
(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
|
|
819
1263
|
:description "Max uniform buffers per shader stage (default 12).")
|
|
820
|
-
(key :name max-uniform-buffer-binding-size :type device-limit
|
|
1264
|
+
(key :name max-uniform-buffer-binding-size :type device-limit :optional true
|
|
821
1265
|
:description "Max bound range of a uniform buffer in bytes (default 65536).")
|
|
822
|
-
(key :name max-storage-buffer-binding-size :type device-limit
|
|
1266
|
+
(key :name max-storage-buffer-binding-size :type device-limit :optional true
|
|
823
1267
|
:description "Max bound range of a storage buffer in bytes (default 134217728).")
|
|
824
|
-
(key :name min-uniform-buffer-offset-alignment :type device-limit
|
|
1268
|
+
(key :name min-uniform-buffer-offset-alignment :type device-limit :optional true
|
|
825
1269
|
:description "Required alignment of a dynamic uniform buffer offset (default 256).")
|
|
826
|
-
(key :name min-storage-buffer-offset-alignment :type device-limit
|
|
1270
|
+
(key :name min-storage-buffer-offset-alignment :type device-limit :optional true
|
|
827
1271
|
:description "Required alignment of a dynamic storage buffer offset (default 256).")
|
|
828
|
-
(key :name max-vertex-buffers :type device-limit
|
|
1272
|
+
(key :name max-vertex-buffers :type device-limit :optional true
|
|
829
1273
|
:description "Max vertex buffers in a render pipeline (default 8).")
|
|
830
|
-
(key :name max-buffer-size :type device-limit
|
|
1274
|
+
(key :name max-buffer-size :type device-limit :optional true
|
|
831
1275
|
:description "Max size of a buffer in bytes (default 268435456).")
|
|
832
|
-
(key :name max-vertex-attributes :type device-limit
|
|
1276
|
+
(key :name max-vertex-attributes :type device-limit :optional true
|
|
833
1277
|
:description "Max vertex attributes across all buffers (default 16).")
|
|
834
|
-
(key :name max-vertex-buffer-array-stride :type device-limit
|
|
1278
|
+
(key :name max-vertex-buffer-array-stride :type device-limit :optional true
|
|
835
1279
|
:description "Max stride of a vertex buffer in bytes (default 2048).")
|
|
836
|
-
(key :name max-inter-stage-shader-variables :type device-limit
|
|
1280
|
+
(key :name max-inter-stage-shader-variables :type device-limit :optional true
|
|
837
1281
|
:description "Max inter-stage shader variables (default 16).")
|
|
838
|
-
(key :name max-color-attachments :type device-limit
|
|
1282
|
+
(key :name max-color-attachments :type device-limit :optional true
|
|
839
1283
|
:description "Max color attachments in a render pass (default 8).")
|
|
840
|
-
(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
|
|
841
1285
|
:description "Max total bytes per sample across color attachments (default 32).")
|
|
842
|
-
(key :name max-compute-workgroup-storage-size :type device-limit
|
|
1286
|
+
(key :name max-compute-workgroup-storage-size :type device-limit :optional true
|
|
843
1287
|
:description "Max var<workgroup> storage in bytes (default 16384).")
|
|
844
|
-
(key :name max-compute-invocations-per-workgroup :type device-limit
|
|
1288
|
+
(key :name max-compute-invocations-per-workgroup :type device-limit :optional true
|
|
845
1289
|
:description "Max x*y*z of a compute @workgroup_size (default 256).")
|
|
846
|
-
(key :name max-compute-workgroup-size-x :type device-limit
|
|
1290
|
+
(key :name max-compute-workgroup-size-x :type device-limit :optional true
|
|
847
1291
|
:description "Max X of a compute @workgroup_size (default 256).")
|
|
848
|
-
(key :name max-compute-workgroup-size-y :type device-limit
|
|
1292
|
+
(key :name max-compute-workgroup-size-y :type device-limit :optional true
|
|
849
1293
|
:description "Max Y of a compute @workgroup_size (default 256).")
|
|
850
|
-
(key :name max-compute-workgroup-size-z :type device-limit
|
|
1294
|
+
(key :name max-compute-workgroup-size-z :type device-limit :optional true
|
|
851
1295
|
:description "Max Z of a compute @workgroup_size (default 64).")
|
|
852
|
-
(key :name max-compute-workgroups-per-dimension :type device-limit
|
|
1296
|
+
(key :name max-compute-workgroups-per-dimension :type device-limit :optional true
|
|
853
1297
|
:description "Max dispatchWorkgroups count per dimension (default 65535)."))
|
|
854
1298
|
|
|
855
1299
|
(form :name canvas
|
|
856
1300
|
:description "Canvas presentation configuration (optional singleton). Carried as a
|
|
857
1301
|
header flag, consumed by the JS runtime at context.configure() before
|
|
858
|
-
the executor runs. Form absent →
|
|
859
|
-
|
|
1302
|
+
the executor runs. Form absent → opaque, as
|
|
1303
|
+
GPUCanvasConfiguration.alphaMode. Write (canvas :alpha-mode
|
|
1304
|
+
premultiplied) for a canvas the page shows through.
|
|
860
1305
|
Native --frame renders offscreen and ignores it. viewFormats/
|
|
861
|
-
colorSpace/toneMapping are
|
|
862
|
-
chained header table, the 3 reserved header bytes
|
|
863
|
-
by the device-limits offset
|
|
864
|
-
(key :name alpha-mode :type canvas-alpha-mode :default
|
|
865
|
-
: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."))
|
|
866
1311
|
|
|
867
1312
|
(form :name shader-module
|
|
868
1313
|
:description "A named WGSL module. The source is opaque text to SJON."
|
|
869
1314
|
(key :name name :type symbol
|
|
870
|
-
:description "Module name referenced by pipeline
|
|
1315
|
+
:description "Module name referenced by a pipeline stage's :module key.")
|
|
871
1316
|
(key :name code :type string
|
|
872
|
-
:description "WGSL source text
|
|
1317
|
+
:description "WGSL source text, kept verbatim (a triple-quoted string's indentation is part of the shader)."))
|
|
873
1318
|
|
|
874
1319
|
(form :name data
|
|
875
1320
|
:description "Binary data: an inline float32 array, a positional shape sub-form
|
|
876
|
-
(cube/teapot/…) the emitter expands to vertex bytes, or a `:
|
|
1321
|
+
(cube/teapot/…) the emitter expands to vertex bytes, or a `:file`
|
|
877
1322
|
image file the emitter reads from disk and embeds as
|
|
878
1323
|
[mime_len][mime][bytes] (consumed by an image-bitmap)."
|
|
879
1324
|
:positional data-shape-section
|
|
880
1325
|
(key :name name :type symbol
|
|
881
|
-
:description "Data name referenced by buffer :
|
|
1326
|
+
:description "Data name referenced by buffer :data / :index-of and image-bitmap :data.")
|
|
882
1327
|
(key :name float32 :type float-list :optional true
|
|
883
1328
|
:description "Inline float32 array embedded little-endian in the payload.")
|
|
884
|
-
(key :name
|
|
1329
|
+
(key :name file :type file-path :optional true
|
|
885
1330
|
:description "Image file path (relative to the source file) embedded as [mime_len][mime][bytes]; decoded at runtime via createImageBitmap.")
|
|
886
1331
|
(key :name mime :type string :optional true
|
|
887
|
-
: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])))
|
|
888
1340
|
|
|
889
1341
|
(form :name image-bitmap
|
|
890
|
-
: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."
|
|
891
1343
|
(key :name name :type symbol)
|
|
892
|
-
(key :name
|
|
893
|
-
:description "The (data … :
|
|
1344
|
+
(key :name data :type data-ref
|
|
1345
|
+
:description "The (data … :file …) entry holding the encoded image bytes."))
|
|
894
1346
|
|
|
895
|
-
; ---- shape sub-forms (positional children of
|
|
1347
|
+
; ---- shape sub-forms (positional children of `(data …)`) ----
|
|
896
1348
|
; `:open true` so generator-specific numeric config (segments, rings, radius,
|
|
897
1349
|
; thickness, …) is accepted without enumerating it per shape; the emitter reads
|
|
898
1350
|
; the keys it knows. Indexed shapes (teapot, dragon) also produce `_indices`.
|
|
@@ -923,42 +1375,34 @@
|
|
|
923
1375
|
|
|
924
1376
|
(form :name wasm-data
|
|
925
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."
|
|
926
|
-
(key :name
|
|
927
|
-
: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.")
|
|
928
1380
|
(key :name func :type symbol
|
|
929
1381
|
:description "Exported function called once to produce the bytes.")
|
|
930
1382
|
(key :name returns :type string
|
|
931
1383
|
:description "Return type → byte count (e.g. array<f32,360> → 1440)."))
|
|
932
1384
|
|
|
933
1385
|
(form :name texture
|
|
934
|
-
:description "GPU texture. `:size
|
|
935
|
-
|
|
936
|
-
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."
|
|
937
1389
|
(key :name name :type symbol)
|
|
938
|
-
(key :name size :type texture-size
|
|
939
|
-
:description "
|
|
940
|
-
(key :name size-from :type image-bitmap-ref :optional true
|
|
941
|
-
:description "Take width/height from a decoded (image-bitmap …) at runtime (mutually exclusive with :size).")
|
|
942
|
-
(key :name width :type byte-count :optional true
|
|
943
|
-
:description "Texel width (when not sized by :size canvas or :size-from).")
|
|
944
|
-
(key :name height :type byte-count :optional true
|
|
945
|
-
: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.")
|
|
946
1392
|
(key :name format :type texture-format
|
|
947
1393
|
:description "Texel format of the texture.")
|
|
948
1394
|
(key :name usage :type texture-usage-list
|
|
949
1395
|
:description "Allowed texture usages (at least one).")
|
|
950
|
-
(key :name sample-count :type
|
|
1396
|
+
(key :name sample-count :type u32 :optional true
|
|
951
1397
|
:description "Samples per texel: 1 (default) or 4 (MSAA). >1 requires render-attachment usage and a resolve-target on the pass.")
|
|
952
1398
|
(key :name dimension :type texture-dimension :optional true
|
|
953
|
-
:description "Texture dimensionality:
|
|
954
|
-
(key :name depth-or-array-layers :type subresource-count :optional true
|
|
955
|
-
: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.")
|
|
956
1400
|
(key :name mip-level-count :type subresource-count :optional true
|
|
957
1401
|
:description "GPUTextureDescriptor.mipLevelCount — number of mip levels to allocate (default 1). Levels beyond what's written stay uninitialized until generated.")
|
|
958
1402
|
(key :name pool :type pool-size :optional true
|
|
959
1403
|
:description "Create N sequential texture ids for ping-pong (actual id = base + (frame + offset) % N)."))
|
|
960
1404
|
|
|
961
|
-
; ---- explicit texture view (create_texture_view, opcode
|
|
1405
|
+
; ---- explicit texture view (create_texture_view, opcode 0x0C) ----
|
|
962
1406
|
; A (texture …) bound directly gets a default 2d view; sampling a 1d/3d/array/
|
|
963
1407
|
; cube texture needs an explicit view whose dimension matches the WGSL binding.
|
|
964
1408
|
; Emitted after textures, before bind groups; `(entry :texture-view v)` binds it.
|
|
@@ -969,8 +1413,8 @@
|
|
|
969
1413
|
(key :name name :type symbol)
|
|
970
1414
|
(key :name texture :type texture-ref
|
|
971
1415
|
:description "Source texture this view aliases.")
|
|
972
|
-
(key :name
|
|
973
|
-
: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.")
|
|
974
1418
|
(key :name aspect :type texture-aspect :optional true
|
|
975
1419
|
:description "Which aspect(s) of a depth/stencil texture the view exposes (default all).")
|
|
976
1420
|
(key :name base-mip-level :type subresource-index :optional true
|
|
@@ -990,20 +1434,20 @@
|
|
|
990
1434
|
indexed shape's (teapot/dragon) index data — avoids a synthetic
|
|
991
1435
|
`_indices` data symbol the SJON cross-ref validator can't resolve."
|
|
992
1436
|
(key :name name :type symbol)
|
|
993
|
-
(key :name size :type byte-
|
|
994
|
-
: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.")
|
|
995
1439
|
(key :name usage :type usage-list
|
|
996
|
-
: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.")
|
|
997
1441
|
(key :name pool :type pool-size :optional true
|
|
998
1442
|
:description "Create N sequential buffer ids for ping-pong (actual id = base + (frame + offset) % N).")
|
|
999
|
-
(key :name
|
|
1000
|
-
: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.")
|
|
1001
1445
|
(key :name index-of :type data-ref :optional true
|
|
1002
|
-
: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.")
|
|
1003
1447
|
(key :name index-format :type index-format :optional true
|
|
1004
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).")
|
|
1005
|
-
(key :name
|
|
1006
|
-
: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
|
|
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."))
|
|
1007
1451
|
|
|
1008
1452
|
; Emitter packs a [type:u8][count:u16-LE] descriptor blob → create_query_set.
|
|
1009
1453
|
(form :name query-set
|
|
@@ -1011,11 +1455,12 @@
|
|
|
1011
1455
|
(key :name name :type symbol)
|
|
1012
1456
|
(key :name type :type query-type
|
|
1013
1457
|
:description "What each query measures: occlusion or timestamp.")
|
|
1014
|
-
(key :name count :type count
|
|
1015
|
-
: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)."))
|
|
1016
1460
|
|
|
1017
1461
|
(form :name queue
|
|
1018
|
-
: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
|
|
1019
1464
|
frames that reference it."
|
|
1020
1465
|
:positional queue-action
|
|
1021
1466
|
(key :name name :type symbol))
|
|
@@ -1024,68 +1469,91 @@
|
|
|
1024
1469
|
:description "Queue op: write bytes into a buffer before/within a frame (GPUQueue.writeBuffer)."
|
|
1025
1470
|
(key :name buffer :type buffer-ref
|
|
1026
1471
|
:description "Destination buffer (needs copy-dst usage).")
|
|
1027
|
-
(key :name offset :type byte-count :default 0
|
|
1472
|
+
(key :name offset :type byte-count-4-aligned :default 0
|
|
1028
1473
|
:description "Byte offset into the destination (WebGPU requires a multiple of 4).")
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
(alt :keys [data])
|
|
1036
|
-
(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)."))
|
|
1037
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.
|
|
1038
1495
|
(form :name copy-texture-to-texture
|
|
1039
1496
|
:description "Queue op: GPU texture→texture copy. context-current-texture names the canvas; otherwise a (texture …) name."
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
:
|
|
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.")))
|
|
1044
1506
|
|
|
1045
1507
|
(form :name copy-external-image-to-texture
|
|
1046
1508
|
:description "Queue op: upload a decoded image (image-bitmap) into a texture. mip-level / origin default to 0 per the WebGPU spec."
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
:
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
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).")))
|
|
1055
1522
|
|
|
1056
1523
|
(form :name resolve-query-set
|
|
1057
1524
|
:description "Queue op: copy resolved query results from a query set into a buffer (GPUCommandEncoder.resolveQuerySet)."
|
|
1058
1525
|
(key :name query-set :type query-set-ref
|
|
1059
1526
|
:description "The query set to resolve.")
|
|
1060
|
-
(key :name first-query :type
|
|
1527
|
+
(key :name first-query :type u32 :default 0
|
|
1061
1528
|
:description "Index of the first query to resolve.")
|
|
1062
|
-
(key :name query-count :type
|
|
1529
|
+
(key :name query-count :type u32
|
|
1063
1530
|
:description "Number of queries to resolve; each resolves to 8 bytes.")
|
|
1064
1531
|
(key :name destination :type buffer-ref
|
|
1065
1532
|
:description "Destination buffer; must have query-resolve usage.")
|
|
1066
|
-
(key :name destination-offset :type byte-count :default 0
|
|
1533
|
+
(key :name destination-offset :type byte-count-256-aligned :default 0
|
|
1067
1534
|
:description "Byte offset into the destination (WebGPU requires a multiple of 256)."))
|
|
1068
1535
|
|
|
1069
1536
|
(form :name copy-buffer-to-buffer
|
|
1070
1537
|
:description "Queue op: GPU buffer→buffer copy (e.g. resolved queries → a map-read readback buffer)."
|
|
1071
1538
|
(key :name source :type buffer-ref
|
|
1072
1539
|
:description "Source buffer (needs copy-src usage).")
|
|
1073
|
-
(key :name source-offset :type byte-count :default 0
|
|
1540
|
+
(key :name source-offset :type byte-count-4-aligned :default 0
|
|
1074
1541
|
:description "Byte offset into the source (multiple of 4).")
|
|
1075
1542
|
(key :name destination :type buffer-ref
|
|
1076
1543
|
:description "Destination buffer (needs copy-dst usage).")
|
|
1077
|
-
(key :name destination-offset :type byte-count :default 0
|
|
1544
|
+
(key :name destination-offset :type byte-count-4-aligned :default 0
|
|
1078
1545
|
:description "Byte offset into the destination (multiple of 4).")
|
|
1079
|
-
(key :name size :type byte-count
|
|
1546
|
+
(key :name size :type byte-count-4-aligned
|
|
1080
1547
|
:description "Bytes to copy (multiple of 4)."))
|
|
1081
1548
|
|
|
1082
|
-
; The legacy nests `module={ url=… }`; SJON flattens to `:
|
|
1083
|
-
;
|
|
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".
|
|
1084
1552
|
(form :name wasm-call
|
|
1085
|
-
: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."
|
|
1086
1554
|
(key :name name :type symbol)
|
|
1087
|
-
(key :name
|
|
1088
|
-
: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).")
|
|
1089
1557
|
(key :name func :type symbol
|
|
1090
1558
|
:description "Exported function to call at frame time.")
|
|
1091
1559
|
(key :name returns :type string
|
|
@@ -1095,30 +1563,32 @@
|
|
|
1095
1563
|
|
|
1096
1564
|
(form :name bind-group
|
|
1097
1565
|
:description "Bind group. `pool` + per-entry `ping-pong` drive ping-pong. The
|
|
1098
|
-
layout is a pipeline's auto-layout
|
|
1099
|
-
(bind-group-layout …)
|
|
1100
|
-
(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."
|
|
1101
1568
|
:positional bind-entry-item
|
|
1102
1569
|
(key :name name :type symbol)
|
|
1103
|
-
(key :name layout
|
|
1104
|
-
:description "The
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
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 …).")
|
|
1109
1582
|
(key :name pool :type pool-size :optional true
|
|
1110
1583
|
:description "Create N sequential bind-group ids for ping-pong selection.")
|
|
1111
|
-
;
|
|
1112
|
-
; (bind-group-layout …). Declarative replacement for the emit-time check.
|
|
1113
|
-
(exclusive-group :cardinality exactly-one
|
|
1114
|
-
(alt :keys [layout-pipeline])
|
|
1115
|
-
(alt :keys [bind-group-layout]))
|
|
1116
|
-
; 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)`.
|
|
1117
1585
|
; Resolved LOCAL-FIRST under bind-group, so this `entry` is distinct from the
|
|
1118
|
-
;
|
|
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.)
|
|
1119
1589
|
(form :name entry
|
|
1120
|
-
:description "One bind-group entry: binding → buffer | sampler | texture resource
|
|
1121
|
-
(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)."
|
|
1122
1592
|
(key :name binding :type binding-index
|
|
1123
1593
|
:description "Binding slot matching @binding(N) in the WGSL.")
|
|
1124
1594
|
(key :name buffer :type buffer-ref :optional true
|
|
@@ -1129,9 +1599,11 @@
|
|
|
1129
1599
|
:description "Bind a (texture …) at this slot via its default 2d view.")
|
|
1130
1600
|
(key :name texture-view :type texture-view-ref :optional true
|
|
1131
1601
|
:description "Bind an explicit (texture-view …) at this slot — for 1d/3d/array/cube sampling.")
|
|
1132
|
-
(
|
|
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]
|
|
1133
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).")
|
|
1134
|
-
(key :name size :type byte-count :optional true
|
|
1606
|
+
(key :name size :type byte-count :optional true :requires [buffer]
|
|
1135
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).")
|
|
1136
1608
|
(key :name ping-pong :type binding-index :optional true
|
|
1137
1609
|
:description "Pool offset for this entry: actual id = base + (frame + offset) % pool.")
|
|
@@ -1142,31 +1614,14 @@
|
|
|
1142
1614
|
(alt :keys [texture])
|
|
1143
1615
|
(alt :keys [texture-view]))))
|
|
1144
1616
|
|
|
1145
|
-
; Head-resolution target for the `(bind-group-layout entry (storage-texture …))`
|
|
1146
|
-
; slot-local form below. WebGPU has no standalone storage-texture resource (a
|
|
1147
|
-
; storage texture is a (texture … :usage [storage-binding])); this global form
|
|
1148
|
-
; exists only so the `bgl-resource` head-set resolves `storage-texture` to a form,
|
|
1149
|
-
; exactly as `buffer`/`sampler`/`texture` resolve to their global resource forms.
|
|
1150
|
-
; It has no emitter phase — never walked at top level — so the real fields live in
|
|
1151
|
-
; the slot-local form; this one just satisfies the head lookup.
|
|
1152
|
-
(form :name storage-texture
|
|
1153
|
-
:description "Storage-texture layout resource (authored inside (bind-group-layout entry …), not at top level)."
|
|
1154
|
-
(key :name name :type symbol :optional true)
|
|
1155
|
-
(key :name format :type texture-format :optional true
|
|
1156
|
-
:description "Texel format of the storage texture.")
|
|
1157
|
-
(key :name access :type storage-texture-access :optional true
|
|
1158
|
-
:description "Access mode (default write-only).")
|
|
1159
|
-
(key :name view-dimension :type view-dimension :optional true
|
|
1160
|
-
:description "View dimension (default 2d)."))
|
|
1161
|
-
|
|
1162
1617
|
; ---- explicit bind-group-layout (uniform_access) ----
|
|
1163
1618
|
; → create_bind_group_layout (opcode 0x06), emitted between samplers and
|
|
1164
1619
|
; pipelines (the legacy phase position). Buffer, sampler, texture, and storage-
|
|
1165
|
-
; texture bindings are modeled. Entries and their resource are SLOT-LOCAL
|
|
1166
|
-
;
|
|
1620
|
+
; texture bindings are modeled. Entries and their resource are SLOT-LOCAL
|
|
1621
|
+
; forms: `(entry …)` and its nested `(buffer|sampler|texture|storage-texture …)`,
|
|
1167
1622
|
; resolved local-first so the natural names don't collide with the global forms.
|
|
1168
1623
|
(form :name bind-group-layout
|
|
1169
|
-
: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."
|
|
1170
1625
|
:positional bgl-entry-item
|
|
1171
1626
|
(key :name name :type symbol)
|
|
1172
1627
|
(form :name entry
|
|
@@ -1176,13 +1631,13 @@
|
|
|
1176
1631
|
:description "Binding slot matching @binding(N) in the WGSL.")
|
|
1177
1632
|
(key :name visibility :type visibility-list
|
|
1178
1633
|
:description "Shader stages that may access this binding (ORed into the WebGPU mask: vertex 0x1, fragment 0x2, compute 0x4).")
|
|
1179
|
-
; Nested slot-local
|
|
1634
|
+
; Nested slot-local resource form: `(buffer :type T)`. Resolved
|
|
1180
1635
|
; local-first under the layout entry, distinct from the global `buffer`.
|
|
1181
1636
|
(form :name buffer
|
|
1182
1637
|
:description "Buffer resource of a layout entry."
|
|
1183
|
-
(key :name type :type buffer-binding-type
|
|
1184
|
-
:description "How the buffer is exposed to WGSL: uniform, storage, or read-only-storage."))
|
|
1185
|
-
; 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-
|
|
1186
1641
|
; objects flow verbatim through gpu.js/--html; native's create_bind_group_layout
|
|
1187
1642
|
; parser reads each field string-for-string.
|
|
1188
1643
|
(form :name sampler
|
|
@@ -1194,7 +1649,7 @@
|
|
|
1194
1649
|
(key :name sample-type :type texture-sample-type :optional true
|
|
1195
1650
|
:description "Sample type of the bound texture (default float).")
|
|
1196
1651
|
(key :name view-dimension :type view-dimension :optional true
|
|
1197
|
-
:description "View dimension:
|
|
1652
|
+
:description "View dimension: 1d, 2d, 2d-array, cube, cube-array or 3d (default 2d).")
|
|
1198
1653
|
(key :name multisampled :type boolean :optional true
|
|
1199
1654
|
:description "Whether the binding is a multisampled texture (default false)."))
|
|
1200
1655
|
(form :name storage-texture
|
|
@@ -1209,24 +1664,24 @@
|
|
|
1209
1664
|
; ---- explicit pipeline-layout ----
|
|
1210
1665
|
; → create_pipeline_layout (opcode 0x07), emitted between bind-group-layouts and
|
|
1211
1666
|
; pipelines. Composes N (bind-group-layout …) into a GPUPipelineLayout that a
|
|
1212
|
-
; (render-pipeline …)/(compute-pipeline …)
|
|
1213
|
-
;
|
|
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
|
|
1214
1669
|
; DIFFERENT explicit layouts (auto derives a single implicit layout per pipeline).
|
|
1215
1670
|
(form :name pipeline-layout
|
|
1216
|
-
: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."
|
|
1217
1672
|
(key :name name :type symbol)
|
|
1218
1673
|
(key :name bind-group-layouts :type bind-group-layout-ref-list
|
|
1219
1674
|
:description "The (bind-group-layout …) forms at @group 0, 1, … in order."))
|
|
1220
1675
|
|
|
1221
1676
|
(form :name sampler
|
|
1222
|
-
:description "GPU sampler.
|
|
1677
|
+
:description "GPU sampler. Defaults match GPUSamplerDescriptor: filters nearest, address-mode clamp-to-edge."
|
|
1223
1678
|
(key :name name :type symbol)
|
|
1224
|
-
(key :name mag-filter :type filter-mode :default
|
|
1225
|
-
:description "Magnification filter — sampling when one texel covers many pixels.
|
|
1226
|
-
(key :name min-filter :type filter-mode :default
|
|
1227
|
-
: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.")
|
|
1228
1683
|
(key :name address-mode :type address-mode :optional true
|
|
1229
|
-
: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.")
|
|
1230
1685
|
(key :name address-mode-u :type address-mode :optional true
|
|
1231
1686
|
:description "Addressing for the U (S) axis; overrides :address-mode for this axis.")
|
|
1232
1687
|
(key :name address-mode-v :type address-mode :optional true
|
|
@@ -1234,85 +1689,133 @@
|
|
|
1234
1689
|
(key :name address-mode-w :type address-mode :optional true
|
|
1235
1690
|
:description "Addressing for the W (R) axis; overrides :address-mode for this axis (3D / cube sampling).")
|
|
1236
1691
|
(key :name mipmap-filter :type filter-mode :optional true
|
|
1237
|
-
: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.")
|
|
1238
1693
|
(key :name lod-min-clamp :type lod-clamp :optional true
|
|
1239
1694
|
:description "Minimum mip level of detail the sampler will use (default 0).")
|
|
1240
1695
|
(key :name lod-max-clamp :type lod-clamp :optional true
|
|
1241
1696
|
:description "Maximum mip level of detail the sampler will use (default 32).")
|
|
1242
|
-
(key :name max-anisotropy :type anisotropy
|
|
1697
|
+
(key :name max-anisotropy :type anisotropy :optional true
|
|
1243
1698
|
:description "Maximum anisotropy for filtering; values > 1 require linear mag/min/mipmap filters.")
|
|
1244
1699
|
(key :name compare :type compare-function :optional true
|
|
1245
1700
|
:description "Comparison function — makes this a comparison sampler (e.g. depth shadow sampling)."))
|
|
1246
1701
|
|
|
1247
|
-
; pngine/pass-v1
|
|
1248
|
-
; (via EmittedForm positional children), so the render-pipeline descriptor has
|
|
1249
|
-
; path.
|
|
1250
|
-
; they emitted `"targetFormat":FMT` where the authored shape emits
|
|
1251
|
-
; `"targets":[{format…}]` — a difference that was load-bearing only against the
|
|
1252
|
-
; now-deleted `.pngine` parity baseline; the runtime (gpu.js) normalizes both.
|
|
1702
|
+
; pngine/pass-v1 authors the canonical positional (vertex …)(fragment …) shape
|
|
1703
|
+
; (via EmittedForm positional children), so the render-pipeline descriptor has
|
|
1704
|
+
; one path.
|
|
1253
1705
|
(form :name render-pipeline
|
|
1254
|
-
:description "GPU render pipeline. Positional (
|
|
1706
|
+
:description "GPU render pipeline. Positional (vertex …)(fragment …)(primitive …)(depth-stencil …)(multisample …) sections mirror GPURenderPipelineDescriptor."
|
|
1255
1707
|
:positional pipeline-section
|
|
1256
1708
|
(key :name name :type symbol)
|
|
1257
|
-
|
|
1258
|
-
|
|
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 …)."))
|
|
1259
1713
|
|
|
1260
|
-
; compute-pipeline is flat (no positional sections) — natural, not a workaround:
|
|
1261
|
-
; a compute pipeline is just module + entry, with no vertex/fragment stages to
|
|
1262
|
-
; nest. The `pngine/init-v1` hook emits one; the flat kvpair shape is correct
|
|
1263
|
-
; as-is (the positional-slot limitation it once worked around was lifted in SJON
|
|
1264
|
-
; 2026-06, but compute-pipeline never needed positional children anyway).
|
|
1265
1714
|
(form :name compute-pipeline
|
|
1266
|
-
:description "GPU compute pipeline:
|
|
1715
|
+
:description "GPU compute pipeline: one positional (compute …) stage naming the WGSL module and its @compute entry point."
|
|
1716
|
+
:positional compute-pipeline-section
|
|
1267
1717
|
(key :name name :type symbol)
|
|
1268
|
-
(key :name
|
|
1269
|
-
:description "
|
|
1270
|
-
(key :name entry :type entry-point :optional true
|
|
1271
|
-
:description "Entry-point function name (defaults to the module's sole @compute fn).")
|
|
1272
|
-
(key :name pipeline-layout :type pipeline-layout-ref :optional true
|
|
1273
|
-
: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 …)."))
|
|
1274
1720
|
|
|
1275
|
-
; ----
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
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.
|
|
1279
1727
|
(form :name vertex
|
|
1280
|
-
:description "Vertex stage:
|
|
1281
|
-
: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)."))
|
|
1282
1734
|
(form :name fragment
|
|
1283
|
-
:description "Fragment stage:
|
|
1284
|
-
: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)."))
|
|
1748
|
+
; Authored per STAGE, mirroring WebGPU's GPUProgrammableStage.constants and
|
|
1749
|
+
; the per-entry-point reflection — but RESOLVED per module, because pngine
|
|
1750
|
+
; specialises the shader text at compile time instead of passing a constants
|
|
1751
|
+
; dict to a runtime. Two stages that specialise one module differently are
|
|
1752
|
+
; refused rather than silently duplicating the module.
|
|
1753
|
+
(form :name constant
|
|
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."
|
|
1755
|
+
(key :name name :type override-name
|
|
1756
|
+
:description "The WGSL `override` identifier this value is for.")
|
|
1757
|
+
(key :name value :type override-number
|
|
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."))
|
|
1285
1759
|
(form :name primitive
|
|
1286
|
-
:description "Primitive assembly state
|
|
1287
|
-
|
|
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.")
|
|
1288
1784
|
(key :name cull-mode :type cull-mode :optional true
|
|
1289
1785
|
:description "Which faces are discarded (WebGPU default: none).")
|
|
1290
1786
|
(key :name front-face :type front-face :optional true
|
|
1291
1787
|
:description "Winding that counts as front-facing (WebGPU default: ccw).")
|
|
1292
|
-
(key :name strip-index-format :type index-format :optional true
|
|
1293
|
-
: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).")
|
|
1294
1788
|
(key :name unclipped-depth :type boolean :optional true
|
|
1295
|
-
:description "Disable depth clipping (clamp fragments to [0,1] instead of discarding them); needs the depth-clip-control device feature (WebGPU default: false).")
|
|
1296
|
-
|
|
1297
|
-
|
|
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.
|
|
1298
1798
|
(form :name depth-stencil
|
|
1299
1799
|
:description "Depth/stencil pipeline state. Positional (stencil-front …)/(stencil-back …) carry per-face stencil state."
|
|
1300
1800
|
:positional depth-stencil-section
|
|
1301
|
-
|
|
1302
|
-
|
|
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.")
|
|
1303
1806
|
(key :name depth-write-enabled :type boolean :optional true
|
|
1304
|
-
: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.")
|
|
1305
1808
|
(key :name depth-compare :type compare-function :optional true
|
|
1306
|
-
:description "Comparison the depth test applies (fragment depth vs stored depth).")
|
|
1307
|
-
(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
|
|
1308
1811
|
:description "Constant bias added to fragment depth — shadow maps / depth pre-pass (triangles only).")
|
|
1309
|
-
(key :name depth-bias-slope-scale :type depth-bias
|
|
1812
|
+
(key :name depth-bias-slope-scale :type depth-bias :optional true
|
|
1310
1813
|
:description "Bias that scales with the triangle's depth slope (triangles only).")
|
|
1311
|
-
(key :name depth-bias-clamp :type depth-bias
|
|
1814
|
+
(key :name depth-bias-clamp :type depth-bias :optional true
|
|
1312
1815
|
:description "Maximum magnitude of the total depth bias (0 = unclamped).")
|
|
1313
|
-
(key :name stencil-read-mask :type
|
|
1816
|
+
(key :name stencil-read-mask :type mask32 :optional true
|
|
1314
1817
|
:description "Bitmask ANDed with stencil values for tests (spec default 0xFFFFFFFF).")
|
|
1315
|
-
(key :name stencil-write-mask :type
|
|
1818
|
+
(key :name stencil-write-mask :type mask32 :optional true
|
|
1316
1819
|
:description "Bitmask ANDed with stencil writes (spec default 0xFFFFFFFF)."))
|
|
1317
1820
|
; Same key set for front/back; the head selects which face the emitter writes.
|
|
1318
1821
|
(form :name stencil-front
|
|
@@ -1337,28 +1840,16 @@
|
|
|
1337
1840
|
:description "Applied when both stencil and depth tests pass."))
|
|
1338
1841
|
(form :name multisample
|
|
1339
1842
|
:description "Multisample pipeline state (MSAA)."
|
|
1340
|
-
(key :name count :type
|
|
1341
|
-
:description "Samples per pixel: 1 or 4; must match the attachment textures' sample-count.")
|
|
1342
|
-
(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
|
|
1343
1846
|
:description "Sample coverage bitmask (spec default 0xFFFFFFFF).")
|
|
1344
1847
|
(key :name alpha-to-coverage-enabled :type boolean :optional true
|
|
1345
|
-
:description "Fragment alpha generates the coverage mask
|
|
1346
|
-
(form :name module
|
|
1347
|
-
:description "The (shader-module …) this stage executes."
|
|
1348
|
-
:positional module-ref)
|
|
1349
|
-
(form :name entry
|
|
1350
|
-
:description "Entry-point function name within the stage's module."
|
|
1351
|
-
:positional entry-point)
|
|
1352
|
-
(form :name topology
|
|
1353
|
-
:description "How vertices assemble into primitives (WebGPU default: triangle-list)."
|
|
1354
|
-
:positional primitive-topology)
|
|
1355
|
-
(form :name buffers
|
|
1356
|
-
:description "Vertex input layout: one (vertex-buffer …) per bound vertex buffer slot."
|
|
1357
|
-
: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."))
|
|
1358
1849
|
(form :name vertex-buffer
|
|
1359
1850
|
:description "Layout of one vertex buffer slot: stride + step mode + (attribute …) children."
|
|
1360
1851
|
:positional attribute-item
|
|
1361
|
-
(key :name array-stride :type byte-count
|
|
1852
|
+
(key :name array-stride :type byte-count-4-aligned
|
|
1362
1853
|
:description "Bytes between consecutive elements; multiple of 4 (spec baseline limit 2048).")
|
|
1363
1854
|
(key :name step-mode :type step-mode :optional true
|
|
1364
1855
|
:description "Advance per vertex or per instance (WebGPU default: vertex)."))
|
|
@@ -1370,9 +1861,6 @@
|
|
|
1370
1861
|
:description "Byte offset of the attribute within one element.")
|
|
1371
1862
|
(key :name format :type vertex-format
|
|
1372
1863
|
:description "Wire format of the attribute data."))
|
|
1373
|
-
(form :name targets
|
|
1374
|
-
:description "Color targets of the fragment stage: one (target …) per attachment."
|
|
1375
|
-
:positional targets-item)
|
|
1376
1864
|
(form :name target
|
|
1377
1865
|
:description "One color target: format plus optional (blend …) state and write mask."
|
|
1378
1866
|
:positional target-section
|
|
@@ -1381,32 +1869,32 @@
|
|
|
1381
1869
|
(key :name write-mask :type write-mask :optional true
|
|
1382
1870
|
:description "Channel write mask: bitmask R=1 G=2 B=4 A=8, or all (15; the WebGPU default)."))
|
|
1383
1871
|
(form :name blend
|
|
1384
|
-
: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."
|
|
1385
1873
|
:positional blend-section)
|
|
1386
1874
|
(form :name color
|
|
1387
1875
|
:description "Blend component for RGB: out.rgb = operation(src.rgb * src-factor, dst.rgb * dst-factor)."
|
|
1388
|
-
(key :name src-factor :type blend-factor
|
|
1389
|
-
:description "Multiplier on the fragment's color (WebGPU default: one).")
|
|
1390
|
-
(key :name dst-factor :type blend-factor
|
|
1391
|
-
: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.")
|
|
1392
1880
|
(key :name operation :type blend-operation :optional true
|
|
1393
1881
|
:description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
|
|
1394
1882
|
(form :name alpha
|
|
1395
1883
|
:description "Blend component for alpha: out.a = operation(src.a * src-factor, dst.a * dst-factor)."
|
|
1396
|
-
(key :name src-factor :type blend-factor
|
|
1397
|
-
:description "Multiplier on the fragment's alpha (WebGPU default: one).")
|
|
1398
|
-
(key :name dst-factor :type blend-factor
|
|
1399
|
-
: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.")
|
|
1400
1888
|
(key :name operation :type blend-operation :optional true
|
|
1401
1889
|
:description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
|
|
1402
1890
|
|
|
1403
1891
|
; ---- render / compute pass ----
|
|
1404
1892
|
(form :name render-pass
|
|
1405
|
-
: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."
|
|
1406
1894
|
:positional render-pass-section
|
|
1407
1895
|
(key :name name :type symbol)
|
|
1408
1896
|
(key :name occlusion-query-set :type query-set-ref :optional true
|
|
1409
|
-
: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.")
|
|
1410
1898
|
(key :name pipeline :type render-pipeline-ref :optional true
|
|
1411
1899
|
:description "The render pipeline this pass draws with. Omit for a pass that only replays :execute-bundles (the bundle records it).")
|
|
1412
1900
|
(key :name vertex-buffers :type buffer-ref-list :optional true
|
|
@@ -1419,7 +1907,7 @@
|
|
|
1419
1907
|
:description "Bind groups set at @group 0..N in order.")
|
|
1420
1908
|
(key :name bind-groups-pool-offsets :type offset-list :optional true
|
|
1421
1909
|
:description "Per-group ping-pong offsets into each group's pool.")
|
|
1422
|
-
(key :name stencil-reference :type
|
|
1910
|
+
(key :name stencil-reference :type u32 :optional true
|
|
1423
1911
|
:description "Reference value used by stencil compare and the replace operation.")
|
|
1424
1912
|
(key :name blend-constant :type blend-constant-color :optional true
|
|
1425
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.")
|
|
@@ -1428,8 +1916,17 @@
|
|
|
1428
1916
|
(key :name scissor-rect :type pixel-rect :optional true
|
|
1429
1917
|
:description "[x y w h] in integer pixels; fragments outside are discarded.")
|
|
1430
1918
|
(key :name execute-bundles :type render-bundle-ref-list :optional true
|
|
1431
|
-
: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."))
|
|
1432
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.
|
|
1433
1930
|
(form :name color-attachment
|
|
1434
1931
|
:description "One color target of a render pass."
|
|
1435
1932
|
(key :name view :type attachment-view
|
|
@@ -1437,30 +1934,53 @@
|
|
|
1437
1934
|
(key :name resolve-target :type attachment-view :optional true
|
|
1438
1935
|
:description "Receives the resolved single-sample output when :view is multisampled.")
|
|
1439
1936
|
(key :name clear-value :type clear-color :optional true
|
|
1440
|
-
:description "RGBA the attachment is cleared to when load-op is clear (
|
|
1441
|
-
|
|
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
|
|
1442
1945
|
:description "clear to :clear-value, or load the existing contents.")
|
|
1443
|
-
(key :name store-op :type store-op
|
|
1946
|
+
(key :name store-op :type store-op
|
|
1444
1947
|
:description "store the pass result, or discard it."))
|
|
1445
1948
|
|
|
1446
1949
|
; Non-default load/store ops emit a preceding set_pass_depth_stencil_ops
|
|
1447
1950
|
; (matches the legacy path).
|
|
1448
|
-
|
|
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
|
|
1449
1969
|
:description "Depth/stencil target of a render pass."
|
|
1450
1970
|
(key :name view :type texture-ref
|
|
1451
1971
|
:description "The depth/stencil (texture …) this pass tests/writes against.")
|
|
1452
1972
|
(key :name depth-clear-value :type unorm :optional true
|
|
1453
|
-
:description "Depth cleared to when depth-load-op is clear
|
|
1454
|
-
(key :name depth-load-op :type load-op :
|
|
1455
|
-
:description "clear depth to :depth-clear-value, or load the existing depth.")
|
|
1456
|
-
(key :name depth-store-op :type store-op :
|
|
1457
|
-
:description "store the resulting depth, or discard it.")
|
|
1458
|
-
(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
|
|
1459
1979
|
:description "Stencil cleared to when stencil-load-op is clear.")
|
|
1460
1980
|
(key :name stencil-load-op :type load-op :optional true
|
|
1461
|
-
: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.")
|
|
1462
1982
|
(key :name stencil-store-op :type store-op :optional true
|
|
1463
|
-
: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."))
|
|
1464
1984
|
|
|
1465
1985
|
(form :name draw
|
|
1466
1986
|
:description "Non-indexed draw call."
|
|
@@ -1482,7 +2002,7 @@
|
|
|
1482
2002
|
(key :name first-index :type count :default 0
|
|
1483
2003
|
:description "Offset into the index buffer, in indices.")
|
|
1484
2004
|
(key :name base-vertex :type count :default 0
|
|
1485
|
-
: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.")
|
|
1486
2006
|
(key :name first-instance :type count :default 0
|
|
1487
2007
|
:description "First instance index."))
|
|
1488
2008
|
|
|
@@ -1490,73 +2010,95 @@
|
|
|
1490
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."
|
|
1491
2011
|
(key :name buffer :type buffer-ref
|
|
1492
2012
|
:description "Buffer holding the indirect args (needs indirect usage).")
|
|
1493
|
-
(key :name offset :type byte-count :default 0
|
|
1494
|
-
: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)."))
|
|
1495
2015
|
|
|
1496
2016
|
(form :name draw-indexed-indirect
|
|
1497
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."
|
|
1498
2018
|
(key :name buffer :type buffer-ref
|
|
1499
2019
|
:description "Buffer holding the indirect args (needs indirect usage).")
|
|
1500
|
-
(key :name offset :type byte-count :default 0
|
|
1501
|
-
: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)."))
|
|
1502
2022
|
|
|
1503
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.
|
|
1504
2031
|
(form :name timestamp-writes
|
|
1505
2032
|
:description "Record GPU timestamps at pass start/end into a (query-set :type timestamp)."
|
|
1506
2033
|
(key :name query-set :type query-set-ref
|
|
1507
2034
|
:description "The timestamp query set written into.")
|
|
1508
|
-
(key :name
|
|
1509
|
-
:description "Query index written at pass start.")
|
|
1510
|
-
(key :name end :type
|
|
1511
|
-
: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)."))
|
|
1512
2039
|
|
|
1513
2040
|
(form :name occlusion-query
|
|
1514
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."
|
|
1515
2042
|
:positional occlusion-draw-item
|
|
1516
|
-
(key :name query-index :type
|
|
2043
|
+
(key :name query-index :type u32 :default 0
|
|
1517
2044
|
:description "Index within the pass's occlusion query set."))
|
|
1518
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.
|
|
1519
2053
|
(form :name compute-pass
|
|
1520
|
-
: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
|
|
1521
2056
|
(key :name name :type symbol)
|
|
1522
2057
|
(key :name pipeline :type compute-pipeline-ref
|
|
1523
2058
|
:description "The compute pipeline this pass dispatches.")
|
|
1524
2059
|
(key :name bind-groups :type bind-group-ref-list :optional true
|
|
1525
2060
|
:description "Bind groups set at @group 0..N in order.")
|
|
1526
2061
|
(key :name bind-groups-pool-offsets :type offset-list :optional true
|
|
1527
|
-
:description "Per-group ping-pong offsets into each group's pool.")
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
|
|
1533
|
-
: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.")
|
|
1534
|
-
(key :name dispatch-indirect-offset :type byte-count :default 0
|
|
1535
|
-
: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."))
|
|
1536
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.
|
|
1537
2080
|
(form :name render-bundle
|
|
1538
|
-
: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
|
|
1539
2083
|
(key :name name :type symbol)
|
|
1540
|
-
(key :name pipeline :type render-pipeline-ref
|
|
1541
|
-
:description "Pipeline recorded into the bundle (the executing pass omits its own).")
|
|
1542
|
-
|
|
1543
|
-
|
|
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.")
|
|
1544
2092
|
(key :name depth-stencil-format :type texture-format :optional true
|
|
1545
|
-
:description "Depth/stencil format the bundle is recorded against.")
|
|
1546
|
-
(key :name sample-count :type
|
|
1547
|
-
: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.")
|
|
1548
2096
|
(key :name vertex-buffers :type buffer-ref-list :optional true
|
|
1549
2097
|
:description "Buffers bound to vertex slots 0..N in order.")
|
|
1550
2098
|
(key :name bind-groups :type bind-group-ref-list :optional true
|
|
1551
2099
|
:description "Bind groups set at @group 0..N in order.")
|
|
1552
2100
|
(key :name index-buffer :type buffer-ref :optional true
|
|
1553
|
-
:description "Index buffer when the bundle draws indexed.")
|
|
1554
|
-
(key :name draw :type count :optional true
|
|
1555
|
-
:description "Record a non-indexed draw of this many vertices.")
|
|
1556
|
-
(key :name draw-indexed :type count :optional true
|
|
1557
|
-
:description "Record an indexed draw of this many indices.")
|
|
1558
|
-
(key :name instance-count :type count :optional true
|
|
1559
|
-
:description "Instances for the recorded :draw."))
|
|
2101
|
+
:description "Index buffer when the bundle draws indexed."))
|
|
1560
2102
|
|
|
1561
2103
|
(form :name frame
|
|
1562
2104
|
:description "Frame program: what runs each frame, in order."
|
|
@@ -1571,18 +2113,24 @@
|
|
|
1571
2113
|
; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
|
|
1572
2114
|
(form :name init
|
|
1573
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.
|
|
1574
2120
|
:lowering (lowering :hook pngine/init-v1
|
|
1575
|
-
:produces [compute-pipeline bind-group entry compute-pass])
|
|
2121
|
+
:produces [compute-pipeline compute bind-group entry compute-pass dispatch])
|
|
1576
2122
|
(key :name name :type symbol)
|
|
1577
2123
|
(key :name buffer :type buffer-ref
|
|
1578
2124
|
:description "The storage buffer the init compute writes (bound at @binding 0).")
|
|
1579
|
-
(key :name
|
|
2125
|
+
(key :name module :type module-ref
|
|
1580
2126
|
:description "The (shader-module …) holding the @compute init entry.")
|
|
1581
|
-
(
|
|
1582
|
-
|
|
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."))
|
|
1583
2131
|
|
|
1584
2132
|
; =====================================================================
|
|
1585
|
-
;
|
|
2133
|
+
; `(pass …)` sugar — container-lowered by pngine/pass-v1 (Phase 2f)
|
|
1586
2134
|
; =====================================================================
|
|
1587
2135
|
; The author writes (pass-graph (pass …) …). The hook sees every pass through
|
|
1588
2136
|
; the whole-document view, sequences cross-pass texture ids, and emits canonical
|
|
@@ -1594,17 +2142,17 @@
|
|
|
1594
2142
|
(value-kind :name pass-item :underlying form :heads (head-set :names [pass]))
|
|
1595
2143
|
|
|
1596
2144
|
(form :name pass
|
|
1597
|
-
:description "One
|
|
2145
|
+
:description "One `(pass …)`: a fullscreen fragment (or compute) shader-art stage.
|
|
1598
2146
|
The hook detects features from the WGSL (pngine/pointer/feedback)."
|
|
1599
2147
|
(key :name name :type symbol)
|
|
1600
|
-
(key :name code :type string
|
|
1601
|
-
: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.")
|
|
1602
2150
|
(key :name feedback :type boolean :optional true
|
|
1603
2151
|
:description "Ping-pong texture pair for feedback; the previous frame is readable as prev_<name>.")
|
|
1604
2152
|
(key :name init :type string :optional true
|
|
1605
2153
|
:description "One-shot WGSL compute source run on the first frame only.")
|
|
1606
|
-
(key :name
|
|
1607
|
-
: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."))
|
|
1608
2156
|
|
|
1609
2157
|
(form :name pass-graph
|
|
1610
2158
|
:description "Container of (pass …) children lowered as a unit so resource ids
|
|
@@ -1612,7 +2160,7 @@
|
|
|
1612
2160
|
:open true
|
|
1613
2161
|
:positional pass-item
|
|
1614
2162
|
:lowering (lowering :hook pngine/pass-v1
|
|
1615
|
-
:produces [shader-module buffer texture sampler bind-group
|
|
1616
|
-
render-pipeline vertex fragment
|
|
2163
|
+
:produces [shader-module buffer texture sampler bind-group entry
|
|
2164
|
+
render-pipeline vertex fragment target
|
|
1617
2165
|
render-pass color-attachment draw frame
|
|
1618
|
-
compute-pipeline compute-pass queue write-buffer])))
|
|
2166
|
+
compute-pipeline compute compute-pass dispatch queue write-buffer])))
|