pngine 4.2.1 → 4.3.1
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/dist/core.d.ts +14 -0
- package/dist/core.mjs +4 -4
- package/dist/dev.d.ts +13 -1
- package/dist/dev.mjs +1 -1
- package/dist/executor.mjs +1 -1
- package/dist/index.d.ts +13 -1
- package/dist/viewer.d.ts +13 -1
- package/dist/viewer.mjs +1 -1
- package/package.json +7 -7
- package/schema/pngine.sjon +128 -7
- package/src/anim.js +55 -7
- package/src/core.js +11 -0
- package/src/gpu.js +99 -4
- package/src/loader.js +14 -7
- package/src/playback-state.js +47 -10
- package/src/uniform-convert.js +17 -4
- package/src/viewer-init.js +6 -1
- package/src/worker-core.js +80 -11
- package/src/worker-prefetch.js +12 -0
- package/wasm/pngine-compiler.wasm +0 -0
- package/wasm/pngine.wasm +0 -0
package/schema/pngine.sjon
CHANGED
|
@@ -402,6 +402,7 @@
|
|
|
402
402
|
(member :name pngine-inputs :description "16 B: time, canvasWidth, canvasHeight, aspect (all f32). Runtime-provided; there is no authored document declaration to navigate to.")
|
|
403
403
|
(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. Runtime-provided; there is no authored document declaration to navigate to.")
|
|
404
404
|
(member :name pngine-frame-inputs :description "20 B: the 16 B of pngine-inputs, then frameIndex (u32) — the executor's frame counter, which is also the ping-pong pool phase. For a jitter sequence (TAA) or any per-frame rotation. Runtime-provided; there is no authored document declaration to navigate to.")
|
|
405
|
+
(member :name control-inputs :description "4 B per declared `(control …)`, in declaration order; the frame's own `write-buffer` carries them, so a guard and a shader read one value.")
|
|
405
406
|
(member :name pointer-inputs :description "48 B: x, y, clickX, clickY, dx, dy, buttons, pressure, modifiers, scrollX, scrollY, _pad (all f32). Runtime-provided; there is no authored document declaration to navigate to.")))
|
|
406
407
|
; The two ref arms are ONE cross-ref target group, never a union of two ref
|
|
407
408
|
; kinds: a union resolves first-match while the emitter looks the name up in
|
|
@@ -417,6 +418,28 @@
|
|
|
417
418
|
:underlying union
|
|
418
419
|
:union (union-shape :alternatives [builtin-data-source data-or-wasm-ref]))
|
|
419
420
|
|
|
421
|
+
; ---- the guard subject: a builtin control or a declared one ----
|
|
422
|
+
; A `(step-group :when …)` names ONE thing, and the two things it can name
|
|
423
|
+
; live in different tables. The union of a member set and a reference kind is
|
|
424
|
+
; `write-buffer-source`'s shape, not a second mechanism: the arms overlap on
|
|
425
|
+
; the symbol shape, so a name neither accepts reports
|
|
426
|
+
; `union_no_branch_matched` naming both explanations, and a name only the
|
|
427
|
+
; reference arm could mean reports that arm's own `not_cross_ref`. Splitting
|
|
428
|
+
; it into two keys would let an author write both spellings at once.
|
|
429
|
+
(value-kind :name builtin-control
|
|
430
|
+
:description "A control the engine provides every frame. Runtime-provided; there is no authored document declaration to navigate to."
|
|
431
|
+
:underlying symbol
|
|
432
|
+
:members (member-set
|
|
433
|
+
(member :name time :description "The built-in control the engine sets every frame: seconds since the frame program started. Needs no (control …) declaration; the compiler reserves the name, so a declared control cannot shadow it.")))
|
|
434
|
+
(value-kind :name control-ref
|
|
435
|
+
:description "Reference to a declared (control :name …)."
|
|
436
|
+
:underlying symbol
|
|
437
|
+
:cross-ref (cross-ref :target [pngine/control]))
|
|
438
|
+
(value-kind :name control-source
|
|
439
|
+
:description "The subject of a guard: the builtin control time, or a name declared by (control …)."
|
|
440
|
+
:underlying union
|
|
441
|
+
:union (union-shape :alternatives [builtin-control control-ref]))
|
|
442
|
+
|
|
420
443
|
; `byte-size` was `[byte-count data-ref]` — a union whose ref arm meant "size
|
|
421
444
|
; this buffer from that data without filling it". Every corpus use of it also
|
|
422
445
|
; carried `:mapped-at-creation <the same data>`, naming one thing twice, and
|
|
@@ -1071,13 +1094,14 @@
|
|
|
1071
1094
|
; `duplicate_cross_ref_target` at the declaration, so a step can never be
|
|
1072
1095
|
; ambiguous. A named graph is in the list because the frame names it in the
|
|
1073
1096
|
; AUTHORED aggregate, where it is a `(pass-graph …)` / `(draw-graph …)` and
|
|
1074
|
-
; not yet the `(step-group …)` its hook emits
|
|
1097
|
+
; not yet the `(step-group …)` its hook emits; a `(select …)` joins for the
|
|
1098
|
+
; same reason (2089e59's fix, applied to the fourth member).
|
|
1075
1099
|
; (It used to be a union tried in order, while the emitter kept
|
|
1076
1100
|
; one table for both pass kinds — a collision silently dropped the render pass.)
|
|
1077
1101
|
(value-kind :name frame-step
|
|
1078
|
-
:description "One frame step: a render-pass, compute-pass or queue name, a named pass-graph/draw-graph (a step group),
|
|
1102
|
+
:description "One frame step: a render-pass, compute-pass or queue name, a named pass-graph/draw-graph (a step group), a step-group name, or a select name (one namespace across the forms)."
|
|
1079
1103
|
:underlying symbol
|
|
1080
|
-
:cross-ref (cross-ref :target [render-pass compute-pass queue step-group pass-graph draw-graph]))
|
|
1104
|
+
:cross-ref (cross-ref :target [render-pass compute-pass queue step-group pass-graph draw-graph select]))
|
|
1081
1105
|
(value-kind :name frame-step-list
|
|
1082
1106
|
:description "Passes and queues run every frame, in order."
|
|
1083
1107
|
:underlying vector :vector (vector-shape :element frame-step :max-len 2048))
|
|
@@ -1672,7 +1696,7 @@
|
|
|
1672
1696
|
; document said twice what the widened union now says once, and the
|
|
1673
1697
|
; exclusive-group existed to stop an author saying both.
|
|
1674
1698
|
(key :name data :type write-buffer-source
|
|
1675
|
-
: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), pngine-frame-inputs (20B, + frameIndex), pointer-inputs (48B)."))
|
|
1699
|
+
: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), pngine-frame-inputs (20B, + frameIndex), pointer-inputs (48B), control-inputs (4B per declared (control …) in declaration order)."))
|
|
1676
1700
|
|
|
1677
1701
|
; Both ends of a copy are dictionaries in the IDL
|
|
1678
1702
|
; (GPUTexelCopyTextureInfo / GPUCopyExternalImageSourceInfo), so they are
|
|
@@ -2313,6 +2337,20 @@
|
|
|
2313
2337
|
(key :name index-buffer :type buffer-ref :optional true
|
|
2314
2338
|
:description "Index buffer when the bundle draws indexed."))
|
|
2315
2339
|
|
|
2340
|
+
; A host-settable f32. It is one value with two readers: a guard compares it
|
|
2341
|
+
; before a group runs, and a shader samples the same slot through
|
|
2342
|
+
; `control-inputs`, so the branch and the draw cannot disagree. The schema
|
|
2343
|
+
; carries what it can (a unique name, a real default); the rest are compiler
|
|
2344
|
+
; checks and the description says so rather than implying enforcement here:
|
|
2345
|
+
; `time` is reserved, the name must be a WGSL identifier because it becomes a
|
|
2346
|
+
; struct member, and it must not collide with a reflected uniform field
|
|
2347
|
+
; because the host addresses both by bare name.
|
|
2348
|
+
(form :name control
|
|
2349
|
+
:description "A named f32 the host sets, readable by guards and by shaders through control-inputs. `time` is reserved by the compiler. The name must be a WGSL identifier and must not collide with a reflected uniform field — both are compiler checks, not schema rules."
|
|
2350
|
+
(key :name name :type symbol
|
|
2351
|
+
:description "Control name, unique among controls. It names a WGSL struct member in control-inputs, so it must be a WGSL identifier, and the host addresses it and reflected uniforms by bare name, so it must not collide with one (both compiler checks).")
|
|
2352
|
+
(key :name default :type real :default 0
|
|
2353
|
+
:description "Initial value: a literal, a bounded expression, or a bare (define …) name. Omitted, it is 0. The compiler rejects a value that is not finite after f32 rounding."))
|
|
2316
2354
|
; A named sequence of frame steps, expanded WHERE IT IS NAMED. This is what a
|
|
2317
2355
|
; `(draw-graph …)` or `(pass-graph …)` with a `:name` emits instead of a
|
|
2318
2356
|
; frame: a graph is several passes, so without a name for the set there is no
|
|
@@ -2320,11 +2358,34 @@
|
|
|
2320
2358
|
; document's only frame and refuse the other. Nothing reaches the wire — the
|
|
2321
2359
|
; emitter inlines a group's steps into the frame that names it, so a frame
|
|
2322
2360
|
; over groups emits exactly the ops the same frame written out by hand does.
|
|
2361
|
+
;
|
|
2362
|
+
; The guard keys are shaped so the schema can carry the rules (plan 4.6):
|
|
2363
|
+
; `:when` is one union slot, each comparison is the existing `real` kind,
|
|
2364
|
+
; and `:requires [when]` turns a comparison or `:else` written without a
|
|
2365
|
+
; subject into a located reject instead of inert input. Which key means what
|
|
2366
|
+
; is in each description; holding TWO comparisons is a window, which is why
|
|
2367
|
+
; that sentence sits on the comparison keys rather than in one shared place.
|
|
2323
2368
|
(form :name step-group
|
|
2324
|
-
:description "A named sequence of frame steps, inlined wherever a (frame …) or another group names it. Emitted by a named (draw-graph …) / (pass-graph …); writable by hand to name a sequence once and run it in several frames."
|
|
2369
|
+
:description "A named sequence of frame steps, inlined wherever a (frame …) or another group names it. Emitted by a named (draw-graph …) / (pass-graph …); writable by hand to name a sequence once and run it in several frames. With :when the group runs only when every comparison key holds (no comparison key = nonzero), and :else names the steps that run otherwise; without :when the group behaves exactly as today."
|
|
2325
2370
|
(key :name name :type symbol)
|
|
2326
2371
|
(key :name perform :type frame-step-list
|
|
2327
|
-
:description "The steps this group stands for, in order.")
|
|
2372
|
+
:description "The steps this group stands for, in order.")
|
|
2373
|
+
(key :name when :type control-source :optional true
|
|
2374
|
+
:description "The guard's subject: the builtin control time, or a (control …) name. The group runs only when every comparison key holds; with no comparison key it runs when the control is nonzero.")
|
|
2375
|
+
(key :name is :type real :optional true :requires [when]
|
|
2376
|
+
:description "Holds when the control equals this value (an exact f32 comparison). Written beside another comparison key, both must hold — two keys make a window.")
|
|
2377
|
+
(key :name is-not :type real :optional true :requires [when]
|
|
2378
|
+
:description "Holds when the control does not equal this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2379
|
+
(key :name below :type real :optional true :requires [when]
|
|
2380
|
+
:description "Holds when the control is less than this value. Written beside another comparison key, both must hold — two keys make a window, as in :at-least 10 :below 10.5.")
|
|
2381
|
+
(key :name above :type real :optional true :requires [when]
|
|
2382
|
+
:description "Holds when the control is greater than this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2383
|
+
(key :name at-least :type real :optional true :requires [when]
|
|
2384
|
+
:description "Holds when the control is greater than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2385
|
+
(key :name at-most :type real :optional true :requires [when]
|
|
2386
|
+
:description "Holds when the control is less than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2387
|
+
(key :name else :type frame-step-list :optional true :requires [when]
|
|
2388
|
+
:description "The steps that run when the guard does not hold. Needs :when; a group without a guard has nothing to be the alternative to."))
|
|
2328
2389
|
(form :name frame
|
|
2329
2390
|
:description "Frame program: what runs each frame, in order."
|
|
2330
2391
|
(key :name name :type symbol)
|
|
@@ -2335,6 +2396,66 @@
|
|
|
2335
2396
|
(key :name perform :type frame-step-list
|
|
2336
2397
|
:description "Passes and queues run every frame, in order."))
|
|
2337
2398
|
|
|
2399
|
+
; =====================================================================
|
|
2400
|
+
; `(select …)` sugar — lowered to a chain of guarded step-groups by
|
|
2401
|
+
; pngine/select-v1 (plan frame-program §4.3)
|
|
2402
|
+
; =====================================================================
|
|
2403
|
+
; `select` picks the first case whose comparison holds, and the whole thing
|
|
2404
|
+
; is sugar: the hook lowers it to the chain of guarded `(step-group …)`
|
|
2405
|
+
; forms a hand-written document would spell out. The schema carries what it
|
|
2406
|
+
; can (the case count, the `:on` union, the comparison keys as `real`); the
|
|
2407
|
+
; one rule no key-set can express — "a case carries at least one comparison
|
|
2408
|
+
; key", because a key-set has no min-children — is the hook's, refused on
|
|
2409
|
+
; the case's own span. The default belongs in `:else`.
|
|
2410
|
+
;
|
|
2411
|
+
; The count bound is head-set bounds on the slot-local `case` form: below
|
|
2412
|
+
; the floor `positional_missing` (on the select's head), above the ceiling
|
|
2413
|
+
; `positional_too_many` (on the 65th child) — the same per-head cardinality
|
|
2414
|
+
; mechanism the pipeline sections use.
|
|
2415
|
+
(value-kind :name select-section :underlying form :heads (head-set
|
|
2416
|
+
(head :name case :min 1 :max 64)))
|
|
2417
|
+
; One case. The comparison keys are the six a `(step-group …)` guard takes,
|
|
2418
|
+
; with the same meanings (every key written must hold, so two keys make a
|
|
2419
|
+
; window); the subject is the select's `:on`, written once, which is why
|
|
2420
|
+
; these carry no `:requires`. No `:name` — a case is a positional arm, not a
|
|
2421
|
+
; target, and the group the hook builds for it is named after the SELECT.
|
|
2422
|
+
(form :name case
|
|
2423
|
+
:description "One case of a (select …): at least one comparison key (the default belongs in the select's :else), and the steps to perform when it is the first case that holds."
|
|
2424
|
+
(key :name is :type real :optional true
|
|
2425
|
+
:description "Holds when the control equals this value (an exact f32 comparison). Written beside another comparison key, both must hold — two keys make a window.")
|
|
2426
|
+
(key :name is-not :type real :optional true
|
|
2427
|
+
:description "Holds when the control does not equal this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2428
|
+
(key :name below :type real :optional true
|
|
2429
|
+
:description "Holds when the control is less than this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2430
|
+
(key :name above :type real :optional true
|
|
2431
|
+
:description "Holds when the control is greater than this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2432
|
+
(key :name at-least :type real :optional true
|
|
2433
|
+
:description "Holds when the control is greater than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2434
|
+
(key :name at-most :type real :optional true
|
|
2435
|
+
:description "Holds when the control is less than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
|
|
2436
|
+
(key :name perform :type frame-step-list
|
|
2437
|
+
:description "The steps this case performs when it is the first case that holds."))
|
|
2438
|
+
; The chain's shape, for the reader: `(select :name backdrop :on scene (case
|
|
2439
|
+
; :is 0 :perform [linePass]) (case :is 1 :perform [gatesPass]) :else
|
|
2440
|
+
; [ringPass])` lowers to
|
|
2441
|
+
; (step-group :name backdrop :when scene :is 0 :perform [linePass] :else [backdrop__case1])
|
|
2442
|
+
; (step-group :name backdrop__case1 :when scene :is 1 :perform [gatesPass] :else [ringPass])
|
|
2443
|
+
; — the first group keeps the select's name (so a frame names `backdrop`
|
|
2444
|
+
; either way), continuations follow the hooks' double-underscore convention,
|
|
2445
|
+
; and the last case's `:else` is the select's `:else`.
|
|
2446
|
+
(form :name select
|
|
2447
|
+
:description "Pick the first case whose comparison holds. Sugar: pngine/select-v1 lowers it to a chain of guarded (step-group …) forms, so a frame names the select exactly as it names a group. Cases are tried in source order and the first match wins (overlap is legal — that is what makes a :below cascade work); no match and no :else, the select does nothing."
|
|
2448
|
+
:lowering (lowering :hook pngine/select-v1
|
|
2449
|
+
:produces [step-group])
|
|
2450
|
+
:positional select-section
|
|
2451
|
+
(key :name name :type symbol
|
|
2452
|
+
:description "Select name — the first group of the lowered chain keeps it, so a (frame …) names the select itself, and the continuation groups are <name>__caseN.")
|
|
2453
|
+
(key :name on :type control-source
|
|
2454
|
+
:description "The control every case compares — the builtin time, or a name declared by (control …). Becomes :when on every group the lowering emits.")
|
|
2455
|
+
(key :name else :type frame-step-list :optional true
|
|
2456
|
+
:description "The steps that run when no case holds. Becomes the last group's :else, so it is the chain's fallback arm."))
|
|
2457
|
+
|
|
2458
|
+
|
|
2338
2459
|
; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
|
|
2339
2460
|
(form :name init
|
|
2340
2461
|
:description "One-shot compute init of a storage buffer (first frame only)."
|
|
@@ -2416,7 +2537,7 @@
|
|
|
2416
2537
|
:positional pass-section
|
|
2417
2538
|
(key :name name :type symbol)
|
|
2418
2539
|
(key :name code :type string
|
|
2419
|
-
: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.")
|
|
2540
|
+
:description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers, and — when the document declares (control …) forms and the code names `controls` — the ControlInputs struct, one f32 member per control in declaration order, on the next binding, with a graph-shared buffer and one control-inputs write per frame). Required — the hook always refused its absence.")
|
|
2420
2541
|
(key :name feedback :type boolean :optional true
|
|
2421
2542
|
:description "Ping-pong texture pair for feedback; the previous frame is readable as prev_<name>.")
|
|
2422
2543
|
; The intermediate's texel format, which is ONE value in WebGPU terms: the
|
package/src/anim.js
CHANGED
|
@@ -58,6 +58,22 @@ function checkTime(time) {
|
|
|
58
58
|
return time;
|
|
59
59
|
}
|
|
60
60
|
|
|
61
|
+
/**
|
|
62
|
+
* A loop length is null (the unbounded clock) or a finite number of seconds
|
|
63
|
+
* greater than zero. Zero, a negative length, NaN, an Infinity or a string
|
|
64
|
+
* would divide the clock into a range nobody meant, so it is the caller's bug,
|
|
65
|
+
* refused before anything changes the way a bad `time` is.
|
|
66
|
+
* @param {unknown} loop
|
|
67
|
+
* @returns {number|null}
|
|
68
|
+
*/
|
|
69
|
+
function checkLoop(loop) {
|
|
70
|
+
if (loop === null) return loop;
|
|
71
|
+
if (typeof loop !== "number" || !Number.isFinite(loop) || loop <= 0) {
|
|
72
|
+
throw new TypeError(`loop must be null or a finite number of seconds greater than zero, got ${String(loop)}`);
|
|
73
|
+
}
|
|
74
|
+
return loop;
|
|
75
|
+
}
|
|
76
|
+
|
|
61
77
|
/**
|
|
62
78
|
* The trailing options of setUniform/setUniforms/writeBuffer: an object or
|
|
63
79
|
* nothing. The positional boolean setUniform once took (a no-op in every
|
|
@@ -127,23 +143,48 @@ export function draw(p, opts = {}) {
|
|
|
127
143
|
}
|
|
128
144
|
|
|
129
145
|
/**
|
|
130
|
-
* Start animation loop
|
|
146
|
+
* Start animation loop.
|
|
147
|
+
*
|
|
148
|
+
* `loop` is the clock length in seconds, or null for the unbounded clock.
|
|
149
|
+
* Absent, the length already set (if any) stays, so a pause and resume keeps
|
|
150
|
+
* it. The option applies to an instance that is already playing too — the
|
|
151
|
+
* PLAY transition returns early there, but the length still lands.
|
|
152
|
+
*
|
|
131
153
|
* @param {Pngine} p
|
|
154
|
+
* @param {{ loop?: number|null }} [opts]
|
|
132
155
|
* @returns {Pngine}
|
|
133
156
|
*/
|
|
134
|
-
export function play(p) {
|
|
157
|
+
export function play(p, opts = {}) {
|
|
158
|
+
if (opts === null || typeof opts !== "object") throw new TypeError(`play: the second argument is an options object, { loop: 60 }, got ${String(opts)}`);
|
|
159
|
+
if (opts.loop !== undefined) checkLoop(opts.loop);
|
|
135
160
|
const i = p._;
|
|
136
|
-
if (!i
|
|
161
|
+
if (!i) return p;
|
|
162
|
+
|
|
163
|
+
const now = performance.now();
|
|
164
|
+
if (opts.loop !== undefined) {
|
|
165
|
+
const before = i.pb.time;
|
|
166
|
+
i.pb = reduce(i.pb, { type: "SET_LOOP", loop: opts.loop, now });
|
|
167
|
+
// Setting the loop can wrap a running clock backward (t=61 → 1 under a
|
|
168
|
+
// 60s length). The TICK seam below cannot catch that one: the next tick
|
|
169
|
+
// moves FORWARD from the wrapped time, so audio would keep playing from
|
|
170
|
+
// 61 while the video restarts at 1. Seek here, before the early return.
|
|
171
|
+
if (i.audio && i.pb.playing && i.pb.time < before) i.audio.seek(i.pb.time);
|
|
172
|
+
}
|
|
173
|
+
if (i.pb.playing) return p;
|
|
137
174
|
|
|
138
|
-
i.pb = reduce(i.pb, { type: "PLAY", now
|
|
175
|
+
i.pb = reduce(i.pb, { type: "PLAY", now });
|
|
139
176
|
|
|
140
177
|
// Start audio synced with visual time
|
|
141
178
|
if (i.audio) i.audio.play(i.pb.time);
|
|
142
179
|
|
|
143
|
-
//
|
|
180
|
+
// Nothing ends the loop but pause/stop/destroy. A loop length wraps the
|
|
181
|
+
// clock; a tick that comes back lower than the one before it is the seam,
|
|
182
|
+
// so the song restarts at the wrapped offset in the same frame.
|
|
144
183
|
const loop = () => {
|
|
145
184
|
if (!i.pb.playing) return;
|
|
185
|
+
const before = i.pb.time;
|
|
146
186
|
i.pb = reduce(i.pb, { type: "TICK", now: performance.now() });
|
|
187
|
+
if (i.audio && i.pb.time < before) i.audio.seek(i.pb.time);
|
|
147
188
|
draw(p, { time: i.pb.time });
|
|
148
189
|
i.animationId = requestAnimationFrame(loop);
|
|
149
190
|
};
|
|
@@ -193,6 +234,12 @@ export function stop(p) {
|
|
|
193
234
|
|
|
194
235
|
/**
|
|
195
236
|
* Seek to specific time
|
|
237
|
+
*
|
|
238
|
+
* With a loop length set, a time past it wraps into the range (the floor form
|
|
239
|
+
* from frame-program §6.5) and the wrapped time is what the draw carries, what
|
|
240
|
+
* `p.time` reads and what the song seeks to. An explicit `draw(p, { time })`
|
|
241
|
+
* still sends the time it was given, unwrapped.
|
|
242
|
+
*
|
|
196
243
|
* @param {Pngine} p
|
|
197
244
|
* @param {number} time - Time in seconds
|
|
198
245
|
* @returns {Pngine}
|
|
@@ -203,10 +250,11 @@ export function seek(p, time) {
|
|
|
203
250
|
if (!i) return p;
|
|
204
251
|
|
|
205
252
|
i.pb = reduce(i.pb, { type: "SEEK", now: performance.now(), time });
|
|
253
|
+
const wrapped = i.pb.time;
|
|
206
254
|
|
|
207
|
-
if (i.audio) i.audio.seek(
|
|
255
|
+
if (i.audio) i.audio.seek(wrapped);
|
|
208
256
|
|
|
209
|
-
draw(p, { time });
|
|
257
|
+
draw(p, { time: wrapped });
|
|
210
258
|
return p;
|
|
211
259
|
}
|
|
212
260
|
|
package/src/core.js
CHANGED
|
@@ -75,6 +75,17 @@ export function createCoreDispatcher(device, ctx) {
|
|
|
75
75
|
dispatcher.setUniformTable(table);
|
|
76
76
|
},
|
|
77
77
|
|
|
78
|
+
/**
|
|
79
|
+
* Install the executor's control table: the Float32Array a host
|
|
80
|
+
* builds over `getControlPtr()` (65 slots — `time` at 0, controls at
|
|
81
|
+
* 1..64), or null when the executor predates the export. No copy:
|
|
82
|
+
* setUniform writes a control where the executor reads it, in place.
|
|
83
|
+
* @param {Float32Array|null} view
|
|
84
|
+
*/
|
|
85
|
+
setControlTable(view) {
|
|
86
|
+
dispatcher.setControlTable(view);
|
|
87
|
+
},
|
|
88
|
+
|
|
78
89
|
/**
|
|
79
90
|
* Install the payload's buffer names, so writeBuffers/getBuffers can
|
|
80
91
|
* address a buffer by the `(buffer :name …)` the author wrote. The
|
package/src/gpu.js
CHANGED
|
@@ -82,6 +82,11 @@ const PNGB_FLAG_DEVICE_LIMITS = 0x04;
|
|
|
82
82
|
// Header flag bit 4: the uniform-table section carries a buffer-name block
|
|
83
83
|
// after its bindings (docs/plans/public-write-buffer.md D2).
|
|
84
84
|
const PNGB_FLAG_BUFFER_NAMES = 0x10;
|
|
85
|
+
// Header flag bits 5 and 6 (frame-program §7.2): bit 5, the section carries a
|
|
86
|
+
// control-name block after the buffer-name block; bit 6, `has_guards` — the
|
|
87
|
+
// payload uses frame-program instructions (§9's load-time handshake).
|
|
88
|
+
const PNGB_FLAG_CONTROL_NAMES = 0x20;
|
|
89
|
+
const PNGB_FLAG_HAS_GUARDS = 0x40;
|
|
85
90
|
// flags bit 3 — the author requested a PREMULTIPLIED canvas ((canvas
|
|
86
91
|
// :alpha-mode premultiplied)); clear = "opaque", the GPUCanvasConfiguration
|
|
87
92
|
// default. The bit used to mean the opposite, back when this runtime's own
|
|
@@ -102,6 +107,22 @@ export function canvasAlphaMode(bytecode) {
|
|
|
102
107
|
return (view.getUint16(6, true) & PNGB_FLAG_PREMULTIPLIED_CANVAS) ? "premultiplied" : "opaque";
|
|
103
108
|
}
|
|
104
109
|
|
|
110
|
+
/**
|
|
111
|
+
* Whether a payload's header sets `has_guards` (flag bit 6): it carries
|
|
112
|
+
* frame-program instructions. The §9 load-time handshake reads this — such a
|
|
113
|
+
* payload must run on an executor that exports getControlPtr, or the executor
|
|
114
|
+
* reads the guard instructions' operands as instructions and renders garbage.
|
|
115
|
+
* False for a non-PNGB or a short buffer (nothing to refuse).
|
|
116
|
+
* @param {Uint8Array|null|undefined} bytecode
|
|
117
|
+
* @returns {boolean}
|
|
118
|
+
*/
|
|
119
|
+
export function payloadHasGuards(bytecode) {
|
|
120
|
+
if (!bytecode || bytecode.length < PNGB_HEADER_SIZE) return false;
|
|
121
|
+
const view = new DataView(bytecode.buffer, bytecode.byteOffset, bytecode.byteLength);
|
|
122
|
+
if (view.getUint32(0, true) !== PNGB_MAGIC) return false;
|
|
123
|
+
return (view.getUint16(6, true) & PNGB_FLAG_HAS_GUARDS) === PNGB_FLAG_HAS_GUARDS;
|
|
124
|
+
}
|
|
125
|
+
|
|
105
126
|
/**
|
|
106
127
|
* Parse uniform table from PNGB bytecode.
|
|
107
128
|
* Returns: { uniforms: Map<string, {bufferId, offset, size, type, elemCount}>,
|
|
@@ -116,6 +137,11 @@ export function canvasAlphaMode(bytecode) {
|
|
|
116
137
|
* own queue ops write it every draw. Read only behind header flag bit 4 and
|
|
117
138
|
* only within the section, so a payload minted before the block — or one
|
|
118
139
|
* whose bit is clear — parses to an empty map and nothing else changes.
|
|
140
|
+
*
|
|
141
|
+
* The uniform-table section's second tail block (header flag bit 5) lists the
|
|
142
|
+
* document's declared controls; each joins `uniforms` marked
|
|
143
|
+
* `{ control: true, slot }` — slot is 1-based, slot 0 being `time`. See the
|
|
144
|
+
* block's reader below for the reserved-empty-slot rule.
|
|
119
145
|
*/
|
|
120
146
|
export function parseUniformTable(bytecode) {
|
|
121
147
|
const view = new DataView(bytecode.buffer, bytecode.byteOffset, bytecode.byteLength);
|
|
@@ -187,6 +213,34 @@ export function parseUniformTable(bytecode) {
|
|
|
187
213
|
}
|
|
188
214
|
}
|
|
189
215
|
|
|
216
|
+
// The control-name block, after the buffer-name block (§7.2): [count u16]
|
|
217
|
+
// then one string id per control, in slot order — element i is slot i + 1,
|
|
218
|
+
// because slot 0 is `time` and never listed. Each control joins the SAME
|
|
219
|
+
// `uniforms` map the reflected fields live in, marked `control` (§6.1), so
|
|
220
|
+
// every consumer of the map sees it; it has no GPU buffer of its own
|
|
221
|
+
// (control-inputs writes it each frame), so bufferId is -1 — no created
|
|
222
|
+
// buffer id. An entry whose string is EMPTY is a reserved slot (the name
|
|
223
|
+
// did not fit the string table; a slot is never reassigned): it counts for
|
|
224
|
+
// control-inputs but joins no map, so setUniform('') keeps the plain "no
|
|
225
|
+
// uniform named" refusal and later slots keep their numbers.
|
|
226
|
+
if ((view.getUint16(6, true) & PNGB_FLAG_CONTROL_NAMES) && pos + 2 <= sectionEnd) {
|
|
227
|
+
const controlCount = view.getUint16(pos, true);
|
|
228
|
+
pos += 2;
|
|
229
|
+
for (let i = 0; i < controlCount && pos + 2 <= sectionEnd; i++, pos += 2) {
|
|
230
|
+
const name = strings[view.getUint16(pos, true)];
|
|
231
|
+
if (!name) continue; // a reserved slot: unnamed, unlistable, still counted
|
|
232
|
+
uniforms.set(name, {
|
|
233
|
+
control: true,
|
|
234
|
+
slot: i + 1,
|
|
235
|
+
bufferId: -1,
|
|
236
|
+
offset: 0,
|
|
237
|
+
size: 4,
|
|
238
|
+
type: 0, // UT_F32 — controls are f32 only in this version (§4.1)
|
|
239
|
+
elemCount: 0,
|
|
240
|
+
});
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
190
244
|
return { uniforms, strings, buffers };
|
|
191
245
|
}
|
|
192
246
|
|
|
@@ -923,17 +977,25 @@ export function createCommandDispatcher(device, ctx) {
|
|
|
923
977
|
// whole WASM memory.
|
|
924
978
|
onQueryResult = onError = onShaderError = null;
|
|
925
979
|
uniformMap = null;
|
|
980
|
+
controlTable = null;
|
|
926
981
|
mem = null;
|
|
927
982
|
targetCtx = null;
|
|
928
983
|
enc = pass = null;
|
|
929
984
|
}
|
|
930
985
|
|
|
931
|
-
// Uniform table: Map<string, {bufferId, offset, size, type, elemCount}>
|
|
986
|
+
// Uniform table: Map<string, {bufferId, offset, size, type, elemCount}> —
|
|
987
|
+
// plus control entries {control: true, slot, …} (parseUniformTable).
|
|
932
988
|
let uniformMap = null;
|
|
989
|
+
// The EXECUTOR's control table as a host view: 65 f32 over getControlPtr
|
|
990
|
+
// (slot 0 is `time`). Installed by the worker or a core-tier host once the
|
|
991
|
+
// executor is instantiated; valid for the instance's life (the executor
|
|
992
|
+
// never grows its memory). Null until then, and on an executor that
|
|
993
|
+
// predates the export — setUniform refuses a control then.
|
|
994
|
+
let controlTable = null;
|
|
933
995
|
|
|
934
996
|
/**
|
|
935
997
|
* Set uniform table from parsed bytecode.
|
|
936
|
-
* @param {Map<string, {bufferId, offset, size, type, elemCount}>} map
|
|
998
|
+
* @param {Map<string, {bufferId: number, offset: number, size: number, type: number, elemCount: number, control?: boolean, slot?: number}>} map
|
|
937
999
|
*/
|
|
938
1000
|
function setUniformTable(map) {
|
|
939
1001
|
uniformMap = map;
|
|
@@ -941,10 +1003,24 @@ export function createCommandDispatcher(device, ctx) {
|
|
|
941
1003
|
}
|
|
942
1004
|
|
|
943
1005
|
/**
|
|
944
|
-
*
|
|
1006
|
+
* Install the executor's control table — the Float32Array a host builds
|
|
1007
|
+
* over `getControlPtr()` (65 slots: `time` at 0, controls at 1..64), or
|
|
1008
|
+
* null when the executor predates the export. No copy: writes land where
|
|
1009
|
+
* the executor reads them, the same frame.
|
|
1010
|
+
* @param {Float32Array|null} view
|
|
1011
|
+
*/
|
|
1012
|
+
function setControlTable(view) {
|
|
1013
|
+
controlTable = view;
|
|
1014
|
+
}
|
|
1015
|
+
|
|
1016
|
+
/**
|
|
1017
|
+
* Set a uniform value by name. A name that is a CONTROL
|
|
1018
|
+
* (getUniforms marks them) is written into the executor's control table —
|
|
1019
|
+
* install the getControlPtr view first with setControlTable — and takes
|
|
1020
|
+
* exactly one finite number; every other name is packed for its GPU buffer.
|
|
945
1021
|
* @param {string} name - Uniform field name
|
|
946
1022
|
* @param {number|number[]|number[][]} value - Value to set (a nested array for a matrix or an array field)
|
|
947
|
-
* @returns {boolean} - true if
|
|
1023
|
+
* @returns {boolean} - true if the value was written; a refusal reached onError
|
|
948
1024
|
*/
|
|
949
1025
|
// A refusal reaches the host through onError (source "set-uniform"), the
|
|
950
1026
|
// route writeBuffer's refusals take — it was a DEBUG-gated console.warn, so
|
|
@@ -956,6 +1032,24 @@ export function createCommandDispatcher(device, ctx) {
|
|
|
956
1032
|
return false;
|
|
957
1033
|
}
|
|
958
1034
|
|
|
1035
|
+
// A control is one f32 the EXECUTOR owns (§6.1): write the table the
|
|
1036
|
+
// guard compares and control-inputs copies, in place — no queue
|
|
1037
|
+
// writeBuffer, so the branch and the shader read the same value in the
|
|
1038
|
+
// same frame. Slot 0 (`time`) is never in the map.
|
|
1039
|
+
if (info.control) {
|
|
1040
|
+
if (!controlTable) {
|
|
1041
|
+
onError && onError({ message: `setUniform: '${name}' is a control, but this executor predates getControlPtr — re-embed the executor with a current pngine, or run the payload on a newer runtime`, source: "set-uniform" });
|
|
1042
|
+
return false;
|
|
1043
|
+
}
|
|
1044
|
+
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
1045
|
+
onError && onError({ message: `setUniform: control '${name}' takes one finite number, got ${Array.isArray(value) ? "an array" : String(value)}`, source: "set-uniform" });
|
|
1046
|
+
return false;
|
|
1047
|
+
}
|
|
1048
|
+
controlTable[info.slot] = value;
|
|
1049
|
+
DEBUG && dbg && console.log(`[GPU] setUniform: control ${name} = ${value} @ slot ${info.slot}`);
|
|
1050
|
+
return true;
|
|
1051
|
+
}
|
|
1052
|
+
|
|
959
1053
|
const buffer = buf[info.bufferId];
|
|
960
1054
|
if (!buffer) {
|
|
961
1055
|
onError && onError({ message: `setUniform: '${name}' names a buffer this payload never created`, source: "set-uniform" });
|
|
@@ -1058,6 +1152,7 @@ export function createCommandDispatcher(device, ctx) {
|
|
|
1058
1152
|
setOnError(fn) { onError = fn; },
|
|
1059
1153
|
setOnQueryResult(fn) { onQueryResult = fn; },
|
|
1060
1154
|
setUniformTable,
|
|
1155
|
+
setControlTable,
|
|
1061
1156
|
setUniform,
|
|
1062
1157
|
setUniforms,
|
|
1063
1158
|
// Host writes by SJON buffer name; bodies in gpu-host-write.js.
|
package/src/loader.js
CHANGED
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
* Parses PNGB v0 format to detect and extract embedded executor WASM.
|
|
5
5
|
* Falls back to shared executor if not embedded.
|
|
6
6
|
*
|
|
7
|
-
* PNGB
|
|
7
|
+
* PNGB Header (40 bytes):
|
|
8
8
|
* - magic: "PNGB" (4 bytes)
|
|
9
|
-
* - version: u16 (0)
|
|
9
|
+
* - version: u16 (0; 1 marks an executor-less guarded payload — D6)
|
|
10
10
|
* - flags: u16 (bit 0 = has_embedded_executor, bit 1 = has_animation_table)
|
|
11
11
|
* - plugins: u8 (PluginSet bitfield)
|
|
12
12
|
* - reserved: [3]u8
|
|
@@ -25,6 +25,10 @@ if (typeof EMBEDDED_ONLY === "undefined") globalThis.EMBEDDED_ONLY = false;
|
|
|
25
25
|
|
|
26
26
|
const PNGB_MAGIC = [0x50, 0x4e, 0x47, 0x42]; // "PNGB"
|
|
27
27
|
const VERSION_V0 = 0;
|
|
28
|
+
// D6 (frame-program §12): version 1 marks an executor-less guarded payload —
|
|
29
|
+
// the only signal a runtime that predates the §9 handshake obeys. Every
|
|
30
|
+
// reader of the field accepts both; the 40-byte layout is unchanged.
|
|
31
|
+
const VERSION_V1 = 1;
|
|
28
32
|
const HEADER_SIZE_V0 = 40;
|
|
29
33
|
|
|
30
34
|
// Header flags
|
|
@@ -58,17 +62,20 @@ export function parsePayload(pngb) {
|
|
|
58
62
|
const view = new DataView(pngb.buffer, pngb.byteOffset, pngb.byteLength);
|
|
59
63
|
const version = view.getUint16(4, true);
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
// v0, and v1 for an executor-less guarded payload (D6): the §9 handshake,
|
|
66
|
+
// not this gate, refuses the pairing that is unsafe to run.
|
|
67
|
+
if (version !== VERSION_V0 && version !== VERSION_V1) {
|
|
62
68
|
throw new Error(`Unsupported PNGB version: ${version}`);
|
|
63
69
|
}
|
|
64
70
|
|
|
65
|
-
return parseV0Header(pngb, view);
|
|
71
|
+
return parseV0Header(pngb, view, version);
|
|
66
72
|
}
|
|
67
73
|
|
|
68
74
|
/**
|
|
69
|
-
* Parse
|
|
75
|
+
* Parse the 40-byte header (v0 layout, shared by v1 — D6 changed the field's
|
|
76
|
+
* value, never its size or position).
|
|
70
77
|
*/
|
|
71
|
-
function parseV0Header(pngb, view) {
|
|
78
|
+
function parseV0Header(pngb, view, version) {
|
|
72
79
|
const flags = view.getUint16(6, true);
|
|
73
80
|
const plugins = pngb[8];
|
|
74
81
|
const executorOffset = view.getUint32(12, true);
|
|
@@ -89,7 +96,7 @@ function parseV0Header(pngb, view) {
|
|
|
89
96
|
const bytecodeLength = stringTableOffset - bytecodeOffset;
|
|
90
97
|
|
|
91
98
|
return {
|
|
92
|
-
version
|
|
99
|
+
version,
|
|
93
100
|
hasEmbeddedExecutor,
|
|
94
101
|
hasAnimationTable,
|
|
95
102
|
plugins: parsePlugins(plugins),
|
package/src/playback-state.js
CHANGED
|
@@ -1,15 +1,21 @@
|
|
|
1
1
|
// Pure playback state machine — the single owner of all play/pause/time math.
|
|
2
2
|
//
|
|
3
|
-
// State: { playing, time, startedAtMs, frame }
|
|
3
|
+
// State: { playing, time, startedAtMs, frame, loop }
|
|
4
4
|
// startedAtMs is the performance.now() baseline chosen so that
|
|
5
5
|
// startedAtMs = nowMs - time*1000 ⇒ a TICK(nowMs) recovers `time`.
|
|
6
6
|
// frame is the pin setFrame holds: a `(frame :name …)` string, or null for
|
|
7
7
|
// the executor's own choice. It rides every draw message.
|
|
8
|
+
// loop is the clock length in seconds, or null for unbounded. A TICK, PAUSE
|
|
9
|
+
// or SEEK whose time reaches it wraps into [0, loop) with the floor form
|
|
10
|
+
// below and rebases startedAtMs, so the invariant above keeps holding and
|
|
11
|
+
// a tab that stalled for several periods lands inside the range in one
|
|
12
|
+
// tick. DRAW records the time it was given, unwrapped.
|
|
8
13
|
// anim.js is a thin driver: it reads the clock, dispatches actions here, then
|
|
9
14
|
// performs the effects (audio, worker draw, requestAnimationFrame) implied by
|
|
10
15
|
// the state transition. No playback field is written outside reduce().
|
|
11
16
|
//
|
|
12
|
-
// The clock runs unbounded. There used to be an
|
|
17
|
+
// The clock runs unbounded until a host sets a loop. There used to be an
|
|
18
|
+
// animation-timeline arm here —
|
|
13
19
|
// scenes resolved from the time, an end behaviour that wrapped or halted it —
|
|
14
20
|
// over a table the worker stopped delivering in Dec 2025 and no SJON form
|
|
15
21
|
// emits, so it was unreachable through pngine() for as long as it existed
|
|
@@ -24,32 +30,63 @@
|
|
|
24
30
|
|
|
25
31
|
// Fresh stopped machine. A new object each call so nothing shares mutable state.
|
|
26
32
|
export function initialPlayback() {
|
|
27
|
-
return { playing: false, time: 0, startedAtMs: 0, frame: null };
|
|
33
|
+
return { playing: false, time: 0, startedAtMs: 0, frame: null, loop: null };
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// The floor form from frame-program §6.5. It stays in [0, loop) for a negative
|
|
37
|
+
// time, where `time % loop` goes negative; null (or a state from before the
|
|
38
|
+
// loop existed) is the unbounded clock.
|
|
39
|
+
function wrapToLoop(time, loop) {
|
|
40
|
+
if (loop === null || loop === undefined) return time;
|
|
41
|
+
return (time / loop - Math.floor(time / loop)) * loop;
|
|
28
42
|
}
|
|
29
43
|
|
|
30
44
|
// Pure reducer: (state, action) → state. Unknown actions are the identity.
|
|
31
45
|
export function reduce(state, action) {
|
|
32
46
|
switch (action.type) {
|
|
47
|
+
case "SET_LOOP": {
|
|
48
|
+
const time = action.loop === null ? state.time : wrapToLoop(state.time, action.loop);
|
|
49
|
+
return {
|
|
50
|
+
...state,
|
|
51
|
+
loop: action.loop,
|
|
52
|
+
time,
|
|
53
|
+
startedAtMs: state.playing && time !== state.time ? action.now - time * 1000 : state.startedAtMs,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
|
|
33
57
|
case "PLAY":
|
|
34
58
|
if (state.playing) return state;
|
|
35
59
|
return { ...state, playing: true, startedAtMs: action.now - state.time * 1000 };
|
|
36
60
|
|
|
37
|
-
case "PAUSE":
|
|
61
|
+
case "PAUSE": {
|
|
38
62
|
if (!state.playing) return state;
|
|
39
|
-
|
|
63
|
+
const raw = (action.now - state.startedAtMs) / 1000;
|
|
64
|
+
const time = wrapToLoop(raw, state.loop);
|
|
65
|
+
return {
|
|
66
|
+
...state,
|
|
67
|
+
playing: false,
|
|
68
|
+
time,
|
|
69
|
+
startedAtMs: time === raw ? state.startedAtMs : action.now - time * 1000,
|
|
70
|
+
};
|
|
71
|
+
}
|
|
40
72
|
|
|
41
73
|
case "STOP":
|
|
42
74
|
return { ...state, playing: false, time: 0, startedAtMs: action.now };
|
|
43
75
|
|
|
44
|
-
case "SEEK":
|
|
76
|
+
case "SEEK": {
|
|
77
|
+
const time = wrapToLoop(action.time, state.loop);
|
|
45
78
|
return {
|
|
46
79
|
...state,
|
|
47
|
-
time
|
|
48
|
-
startedAtMs: state.playing ? action.now -
|
|
80
|
+
time,
|
|
81
|
+
startedAtMs: state.playing ? action.now - time * 1000 : state.startedAtMs,
|
|
49
82
|
};
|
|
83
|
+
}
|
|
50
84
|
|
|
51
|
-
case "TICK":
|
|
52
|
-
|
|
85
|
+
case "TICK": {
|
|
86
|
+
const raw = (action.now - state.startedAtMs) / 1000;
|
|
87
|
+
const time = wrapToLoop(raw, state.loop);
|
|
88
|
+
return time === raw ? { ...state, time } : { ...state, time, startedAtMs: action.now - time * 1000 };
|
|
89
|
+
}
|
|
53
90
|
|
|
54
91
|
case "DRAW":
|
|
55
92
|
return action.record !== undefined ? { ...state, time: action.record } : state;
|