texture2ddecoder-wasm


A WebAssembly-based JavaScript/TypeScript library for decoding compressed texture formats. This project was inspired by K0lb3's texture2ddecoder Python wrapper and brings the same powerful texture decoding capabilities to Node.js and web environments through WebAssembly.

Built on top of Perfare's Texture2DDecoder from AssetStudio, with cross-platform WebAssembly bindings for JavaScript/TypeScript environments.

Features

- Zero native dependencies - Pure WebAssembly, works on any platform
- Browser and Node.js compatible - Works in both browser and Node.js environments
- Comprehensive format support - Decode BC1-7, ETC1/2, PVRTC, ASTC, ATC, EAC, and Crunch formats
- TypeScript support - Full type definitions included
- Unity Asset support - Decode textures from Unity game assets
- Fast performance - Native-speed decoding via WebAssembly

Supported Formats

$3

- BC1 (DXT1) - RGB compression
- BC3 (DXT5) - RGBA compression
- BC4 - Single channel compression
- BC5 - Dual channel compression
- BC6 - HDR compression
- BC7 - High quality compression

$3

- ETC1 - RGB compression
- ETC2 - Improved RGB compression
- ETC2A1 - RGB + 1-bit alpha
- ETC2A8 - RGB + 8-bit alpha

$3

- EAC R11 - Single channel
- EAC R11 (signed) - Single channel signed
- EAC RG11 - Dual channel
- EAC RG11 (signed) - Dual channel signed

$3

- PVRTC - PowerVR Texture Compression (2bpp and 4bpp)
- ASTC - Adaptive Scalable Texture Compression (various block sizes)
- ATC - AMD Texture Compression (RGB4 and RGBA8)
- Crunch - Crunch compressed textures
- Unity Crunch - Unity's variant of Crunch compression

Installation

``bash
npm install texture2ddecoder-wasm
`

or

`bash
yarn add texture2ddecoder-wasm
`

> 🚀 New to this library? Check out the Quick Start Guide for the fastest way to get running!
> 📖 Need bundler setup? See the Complete Bundler Guide for detailed configurations.

Usage

> 💡 See the examples/ directory for complete working configurations for popular frameworks!

$3

`typescript
import { decode_astc } from "texture2ddecoder-wasm";
import * as fs from "fs";

// Load compressed texture data
const data = fs.readFileSync("texture.astc");

// Decode ASTC texture
const width = 512;
const height = 512;
const blockWidth = 4;
const blockHeight = 4;

const decoded = await decode_astc(data, width, height, blockWidth, blockHeight);

if (decoded) {
// decoded is a Uint8Array containing BGRA pixel data
// Use with image libraries like sharp, jimp, etc.
console.log("Decoded successfully!");
}
`

$3

For modern frameworks (React, Vue, Svelte, Next.js, etc.), you can use CDN for quick setup or local files for production:

#### Quick Start - Using CDN (Recommended for Development)

`typescript
import { initialize, decode_bc1 } from "texture2ddecoder-wasm";

// Initialize with CDN
await initialize({
wasmPath: "https://cdn.jsdelivr.net/npm/texture2ddecoder-wasm@1.2.1/wasm",
});

// Load and decode texture
const response = await fetch("texture.bin");
const data = new Uint8Array(await response.arrayBuffer());
const decoded = await decode_bc1(data, 512, 512);
`

Benefits:

- ✅ No manual file copying needed
- ✅ Fastest setup time
- ✅ Cached by CDN globally
- ✅ Perfect for prototyping and development

#### Production Setup - Using Local Files

For production, copy WASM files to your public directory:

`bash
npx texture2ddecoder-copy-wasm public/wasm
`

`typescript
import { initialize, decode_bc1 } from "texture2ddecoder-wasm";

// Initialize with local path
await initialize({ wasmPath: "/wasm" });

const decoded = await decode_bc1(data, 512, 512);
`

Benefits:

- ✅ Faster loading (same domain)
- ✅ Works offline
- ✅ No external dependencies

Framework-Specific Examples:

Vite + React:

`typescript
import { initialize, decode_bc1 } from "texture2ddecoder-wasm";

// Development: Use CDN
await initialize({
wasmPath: "https://cdn.jsdelivr.net/npm/texture2ddecoder-wasm@1.2.1/wasm",
});

// Production: Use local files (copy with: npx texture2ddecoder-copy-wasm public/wasm)
await initialize({ wasmPath: "/wasm" });
`

Next.js:

`typescript
// In a 'use client' component
import { initialize, decode_bc1 } from "texture2ddecoder-wasm";

// Development: Use CDN
await initialize({
wasmPath: "https://cdn.jsdelivr.net/npm/texture2ddecoder-wasm@1.2.1/wasm",
});

// Production: Use local files (copy with: npx texture2ddecoder-copy-wasm public/wasm)
await initialize({ wasmPath: "/wasm" });
`

Webpack 5:

`typescript
import { initialize, decode_bc1 } from "texture2ddecoder-wasm";

// Development: Use CDN
await initialize({
wasmPath: "https://cdn.jsdelivr.net/npm/texture2ddecoder-wasm@1.2.1/wasm",
});

// Production: Use local files (copy with: npx texture2ddecoder-copy-wasm public/wasm)
await initialize({ wasmPath: "/wasm" });
`

$3

You can use the library directly from jsDelivr CDN without any installation:

`html








Decode Textures from CDN




`

Benefits:

- ✅ Zero build setup
- ✅ No npm install needed
- ✅ Cached by jsDelivr globally
- ✅ Perfect for quick prototypes

Production tip: Pin to a specific version (e.g., @1.2.1) instead of @latest for stability.

Complete working example: See examples/cdn-example.html for a full interactive demo.

$3

`typescript
import { initialize, decode_bc3 } from "texture2ddecoder-wasm";

// Node.js - no parameter needed (auto-detects module location)
await initialize();

// Browser - provide path to WASM files
await initialize({ wasmPath: "/wasm" });

// Browser with CDN - provide full CDN URL
await initialize({
wasmPath: "https://cdn.jsdelivr.net/npm/texture2ddecoder-wasm@1.2.1/wasm",
});

// Browser with custom locateFile for advanced use cases
await initialize({
wasmPath: "/wasm",
locateFile: (path) => /custom-path/${path},
});

// Now decode functions will use the already-initialized module
const result = await decode_bc3(data, width, height);
`

API Reference

All decode functions accept Uint8Array | ArrayBuffer as input and return a Promise. The returned Uint8Array contains BGRA pixel data (4 bytes per pixel).

Note: In Node.js, you can still pass Buffer objects (which extend Uint8Array) and receive Uint8Array results that are compatible with Buffer operations.

$3

#### decode_bc1(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes BC1 (DXT1) compressed texture to BGRA.

#### decode_bc3(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes BC3 (DXT5) compressed texture to BGRA.

#### decode_bc4(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes BC4 compressed texture to BGRA.

#### decode_bc5(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes BC5 compressed texture to BGRA.

#### decode_bc6(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes BC6 compressed texture to BGRA.

#### decode_bc7(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes BC7 compressed texture to BGRA.

$3

#### decode_etc1(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes ETC1 compressed texture to BGRA.

#### decode_etc2(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes ETC2 compressed texture to BGRA.

#### decode_etc2a1(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes ETC2 with 1-bit alpha compressed texture to BGRA.

#### decode_etc2a8(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes ETC2 with 8-bit alpha compressed texture to BGRA.

$3

#### decode_eacr(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes EAC R11 compressed texture to BGRA.

#### decode_eacr_signed(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes EAC R11 signed compressed texture to BGRA.

#### decode_eacrg(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes EAC RG11 compressed texture to BGRA.

#### decode_eacrg_signed(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes EAC RG11 signed compressed texture to BGRA.

$3

#### decode_pvrtc(data: Uint8Array | ArrayBuffer, width: number, height: number, is2bpp: boolean = false): Promise

Decodes PVRTC compressed texture to BGRA.

- is2bpp: Set to true for 2 bits-per-pixel mode, false for 4 bits-per-pixel (default)

#### decode_astc(data: Uint8Array | ArrayBuffer, width: number, height: number, blockWidth: number, blockHeight: number): Promise

Decodes ASTC compressed texture to BGRA.

- blockWidth: Block width (typically 4, 5, 6, 8, 10, or 12)
- blockHeight: Block height (typically 4, 5, 6, 8, 10, or 12)

#### decode_atc_rgb4(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes ATC RGB4 compressed texture to BGRA.

#### decode_atc_rgba8(data: Uint8Array | ArrayBuffer, width: number, height: number): Promise

Decodes ATC RGBA8 compressed texture to BGRA.

$3

#### unpack_crunch(data: Uint8Array | ArrayBuffer): Promise

Unpacks Crunch compressed data.

#### unpack_unity_crunch(data: Uint8Array | ArrayBuffer): Promise

Unpacks Unity Crunch compressed data.

$3

#### initialize(options?: { wasmPath?: string; locateFile?: (path: string, prefix: string) => string }): Promise

Manually initialize the WebAssembly module. This is called automatically on first use of any decode function in Node.js, but must be called explicitly in browser environments.

Parameters:

- options.wasmPath - (Browser required) Path or URL to the directory containing WASM files
- options.locateFile - (Optional) Custom function to locate WASM binary files for advanced use cases

Node.js Example:

`typescript
await initialize(); // Auto-detects and loads from dist/wasm/
`

Browser Examples:

`typescript
// Basic usage - local path
await initialize({ wasmPath: "/wasm" });

// With CDN
await initialize({
wasmPath: "https://cdn.jsdelivr.net/npm/texture2ddecoder-wasm@1.2.1/wasm",
});

// With custom locateFile for advanced scenarios
await initialize({
wasmPath: "/wasm",
locateFile: (path) => https://cdn.example.com/custom/${path},
});
`

Framework Integration:
This approach works seamlessly with:

- ✅ React / Next.js
- ✅ Vue / Nuxt
- ✅ Svelte / SvelteKit
- ✅ Webpack 5 / Vite / Rollup
- ✅ Server-Side Rendering (SSR) - Call initialize() in client-side code only

Building from Source

$3

- Node.js ≥14.0.0
- Docker - Required for building the WebAssembly module (no local Emscripten installation needed)

Install Docker from: https://www.docker.com/get-started

$3

`bash


Clone the repository

- npm run build:wasm - Build the WebAssembly module using Docker and Emscripten
- npm run build:ts - Compile TypeScript
- npm run build - Build both WASM and TypeScript
- npm test - Run tests

$3

The WebAssembly build uses Docker with the official Emscripten SDK image, which means:

- No need to install Emscripten locally
- Consistent build environment across all platforms
- Automatic compiler toolchain setup
- Works on Windows, macOS, and Linux

The build script (scripts/build-wasm.sh) automatically:

1. Checks if Docker is installed
2. Pulls the latest Emscripten SDK image
3. Compiles the C++ texture decoders to WebAssembly
4. Generates optimized WASM and JavaScript glue code

License & Credits

This project is licensed under MIT.

Inspired by K0lb3's texture2ddecoder Python library.

The texture compression codecs were derived from the following sources:

| Codec | License | Source |
| -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| ATC | MIT | Perfare/AssetStudio - Texture2DDecoderNative/atc.cpp |
| ASTC | MIT | Ishotihadus/mikunyan - ext/decoders/native/astc.c |
| BCn | MIT | Perfare/AssetStudio - Texture2DDecoderNative/bcn.cpp |
| ETC | MIT | Ishotihadus/mikunyan - ext/decoders/native/etc.c |
| f16 | MIT | Maratyszcza/FP16 |
| PVRTC | MIT | Ishotihadus/mikunyan - ext/decoders/native/pvrtc.c |
| Crunch | PUBLIC DOMAIN | BinomialLLC/crunch |
| Crunch (Unity) | ZLIB | Unity-Technologies/crunch |

Related Projects

- texture2ddecoder - Python wrapper (original inspiration)
- AssetStudio - Original C++ texture decoders
- UnityPy - Unity asset extraction tool

Contributing

Contributions are welcome! Please read our Contributing Guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

$3

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/texture2ddecoder-wasm.git
3. Initialize submodules: git submodule update --init --recursive
4. Install dependencies: npm install
5. Build the project: npm run build
6. Run tests: npm test`
7. Create a branch, make your changes, and submit a Pull Request

See CONTRIBUTING.md for detailed guidelines.

Platform Support

- Node.js: ≥14.0.0
- Browsers: Modern browsers with WebAssembly support (Chrome, Firefox, Safari, Edge)
- Operating Systems: Windows, macOS, Linux (WebAssembly is platform-independent)

$3

The package works in all modern browsers that support:

- WebAssembly
- ES6 Modules (or use a bundler like Webpack/Vite)
- Typed Arrays (Uint8Array)

Tested and working in:

- Chrome/Edge 57+
- Firefox 52+
- Safari 11+
- Opera 44+

Examples

See browser-example.html for a complete browser usage example.