@ludicon/spark.js 0.0.6 → 0.0.8

package/README.md

@@ -62,7 +62,7 @@ To run local examples:
 npm run dev
 ```
 
-And visit `http://localhost:5174/examples/basic.html`.
+This will open `http://localhost:5174/examples/index.thml` where you can browse the examples.
 
 > Note: Browsers treat http://localhost as a secure context, so HTTPS is not required when testing locally on the same machine. However, to access the dev server from another device you must enable HTTPS for WebGPU features to work.
 >
@@ -81,8 +81,8 @@ Load an image and encode it to a compressed GPU texture.
 
 #### Parameters
 
-- **`source`** (`GPUtexture | string | HTMLImageElement | HTMLCanvasElement | Blob | ArrayBuffer`)  
-  The image to encode. Can be a GPUtexture, URL, DOM image/canvas, binary buffer, or blob.
+- **`source`** (`string | HTMLImageElement | ImageBitmap | GPUtexture`)  
+  The image to encode. Can be a GPUTexture, URL, DOM image or ImageBitmap.
 
 - **`options`** *(optional object)*
   Configuration options for encoding:
@@ -118,6 +118,38 @@ Load an image and encode it to a compressed GPU texture.
 - `Promise<GPUTexture>` — the compressed GPU texture, ready for use in WebGPU.
 
 
+## Integration with three.js
+
+Using spark.js with [three.js](https://threejs.org/) is straightforward. You can encode textures with Spark and expose them to three.js as external textures:
+
+```js
+// Load and encode texture using spark:
+const gpuTexture = await spark.encodeTexture(textureUrl, { srgb: true, flipY: true });
+
+// Wrap the GPUTexture for three.js
+const externalTex = new THREE.ExternalTexture(gpuTexture);
+
+// Then use as any other texture:
+const material = new THREE.MeshBasicMaterial({ map: externalTex });
+
+```
+
+To facilitate the use of Spark when loading GLTF assets, import the provided helper:
+
+```jsd
+import { registerSparkLoader } from "@ludicon/spark.js/three-gltf";
+```
+
+Then register Spark with an existing GLTFLoader instance:
+
+```js
+const loader = new GLTFLoader()
+registerSparkLoader(loader, spark)
+```
+
+After registration, the loader will automatically encode textures with Spark whenever applicable.
+
+
 ## License
 
 *spark.js* is free for non-commercial use. 

package/dist/spark.esm.js

@@ -412,17 +412,35 @@ function imageToByteArray(image) {
   const imageData = ctx.getImageData(0, 0, image.width, image.height);
   return new Uint8Array(imageData.data.buffer);
 }
-function loadImage(url) {
-  return new Promise(function(resolve, reject) {
-    const image = new Image();
-    image.crossOrigin = "anonymous";
-    image.onload = function() {
-      resolve(image);
-    };
-    image.onerror = reject;
-    image.src = url;
+function isSvgUrl(url) {
+  return /\.svg(?:$|\?)/i.test(url) || /^data:image\/svg\+xml[,;]/i.test(url);
+}
+function loadImageElement(url) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.decoding = "async";
+    img.onload = () => resolve(img);
+    img.onerror = reject;
+    img.src = url;
+  });
+}
+async function loadImageBitmap(url, opts = {}) {
+  const res = await fetch(url, { mode: "cors" });
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+  const blob = await res.blob();
+  return createImageBitmap(blob, {
+    imageOrientation: opts.flipY ? "flipY" : "none",
+    colorSpaceConversion: opts.colorSpaceConversion ?? "none"
   });
 }
+function loadImage(url) {
+  if (isSvgUrl(url)) {
+    return loadImageElement(url);
+  } else {
+    return loadImageBitmap(url);
+  }
+}
 const BYTES_PER_ROW_ALIGNMENT = 256;
 const MIN_MIP_SIZE = 4;
 function computeMipmapLayout(w, h, blockSize, mipmaps) {
@@ -457,6 +475,7 @@ class Spark {
   #querySet;
   #queryBuffer;
   #queryReadbackBuffer;
+  #encodeCounter = 0;
   /**
    * Initialize the encoder by detecting available compression formats.
    * @param {GPUDevice} device - WebGPU device.
@@ -550,13 +569,13 @@ class Spark {
    * Try to determine the best compression options automatically. Do not use this in production, this is
    * for the convenience of the spark.js image viewer only.
    *
-   * @param {string | HTMLImageElement | HTMLCanvasElement | Blob | ArrayBuffer | GPUTexture} source - Image input.
+   * @param {string | HTMLImageElement | ImageBitmap | GPUTexture} source - Image input.
    * @param {Object} options - Encoding options.
    * @returns {Object} - Recommended encoding options with an explicit encoding format.
    */
   async selectPreferredOptions(source, options = {}) {
     if (options.format == void 0 || options.format == "auto") {
-      const image = source instanceof Image || source instanceof GPUTexture ? source : await loadImage(source);
+      const image = source instanceof Image || source instanceof ImageBitmap || source instanceof GPUTexture ? source : await loadImage(source);
       options.format = "auto";
       const format = await this.#getBestMatchingFormat(options, image);
       options.format = SparkFormatName[format];
@@ -572,8 +591,8 @@ class Spark {
   /**
    * Load an image and encode it to a compressed GPU texture.
    *
-   * @param {GPUTexture | string | HTMLImageElement | HTMLCanvasElement | Blob | ArrayBuffer} source
-   *        The image to encode. Can be a GPUTexture, URL, DOM image/canvas, binary buffer, or Blob.
+   * @param {string | HTMLImageElement | ImageBitmap | GPUTexture} source
+   *        The image to encode. Can be a GPUTexture, URL, DOM image or ImageBitmap.
    *
    * @param {Object} [options] - Optional configuration for encoding.
    *
@@ -610,7 +629,7 @@ class Spark {
    */
   async encodeTexture(source, options = {}) {
     assert(this.#device, "Spark is not initialized");
-    const image = source instanceof Image || source instanceof GPUTexture ? source : await loadImage(source);
+    const image = source instanceof Image || source instanceof ImageBitmap || source instanceof GPUTexture ? source : await loadImage(source);
     console.log("Loaded image", image);
     const format = await this.#getBestMatchingFormat(options, image);
     const pipelinePromise = this.#loadPipeline(format);
@@ -622,7 +641,8 @@ class Spark {
     const srgb = (options.srgb || options.format?.endsWith("srgb")) && SparkFormatIsRGB[format];
     const webgpuFormat = SparkWebGPUFormats[format] + (srgb ? "-srgb" : "");
     const viewFormats = srgb ? ["rgba8unorm", "rgba8unorm-srgb"] : ["rgba8unorm"];
-    console.time("create input texture");
+    const counter = this.#encodeCounter++;
+    console.time("create input texture #" + counter);
     let inputUsage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.STORAGE_BINDING;
     const needsProcessing = options.flipY || width != image.width || height != image.height;
     if (!needsProcessing && !(image instanceof GPUTexture)) {
@@ -678,7 +698,7 @@ class Spark {
       this.#generateMipmaps(commandEncoder, inputTexture, mipmapCount, width, height, srgb);
     }
     commandEncoder.popDebugGroup?.();
-    console.timeEnd("create input texture");
+    console.timeEnd("create input texture #" + counter);
     const outputTexture = this.#device.createTexture({
       size: [width, height, 1],
       mipLevelCount: mipmapCount,
@@ -689,7 +709,7 @@ class Spark {
       size: outputSize,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
     });
-    console.time("dispatch compute shader");
+    console.time("dispatch compute shader #" + counter);
     commandEncoder.pushDebugGroup?.("spark encode texture");
     let args = {};
     if (this.#querySet && typeof commandEncoder.writeTimestamp !== "function") {
@@ -757,7 +777,7 @@ class Spark {
     }
     commandEncoder.popDebugGroup?.();
     this.#device.queue.submit([commandEncoder.finish()]);
-    console.timeEnd("dispatch compute shader");
+    console.timeEnd("dispatch compute shader #" + counter);
     tmpTexture?.destroy();
     if (inputTexture != image) {
       inputTexture?.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludicon/spark.js",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Real-Time GPU Texture Codecs for the Web",
   "main": "dist/spark.esm.js",
   "module": "dist/spark.esm.js",
@@ -8,10 +8,12 @@
   "exports": {
     ".": {
       "import": "./dist/spark.esm.js"
-    }
+    },
+    "./three-gltf": "./src/three-gltf.js"
   },
   "files": [
     "dist",
+    "src/three-gltf.js",
     "README.md",
     "LICENSE"
   ],
@@ -61,8 +63,17 @@
     "npm-run-all": "^4.1.5",
     "prettier": "^3.0.0",
     "rimraf": "^5.0.0",
+    "three": "^0.180.0",
     "vite": "^7.0.0"
   },
+  "peerDependencies": {
+    "three": "^0.180.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/three-gltf.js

@@ -0,0 +1,189 @@
+import * as THREE from "three/webgpu"
+
+const Channel = {
+  R: 1, // 0001
+  G: 2, // 0010
+  B: 4, // 0100
+  A: 8, // 1000
+  RG: 3, // 0011
+  RGB: 7, // 0111
+  RGBA: 15 // 1111
+}
+
+class GLTFSparkPlugin {
+  constructor(name, parser, spark) {
+    this.name = name
+    this.parser = parser
+
+    this.loaders = {
+      ["rgba"]: new SparkLoader(parser.fileLoader.manager, spark, "rgba"),
+      ["rgba-srgb"]: new SparkLoader(parser.fileLoader.manager, spark, "rgba", THREE.SRGBColorSpace),
+      ["rgb"]: new SparkLoader(parser.fileLoader.manager, spark, "rgb"),
+      ["rgb-srgb"]: new SparkLoader(parser.fileLoader.manager, spark, "rgb", THREE.SRGBColorSpace),
+      ["rg"]: new SparkLoader(parser.fileLoader.manager, spark, "rg"),
+      ["r"]: new SparkLoader(parser.fileLoader.manager, spark, "r"),
+      [""]: new THREE.TextureLoader()
+    }
+
+    const textureCount = this.parser.json.textures?.length || 0
+    const textureColorSpaces = new Array(textureCount).fill(THREE.NoColorSpace)
+    const textureChannels = new Array(textureCount).fill(0)
+    const textureIsNormal = new Array(textureCount).fill(false)
+    const textureIsUncompressed = new Array(textureCount).fill(false)
+
+    function assignTexture(index, channels, colorSpace, isNormal, isUncompressed) {
+      if (index === undefined) return
+
+      textureChannels[index] |= channels
+
+      if (colorSpace) {
+        textureColorSpaces[index] = colorSpace
+      }
+      if (isNormal) {
+        textureIsNormal[index] = true
+
+        // Normal map unpacking not supported in three.js prior to r181
+        if (!("NormalRGPacking" in THREE)) {
+          textureChannels[index] |= Channel.RGB
+        }
+      }
+      if (isUncompressed) {
+        textureIsUncompressed[index] = true
+      }
+    }
+
+    for (const materialDef of this.parser.json.materials) {
+      const baseColorTextureIndex = materialDef.pbrMetallicRoughness?.baseColorTexture?.index
+      if (baseColorTextureIndex !== undefined) {
+        textureColorSpaces[baseColorTextureIndex] = THREE.SRGBColorSpace
+        textureChannels[baseColorTextureIndex] |= Channel.RGB
+
+        // Base color texture expects alpha when alpha mode is MASK or BLEND.
+        if (materialDef.alphaMode == "MASK" || materialDef.alphaMode == "BLEND") {
+          textureChannels[baseColorTextureIndex] |= Channel.A
+        }
+      }
+
+      assignTexture(materialDef.normalTexture?.index, Channel.RG, THREE.NoColorSpace, true)
+      assignTexture(materialDef.emissiveTexture?.index, Channel.RGB, THREE.SRGBColorSpace)
+      assignTexture(materialDef.occlusionTexture?.index, Channel.R)
+      assignTexture(materialDef.pbrMetallicRoughness?.metallicRoughnessTexture?.index, Channel.G | Channel.B)
+
+      // KHR_materials_anisotropy - RG contains direction, B contains strength.
+      assignTexture(materialDef.anisotropyTexture?.index, Channel.RGB)
+
+      // KHR_materials_clearcoat
+      assignTexture(materialDef.clearcoatTexture?.index, Channel.RGB, THREE.SRGBColorSpace)
+      assignTexture(materialDef.clearcoatRoughnessTexture?.index, Channel.R)
+      assignTexture(materialDef.clearcoatNormalTexture?.index, Channel.RG, THREE.NoColorSpace, true)
+
+      // KHR_materials_diffuse_transmission
+      assignTexture(materialDef.diffuseTransmissionTexture?.index, Channel.A)
+      assignTexture(materialDef.diffuseTransmissionColorTexture?.index, Channel.RGB, THREE.SRGBColorSpace)
+
+      // KHR_materials_iridescence
+      assignTexture(materialDef.iridescenceTexture?.index, Channel.R)
+      assignTexture(materialDef.iridescenceThicknessTexture?.index, Channel.G)
+
+      // KHR_materials_sheen
+      assignTexture(materialDef.sheenColorTexture?.index, Channel.RGB, THREE.SRGBColorSpace)
+      assignTexture(materialDef.sheenRoughnessTextureIndex?.index, Channel.A)
+
+      // KHR_materials_specular
+      assignTexture(materialDef.specularTexture?.index, Channel.RGB, THREE.SRGBColorSpace)
+      assignTexture(materialDef.specularColorTexture?.index, Channel.A)
+
+      // KHR_materials_transmission
+      assignTexture(materialDef.transmissionTexture?.index, Channel.R)
+
+      // KHR_materials_volume
+      assignTexture(materialDef.thicknessTexture?.index, Channel.G)
+    }
+
+    this.textureColorSpaces = textureColorSpaces
+    this.textureChannels = textureChannels
+    this.textureIsNormal = textureIsNormal
+    this.textureIsUncompressed = textureIsUncompressed
+  }
+
+  loadTexture(textureIndex) {
+    const tex = this.parser.json.textures[textureIndex]
+    const imageIndex = tex.source ?? tex.extensions.EXT_texture_webp?.source ?? tex.extensions.EXT_texture_avif?.source
+    const colorSpace = this.textureColorSpaces[textureIndex]
+    const channels = this.textureChannels[textureIndex]
+    const isUncompressed = this.textureIsUncompressed[textureIndex]
+
+    let format = "rgba" // Default to 'rgba'
+    if ((channels & Channel.R) == channels) {
+      format = "r"
+    } else if ((channels & Channel.RG) == channels) {
+      format = "rg"
+    } else if ((channels & Channel.RGB) == channels) {
+      format = "rgb" + (colorSpace === THREE.SRGBColorSpace ? "-srgb" : "")
+    } else {
+      format = "rgba" + (colorSpace === THREE.SRGBColorSpace ? "-srgb" : "")
+    }
+    if (isUncompressed) {
+      format = ""
+    }
+
+    const loader = this.loaders[format]
+
+    return this.parser.loadTextureImage(textureIndex, imageIndex, loader)
+  }
+}
+
+class SparkLoader extends THREE.TextureLoader {
+  constructor(manager, spark, format, colorSpace = THREE.NoColorSpace) {
+    super(manager)
+    this.spark = spark
+    this.format = format
+    this.colorSpace = colorSpace
+  }
+
+  load(url, onLoad, onProgress, onError) {
+    const format = this.format
+    const srgb = this.colorSpace === THREE.SRGBColorSpace
+    const mips = true
+
+    this.spark
+      .encodeTexture(url, { format, srgb, mips })
+      .then(gpuTexture => {
+        const texture = new THREE.ExternalTexture(gpuTexture)
+        if (this.format == "rg" && "NormalRGPacking" in THREE) {
+          texture.userData.unpackNormal = THREE.NormalRGPacking
+        }
+        onLoad(texture)
+      })
+      .catch(err => {
+        // Fallback: load the original image uncompressed
+        super.load(
+          url,
+          tex => {
+            tex.colorSpace = this.colorSpace
+            onLoad?.(tex)
+          },
+          onProgress,
+          // If the fallback also fails, surface the original encoder error first
+          fallbackErr => onError?.(err ?? fallbackErr)
+        )
+      })
+  }
+}
+
+export function registerSparkLoader(loader, spark) {
+  // Remove existing webp and avif plugins:
+  for (let i = 0; i < loader.pluginCallbacks.length; i++) {
+    const plugin = loader.pluginCallbacks[i](loader)
+
+    if (plugin.name == "EXT_texture_webp" || plugin.name == "EXT_texture_avif") {
+      loader.unregister(loader.pluginCallbacks[i])
+      i--
+    }
+  }
+
+  // Install plugin for standard textures, and textures using webp and avif extensions.
+  loader.register(parser => new GLTFSparkPlugin("spark", parser, spark))
+  loader.register(parser => new GLTFSparkPlugin("EXT_texture_webp", parser, spark))
+  loader.register(parser => new GLTFSparkPlugin("EXT_texture_avif", parser, spark))
+}