nucleation 0.6.0 → 0.8.0

package/Field3.mjs

@@ -0,0 +1,160 @@
+// generated by diplomat-tool
+import { FieldRange } from "./FieldRange.mjs"
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Field3_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Field3_destroy(ptr);
+});
+
+/**
+ * Immutable scalar field evaluated over world-space `(x, y, z)`.
+ *
+ * A `Field3` has scalar semantics only. It may be shared by geometry and
+ * material consumers without being reinterpreted as a signed-distance field.
+ */
+export class Field3 {
+    // 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("Field3 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) {
+            Field3_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Deterministic value-noise FBM normalized to `[-1, 1]`.
+     */
+    static valueNoiseFbm(frequency, seed, octaves) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Field3_value_noise_fbm(diplomatReceive.buffer, frequency, seed, octaves);
+
+        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 Field3(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    evalAt(x, y, z) {
+
+        const result = wasm.Field3_eval_at(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The field's analytically proven output range.
+     *
+     * Returns `NotFound` when no range can be proven — callers mapping a
+     * field onto a gradient must handle that rather than silently
+     * propagating a sentinel into their `lo`/`hi` bounds.
+     */
+    outputRange() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 9, 4, true);
+
+
+        const result = wasm.Field3_output_range(diplomatReceive.buffer, this.ffiValue);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return FieldRange._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    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.Field3_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 Field3(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.Field3_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();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/FieldProgram.d.mts

@@ -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/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/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/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/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/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)
+    }
+}