@aethervtt/shard-noise 0.0.1

package/dist/graph.js

@@ -0,0 +1,370 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { MAX_OCTAVES, nodeDef } from "./nodes.js";
+function pointer(segment) {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+const fail = (code, path, message, hint) => new ShardError(code, message, { path, ...hint ? { hint } : {} });
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseGraph(json) {
+  const errors = [];
+  if (!isObject(json)) {
+    errors.push(
+      new ShardError("noise/invalid-graph", "A noise graph is a JSON object", {
+        path: "",
+        hint: 'Start from { "output": "height", "nodes": { \u2026 } }.'
+      })
+    );
+    return { errors };
+  }
+  for (const key of Object.keys(json)) {
+    if (!["$schema", "output", "nodes", "dimensions", "extent", "description"].includes(key)) {
+      errors.push(
+        fail(
+          "noise/invalid-graph",
+          `/${pointer(key)}`,
+          `Unknown graph field "${key}"`,
+          "Graph fields: output, nodes, dimensions, extent, description."
+        )
+      );
+    }
+  }
+  const dimensions = json.dimensions ?? 3;
+  if (dimensions !== 2 && dimensions !== 3 && dimensions !== 4) {
+    errors.push(fail("noise/invalid-graph", "/dimensions", '"dimensions" must be 2, 3, or 4'));
+  }
+  const dims = dimensions === 2 || dimensions === 4 ? dimensions : 3;
+  const extent = json.extent;
+  if (extent !== void 0 && (typeof extent !== "number" || !(extent > 0))) {
+    errors.push(
+      fail("noise/invalid-graph", "/extent", '"extent" must be a positive number of units')
+    );
+  }
+  if (json.description !== void 0 && typeof json.description !== "string") {
+    errors.push(fail("noise/invalid-graph", "/description", '"description" must be a string'));
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  if (!isObject(json.nodes) || Object.keys(json.nodes).length === 0) {
+    errors.push(
+      fail(
+        "noise/invalid-graph",
+        "/nodes",
+        'A graph needs a "nodes" object with at least one node',
+        'Add "nodes": { "height": { "fbm": { "octaves": 5 } } }.'
+      )
+    );
+  } else {
+    for (const [name, body] of Object.entries(json.nodes)) {
+      const node = parseNode(body, `/nodes/${pointer(name)}`, dims, errors);
+      if (node) nodes.set(name, node);
+    }
+  }
+  const output = json.output;
+  if (typeof output !== "string") {
+    errors.push(
+      fail("noise/invalid-graph", "/output", '"output" must name the node the graph returns')
+    );
+  } else if (isObject(json.nodes) && !(output in json.nodes)) {
+    errors.push(
+      fail(
+        "noise/unknown-node",
+        "/output",
+        `"output" names "${output}", which isn't a node`,
+        hintFor(output, json.nodes)
+      )
+    );
+  }
+  if (isObject(json.nodes)) {
+    for (const node of nodes.values()) checkRefs(node, json.nodes, errors);
+    checkCycles(nodes, errors);
+  }
+  if (errors.length > 0) return { errors };
+  return {
+    graph: {
+      output,
+      dimensions: dims,
+      extent,
+      description: json.description,
+      nodes
+    },
+    errors
+  };
+}
+function hintFor(_name, nodes) {
+  const names = Object.keys(nodes);
+  return names.length > 0 ? `Nodes in this graph: ${names.join(", ")}.` : 'Add the node under "nodes".';
+}
+function parseInput(v, path, dims, errors) {
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) {
+      errors.push(
+        new ShardError("noise/invalid-param", "Numbers must be finite", {
+          path,
+          hint: "Check the parameter against .shard/schemas/noise.schema.json."
+        })
+      );
+      return void 0;
+    }
+    return { kind: "const", value: v };
+  }
+  if (typeof v === "string") return { kind: "ref", name: v, path };
+  if (isObject(v)) {
+    const node = parseNode(v, path, dims, errors);
+    return node ? { kind: "node", node } : void 0;
+  }
+  errors.push(
+    fail("noise/invalid-param", path, "An input is a node name, an inline node, or a number")
+  );
+  return void 0;
+}
+function parseNode(body, path, dims, errors) {
+  if (typeof body === "number") {
+    const def2 = nodeDef("constant");
+    return { type: "constant", def: def2, params: { value: body }, path };
+  }
+  if (!isObject(body) || Object.keys(body).length !== 1) {
+    errors.push(
+      new ShardError("noise/invalid-node", "A node is an object with exactly one key: its type", {
+        path,
+        hint: 'For example { "fbm": { "octaves": 5 } }.'
+      })
+    );
+    return void 0;
+  }
+  const [type, raw] = Object.entries(body)[0];
+  const def = nodeDef(type);
+  const at = `${path}/${pointer(type)}`;
+  if (!def) {
+    errors.push(
+      new ShardError("noise/unknown-type", `Unknown node type "${type}"`, {
+        path: at,
+        hint: "Types: value, perlin, simplex, cellular, fbm, ridged, billow, add, multiply, min, max, lerp, select, remap, clamp, curve, terrace, abs, power, constant, warp, scale, translate."
+      })
+    );
+    return void 0;
+  }
+  if (def.form === "value") {
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      errors.push(fail("noise/invalid-param", at, `"${type}" takes a number`));
+      return void 0;
+    }
+    return { type, def, params: { value: raw }, path: at };
+  }
+  if (def.form === "list") {
+    if (!Array.isArray(raw) || raw.length < 2) {
+      errors.push(
+        new ShardError("noise/arity", `"${type}" takes an array of two or more inputs`, {
+          path: at,
+          hint: 'Give it two or more inputs: node names, inline nodes, or numbers, e.g. ["a", "b"].'
+        })
+      );
+      return void 0;
+    }
+    const inputs = [];
+    raw.forEach((v, i) => {
+      const input = parseInput(v, `${at}/${i}`, dims, errors);
+      if (input) inputs.push(input);
+    });
+    return { type, def, params: { inputs }, path: at };
+  }
+  let fields;
+  if (def.form === "unary" && !isObject(raw)) fields = { input: raw };
+  else if (def.form === "unary" && isObject(raw) && !("input" in raw)) fields = { input: raw };
+  else if (isObject(raw)) fields = raw;
+  else {
+    errors.push(
+      fail(
+        "noise/invalid-node",
+        at,
+        `"${type}" takes an object of parameters`,
+        `Parameters: ${Object.keys(def.params).join(", ")}.`
+      )
+    );
+    return void 0;
+  }
+  const params = {};
+  for (const key of Object.keys(fields)) {
+    if (!(key in def.params)) {
+      errors.push(
+        fail(
+          "noise/invalid-param",
+          `${at}/${pointer(key)}`,
+          `"${type}" has no parameter "${key}"`,
+          `Parameters: ${Object.keys(def.params).join(", ")}.`
+        )
+      );
+    }
+  }
+  for (const [key, p] of Object.entries(def.params)) {
+    const value = parseParam(p, fields[key], `${at}/${pointer(key)}`, type, key, dims, errors);
+    if (value !== void 0) params[key] = value;
+  }
+  return { type, def, params, path: at };
+}
+function parseParam(p, v, path, type, key, dims, errors) {
+  const bad = (what) => {
+    errors.push(fail("noise/invalid-param", path, `"${type}.${key}" ${what}`, p.description));
+    return void 0;
+  };
+  if (v === void 0) {
+    if (p.type === "input") {
+      errors.push(fail("noise/arity", path, `"${type}" needs "${key}"`, p.description));
+      return void 0;
+    }
+    if (p.type === "points") {
+      errors.push(fail("noise/arity", path, `"${type}" needs "${key}"`, p.description));
+      return void 0;
+    }
+    if ("default" in p && p.default !== void 0) {
+      if (key === "dims" && dims === 2) return 2;
+      return p.default;
+    }
+    return void 0;
+  }
+  switch (p.type) {
+    case "input":
+      return parseInput(v, path, dims, errors);
+    case "number": {
+      if (typeof v !== "number" || !Number.isFinite(v)) return bad("must be a number");
+      if (p.positive && !(v > 0)) return bad("must be greater than 0");
+      if (p.min !== void 0 && v < p.min) return bad(`must be at least ${p.min}`);
+      if (p.max !== void 0 && v > p.max) return bad(`must be at most ${p.max}`);
+      return v;
+    }
+    case "integer": {
+      if (typeof v !== "number" || !Number.isInteger(v)) return bad("must be an integer");
+      if (key === "octaves" && v > MAX_OCTAVES) {
+        errors.push(
+          new ShardError(
+            "noise/too-many-octaves",
+            `"${type}" has ${v} octaves; the most is ${MAX_OCTAVES}`,
+            {
+              path,
+              hint: "Past 16 octaves the extra detail is below a pixel anywhere; raise frequency instead."
+            }
+          )
+        );
+        return void 0;
+      }
+      if (p.min !== void 0 && v < p.min) return bad(`must be at least ${p.min}`);
+      if (p.max !== void 0 && v > p.max) return bad(`must be at most ${p.max}`);
+      return v;
+    }
+    case "boolean":
+      return typeof v === "boolean" ? v : bad("must be true or false");
+    case "enum": {
+      if (!p.values.includes(v))
+        return bad(`must be one of ${p.values.join(", ")}`);
+      if (key === "dims" && v === 4 && dims !== 4) {
+        errors.push(
+          new ShardError("noise/domain-mismatch", `"${type}" is 4D but the graph is ${dims}D`, {
+            path,
+            hint: 'Set "dimensions": 4 on the graph and sample it with a w coordinate, or use dims 3.'
+          })
+        );
+        return void 0;
+      }
+      return v;
+    }
+    case "pair": {
+      if (!Array.isArray(v) || v.length !== 2 || !v.every((x) => typeof x === "number" && Number.isFinite(x))) {
+        return bad("must be [a, b]");
+      }
+      return v;
+    }
+    case "vec": {
+      if (typeof v === "number" && Number.isFinite(v)) return [v, v, v, v];
+      if (!Array.isArray(v) || v.length < 2 || v.length > 4 || !v.every((x) => typeof x === "number" && Number.isFinite(x))) {
+        return bad("must be a number or [x, y, z]");
+      }
+      const fill = key === "by" && type === "scale" ? 1 : 0;
+      return [v[0], v[1], v[2] ?? fill, v[3] ?? fill];
+    }
+    case "points": {
+      if (!Array.isArray(v) || v.length < 2) {
+        errors.push(
+          fail("noise/arity", path, `"${type}.${key}" needs at least two points`, p.description)
+        );
+        return void 0;
+      }
+      let last = -Infinity;
+      for (let i = 0; i < v.length; i++) {
+        const pt = v[i];
+        if (!Array.isArray(pt) || pt.length !== 2 || !pt.every((x) => typeof x === "number" && Number.isFinite(x))) {
+          errors.push(fail("noise/invalid-param", `${path}/${i}`, "A point is [x, y]"));
+          return void 0;
+        }
+        if (pt[0] <= last) {
+          errors.push(fail("noise/invalid-param", `${path}/${i}`, "Curve points need increasing x"));
+          return void 0;
+        }
+        last = pt[0];
+      }
+      return v;
+    }
+  }
+}
+function eachInput(node, f) {
+  for (const value of Object.values(node.params)) {
+    if (Array.isArray(value)) {
+      for (const v of value) if (isInput(v)) f(v);
+    } else if (isInput(value)) f(value);
+  }
+}
+function isInput(v) {
+  return isObject(v) && (v.kind === "ref" || v.kind === "node" || v.kind === "const");
+}
+function forEachInput(node, f) {
+  eachInput(node, f);
+}
+function checkRefs(node, names, errors) {
+  eachInput(node, (input) => {
+    if (input.kind === "ref" && !(input.name in names)) {
+      errors.push(
+        // Hint for the docs: name a node under "nodes", or add it there.
+        new ShardError("noise/unknown-node", `"${input.name}" isn't a node in this graph`, {
+          path: input.path,
+          hint: hintFor(input.name, names)
+        })
+      );
+    } else if (input.kind === "node") checkRefs(input.node, names, errors);
+  });
+}
+function checkCycles(nodes, errors) {
+  const state = /* @__PURE__ */ new Map();
+  const reported = /* @__PURE__ */ new Set();
+  const visit = (name, trail) => {
+    const s = state.get(name);
+    if (s === "done") return;
+    if (s === "visiting") {
+      const loop = trail.slice(trail.indexOf(name));
+      const key = [...loop].sort().join(">");
+      if (!reported.has(key)) {
+        reported.add(key);
+        errors.push(
+          new ShardError("noise/cycle", `Nodes form a cycle: ${[...loop, name].join(" \u2192 ")}`, {
+            path: `/nodes/${pointer(name)}`,
+            hint: "A node can\u2019t depend on itself; break the loop with a separate node."
+          })
+        );
+      }
+      return;
+    }
+    const node = nodes.get(name);
+    if (!node) return;
+    state.set(name, "visiting");
+    const walk = (n) => eachInput(n, (input) => {
+      if (input.kind === "ref") visit(input.name, [...trail, name]);
+      else if (input.kind === "node") walk(input.node);
+    });
+    walk(node);
+    state.set(name, "done");
+  };
+  for (const name of nodes.keys()) visit(name, []);
+}
+export {
+  forEachInput,
+  parseGraph,
+  pointer
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { compileGraph, FRACTAL, type NoiseProgram, OP, POSITION_REGS, SKEW, WIDTH, } from './compile.js';
+export { NOISE_LIBRARY_PATH, registerNoiseGraph, registerNoiseLibrary } from './gpu.js';
+export { forEachInput, type GraphInput, type GraphNode, type ParamValue, type ParsedGraph, parseGraph, pointer, } from './graph.js';
+export { BLOCK, computeOrigins, directionToFace, faceToDirection, gridOrigin, gridPoints, ORIGIN_WORDS, type OriginTerms, patchOrigin, patchPoints, } from './kernel.js';
+export { loadNoiseKernel, type NoiseKernel, noiseKernel, simdSupported, useNoiseKernel, } from './loader.js';
+export { MAX_SAMPLE_POINTS, noiseMethods, resolveGraph } from './methods.js';
+export { CELL_DISTANCES, CELL_RETURNS, MAX_OCTAVES, NODE_DEFS, type NodeCategory, type NodeDef, nodeDef, type ParamDef, SOURCE_KINDS, type SourceKind, } from './nodes.js';
+export { NoiseGraph, type NoiseGraphArtifact, NoiseGraphAssetType, NoiseGraphImporter, NoiseGraphStore, NoiseGraphs, noiseNames, type ProgramJson, } from './noise-graph.js';
+export { noisePlugin } from './plugin.js';
+export { type AsyncOptions, type Grid2d, type GridParams, noiseOrigins, normalizeGrid, poolTiming, type SpherePatch, sampleGrid2d, sampleGrid2dAsync, sampleNoise, sampleNoiseAsync, sampleNoiseGradient, sampleOffset, sampleSpherePatch, sampleSpherePatchAsync, } from './sample.js';
+export { noiseJsonSchema } from './schema.js';
+export { type NoiseDomain, type NoisePreviewOptions, type NoiseStats, noiseStats, previewNoise, } from './stats.js';
+export { generateWgsl, NOISE_LIBRARY, type WgslOptions } from './wgsl.js';

package/dist/index.js

@@ -0,0 +1,127 @@
+import {
+  compileGraph,
+  FRACTAL,
+  OP,
+  POSITION_REGS,
+  SKEW,
+  WIDTH
+} from "./compile.js";
+import { NOISE_LIBRARY_PATH, registerNoiseGraph, registerNoiseLibrary } from "./gpu.js";
+import {
+  forEachInput,
+  parseGraph,
+  pointer
+} from "./graph.js";
+import {
+  BLOCK,
+  computeOrigins,
+  directionToFace,
+  faceToDirection,
+  gridOrigin,
+  gridPoints,
+  ORIGIN_WORDS,
+  patchOrigin,
+  patchPoints
+} from "./kernel.js";
+import {
+  loadNoiseKernel,
+  noiseKernel,
+  simdSupported,
+  useNoiseKernel
+} from "./loader.js";
+import { MAX_SAMPLE_POINTS, noiseMethods, resolveGraph } from "./methods.js";
+import {
+  CELL_DISTANCES,
+  CELL_RETURNS,
+  MAX_OCTAVES,
+  NODE_DEFS,
+  nodeDef,
+  SOURCE_KINDS
+} from "./nodes.js";
+import {
+  NoiseGraph,
+  NoiseGraphAssetType,
+  NoiseGraphImporter,
+  NoiseGraphStore,
+  NoiseGraphs,
+  noiseNames
+} from "./noise-graph.js";
+import { noisePlugin } from "./plugin.js";
+import {
+  noiseOrigins,
+  normalizeGrid,
+  poolTiming,
+  sampleGrid2d,
+  sampleGrid2dAsync,
+  sampleNoise,
+  sampleNoiseAsync,
+  sampleNoiseGradient,
+  sampleOffset,
+  sampleSpherePatch,
+  sampleSpherePatchAsync
+} from "./sample.js";
+import { noiseJsonSchema } from "./schema.js";
+import {
+  noiseStats,
+  previewNoise
+} from "./stats.js";
+import { generateWgsl, NOISE_LIBRARY } from "./wgsl.js";
+export {
+  BLOCK,
+  CELL_DISTANCES,
+  CELL_RETURNS,
+  FRACTAL,
+  MAX_OCTAVES,
+  MAX_SAMPLE_POINTS,
+  NODE_DEFS,
+  NOISE_LIBRARY,
+  NOISE_LIBRARY_PATH,
+  NoiseGraph,
+  NoiseGraphAssetType,
+  NoiseGraphImporter,
+  NoiseGraphStore,
+  NoiseGraphs,
+  OP,
+  ORIGIN_WORDS,
+  POSITION_REGS,
+  SKEW,
+  SOURCE_KINDS,
+  WIDTH,
+  compileGraph,
+  computeOrigins,
+  directionToFace,
+  faceToDirection,
+  forEachInput,
+  generateWgsl,
+  gridOrigin,
+  gridPoints,
+  loadNoiseKernel,
+  nodeDef,
+  noiseJsonSchema,
+  noiseKernel,
+  noiseMethods,
+  noiseNames,
+  noiseOrigins,
+  noisePlugin,
+  noiseStats,
+  normalizeGrid,
+  parseGraph,
+  patchOrigin,
+  patchPoints,
+  pointer,
+  poolTiming,
+  previewNoise,
+  registerNoiseGraph,
+  registerNoiseLibrary,
+  resolveGraph,
+  sampleGrid2d,
+  sampleGrid2dAsync,
+  sampleNoise,
+  sampleNoiseAsync,
+  sampleNoiseGradient,
+  sampleOffset,
+  sampleSpherePatch,
+  sampleSpherePatchAsync,
+  simdSupported,
+  useNoiseKernel
+};

package/dist/kernel.d.ts

@@ -0,0 +1,99 @@
+// Types for kernel.js (plain JavaScript so worker threads can import it without a loader).
+
+export declare const BLOCK: number
+export declare const ORIGIN_WORDS: number
+
+/** How each source octave's lattice position depends on the sample origin. */
+export interface OriginTerms {
+  /** Per term, xyzw: frequency × domain scale (f32 values). */
+  readonly a: Float64Array
+  /** Per term, xyzw: frequency × domain offset (f64). */
+  readonly b: Float64Array
+  /** Per term: 0 (none), 2, 3, or 4 (the simplex skew for that many dimensions). */
+  readonly skew: Uint8Array
+}
+
+/** What `evalProgram` needs from a compiled program. */
+export interface ProgramData {
+  readonly code: Int32Array
+  readonly consts: Float32Array
+  readonly registers: number
+  readonly result: number
+}
+
+export interface KernelState {
+  readonly memory: WebAssembly.Memory
+}
+
+export interface SpherePatch {
+  /** Cube face: 0 +X, 1 −X, 2 +Y, 3 −Y, 4 +Z, 5 −Z. */
+  readonly face: number
+  /** Lower corner in face coordinates, [-1, 1]. */
+  readonly x0: number
+  readonly y0: number
+  /** Side length in face coordinates (2 is the whole face). */
+  readonly extent: number
+  /** Vertices per side, edges included. */
+  readonly resolution: number
+  readonly radius: number
+}
+
+export interface Grid2d {
+  /** Lower corner. */
+  readonly origin: readonly [number, number]
+  readonly size: readonly [number, number]
+  /** Samples per side, edges included. */
+  readonly resolution: readonly [number, number]
+  /** The plane's z. Default 0. */
+  readonly z?: number
+}
+
+export declare function computeOrigins(
+  terms: OriginTerms,
+  origin: ArrayLike<number>,
+  out: Int32Array,
+): Int32Array
+export declare function instantiate(
+  module: WebAssembly.Module,
+  instance?: WebAssembly.Instance,
+): KernelState
+export declare function evalProgram(
+  state: KernelState,
+  program: ProgramData,
+  seed: number,
+  origins: Int32Array,
+  pts: ArrayLike<number>,
+  stride: number,
+  count: number,
+  out: Float32Array,
+  outOffset?: number,
+): void
+export declare function faceToDirection<T extends { [i: number]: number }>(
+  face: number,
+  u: number,
+  v: number,
+  out: T,
+  offset?: number,
+): T
+export declare function directionToFace(
+  x: number,
+  y: number,
+  z: number,
+  out: { [i: number]: number },
+): number
+export declare function patchOrigin(p: SpherePatch, out: Float64Array): Float64Array
+export declare function patchPoints(
+  p: SpherePatch,
+  origin: ArrayLike<number>,
+  row0: number,
+  row1: number,
+  out: Float32Array,
+): Float32Array
+export declare function gridOrigin(g: Grid2d, out: Float64Array): Float64Array
+export declare function gridPoints(
+  g: Grid2d,
+  origin: ArrayLike<number>,
+  row0: number,
+  row1: number,
+  out: Float32Array,
+): Float32Array