@ludicon/spark.js 0.0.15 → 0.1.0

package/README.md

@@ -1,12 +1,12 @@
 # spark.js⚡️
 
-[![npm version](https://img.shields.io/npm/v/@ludicon/spark.js.svg)](https://www.npmjs.com/package/@ludicon/spark.js) [![install size](https://packagephobia.com/badge?p=@ludicon/spark.js)](https://packagephobia.com/result?p=@ludicon/spark.js) [![WebGPU](https://img.shields.io/badge/WebGPU-supported-green.svg)](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API)
+[![npm version](https://img.shields.io/npm/v/@ludicon/spark.js.svg)](https://www.npmjs.com/package/@ludicon/spark.js) [![install size](https://packagephobia.com/badge?p=@ludicon/spark.js)](https://packagephobia.com/result?p=@ludicon/spark.js) [![WebGPU](https://img.shields.io/badge/WebGPU-supported-green.svg)](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API) [![WebGL2](https://img.shields.io/badge/WebGL2-supported-blue.svg)](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API)
 
 Real-time texture compression library for the Web.
 
 [*spark.js*](https://ludicon.com/sparkjs) is a standalone JavaScript library that exposes a subset of the [*Spark*](https://ludicon.com/spark) codecs through a simple and lightweight API.
 
-It enables the use of standard image formats in WebGPU applications transcoding them at load-time to native GPU formats like BC7, ASTC, and ETC2, using fast, high-quality GPU encoders.
+It enables the use of standard image formats in WebGL and WebGPU applications transcoding them at load-time to native GPU formats like BC7, ASTC, and ETC2, using fast, high-quality GPU encoders.
 
 Try the [image viewer](https://ludicon.com/sparkjs/viewer/) or the [gltf demo](https://ludicon.com/sparkjs/gltf-demo/):
 
@@ -20,7 +20,7 @@ Try the [image viewer](https://ludicon.com/sparkjs/viewer/) or the [gltf demo](h
 npm install @ludicon/spark.js
 ```
 
-## Usage Example
+## WebGPU Usage Example
 
 ```js
 import { Spark } from "@ludicon/spark.js"
@@ -41,6 +41,23 @@ The main entry point is `spark.encodeTexture()`, which loads an image and transc
 
 If the input image dimensions are not multiples of the block size, it will be resized to meet GPU format requirements. For best results, use images with dimensions that are multiples of 4.
 
+## WebGL Usage Example
+
+```js
+import { SparkGL } from "@ludicon/spark.js"
+
+// Initialize a WebGL2 context with required extensions
+const canvas = document.createElement("canvas")
+const gl = canvas.getContext("webgl2", { preserveDrawingBuffer: true })
+
+// Create spark instance for the WebGL2 context
+const spark = await SparkGL.create(gl)
+
+// Load and encode an image into a WebGL texture
+const texture = await spark.encodeTexture("image.avif").texture
+```
+
+The main difference is the use of the `SparkGL` class instead of `Spark`. The API of the `spark` object is the same, but `spark.encodeTexture()` returns an object with a `texture` property with resulting WebGL texture handle.
 
 ## Development
 
@@ -55,10 +72,11 @@ npm run build
 npm run watch
 ```
 
+## Examples
 
-## Running examples
+Live examples are available at: **https://ludicon.github.io/spark.js/**
 
-To run local examples:
+To run examples locally with hot reload:
 
 ```bash
 npm run dev
@@ -78,6 +96,8 @@ This will open `http://localhost:5174/examples/index.thml` where you can browse
 
 ## Documentation
 
+For full documentation, see the [API reference](API.md).
+
 ### `encodeTexture(source, options)`
 
 Load an image and encode it to a compressed GPU texture.
@@ -101,14 +121,17 @@ Load an image and encode it to a compressed GPU texture.
     
     Default: `rgb`.
 
-  - **`alpha`** 
-    Hint for the automatic format selector. When no explicit format is provided, the format is assumed to be `"rgb"`. Supplying `alpha: true` will default to "rgba" instead.
-
   - **`preferLowQuality`** 
     Hint for the automatic format selector. When the input format is `"rgb"` it chooses 8 bit per block formats like `"bc1"` or `"etc2"` instead of `"bc7"` or `"astc"`.
 
   - **`mips`** or **`generateMipmaps`** (`boolean`)
-    Whether to generate mipmaps. Mipmaps are generated with a basic box filter in linear space. Default: `false`.
+    Whether to generate mipmaps. Default: `false`.
+
+  - **`mipmapFilter`** (`string`)
+    The filter to use for mipmap generation. Can be `"box"` for a simple box filter, or `"magic"` for a higher-quality 4-tap filter with sharpening properties. Default: `"magic"`.
+
+  - **`mipsAlphaScale`** (`number[]`)
+    Optional array of alpha scale values to apply to each generated mipmap level. The array should contain one value per mipmap level (starting with mip level 1, since level 0 is the base image). Each value multiplies the alpha channel of the corresponding mipmap level. Values greater than 1.0 increase opacity, while values less than 1.0 increase transparency. This is useful for techniques like alpha-tested mipmaps where you want to compensate for alpha loss at lower mip levels. If the array is shorter than the number of mipmap levels, the last value is used for remaining levels. Only applies when `mips` is `true`. Default: `undefined` (no scaling applied).
 
   - **`srgb`** (`boolean`)
     Whether to encode the image using an as sRGB format. This also affects mipmap generation. The `srgb` mode can also be inferred from the `format`. Default: `false`. 
@@ -164,5 +187,4 @@ After registration, the loader will automatically encode textures with Spark whe
 - The JavaScript code is released under MIT license. 
 - Use of the *Spark* shaders is covered under the <a href="https://ludicon.com/sparkjs/eula.html">*spark.js* EULA</a>. 
 
-See https://ludicon.com/sparkjs#Licensing for details on how to use *spark.js* in commercial projects. 
-
+See https://ludicon.com/sparkjs#Licensing for details on how to use *spark.js* in commercial projects.