pngine 4.2.1 → 4.3.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/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/src/uniform-convert.js
CHANGED
|
@@ -62,19 +62,32 @@ export function uniformTypeName(tag) {
|
|
|
62
62
|
* block's base. `buffer` is null when the payload names nothing: one minted
|
|
63
63
|
* before the buffer-name block (3.0.1 and earlier), or a buffer the block
|
|
64
64
|
* does not list.
|
|
65
|
-
*
|
|
65
|
+
*
|
|
66
|
+
* A control entry (parseUniformTable marks them) describes with the same key
|
|
67
|
+
* set as every field and `control: true`: type "f32", no buffer — its value
|
|
68
|
+
* reaches the GPU through the frame's own control-inputs write, so no host
|
|
69
|
+
* writeBuffer can name it — offset 0, elemCount 0 (§6.1).
|
|
70
|
+
* @param {Map<string, {bufferId: number, offset: number, size: number, type: number, elemCount: number, control?: boolean, slot?: number}>} uniforms
|
|
66
71
|
* @param {Map<string, {id: number, pool?: number}>} buffers - the buffer-name block
|
|
67
|
-
* @returns {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number}>}
|
|
72
|
+
* @returns {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number, control: boolean}>}
|
|
68
73
|
*/
|
|
69
74
|
export function describeUniforms(uniforms, buffers) {
|
|
70
75
|
const nameOf = (id) => {
|
|
71
76
|
for (const [name, b] of buffers) if (id >= b.id && id < b.id + (b.pool || 1)) return name;
|
|
72
77
|
return null;
|
|
73
78
|
};
|
|
74
|
-
/** @type {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number}>} */
|
|
79
|
+
/** @type {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number, control: boolean}>} */
|
|
75
80
|
const out = {};
|
|
76
81
|
for (const [name, info] of uniforms) {
|
|
77
|
-
|
|
82
|
+
const control = info.control === true;
|
|
83
|
+
out[name] = {
|
|
84
|
+
type: uniformTypeName(info.type),
|
|
85
|
+
size: info.size,
|
|
86
|
+
buffer: control ? null : nameOf(info.bufferId),
|
|
87
|
+
offset: info.offset,
|
|
88
|
+
elemCount: info.elemCount,
|
|
89
|
+
control,
|
|
90
|
+
};
|
|
78
91
|
}
|
|
79
92
|
return out;
|
|
80
93
|
}
|
package/src/viewer-init.js
CHANGED
|
@@ -12,6 +12,11 @@ import { initialPlayback } from "./playback-state.js";
|
|
|
12
12
|
|
|
13
13
|
const PNGB_HEADER_SIZE = 40;
|
|
14
14
|
const PNGB_VERSION_V0 = 0;
|
|
15
|
+
// D6 (frame-program §12): version 1 marks an executor-less guarded payload.
|
|
16
|
+
// The viewer's contract still requires an embedded executor, but a v1 payload
|
|
17
|
+
// must be refused for THAT reason — never by the version gate, which an old
|
|
18
|
+
// runtime reads but a new one must not hide behind.
|
|
19
|
+
const PNGB_VERSION_V1 = 1;
|
|
15
20
|
const PNGB_FLAG_HAS_EMBEDDED_EXECUTOR = 0x01;
|
|
16
21
|
const NO_EMBEDDED_EXECUTOR_ERROR =
|
|
17
22
|
"No embedded executor in payload. Use an embedded-executor PNG payload, or use pngine/dev with wasmUrl fallback.";
|
|
@@ -198,7 +203,7 @@ function assertEmbeddedExecutorPayload(bytecode) {
|
|
|
198
203
|
|
|
199
204
|
const view = new DataView(bytecode.buffer, bytecode.byteOffset, bytecode.byteLength);
|
|
200
205
|
const version = view.getUint16(4, true);
|
|
201
|
-
if (version !== PNGB_VERSION_V0) {
|
|
206
|
+
if (version !== PNGB_VERSION_V0 && version !== PNGB_VERSION_V1) {
|
|
202
207
|
throw new Error(`Unsupported PNGB version: ${version}`);
|
|
203
208
|
}
|
|
204
209
|
|
package/src/worker-core.js
CHANGED
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
// whole block is dropped from its bundle. (RESIZE is NOT
|
|
36
36
|
// gated — both profiles react to a canvas resize.)
|
|
37
37
|
|
|
38
|
-
import { createCommandDispatcher, parseUniformTable, parseDeviceLimits, requiredFeaturesFor, canvasAlphaMode } from "./gpu.js";
|
|
38
|
+
import { createCommandDispatcher, parseUniformTable, parseDeviceLimits, requiredFeaturesFor, canvasAlphaMode, payloadHasGuards } from "./gpu.js";
|
|
39
39
|
import { describeUniforms } from "./uniform-convert.js";
|
|
40
40
|
import { parsePayload, getExecutorImports } from "./loader.js";
|
|
41
41
|
|
|
@@ -85,6 +85,16 @@ export const MSG = {
|
|
|
85
85
|
const NO_EMBEDDED_EXECUTOR_ERROR =
|
|
86
86
|
"No embedded executor in payload. Use an embedded-executor PNG payload, or use pngine/dev with wasmUrl fallback.";
|
|
87
87
|
|
|
88
|
+
// §9's load-time handshake: a payload whose header says has_guards carries
|
|
89
|
+
// frame-program instructions, and an executor that predates them treats each
|
|
90
|
+
// as a no-op and reads its OPERANDS as instructions — garbage, silently. The
|
|
91
|
+
// executor that runs it must export getControlPtr; refuse the load naming the
|
|
92
|
+
// two fixes. A guarded payload that EMBEDS its executor carries a current one
|
|
93
|
+
// (the same compiler set the bit), so it passes; an old RUNTIME rendering it
|
|
94
|
+
// never reaches this check and the guards run inside the embedded executor.
|
|
95
|
+
const GUARDED_PAYLOAD_ERROR =
|
|
96
|
+
"payload uses frame-program guards, but this executor predates them (no getControlPtr export) — re-embed the executor with a current pngine, or run the payload on a newer runtime";
|
|
97
|
+
|
|
88
98
|
// The default browser environment, wired from worker globals. Only called from
|
|
89
99
|
// the worker entries (never node), so the global references are safe here.
|
|
90
100
|
export function browserEnv() {
|
|
@@ -137,6 +147,13 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
137
147
|
// GPU resource on a fresh device without the host re-sending it.
|
|
138
148
|
let lastBytecode = null;
|
|
139
149
|
let uniformMap = null;
|
|
150
|
+
// The EXECUTOR's control table as a host view (65 f32 over getControlPtr;
|
|
151
|
+
// slot 0 is `time`), rebuilt whenever an executor is adopted, and handed to
|
|
152
|
+
// whichever dispatcher then owns rendering — controls are written through
|
|
153
|
+
// gpu.setUniform (§6.1), so the dispatcher needs the view the executor
|
|
154
|
+
// reads. Null on an executor that predates the export; a payload that
|
|
155
|
+
// actually uses controls is refused at load (§9) rather than limping.
|
|
156
|
+
let controlTable = null;
|
|
140
157
|
// The payload's buffer-name block, kept beside the uniform table so
|
|
141
158
|
// getUniforms can name each field's buffer the way writeBuffer speaks it.
|
|
142
159
|
let bufferNames = new Map();
|
|
@@ -192,6 +209,7 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
192
209
|
gpu = env.makeDispatcher(device, context);
|
|
193
210
|
gpu.setDebug(debugMode);
|
|
194
211
|
if (memory) gpu.setMemory(memory); // null at first init; handleInit binds it post-executor
|
|
212
|
+
if (controlTable) gpu.setControlTable(controlTable); // re-adopted on a reload's fresh dispatcher
|
|
195
213
|
gpu.setCanvasSize(canvas.width, canvas.height);
|
|
196
214
|
gpu.setOnShaderError((err) => { post({ type: "shader-error", ...err }); });
|
|
197
215
|
gpu.setOnError((err) => reportCommandError(err.message, err.source));
|
|
@@ -220,6 +238,13 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
220
238
|
memory = wasm.memory;
|
|
221
239
|
abiVersion = wasm.getAbiVersion?.() ?? 1;
|
|
222
240
|
executorBytes = bytes;
|
|
241
|
+
// The control-table view follows the executor it reads: rebuilt on every
|
|
242
|
+
// adoption (a reload can swap executors), valid for the instance's life
|
|
243
|
+
// (the executor never grows its memory). Pushed to the dispatcher below —
|
|
244
|
+
// a kept dispatcher (gpuDirty false) must not keep the OLD memory's view.
|
|
245
|
+
controlTable = typeof wasm.getControlPtr === "function"
|
|
246
|
+
? new Float32Array(memory.buffer, wasm.getControlPtr(), 65)
|
|
247
|
+
: null;
|
|
223
248
|
if (debug) console.log("[Worker] Executor ABI version:", abiVersion);
|
|
224
249
|
// The dispatcher decodes every command stream out of the EXECUTOR's
|
|
225
250
|
// memory; a swap without this rebind reads the new payload's stream from
|
|
@@ -227,6 +252,7 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
227
252
|
// dispatcher (rebinding memory again); this covers a load whose previous
|
|
228
253
|
// init stream was empty (gpuDirty false, dispatcher kept).
|
|
229
254
|
gpu?.setMemory(memory);
|
|
255
|
+
gpu?.setControlTable?.(controlTable);
|
|
230
256
|
}
|
|
231
257
|
|
|
232
258
|
// The embedded executor a payload carries, or null when it has none. A
|
|
@@ -446,8 +472,14 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
446
472
|
wasm = instance.exports;
|
|
447
473
|
memory = wasm.memory;
|
|
448
474
|
abiVersion = wasm.getAbiVersion?.() ?? 1;
|
|
475
|
+
// Same view the embedded path builds (adoptExecutor): the shared
|
|
476
|
+
// executor's own table, handed to the dispatcher for setUniform routing.
|
|
477
|
+
controlTable = typeof wasm.getControlPtr === "function"
|
|
478
|
+
? new Float32Array(memory.buffer, wasm.getControlPtr(), 65)
|
|
479
|
+
: null;
|
|
449
480
|
if (data.debug) console.log("[Worker] Executor ABI version:", abiVersion);
|
|
450
481
|
gpu.setMemory(memory);
|
|
482
|
+
gpu.setControlTable?.(controlTable);
|
|
451
483
|
initialized = true;
|
|
452
484
|
|
|
453
485
|
if (data.bytecode) await loadBytecode(data.bytecode);
|
|
@@ -520,6 +552,17 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
520
552
|
// for input, init() to emit resource-creation commands, frame() to render,
|
|
521
553
|
// getCommandPtr/getCommandLen for the command-buffer output.
|
|
522
554
|
async function loadBytecode(bytecode) {
|
|
555
|
+
// Normalize once, before every consumer below.
|
|
556
|
+
const bytecodeArray = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
|
|
557
|
+
|
|
558
|
+
// The §9 handshake, FIRST: a refused load leaves the running engine
|
|
559
|
+
// exactly as it was (no dispatcher reset, no byte writes), the way a
|
|
560
|
+
// rejected executor adoption does. init() has not run, so there is no
|
|
561
|
+
// half-loaded state to unwind.
|
|
562
|
+
if (payloadHasGuards(bytecodeArray) && typeof wasm?.getControlPtr !== "function") {
|
|
563
|
+
throw new Error(GUARDED_PAYLOAD_ERROR);
|
|
564
|
+
}
|
|
565
|
+
|
|
523
566
|
// Reset GPU state if the dispatcher has executed anything. Keyed on
|
|
524
567
|
// `gpuDirty`, not `moduleLoaded`: the latter is set only on SUCCESS, so a
|
|
525
568
|
// load whose init stream rejected midway (an undecodable image blob, a
|
|
@@ -536,7 +579,6 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
536
579
|
bufferNames = new Map();
|
|
537
580
|
|
|
538
581
|
// Split PNGB: bytecode (small) → bytecodePtr, data section (large) → dataPtr
|
|
539
|
-
const bytecodeArray = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
|
|
540
582
|
lastBytecode = bytecodeArray; // retain so device-loss recovery can rebuild resources
|
|
541
583
|
const payloadOffsets = parsePayload(bytecodeArray).offsets;
|
|
542
584
|
const dataOffset = payloadOffsets.data;
|
|
@@ -651,24 +693,45 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
651
693
|
}
|
|
652
694
|
}
|
|
653
695
|
|
|
696
|
+
// The control table gets the same save/restore around a preview — at most
|
|
697
|
+
// 64 floats (§6.2). The SNAPSHOT is the prefetch's to take, inside its own
|
|
698
|
+
// locked section BEFORE it applies the thumbnail's uniforms: one taken
|
|
699
|
+
// here, inside renderEphemeral, would capture the thumbnail's values, and
|
|
700
|
+
// the resize repaint never changes controls at all. Restoring writes every
|
|
701
|
+
// slot back; slot 0 is the frame's own time and frame() overwrites it
|
|
702
|
+
// before the next body runs. A preview still cannot undo GPU work — the
|
|
703
|
+
// uniform writes that went to buffers stay.
|
|
704
|
+
function snapshotControls() {
|
|
705
|
+
return controlTable ? controlTable.slice() : null;
|
|
706
|
+
}
|
|
707
|
+
function restoreControls(saved) {
|
|
708
|
+
if (controlTable && saved) controlTable.set(saved);
|
|
709
|
+
}
|
|
710
|
+
|
|
654
711
|
async function handleDraw(data) {
|
|
655
712
|
if (!initialized || !moduleLoaded || deviceLost) return;
|
|
656
713
|
|
|
657
714
|
// Apply pointer state before rendering (if provided)
|
|
658
715
|
if (data.pointer) gpu.setPointer(data.pointer);
|
|
659
716
|
|
|
660
|
-
// Apply uniforms before rendering (if provided)
|
|
661
|
-
if (data.uniforms && typeof data.uniforms === "object") {
|
|
662
|
-
const count = gpu.setUniforms(data.uniforms);
|
|
663
|
-
if (debugMode && count > 0) {
|
|
664
|
-
console.log(`[Worker] Set ${count} uniforms`);
|
|
665
|
-
}
|
|
666
|
-
}
|
|
667
|
-
|
|
668
717
|
const t = data.time ?? 0;
|
|
669
718
|
await withRenderLock(async () => {
|
|
719
|
+
// Host inputs land INSIDE the render lock (§6.2), at the head of the
|
|
720
|
+
// frame that carries them: uniforms and controls first, host buffer
|
|
721
|
+
// writes beside them, then the frame. Applied before the lock was
|
|
722
|
+
// taken, a thumbnail render could run between a draw's writes and its
|
|
723
|
+
// frame — overwriting the draw's control values with the thumbnail's
|
|
724
|
+
// `scene` lane, or leaking the draw's into the thumbnail, depending on
|
|
725
|
+
// the interleave. A control rides this same `uniforms` map (§6.1), so
|
|
726
|
+
// it inherits the ordering for free.
|
|
727
|
+
if (data.uniforms && typeof data.uniforms === "object") {
|
|
728
|
+
const count = gpu.setUniforms(data.uniforms);
|
|
729
|
+
if (debugMode && count > 0) {
|
|
730
|
+
console.log(`[Worker] Set ${count} uniforms`);
|
|
731
|
+
}
|
|
732
|
+
}
|
|
670
733
|
// Host buffer writes ride the draw message and land at the head of the
|
|
671
|
-
// frame that carries them — INSIDE the render lock,
|
|
734
|
+
// frame that carries them — INSIDE the render lock, like the uniforms
|
|
672
735
|
// above, because a `poolIndex: "active"` write resolves against the
|
|
673
736
|
// executor's frame counter, and a prefetch thumbnail render moves and
|
|
674
737
|
// restores that counter under this same lock (renderEphemeral). Read
|
|
@@ -734,6 +797,7 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
734
797
|
moduleLoaded = false;
|
|
735
798
|
initialized = false;
|
|
736
799
|
uniformMap = null;
|
|
800
|
+
controlTable = null;
|
|
737
801
|
bufferNames = new Map();
|
|
738
802
|
frameNames = new Map();
|
|
739
803
|
appliedFrame = null;
|
|
@@ -949,6 +1013,11 @@ export function createWorkerHandlers(env, opts = {}) {
|
|
|
949
1013
|
// every pooled binding. renderEphemeral (shared with the resize
|
|
950
1014
|
// repaint) saves and restores the counter around the render.
|
|
951
1015
|
renderEphemeral,
|
|
1016
|
+
// The control-table half of the same side-effect-freeness: drain()
|
|
1017
|
+
// snapshots the live values before applying a thumbnail's uniforms and
|
|
1018
|
+
// restores them after (§6.2).
|
|
1019
|
+
snapshotControls,
|
|
1020
|
+
restoreControls,
|
|
952
1021
|
getCanvas: () => canvas,
|
|
953
1022
|
getGpu: () => gpu,
|
|
954
1023
|
loaded: () => moduleLoaded,
|
package/src/worker-prefetch.js
CHANGED
|
@@ -9,6 +9,8 @@
|
|
|
9
9
|
// env — makeOffscreen, grabBitmap, defer, gpuTextureUsage
|
|
10
10
|
// post(msg, xfer?) — self.postMessage
|
|
11
11
|
// render(t, w, h) — the shared frame renderer (awaited)
|
|
12
|
+
// snapshotControls()/restoreControls(saved) — the live control table's
|
|
13
|
+
// save/restore around a thumbnail's own uniforms (§6.2)
|
|
12
14
|
// getCanvas() — the visible OffscreenCanvas (thumbnail source)
|
|
13
15
|
// getGpu() — the current command dispatcher
|
|
14
16
|
// loaded() — moduleLoaded (drain / prefetch guards)
|
|
@@ -163,6 +165,15 @@ export function createPrefetch(host) {
|
|
|
163
165
|
// context (or capturing this block's frame onto the visible canvas).
|
|
164
166
|
await host.withRenderLock(async () => {
|
|
165
167
|
gpu.setRenderTargetContext(prefetchCtx);
|
|
168
|
+
// Snapshot the LIVE control values before the thumbnail's uniforms
|
|
169
|
+
// touch the table — inside this locked section, because that is
|
|
170
|
+
// where the values stop being live: a thumbnail's `scene` lane
|
|
171
|
+
// writes the same table the next live frame reads. Restored in the
|
|
172
|
+
// finally below, the way renderEphemeral restores the frame
|
|
173
|
+
// counter. (A snapshot taken inside renderEphemeral itself would
|
|
174
|
+
// capture the thumbnail's values — §6.2.) Uniform writes that went
|
|
175
|
+
// to GPU buffers are NOT restored: a preview cannot undo GPU work.
|
|
176
|
+
const savedControls = host.snapshotControls();
|
|
166
177
|
try {
|
|
167
178
|
// Apply this block's score uniforms (when present) so the thumbnail
|
|
168
179
|
// renders the animation's value at its center time, exactly as the
|
|
@@ -174,6 +185,7 @@ export function createPrefetch(host) {
|
|
|
174
185
|
// hosts built before it existed.
|
|
175
186
|
await (host.renderEphemeral ?? host.render)(centerTime, prefetchCanvas.width, prefetchCanvas.height);
|
|
176
187
|
} finally {
|
|
188
|
+
host.restoreControls(savedControls);
|
|
177
189
|
gpu.setRenderTargetContext(null);
|
|
178
190
|
}
|
|
179
191
|
});
|
|
Binary file
|
package/wasm/pngine.wasm
CHANGED
|
Binary file
|