@nasedkinpv/opensubdiv-wasm

WebAssembly port of Pixar's OpenSubdiv for browser and Node.js.

High-performance Catmull-Clark subdivision surfaces with Three.js integration.

Live Demo — WebGPU + HDR environment

Features

• Catmull-Clark subdivision (levels 1-5)
• Real-time animation via StencilTable caching
• Zero-copy typed array access to WASM memory
• Three.js BufferGeometry integration
• Face-varying UV interpolation
• Mixed quad/triangle mesh support

Bundle Size

File	Size	Gzipped
opensubdiv.wasm	163 KB	60 KB
opensubdiv.mjs	46 KB	13 KB
Total	209 KB	72 KB

Installation

npm install @nasedkinpv/opensubdiv-wasm

Quick Start

Low-level WASM API

import OpenSubdiv from '@nasedkinpv/opensubdiv-wasm';

const module = await OpenSubdiv();

const positions = new Float32Array([
  -1, -1, 1,  1, -1, 1,  1, 1, 1,  -1, 1, 1,  // front
  -1, -1, -1, 1, -1, -1, 1, 1, -1, -1, 1, -1  // back
]);

const quadIndices = new Int32Array([
  0, 1, 2, 3,  // front
  5, 4, 7, 6,  // back
  4, 0, 3, 7,  // left
  1, 5, 6, 2,  // right
  3, 2, 6, 7,  // top
  4, 5, 1, 0   // bottom
]);

const mesh = new module.SubdivisionMesh();
mesh.initFromQuads(positions, quadIndices, 6, 2, module.BOUNDARY_EDGE_ONLY);

console.log('Vertices:', mesh.getVertexCount());
console.log('Triangles:', mesh.getTriangleCount());

const subdivided = mesh.getPositions();  // Float32Array
const normals = mesh.getNormals();       // Float32Array  
const indices = mesh.getIndices();       // Uint32Array

mesh.delete();  // Free WASM memory

Three.js Integration

import * as THREE from 'three';
import { SubdivisionSurface } from '@nasedkinpv/opensubdiv-wasm/threejs';

const surface = new SubdivisionSurface({ level: 2 });
await surface.init();

surface.initFromQuads(positions, quadIndices);
const geometry = surface.toBufferGeometry(THREE);

const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);

// Animation (fast path using cached stencils)
function animate() {
  modifyControlVertices(positions);
  surface.updatePositions(positions);
  surface.updateBufferGeometry(geometry);
}

surface.dispose();

API Reference

See THREEJS_USAGE.md for complete API documentation.

When loading the ESM build in a custom runtime or bundler, you can pass Emscripten module options such as locateFile() to control where opensubdiv.wasm is fetched from.

Performance

Benchmarked with 984 input vertices (quad mesh):

Level	Output Verts	Triangles	Time	Throughput
1	~4K	~8K	~1.5ms	~2,600 v/ms
2	~16K	~31K	~5ms	~3,000 v/ms
3	~63K	~126K	~25ms	~2,500 v/ms
4	~251K	~503K	~120ms	~2,100 v/ms

• WASM init: ~17ms (one-time)
• Level 2: Sweet spot for real-time (5ms for 16K verts)
• Animation updates: Use pre-computed StencilTables, ~10-100x faster than re-subdivision

Building from Source

Requirements

• Emscripten (for WASM compilation)
• Binaryen (for wasm-opt optimization)

# Homebrew (macOS)
brew install emscripten binaryen

# Or install via emsdk (cross-platform)
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest

# Binaryen via npm is also supported
npm install -g binaryen

Build Commands

# Activate Emscripten if you installed it via emsdk
source /path/to/emsdk/emsdk_env.sh

# Full build (WASM + wasm-opt + TypeScript wrapper)
npm run build

# Quick build without wasm-opt (faster iteration)
npm run build:quick

# Run tests
npm test

Both npm run build and npm run build:quick now refresh the GitHub Pages demo assets in docs/ from the current dist/ output, so the package build and the live demo stay aligned.

Build Scripts

Script	Description
build	Full optimized build (WASM + wasm-opt + threejs)
build:quick	Skip wasm-opt for faster iteration
build:wasm	Build CommonJS WASM module
build:wasm:esm	Build ES Module WASM module
build:wasm:optimize	Run wasm-opt -Oz on WASM binary
build:threejs	Compile TypeScript wrapper
build:docs	Sync release artifacts and metadata into docs/ for GitHub Pages

License

TOST-1.0 (Tomorrow Open Source Technology License - modified Apache 2.0)

Based on OpenSubdiv by Pixar Animation Studios.

Trademark Notice

This project is not affiliated with, endorsed by, or sponsored by Pixar Animation Studios, DreamWorks Animation, or any of their affiliates.

"OpenSubdiv", "Pixar", and "DreamWorks" are trademarks of their respective owners. Use of these names is solely for attribution purposes as required by the license.

Credits

• OpenSubdiv: Pixar Animation Studios
• WASM Port: nasedkinpv
• Original Fork: discere-os/OpenSubdiv.wasm

See NOTICE.txt for full attribution.