@downdraft/engine 0.0.0 → 0.1.1

package/core/src/assets/index.ts

@@ -0,0 +1,74 @@
+// Assets sub-barrel — re-exports all asset-related items.
+export { GPUResourceCache } from "./cache";
+export type { GPUCacheEntry } from "./cache";
+export { EquirectToCubemapConverter } from "./cubemap-converter";
+export type { EquirectToCubemapOptions } from "./cubemap-converter";
+export { EnvironmentManager } from "./environment-manager";
+export type { EnvironmentManagerOptions, EnvironmentMap } from "./environment-manager";
+export { AssetImporter } from "./importer";
+export type { ImportOptions, ImportResult } from "./importer";
+export { IrradianceGenerator } from "./irradiance-generator";
+export type { IrradianceOptions } from "./irradiance-generator";
+export { detectAudioFormat, loadAudioFile, loadAudioFromBuffer, registerAudioLoader } from "./loader-audio";
+export { createEquirectangularGPUTexture, createGPUCubemap, loadCubemapFromDirectory, loadCubemapFromFiles } from "./loader-cubemap";
+export type { CubemapData, CubemapFaceData } from "./loader-cubemap";
+export { loadDDSFromBuffer, loadDDSTexture, parseDDS } from "./loader-dds";
+export { loadEXRTexture, loadHDRFile, loadHDRTexture, parseEXR, parseHDR } from "./loader-hdr";
+export { GLBLoader } from "./loader-mesh";
+export type { GLTFAccessor, GLTFBuffer, GLTFBufferView, GLTFDocument, GLTFMesh, GLTFNode, GLTFPrimitive } from "./loader-mesh";
+export { ShaderLoader } from "./loader-shader";
+export type { ShaderSource } from "./loader-shader";
+export { createGPUTextureFromData, createSampler, detectTextureFormat, loadKTX2Texture, loadTexture, loadTextureFromImage, parseKTX2FromBuffer } from "./loader-texture";
+export type { TextureData, TextureFormat } from "./loader-texture";
+export { LODGenerator } from "./lod";
+export type { LODConfig, LODLevel } from "./lod";
+export { AssetManager } from "./manager";
+export type {
+    AssetDestructor,
+    AssetLoadProgress,
+    AssetManagerOptions,
+    AssetPriority,
+    AssetRef,
+    ProgressCallback,
+    SearchPath
+} from "./manager";
+export { bridgeMaterial, bridgeMaterials } from "./material-bridge";
+export type { BridgedMaterial } from "./material-bridge";
+export { importMaterial, importModel, importSingleMesh } from "./model-importer";
+export type { ImportedModel, ImportModelOptions } from "./model-importer";
+export { destroyGPUMesh, uploadMeshesToGPU, uploadMeshToGPU } from "./model-to-gpu";
+export type { GPUMesh } from "./model-to-gpu";
+export { convertPluginMesh, convertPluginModel } from "./model-to-mesh";
+export type { PluginMaterialData, PluginMeshData, PluginModelData, TargetLayout } from "./model-to-mesh";
+// Model normalization — transform math for import-time correction
+export {
+    applyRootRotation, applyRootScale, applyUnitScale, applyUpAxisConversion, autoFit, centerToOrigin, computeBounds, isExtremeScale, maxDimension, UNIT_TO_METERS
+} from "./model-normalizer";
+export type { Bounds } from "./model-normalizer";
+// Import settings — per-model normalization configuration
+export { createDefaultImportSettings, mergeImportSettings } from "./import-settings";
+export type { ImportSettings, SettingsSource, UnitSystem, UpAxis } from "./import-settings";
+// Import cache — caches resolved ImportSettings keyed by model path
+export { isCacheEntryValid, MemoryImportCache } from "./import-cache";
+export type { CacheEntry, ImportCache } from "./import-cache";
+export { PrefilteredSpecularGenerator } from "./prefilter-generator";
+export type { PrefilterOptions } from "./prefilter-generator";
+
+// Blob Storage & Asset Manifest
+export { makeBlobUri, parseBlobUri } from "./blob-store";
+export type {
+    BlobGetOptions,
+    BlobListOptions,
+    BlobListResult,
+    BlobObject,
+    BlobPutOptions,
+    BlobStore,
+    BlobStoreConfig
+} from "./blob-store";
+export {
+    createEmptyManifest, DEFAULT_CACHE_DIR,
+    MANIFEST_FILENAME, packCacheKey,
+    validateManifest
+} from "./manifest";
+export type { AssetManifest, AssetPackEntry, PluginPackEntry } from "./manifest";
+

package/core/src/assets/irradiance-generator.ts

@@ -0,0 +1,198 @@
+
+import { createValidatedShaderModule } from "../render/shader-validator";
+const IRRADIANCE_SHADER = /* wgsl */ `
+struct Uniforms {
+  faceSize: u32,
+  sampleCount: u32,
+  _pad0: u32,
+  _pad1: u32,
+};
+
+@group(0) @binding(0) var srcTex: texture_2d_array<f32>;
+@group(0) @binding(1) var dstTex: texture_storage_2d_array<rgba16float, write>;
+@group(0) @binding(2) var<uniform> uniforms: Uniforms;
+@group(0) @binding(3) var srcSampler: sampler;
+
+const PI: f32 = 3.141592653589793;
+
+fn faceDirToUV(face: u32, u: f32, v: f32) -> vec3<f32> {
+  let a = u * 2.0 - 1.0;
+  let b = v * 2.0 - 1.0;
+  switch face {
+    case 0u: { return vec3<f32>( 1.0, -b, -a); }
+    case 1u: { return vec3<f32>(-1.0, -b,  a); }
+    case 2u: { return vec3<f32>( a,  1.0,  b); }
+    case 3u: { return vec3<f32>( a, -1.0, -b); }
+    case 4u: { return vec3<f32>( a, -b,  1.0); }
+    case 5u: { return vec3<f32>(-a, -b, -1.0); }
+    default: { return vec3<f32>(0.0, 0.0, 0.0); }
+  }
+}
+
+fn dirToFaceUV(dir: vec3<f32>) -> vec3<f32> {
+  let absX = abs(dir.x);
+  let absY = abs(dir.y);
+  let absZ = abs(dir.z);
+
+  var face: u32 = 0u;
+  var ma: f32 = 0.0;
+  var sc: f32 = 0.0;
+  var tc: f32 = 0.0;
+
+  if (absX > absY && absX > absZ) {
+    if (dir.x > 0.0) { face = 0u; sc = -dir.z; tc = -dir.y; ma = dir.x; }
+    else { face = 1u; sc = dir.z; tc = -dir.y; ma = -dir.x; }
+  } else if (absY > absZ) {
+    if (dir.y > 0.0) { face = 2u; sc = dir.x; tc = dir.z; ma = dir.y; }
+    else { face = 3u; sc = dir.x; tc = -dir.z; ma = -dir.y; }
+  } else {
+    if (dir.z > 0.0) { face = 4u; sc = dir.x; tc = -dir.y; ma = dir.z; }
+    else { face = 5u; sc = -dir.x; tc = -dir.y; ma = -dir.z; }
+  }
+
+  let u = (sc / ma + 1.0) * 0.5;
+  let v = (tc / ma + 1.0) * 0.5;
+  return vec3<f32>(u, v, f32(face));
+}
+
+fn sampleCubemap(dir: vec3<f32>) -> vec3<f32> {
+  let info = dirToFaceUV(dir);
+  let face = u32(info.z);
+  let u = info.x;
+  let v = info.y;
+  let coords = vec2<i32>(i32(u * f32(textureDimensions(srcTex, 0).x)), i32(v * f32(textureDimensions(srcTex, 0).y)));
+  return textureLoad(srcTex, coords, i32(face), 0).rgb;
+}
+
+fn tangentToWorld(N: vec3<f32>, tangent: vec3<f32>, bitangent: vec3<f32>, sample: vec3<f32>) -> vec3<f32> {
+  return normalize(tangent * sample.x + bitangent * sample.y + N * sample.z);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let faceSize = uniforms.faceSize;
+  if (gid.x >= faceSize || gid.y >= faceSize) { return; }
+
+  let face = gid.z;
+  let u = (f32(gid.x) + 0.5) / f32(faceSize);
+  let v = (f32(gid.y) + 0.5) / f32(faceSize);
+  let N = normalize(faceDirToUV(face, u, v));
+
+  let up = select(vec3<f32>(0.0, 1.0, 0.0), vec3<f32>(1.0, 0.0, 0.0), abs(N.y) > 0.999);
+  let tangent = normalize(cross(up, N));
+  let bitangent = cross(N, tangent);
+
+  var irradiance = vec3<f32>(0.0);
+  var sampleCount = 0u;
+
+  let phiSteps = 64u;
+  let thetaSteps = 32u;
+
+  for (var phiStep = 0u; phiStep < phiSteps; phiStep++) {
+    for (var thetaStep = 0u; thetaStep < thetaSteps; thetaStep++) {
+      let phi = (f32(phiStep) + 0.5) / f32(phiSteps) * 2.0 * PI;
+      let theta = (f32(thetaStep) + 0.5) / f32(thetaSteps) * 0.5 * PI;
+
+      let tangentSample = vec3<f32>(
+        sin(theta) * cos(phi),
+        sin(theta) * sin(phi),
+        cos(theta),
+      );
+
+      let sampleVec = tangentToWorld(N, tangent, bitangent, tangentSample);
+      irradiance += sampleCubemap(sampleVec) * cos(theta);
+      sampleCount++;
+    }
+  }
+
+  irradiance = irradiance * PI / f32(sampleCount);
+  textureStore(dstTex, vec2<i32>(i32(gid.x), i32(gid.y)), i32(face), vec4<f32>(irradiance, 1.0));
+}
+`;
+
+export interface IrradianceOptions {
+  faceSize: number;
+}
+
+export class IrradianceGenerator {
+  private device: GPUDevice;
+  private pipeline: GPUComputePipeline | null = null;
+  private bindGroupLayout: GPUBindGroupLayout | null = null;
+  private uniformBuffer: GPUBuffer | null = null;
+  private sampler: GPUSampler | null = null;
+
+  constructor(device: GPUDevice) {
+    this.device = device;
+  }
+
+  private ensurePipeline(): void {
+    if (this.pipeline) return;
+
+    this.bindGroupLayout = this.device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: "float", viewDimension: "2d-array" } },
+        { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d-array" } },
+        { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+        { binding: 3, visibility: GPUShaderStage.COMPUTE, sampler: { type: "filtering" } },
+      ],
+    });
+
+    const shaderModule = createValidatedShaderModule(this.device, { code: IRRADIANCE_SHADER, label: "IrradianceGenerator" });
+
+    this.pipeline = this.device.createComputePipeline({
+      layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+      compute: { module: shaderModule, entryPoint: "cs_main" },
+    });
+
+    this.uniformBuffer = this.device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+  }
+
+  generate(srcCubemap: GPUTexture, options: IrradianceOptions): GPUTexture {
+    this.ensurePipeline();
+
+    const faceSize = options.faceSize;
+    const dstTexture = this.device.createTexture({
+      size: [faceSize, faceSize, 6],
+      format: "rgba16float",
+      usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING,
+    });
+
+    const srcView = srcCubemap.createView({ dimension: "2d-array" });
+    const dstView = dstTexture.createView({ dimension: "2d-array" });
+
+    const uniformData = new Uint32Array(4);
+    uniformData[0] = faceSize;
+    uniformData[1] = 0;
+    this.device.queue.writeBuffer(this.uniformBuffer!, 0, uniformData);
+
+    const sampler = this.sampler ??= this.device.createSampler({
+      magFilter: "linear",
+      minFilter: "linear",
+    });
+
+    const bindGroup = this.device.createBindGroup({
+      layout: this.bindGroupLayout!,
+      entries: [
+        { binding: 0, resource: srcView },
+        { binding: 1, resource: dstView },
+        { binding: 2, resource: { buffer: this.uniformBuffer! } },
+        { binding: 3, resource: sampler },
+      ],
+    });
+
+    const encoder = this.device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(this.pipeline!);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(Math.ceil(faceSize / 8), Math.ceil(faceSize / 8), 6);
+    pass.end();
+    this.device.queue.submit([encoder.finish()]);
+
+    // GPUSampler has no destroy() — it's lightweight and GC'd. Cached on the
+    // instance via ??= above to avoid per-call allocation.
+    return dstTexture;
+  }
+}

package/core/src/assets/loader-audio.ts

@@ -0,0 +1,86 @@
+import type { AudioEngine } from "../audio/engine";
+import type { AudioBufferDesc, AudioFormat } from "../audio/interface";
+import type { AssetManager } from "./manager";
+
+const EXTENSION_FORMAT_MAP: Record<string, AudioFormat> = {
+  wav: "wav",
+  wave: "wav",
+  ogg: "ogg",
+  oga: "ogg",
+  mp3: "mp3",
+  flac: "flac",
+};
+
+export function detectAudioFormat(uri: string): AudioFormat | null {
+  const ext = uri.split(".").pop()?.toLowerCase() ?? "";
+  return EXTENSION_FORMAT_MAP[ext] ?? null;
+}
+
+export async function loadAudioFile(
+  uri: string,
+  engine: AudioEngine,
+): Promise<AudioBufferDesc> {
+  const format = detectAudioFormat(uri);
+  if (!format) {
+    throw new Error(`Unsupported audio format: ${uri}`);
+  }
+
+  // Lazy node:fs import — this module is reachable from the browser-side
+  // barrel, so node builtins must not be evaluated at import time. Fall back
+  // to fetch() when fs is unavailable (browser/worker realms).
+  let fsPromises: typeof import("node:fs").promises | null = null;
+  try {
+    fsPromises = (await import("node:fs")).promises;
+  } catch {
+    // node:fs unavailable (browser bundle) — use fetch below.
+  }
+  let data: ArrayBuffer;
+  if (fsPromises) {
+    const buf = await fsPromises.readFile(uri);
+    data = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  } else {
+    const res = await fetch(uri);
+    if (!res.ok) throw new Error(`Failed to load audio "${uri}": HTTP ${res.status}`);
+    data = await res.arrayBuffer();
+  }
+  const desc: AudioBufferDesc = {
+    id: uri,
+    format,
+    samples: new Float32Array(data.byteLength / 4),
+  };
+  const view = new DataView(data);
+  for (let i = 0; i < desc.samples.length; i++) {
+    desc.samples[i] = view.getFloat32(i * 4, true);
+  }
+  engine.loadBuffer(desc);
+  return desc;
+}
+
+export async function loadAudioFromBuffer(
+  format: AudioFormat,
+  data: ArrayBuffer,
+  engine: AudioEngine,
+): Promise<AudioBufferDesc> {
+  const desc: AudioBufferDesc = {
+    id: `buffer-${Date.now()}`,
+    format,
+    samples: new Float32Array(data.byteLength / 4),
+  };
+  const view = new DataView(data);
+  for (let i = 0; i < desc.samples.length; i++) {
+    desc.samples[i] = view.getFloat32(i * 4, true);
+  }
+  engine.loadBuffer(desc);
+  return desc;
+}
+
+export function registerAudioLoader(
+  manager: AssetManager,
+  engine: AudioEngine,
+): void {
+  for (const ext of Object.keys(EXTENSION_FORMAT_MAP)) {
+    manager.registerLoader(ext, async (uri: string) => {
+      return loadAudioFile(uri, engine);
+    });
+  }
+}

package/core/src/assets/loader-cubemap.ts

@@ -0,0 +1,211 @@
+import { sanitizeUri } from "../safety/path";
+import { loadHDRFile } from "./loader-hdr";
+import type { TextureData } from "./loader-texture";
+
+export interface CubemapFaceData {
+  width: number;
+  height: number;
+  data: Float32Array;
+}
+
+export interface CubemapData {
+  width: number;
+  height: number;
+  faces: CubemapFaceData[]; // 6 faces: +X, -X, +Y, -Y, +Z, -Z
+  isHDR: boolean;
+}
+
+const FACE_NAMES = ["px", "nx", "py", "ny", "pz", "nz"] as const;
+
+export async function loadCubemapFromFiles(
+  faceUris: [string, string, string, string, string, string],
+): Promise<CubemapData> {
+  const faces: CubemapFaceData[] = [];
+
+  for (let i = 0; i < 6; i++) {
+    // Validate face URI: reject file://, .., absolute paths
+    const safeUri = sanitizeUri(faceUris[i]);
+    const texData = await loadHDRFile(safeUri);
+    if (!texData) continue;
+    if (texData.data instanceof Float32Array) {
+      faces.push({
+        width: texData.width,
+        height: texData.height,
+        data: texData.data,
+      });
+    } else {
+      // Convert Uint8Array to Float32Array
+      const uint8Data = texData.data as Uint8Array;
+      const floatData = new Float32Array(uint8Data.length);
+      for (let j = 0; j < uint8Data.length; j++) {
+        floatData[j] = uint8Data[j] / 255;
+      }
+      faces.push({
+        width: texData.width,
+        height: texData.height,
+        data: floatData,
+      });
+    }
+  }
+
+  const width = faces[0].width;
+  const height = faces[0].height;
+  const isHDR = faces.every((f) => f.data.every((v, idx) => idx % 4 !== 3 || v <= 1.0)) || faces[0].data.some((v) => v > 1.0);
+
+  return { width, height, faces, isHDR };
+}
+
+export async function loadCubemapFromDirectory(
+  basePath: string,
+  prefix: string = "",
+  extension: string = ".hdr",
+): Promise<CubemapData> {
+  const faceUris = FACE_NAMES.map((name) => `${basePath}/${prefix}${name}${extension}`) as [
+    string, string, string, string, string, string,
+  ];
+  // Validate each constructed face URI for path safety
+  faceUris.forEach((uri) => {
+    sanitizeUri(uri);
+  });
+  return loadCubemapFromFiles(faceUris);
+}
+
+export function createGPUCubemap(
+  device: GPUDevice,
+  cubemap: CubemapData,
+  format: GPUTextureFormat = "rgba16float",
+): GPUTexture {
+  const { width, height, faces } = cubemap;
+
+  const texture = device.createTexture({
+    size: [width, height, 6],
+    format,
+    usage: GPUTextureUsage.TEXTURE_BINDING |
+           GPUTextureUsage.COPY_DST |
+           GPUTextureUsage.RENDER_ATTACHMENT,
+  });
+
+  for (let face = 0; face < 6; face++) {
+    const faceData = faces[face];
+    // Convert Float32Array to Uint16Array for rgba16float
+    if (format === "rgba16float") {
+      const halfData = new Uint16Array(faceData.data.length);
+      for (let i = 0; i < faceData.data.length; i++) {
+        halfData[i] = floatToHalf(faceData.data[i]);
+      }
+      device.queue.writeTexture(
+        { texture, origin: [0, 0, face] },
+        halfData as unknown as GPUAllowSharedBufferSource,
+        { bytesPerRow: width * 8 },
+        { width, height },
+      );
+    } else if (format === "rgba32float") {
+      device.queue.writeTexture(
+        { texture, origin: [0, 0, face] },
+        faceData.data as unknown as GPUAllowSharedBufferSource,
+        { bytesPerRow: width * 16 },
+        { width, height },
+      );
+    } else {
+      // Assume 8-bit format
+      const uint8Data = new Uint8Array(faceData.data.length);
+      for (let i = 0; i < faceData.data.length; i++) {
+        uint8Data[i] = Math.min(255, Math.max(0, Math.round(faceData.data[i] * 255)));
+      }
+      device.queue.writeTexture(
+        { texture, origin: [0, 0, face] },
+        uint8Data as unknown as GPUAllowSharedBufferSource,
+        { bytesPerRow: width * 4 },
+        { width, height },
+      );
+    }
+  }
+
+  return texture;
+}
+
+export function createEquirectangularGPUTexture(
+  device: GPUDevice,
+  texData: TextureData,
+  format: GPUTextureFormat = "rgba16float",
+): GPUTexture {
+  const { width, height, data } = texData;
+  const texture = device.createTexture({
+    size: [width, height],
+    format,
+    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+  });
+
+  if (data instanceof Float32Array) {
+    if (format === "rgba16float") {
+      const halfData = new Uint16Array(data.length);
+      for (let i = 0; i < data.length; i++) {
+        halfData[i] = floatToHalf(data[i]);
+      }
+      device.queue.writeTexture(
+        { texture },
+        halfData,
+        { bytesPerRow: width * 8 },
+        { width, height },
+      );
+    } else {
+      device.queue.writeTexture(
+        { texture },
+        data as unknown as GPUAllowSharedBufferSource,
+        { bytesPerRow: width * 16 },
+        { width, height },
+      );
+    }
+  } else {
+    device.queue.writeTexture(
+      { texture },
+      data as unknown as GPUAllowSharedBufferSource,
+      { bytesPerRow: width * 4 },
+      { width, height },
+    );
+  }
+
+  return texture;
+}
+
+function floatToHalf(f: number): number {
+  const f32 = new Float32Array(1);
+  const u32 = new Uint32Array(f32.buffer);
+  f32[0] = f;
+  const x = u32[0];
+  const sign = (x >>> 31) & 1;
+  let exp = (x >>> 23) & 0xff;
+  let mant = x & 0x7fffff;
+
+  if (exp === 0xff) {
+    // Inf or NaN
+    return (sign << 15) | 0x7c00 | (mant ? 1 : 0);
+  }
+
+  if (exp === 0) {
+    // Subnormal or zero
+    if (mant === 0) return sign << 15;
+    // Normalize subnormal
+    let shift = 0;
+    while ((mant & 0x400000) === 0) {
+      mant <<= 1;
+      shift++;
+    }
+    mant &= 0x7fffff;
+    exp = 1 - shift;
+  }
+
+  exp = exp - 127 + 15;
+  if (exp <= 0) {
+    if (exp < -10) return sign << 15;
+    mant |= 0x800000;
+    const shift = 14 - exp;
+    mant >>= shift;
+    return (sign << 15) | mant;
+  }
+  if (exp > 30) {
+    return (sign << 15) | 0x7c00;
+  }
+
+  return (sign << 15) | (exp << 10) | (mant >> 13);
+}