nucleation 0.10.21 → 0.10.23

package/renderer/FieldProgram.d.ts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { FieldProgramDistanceKind } from "./FieldProgramDistanceKind.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { SdfBounds } from "./SdfBounds.mjs"
+import type { SdfNormal } from "./SdfNormal.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A validated, sandboxed custom SDF field program: deterministic typed
+ * bytecode over scalar/vec3/bool values with bounded loops, carrying
+ * its own explicit finite bounds and distance-kind metadata. Build one
+ * with {@link FieldProgramBuilder} or import it from JSON.
+ */
+export class FieldProgram {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static fromJsonString(json: string): FieldProgram;
+
+    toJson(): string;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    /**
+     * Unit-length gradient of the scalar output at `(x, y, z)`: the
+     * program's own forward-mode analytic gradient where it's
+     * differentiable there, falling back to a numerical estimate
+     * (central differences via `epsilon`) otherwise.
+     */
+    gradient(x: number, y: number, z: number, epsilon: number): SdfNormal;
+
+    bounds(): SdfBounds;
+
+    distanceKind(): FieldProgramDistanceKind;
+}

package/renderer/FieldProgram.mjs

@@ -0,0 +1,167 @@
+// generated by diplomat-tool
+import { FieldProgramDistanceKind } from "./FieldProgramDistanceKind.mjs"
+import { NucleationError } from "./NucleationError.mjs"
+import { SdfBounds } from "./SdfBounds.mjs"
+import { SdfNormal } from "./SdfNormal.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const FieldProgram_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.FieldProgram_destroy(ptr);
+});
+
+/**
+ * A validated, sandboxed custom SDF field program: deterministic typed
+ * bytecode over scalar/vec3/bool values with bounded loops, carrying
+ * its own explicit finite bounds and distance-kind metadata. Build one
+ * with {@link FieldProgramBuilder} or import it from JSON.
+ */
+export class FieldProgram {
+    // Internal ptr reference:
+    #ptr = null;
+
+    // Lifetimes are only to keep dependencies alive.
+    // Since JS won't garbage collect until there are no incoming edges.
+    #selfEdge = [];
+
+    #internalConstructor(symbol, ptr, selfEdge) {
+        if (symbol !== diplomatRuntime.internalConstructor) {
+            console.error("FieldProgram is an Opaque type. You cannot call its constructor.");
+            return;
+        }
+        this.#ptr = ptr;
+        this.#selfEdge = selfEdge;
+
+        // Are we being borrowed? If not, we can register.
+        if (this.#selfEdge.length === 0) {
+            FieldProgram_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    static fromJsonString(json) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const jsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, json)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.FieldProgram_from_json_string(diplomatReceive.buffer, jsonSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new FieldProgram(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    toJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.FieldProgram_to_json(diplomatReceive.buffer, this.ffiValue, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    evalAt(x, y, z) {
+
+        const result = wasm.FieldProgram_eval_at(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Unit-length gradient of the scalar output at `(x, y, z)`: the
+     * program's own forward-mode analytic gradient where it's
+     * differentiable there, falling back to a numerical estimate
+     * (central differences via `epsilon`) otherwise.
+     */
+    gradient(x, y, z, epsilon) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 13, 4, true);
+
+
+        const result = wasm.FieldProgram_gradient(diplomatReceive.buffer, this.ffiValue, x, y, z, epsilon);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return SdfNormal._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    bounds() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 24, 4, false);
+
+
+        const result = wasm.FieldProgram_bounds(diplomatReceive.buffer, this.ffiValue);
+
+        try {
+            return SdfBounds._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    distanceKind() {
+
+        const result = wasm.FieldProgram_distance_kind(this.ffiValue);
+
+        try {
+            return new FieldProgramDistanceKind(diplomatRuntime.internalConstructor, result);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/FieldProgramBinaryOp.d.mts

@@ -0,0 +1,42 @@
+// generated by diplomat-tool
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Binary field-program operations (see `crate::sdf::BinaryOp`). `Add`
+ * and `Sub` accept either two scalars or two vec3s.
+ */
+export class FieldProgramBinaryOp {
+
+    /** @internal */
+    static fromValue(value: FieldProgramBinaryOp | string): FieldProgramBinaryOp;
+
+    get value(): string;
+
+    /** @internal */
+    get ffiValue(): number;
+
+    static Add : FieldProgramBinaryOp;
+    static Sub : FieldProgramBinaryOp;
+    static Mul : FieldProgramBinaryOp;
+    static Div : FieldProgramBinaryOp;
+    static Min : FieldProgramBinaryOp;
+    static Max : FieldProgramBinaryOp;
+    static Pow : FieldProgramBinaryOp;
+    static Atan2 : FieldProgramBinaryOp;
+    static Lt : FieldProgramBinaryOp;
+    static Le : FieldProgramBinaryOp;
+    static Gt : FieldProgramBinaryOp;
+    static Ge : FieldProgramBinaryOp;
+    static Eq : FieldProgramBinaryOp;
+    static Dot : FieldProgramBinaryOp;
+    static Cross : FieldProgramBinaryOp;
+    /**
+     * `vec3 * scalar`, componentwise.
+     */
+    static Scale : FieldProgramBinaryOp;
+
+
+    constructor(value: FieldProgramBinaryOp | string );
+}

package/renderer/FieldProgramBinaryOp.d.ts

@@ -0,0 +1,42 @@
+// generated by diplomat-tool
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Binary field-program operations (see `crate::sdf::BinaryOp`). `Add`
+ * and `Sub` accept either two scalars or two vec3s.
+ */
+export class FieldProgramBinaryOp {
+
+    /** @internal */
+    static fromValue(value: FieldProgramBinaryOp | string): FieldProgramBinaryOp;
+
+    get value(): string;
+
+    /** @internal */
+    get ffiValue(): number;
+
+    static Add : FieldProgramBinaryOp;
+    static Sub : FieldProgramBinaryOp;
+    static Mul : FieldProgramBinaryOp;
+    static Div : FieldProgramBinaryOp;
+    static Min : FieldProgramBinaryOp;
+    static Max : FieldProgramBinaryOp;
+    static Pow : FieldProgramBinaryOp;
+    static Atan2 : FieldProgramBinaryOp;
+    static Lt : FieldProgramBinaryOp;
+    static Le : FieldProgramBinaryOp;
+    static Gt : FieldProgramBinaryOp;
+    static Ge : FieldProgramBinaryOp;
+    static Eq : FieldProgramBinaryOp;
+    static Dot : FieldProgramBinaryOp;
+    static Cross : FieldProgramBinaryOp;
+    /**
+     * `vec3 * scalar`, componentwise.
+     */
+    static Scale : FieldProgramBinaryOp;
+
+
+    constructor(value: FieldProgramBinaryOp | string );
+}

package/renderer/FieldProgramBinaryOp.mjs

@@ -0,0 +1,118 @@
+// generated by diplomat-tool
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+
+
+/**
+ * Binary field-program operations (see `crate::sdf::BinaryOp`). `Add`
+ * and `Sub` accept either two scalars or two vec3s.
+ */
+export class FieldProgramBinaryOp {
+    #value = undefined;
+
+    static #values = new Map([
+        ["Add", 0],
+        ["Sub", 1],
+        ["Mul", 2],
+        ["Div", 3],
+        ["Min", 4],
+        ["Max", 5],
+        ["Pow", 6],
+        ["Atan2", 7],
+        ["Lt", 8],
+        ["Le", 9],
+        ["Gt", 10],
+        ["Ge", 11],
+        ["Eq", 12],
+        ["Dot", 13],
+        ["Cross", 14],
+        ["Scale", 15]
+    ]);
+
+    static getAllEntries() {
+        return FieldProgramBinaryOp.#values.entries();
+    }
+
+    #internalConstructor(value) {
+        if (arguments.length > 1 && arguments[0] === diplomatRuntime.internalConstructor) {
+            // We pass in two internalConstructor arguments to create *new*
+            // instances of this type, otherwise the enums are treated as singletons.
+            if (arguments[1] === diplomatRuntime.internalConstructor ) {
+                this.#value = arguments[2];
+                return this;
+            }
+            return FieldProgramBinaryOp.#objectValues[arguments[1]];
+        }
+
+        if (value instanceof FieldProgramBinaryOp) {
+            return value;
+        }
+
+        let intVal = FieldProgramBinaryOp.#values.get(value);
+
+        // Nullish check, checks for null or undefined
+        if (intVal != null) {
+            return FieldProgramBinaryOp.#objectValues[intVal];
+        }
+
+        throw TypeError(value + " is not a FieldProgramBinaryOp and does not correspond to any of its enumerator values.");
+    }
+
+    /** @internal */
+    static fromValue(value) {
+        return new FieldProgramBinaryOp(value);
+    }
+
+    get value(){
+        return [...FieldProgramBinaryOp.#values.keys()][this.#value];
+    }
+
+    /** @internal */
+    get ffiValue(){
+        return this.#value;
+    }
+    static #objectValues = [
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 0),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 1),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 2),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 3),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 4),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 5),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 6),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 7),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 8),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 9),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 10),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 11),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 12),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 13),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 14),
+        new FieldProgramBinaryOp(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 15),
+    ];
+
+    static Add = FieldProgramBinaryOp.#objectValues[0];
+    static Sub = FieldProgramBinaryOp.#objectValues[1];
+    static Mul = FieldProgramBinaryOp.#objectValues[2];
+    static Div = FieldProgramBinaryOp.#objectValues[3];
+    static Min = FieldProgramBinaryOp.#objectValues[4];
+    static Max = FieldProgramBinaryOp.#objectValues[5];
+    static Pow = FieldProgramBinaryOp.#objectValues[6];
+    static Atan2 = FieldProgramBinaryOp.#objectValues[7];
+    static Lt = FieldProgramBinaryOp.#objectValues[8];
+    static Le = FieldProgramBinaryOp.#objectValues[9];
+    static Gt = FieldProgramBinaryOp.#objectValues[10];
+    static Ge = FieldProgramBinaryOp.#objectValues[11];
+    static Eq = FieldProgramBinaryOp.#objectValues[12];
+    static Dot = FieldProgramBinaryOp.#objectValues[13];
+    static Cross = FieldProgramBinaryOp.#objectValues[14];
+    /**
+     * `vec3 * scalar`, componentwise.
+     */
+    static Scale = FieldProgramBinaryOp.#objectValues[15];
+
+
+    constructor(value) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/FieldProgramBuilder.d.mts

@@ -0,0 +1,104 @@
+// generated by diplomat-tool
+import type { FieldProgram } from "./FieldProgram.mjs"
+import type { FieldProgramBinaryOp } from "./FieldProgramBinaryOp.mjs"
+import type { FieldProgramDistanceKind } from "./FieldProgramDistanceKind.mjs"
+import type { FieldProgramUnaryOp } from "./FieldProgramUnaryOp.mjs"
+import type { FieldProgramValueType } from "./FieldProgramValueType.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Programmatic builder for a {@link FieldProgram}: append typed stack
+ * instructions, then {@link FieldProgramBuilder::build} to validate and
+ * obtain a {@link FieldProgram}. Consuming: every method after `build()`
+ * (successful or not) returns `AlreadyConsumed`.
+ */
+export class FieldProgramBuilder {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static create(): FieldProgramBuilder;
+
+    /**
+     * Declare a new typed local slot and return its index.
+     */
+    addSlot(valueType: FieldProgramValueType): number;
+
+    pushConstScalar(value: number): void;
+
+    pushConstVec3(x: number, y: number, z: number): void;
+
+    pushConstBool(value: boolean): void;
+
+    /**
+     * Push the `Vec3` position the program is being evaluated at.
+     */
+    pushPos(): void;
+
+    loadLocal(slot: number): void;
+
+    storeLocal(slot: number): void;
+
+    /**
+     * Discard the top of the stack.
+     */
+    pop(): void;
+
+    unaryOp(op: FieldProgramUnaryOp): void;
+
+    binaryOp(op: FieldProgramBinaryOp): void;
+
+    /**
+     * Pop `(x, lo, hi)`, push `x` clamped to `[lo, hi]`.
+     */
+    clamp(): void;
+
+    /**
+     * Pop `(a, b, cond)`, push `a` if `cond` else `b`.
+     */
+    select(): void;
+
+    /**
+     * Pop `(x, y, z)`, push `Vec3([x, y, z])`.
+     */
+    makeVec3(): void;
+
+    /**
+     * Pop a `Bool`; if true, stop the nearest enclosing repeat after
+     * this iteration. Only valid inside `beginRepeat`/`endRepeat`.
+     */
+    breakIf(): void;
+
+    /**
+     * Open a new statically bounded repeat block; subsequent
+     * instructions append to its body until `endRepeat`.
+     */
+    beginRepeat(count: number): void;
+
+    /**
+     * Close the innermost open repeat block.
+     */
+    endRepeat(): void;
+
+    /**
+     * Declare which scalar slot holds the program's output.
+     */
+    setOutput(slot: number): void;
+
+    /**
+     * Set the program's explicit, author-asserted finite bounds.
+     */
+    setBounds(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void;
+
+    setDistanceKind(kind: FieldProgramDistanceKind): void;
+
+    /**
+     * Validate and finalize. Consumes the builder even on failure.
+     */
+    build(): FieldProgram;
+}

package/renderer/FieldProgramBuilder.d.ts

@@ -0,0 +1,104 @@
+// generated by diplomat-tool
+import type { FieldProgram } from "./FieldProgram.mjs"
+import type { FieldProgramBinaryOp } from "./FieldProgramBinaryOp.mjs"
+import type { FieldProgramDistanceKind } from "./FieldProgramDistanceKind.mjs"
+import type { FieldProgramUnaryOp } from "./FieldProgramUnaryOp.mjs"
+import type { FieldProgramValueType } from "./FieldProgramValueType.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Programmatic builder for a {@link FieldProgram}: append typed stack
+ * instructions, then {@link FieldProgramBuilder::build} to validate and
+ * obtain a {@link FieldProgram}. Consuming: every method after `build()`
+ * (successful or not) returns `AlreadyConsumed`.
+ */
+export class FieldProgramBuilder {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static create(): FieldProgramBuilder;
+
+    /**
+     * Declare a new typed local slot and return its index.
+     */
+    addSlot(valueType: FieldProgramValueType): number;
+
+    pushConstScalar(value: number): void;
+
+    pushConstVec3(x: number, y: number, z: number): void;
+
+    pushConstBool(value: boolean): void;
+
+    /**
+     * Push the `Vec3` position the program is being evaluated at.
+     */
+    pushPos(): void;
+
+    loadLocal(slot: number): void;
+
+    storeLocal(slot: number): void;
+
+    /**
+     * Discard the top of the stack.
+     */
+    pop(): void;
+
+    unaryOp(op: FieldProgramUnaryOp): void;
+
+    binaryOp(op: FieldProgramBinaryOp): void;
+
+    /**
+     * Pop `(x, lo, hi)`, push `x` clamped to `[lo, hi]`.
+     */
+    clamp(): void;
+
+    /**
+     * Pop `(a, b, cond)`, push `a` if `cond` else `b`.
+     */
+    select(): void;
+
+    /**
+     * Pop `(x, y, z)`, push `Vec3([x, y, z])`.
+     */
+    makeVec3(): void;
+
+    /**
+     * Pop a `Bool`; if true, stop the nearest enclosing repeat after
+     * this iteration. Only valid inside `beginRepeat`/`endRepeat`.
+     */
+    breakIf(): void;
+
+    /**
+     * Open a new statically bounded repeat block; subsequent
+     * instructions append to its body until `endRepeat`.
+     */
+    beginRepeat(count: number): void;
+
+    /**
+     * Close the innermost open repeat block.
+     */
+    endRepeat(): void;
+
+    /**
+     * Declare which scalar slot holds the program's output.
+     */
+    setOutput(slot: number): void;
+
+    /**
+     * Set the program's explicit, author-asserted finite bounds.
+     */
+    setBounds(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void;
+
+    setDistanceKind(kind: FieldProgramDistanceKind): void;
+
+    /**
+     * Validate and finalize. Consumes the builder even on failure.
+     */
+    build(): FieldProgram;
+}