Port gl-matrix to WebAssembly by rust, wasm-bindgen and wasm-pack.
- Complete: Support all functions in gl-matrix.
- Pure: Write by pure rust without any third-part dependencies.
- Small: 25K(gzip, separate files) / 32K (gzip, wasm buffer will be embedded js file).
- Reliable: Full unit tests as same as gl-matrix.
- Fast: Some tricks to speed up the performance in production version.
Although this library support all functions in gl-matrix, but there are a little difference:
- Namespace: this library use
Matrix4... as namespace, it is not as same as gl-matrix's
- Async: You must initialize this library by async way, it's painful, but wasm requires.
- Data storage: When you use some ways such as
const vec2 = Vector2.create();to create vectors and matrixes, you will get a Object contains pointer but not TypedArray. This is the largest difference between wasm and js version. In was version, all data are stored in wasm memory, and js side only store those pointers. If you want to get the real value of wasm object, please use
object.elements, it will return a
Float32Arraythat could be pass to GPU, or you can use
object... to get each element by index.
First, install it:
npm i gl-matrix-wasm --save
Then you can use two ways to import and use it:
One JS file
In current time, this way is suggested. It combine wasm file and js wrapper file to one js file(as umd module) which embed a wasm buffer. That means you don't need any external tools, you can use it just as you use gl-matrix before.
This way faces the future, it provides a wasm file and a js(es6) file, in js file, it simply import the wasm file. It means you need some tools to compile it to es5 and split wasm file to your final results.
A common toolchain that support wasm is webpack(4.0+), your can put these config to your webpack.config.js file:
module:rules:......test: /\.wasm$/type: 'webassembly/experimental'......
And you must not exclude node_modules/gl-matrix in your js loader.
Now, you can use this library is separate-files mode:
I did many tests to show how wasm version faster than js. But unfortunately, wasm does not run faster for all scene.
So, for evaluating performance reliably, I made two kinds of tests: benchmark and real-world.
PS: In current time, rust & wasm-bindgen version is slower than c++ & emscripten, see #1585.
Real world is different from benchmark, I made some tests for each matrix4's method with 10000 calling, and a "really real world" test is also provided, it supposes we will execute operations "Mul x 4 -> fromRTS x 1 -> getElements" 1000 times per frame and run it in 60fps.
You can run these tests yourself:
CPU & Memory
Welcome to contribute, you can run this project in development environment follow this steps:
$ curl https://sh.rustup.rs -sSf | sh$ rustup default nightly$ rustup target add wasm32-unknown-unknown --toolchain nightly$ cargo +nightly install wasm-pack$ cargo update
Install node packages
$ npm i
Low performance, but could be used to debug rust sources.
npm run dev
High performance, but could not be used to debug rust sources.
npm run dev-build
We use karma for testing.
npm run test
SIMD on WebAssembly.