@tinypoly/gpu-renderer 0.0.0-stage → 0.0.1

package/src/structLayout.ts

@@ -0,0 +1,93 @@
+/**
+ * One description of a struct, from which both the WGSL declaration and the TypeScript writer come. The kernel's
+ * `Material` and `Frame` structs have dozens of fields each; keeping their word offsets by hand in two languages is the
+ * kind of mistake that compiles on both sides and then reads the wrong float on the device, where nothing can be printed.
+ *
+ * The alignment rules are WGSL's own for the host-shareable types used here.
+ */
+export type FieldType = "f32" | "u32" | "vec2u" | "vec4f" | "mat4f";
+
+export interface StructField {
+  name: string;
+  type: FieldType;
+  /** One line of documentation, carried into the generated WGSL. */
+  doc?: string;
+}
+
+export interface StructLayout {
+  name: string;
+  /** The WGSL declaration. */
+  wgsl: string;
+  /** Size in 32 bit words, rounded up to the struct's alignment, which is also its array stride. */
+  words: number;
+  /** Where each field starts, in words. */
+  offsets: Record<string, number>;
+  types: Record<string, FieldType>;
+}
+
+const SPEC: Record<FieldType, { words: number; align: number; wgsl: string }> = {
+  f32: { words: 1, align: 1, wgsl: "f32" },
+  u32: { words: 1, align: 1, wgsl: "u32" },
+  vec2u: { words: 2, align: 2, wgsl: "vec2<u32>" },
+  vec4f: { words: 4, align: 4, wgsl: "vec4<f32>" },
+  mat4f: { words: 16, align: 4, wgsl: "mat4x4<f32>" },
+};
+
+const roundUp = (value: number, align: number) => Math.ceil(value / align) * align;
+
+export function layoutStruct(name: string, fields: readonly StructField[]): StructLayout {
+  const offsets: Record<string, number> = {};
+  const types: Record<string, FieldType> = {};
+  const lines: string[] = [];
+  let at = 0;
+  let align = 1;
+
+  for (const field of fields) {
+    const spec = SPEC[field.type];
+
+    if (field.name in offsets) throw new Error(`Duplicate field ${field.name} in ${name}.`);
+
+    at = roundUp(at, spec.align);
+    offsets[field.name] = at;
+    types[field.name] = field.type;
+    at += spec.words;
+    align = Math.max(align, spec.align);
+
+    if (field.doc) lines.push(`  // ${field.doc}`);
+
+    lines.push(`  ${field.name}: ${spec.wgsl},`);
+  }
+
+  // A struct holding a vec4 is aligned to 16 bytes; anything smaller to 4, which a uniform still pads to 16.
+  const words = roundUp(at, Math.max(align, 4));
+
+  return { name, wgsl: `struct ${name} {\n${lines.join("\n")}\n};\n`, words, offsets, types };
+}
+
+/** Writes named values into a struct's words. Missing fields stay zero; unknown ones are an error. */
+export function writeStruct(
+  layout: StructLayout,
+  target: ArrayBuffer,
+  wordOffset: number,
+  values: Record<string, number | readonly number[] | ArrayLike<number> | boolean>) {
+  const floats = new Float32Array(target);
+  const words = new Uint32Array(target);
+
+  for (const [name, value] of Object.entries(values)) {
+    const offset = layout.offsets[name];
+
+    if (offset === undefined) throw new Error(`${layout.name} has no field ${name}.`);
+
+    const at = wordOffset + offset;
+    const type = layout.types[name];
+
+    if (type === "u32" || type === "vec2u") {
+      if (typeof value === "number" || typeof value === "boolean") words[at] = Number(value) >>> 0;
+      else for (let i = 0; i < Math.min(value.length, SPEC[type].words); i++) words[at + i] = value[i] >>> 0;
+    } else if (typeof value === "number" || typeof value === "boolean") {
+      floats[at] = Number(value);
+    } else {
+      for (let i = 0; i < Math.min(value.length, SPEC[type].words); i++) floats[at + i] = value[i];
+    }
+  }
+}

package/src/texturePack.ts

@@ -0,0 +1,152 @@
+import type { SerializedScene, SerializedTexture } from "./upstream.js";
+
+/**
+ * Every texture of a scene in one storage buffer, led by a table saying where each one lives. Core WebGPU has no binding
+ * arrays and `texture_2d_array` wants one size and one format for every layer, which a Three.js scene does not provide,
+ * so the texels are read by hand. See the decision in ARCHITECTURE.md.
+ *
+ * Byte textures keep their eight bits per channel, four to a word, and are decoded from sRGB as they are read. Float
+ * textures keep all four, because their range is the reason they are float at all.
+ */
+export interface PackedTextures {
+  /**
+   * One buffer for all of it: `TEXTURE_WORDS` words per texture first, as `TextureInfo` in `wgsl/common.wgsl.ts`, then
+   * the texels each entry points at. A byte texture takes one word per texel, RGBA in the low to high bytes; a float
+   * texture takes four, each the bits of one linear channel. Keeping the two in one binding is what holds the shader
+   * inside the eight storage buffers a WebGPU device has to offer.
+   */
+  data: Uint32Array;
+  count: number;
+  /** The index in the table of each texture, by the id the materials refer to it with. */
+  indexOf: Map<string, number>;
+  /** Where the words a caller appended begin, which is how the environment's distribution rides along. */
+  extraOffset: number;
+}
+
+/** Textures and raw words that are not part of the scene snapshot, such as the environment and its distribution. */
+export interface TextureExtras {
+  textures?: readonly SerializedTexture[];
+  words?: Uint32Array;
+}
+
+/** Sixteen words per entry: see `TextureInfo` in `wgsl/common.wgsl.ts`. */
+export const TEXTURE_WORDS = 16;
+
+/** What a material's map index means when the material has no such map. */
+export const NO_TEXTURE = 0xffffffff;
+
+const TEXTURE_FLOAT = 1;
+const TEXTURE_SRGB = 2;
+const TEXTURE_NEAREST = 4;
+const TEXTURE_FLIP_Y = 8;
+/** An environment map whose mapping bends the view ray instead of mirroring it. */
+const TEXTURE_REFRACTION = 16;
+
+/** Three's own wrap constants, which the shader compares against. */
+const REPEAT = 1000;
+const MIRRORED_REPEAT = 1002;
+
+/** How many UV sets the geometry carries, and so the highest channel a texture may ask for. */
+export const UV_CHANNELS = 2;
+
+const texelCount = (texture: SerializedTexture) => Math.max(0, texture.width) * Math.max(0, texture.height);
+
+const isFloat = (texture: SerializedTexture) => texture.data instanceof Float32Array;
+
+/**
+ * Whether the shader has to decode this texture's colour from sRGB. Only byte textures can still be encoded: a float
+ * texture was converted to linear when the scene was serialized, and had its colour space rewritten to say so.
+ */
+const isEncoded = (texture: SerializedTexture) => !isFloat(texture) && texture.colorSpace === "srgb";
+
+/**
+ * Where everything will go, before anything is written: which index each texture gets and where the words after the
+ * texels begin. Materials and lights point into that tail by absolute offset, so they need it before the buffer exists.
+ */
+export interface TexturePlan {
+  textures: SerializedTexture[];
+  indexOf: Map<string, number>;
+  tableWords: number;
+  /** Where the words appended after the texels begin. */
+  extraOffset: number;
+}
+
+export function planTextures(scene: SerializedScene, extraTextures: readonly SerializedTexture[] = []): TexturePlan {
+  const seen = new Set<string>();
+
+  // A texture id appears once, whoever refers to it; the first copy wins.
+  const textures = [...scene.textures ?? [], ...extraTextures]
+    .filter(texture => texelCount(texture) > 0 && texture.data.length >= texelCount(texture) * 4)
+    .filter(texture => !seen.has(texture.id) && !!seen.add(texture.id));
+
+  const indexOf = new Map(textures.map((texture, index) => [texture.id, index]));
+  const tableWords = Math.max(1, textures.length) * TEXTURE_WORDS;
+  const texelWords = textures.reduce((sum, texture) => sum + texelCount(texture) * (isFloat(texture) ? 4 : 1), 0);
+
+  return { textures, indexOf, tableWords, extraOffset: tableWords + texelWords };
+}
+
+export function packTextures(scene: SerializedScene, extras: TextureExtras = {}): PackedTextures {
+  return writeTextures(planTextures(scene, extras.textures), extras.words ?? new Uint32Array(0));
+}
+
+/** The buffer a plan describes, with `extraWords` appended at its `extraOffset`. */
+export function writeTextures(plan: TexturePlan, extraWords: Uint32Array): PackedTextures {
+  const { textures, indexOf, tableWords } = plan;
+
+  // WebGPU rejects an empty binding, and a scene with no textures at all is ordinary.
+  const data = new Uint32Array(Math.max(4, plan.extraOffset + extraWords.length));
+  const words = data;
+  const floats = new Float32Array(data.buffer);
+  let texelAt = tableWords;
+
+  textures.forEach((texture, index) => {
+    const at = index * TEXTURE_WORDS;
+    const texels = texelCount(texture);
+    const float = isFloat(texture);
+
+    words[at] = texture.width;
+    words[at + 1] = texture.height;
+    words[at + 2] = texelAt;
+    words[at + 3] = (float ? TEXTURE_FLOAT : 0)
+      | (isEncoded(texture) ? TEXTURE_SRGB : 0)
+      | (texture.nearest ? TEXTURE_NEAREST : 0)
+      | (texture.flipY ? TEXTURE_FLIP_Y : 0)
+      | (texture.refraction ? TEXTURE_REFRACTION : 0);
+    words[at + 4] = texture.wrapS;
+    words[at + 5] = texture.wrapT;
+    words[at + 6] = Math.min(Math.max(0, texture.channel | 0), UV_CHANNELS - 1);
+    words[at + 7] = 0;
+
+    // Three's Matrix3 arrives column major, so a row of the affine transform reads across the columns.
+    const matrix = texture.matrix?.length === 9 ? texture.matrix : [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+    floats.set([matrix[0], matrix[3], matrix[6], 0], at + 8);
+    floats.set([matrix[1], matrix[4], matrix[7], 0], at + 12);
+
+    if (float) {
+      // The channels keep their bits and the shader reads them back as floats.
+      floats.set((texture.data as Float32Array).subarray(0, texels * 4), texelAt);
+      texelAt += texels * 4;
+    } else {
+      const source = texture.data as Uint8Array;
+
+      for (let texel = 0; texel < texels; texel++) {
+        const offset = texel * 4;
+
+        words[texelAt + texel] = source[offset]
+          | (source[offset + 1] << 8)
+          | (source[offset + 2] << 16)
+          | (source[offset + 3] << 24);
+      }
+
+      texelAt += texels;
+    }
+  });
+
+  data.set(extraWords, texelAt);
+
+  return { data, count: textures.length, indexOf, extraOffset: texelAt };
+}
+
+export { MIRRORED_REPEAT, REPEAT };

package/src/upstream.ts

@@ -0,0 +1,56 @@
+// Everything this renderer takes from @tinypoly/cpu-renderer passes through here, so a version bump has one place to
+// audit. The sibling package owns the scene snapshot, the settings and the tone mapping; this one owns the GPU.
+
+export {
+  DEFAULT_RENDER_ENVIRONMENT,
+  DEFAULT_RENDER_SETTINGS,
+  mergeSettings,
+  sceneSignature,
+  serializeCamera,
+  serializeScene,
+} from "@tinypoly/cpu-renderer";
+
+// The renderer's own public shapes, so a host can swap one renderer for the other without touching its types.
+export type {
+  Bucket,
+  CameraState,
+  Listener,
+  RenderBackgroundMode,
+  RenderCamera,
+  RenderEnvironment,
+  RenderImage,
+  RenderPhase,
+  RenderPixels,
+  RenderScene,
+  RenderSettings,
+  RenderSettingsInput,
+  RenderToneMapping,
+  SerializedScene,
+  SerializedSceneResult,
+} from "@tinypoly/cpu-renderer";
+
+// The engine entry point is the lower level one, and the sibling's README warns that it moves more often.
+export { EventEmitter } from "@tinypoly/cpu-renderer/engine";
+
+export { encodeColor, srgbToLinear } from "@tinypoly/cpu-renderer/engine";
+
+// The GLSL interpreter runs vertex shaders here, where a vertex's position has to be known before the hierarchy is
+// built; the same interpreter bakes a procedural sky and a material's compute simulation, exactly as the CPU renderer
+// does. Only fragment shaders are translated to WGSL, because only they run per sample.
+export {
+  CpuComputePipeline,
+  CpuEnvironment,
+  CpuShader,
+  matrixValue,
+  sampleTexture,
+} from "@tinypoly/cpu-renderer/engine";
+
+export type {
+  SerializedFog,
+  SerializedLight,
+  SerializedMaterial,
+  SerializedMesh,
+  SerializedShader,
+  SerializedTexture,
+  UniformValue,
+} from "@tinypoly/cpu-renderer/engine";

package/src/volumetric.ts

@@ -0,0 +1,42 @@
+import type { SerializedLight } from "./upstream.js";
+
+/**
+ * The CPU renderer's volumetric lights (`userData.cpuRenderer.volumetric` on a point or spot light): light scattered by
+ * the air along every view ray, marched as `volumetricLight.js` marches it and added over the image the same way. The
+ * kernel reads one record of `VOLUMETRIC_WORDS` floats per light from the texture buffer's tail.
+ */
+export const VOLUMETRIC_WORDS = 20;
+
+const clamp = (value: number, low = 0, high = 1) => Math.min(high, Math.max(low, value));
+
+function normalize(v: readonly number[]): number[] {
+  const length = Math.hypot(v[0], v[1], v[2]) || 1;
+
+  return [v[0] / length, v[1] / length, v[2] / length];
+}
+
+/** The records, or an empty array when no light scatters. */
+export function packVolumetricLights(lights: readonly SerializedLight[]): Float32Array {
+  const volumetric = lights.filter(light => light.volumetric && (light.type === "PointLight" || light.type === "SpotLight"));
+  const records = new Float32Array(volumetric.length * VOLUMETRIC_WORDS);
+
+  volumetric.forEach((light, index) => {
+    const density = Math.max(0, light.medium?.density ?? 0.01);
+    const spread = clamp(light.medium?.spread ?? 0);
+    // Scattered light reaches past the cone: up to 1.5 rad (86 degrees) off the axis with a full spread.
+    const outer = light.angle + spread * Math.max(0, 1.5 - light.angle);
+    const axis = normalize([0, 1, 2].map(k => light.target[k] - light.position[k]));
+    const radius = light.distance > 0 ? light.distance : -3 * Math.log(0.0001);
+    const spot = light.type === "SpotLight";
+
+    records.set([
+      ...light.position, spot ? 1 : 0,
+      ...axis, radius,
+      ...light.color.map(channel => channel * light.intensity), density,
+      light.angle, light.penumbra, light.distance, outer,
+      spread, clamp(light.medium?.anisotropy ?? 0, -0.95, 0.95), light.castShadow ? 1 : 0, 0,
+    ], index * VOLUMETRIC_WORDS);
+  });
+
+  return records;
+}