Skip to content

WASM and JavaScript module

Jump to bottom
Syoyo Fujita edited this page Jun 16, 2025 · 8 revisions

Project folder

Located in web folder

https://github.com/lighttransport/tinyusdz/tree/dev/web

Use Emscripten to build WASM/JS module.

SharedArrayBuffer feature is not required.

WASM module is being built with no thread support by default, so works without SharedArrayBuffer feature. (e.g. static-site hosting service like Github Pages, where Cross-Origin isolation headers cannot be appended)

We have a plan to make TinyUSDZ multithreaded, and provide WASM build with SharedArrayBuffer feature.

FetchAssetResolver & EMAssetResolver

Since it is impossible or quite difficult to call JS fetch(or other async function) to do async file read from C++(synchronous), we provide JavaScript/WASM specific FetchAssetResolver(JavaScript) and EMAssetResolver(C++).

How asset resolve in USD composition works

  • First list up asset paths for each composition op(subLayer, references, payload)
  • fetch asset(URI) and store it to memory
  • Set asset binary to EMAssetResolver(C++).
  • Use EMAssetResolver for AssetResolver in USD progressive composition(in C++).
    • EMAssetResolver returns corresponding binary for given asset name.

Limitation

  • File(asset) must be read into memory a priori. So it may fail to load larger USD file.

JS library

  • TinyUSDZLoader.js : USD loader, extends Three.js Loader class. Internally it imports WASM module.
  • TinyUSDZLoaderUtils.js : Material setup(also requires Three.js), etc.
  • TinyUSDZComposer.js : USD composition utils. Depends 'TinyUSDZLoader.js'

Three.js

Currently we only support Three.js for demo .

UsdPreviewSurface

UsdPreviewSurface parameters are directly mapped to Three.js's MeshPhysicalMaterial material.

UsdPreviewSurface Parameter three.js MeshPhysicalMaterial Property Notes
diffuseColor color Both define the base color/albedo.
emissiveColor emissive For self-illumination.
roughness roughness Controls surface roughness.
metallic metalness Controls metallic appearance.
clearcoat clearcoat MeshPhysicalMaterial supports clearcoat.
clearcoatRoughness clearcoatRoughness MeshPhysicalMaterial supports clearcoatRoughness.
opacity opacity Set transparent = true if opacity < 1.
ior (indexOfRefraction) ior Supported by MeshPhysicalMaterial (three.js r125+).
normal normalMap For normal mapping.
occlusion aoMap Ambient occlusion. Texture only
displacement displacementMap/ displacementScale Displacement mapping. Texture only

Note on displacement mapping

Mesh subdivision is not supported well. To make displacement mapping work nicely, Meshes must be tessellated finely before creating USD, or tesselate in JavaScript layer.

TODO

  • Support specularWorkflow
  • Support refraction(refractive transmission)

MaterialX

TODO

WASM binary size

as of 2025/Jun.

  • 1.9 MB with -Oz
    • 400 kb with zstd compression
  • 6~7 MB with -Oz + ASYNCIFY

npm release(Developer only)

Need to manually invoke Github Actions for npm publish.

https://github.com/lighttransport/tinyusdz/actions/workflows/wasmPublish.yml

image

Edit version and run workflow.

TODO: cli command using curl

Clone this wiki locally