glmaths 0.0.2 → 0.0.3

package/README.md

@@ -44,13 +44,16 @@ You can pass vector in a vector, just like in GLSL: `vec4(vec2(0, 1), 2, 3)`
 If you code in TypeScript, you can opt for [a fork of TypeScript](https://github.com/dkaraush/Typescript) to enable operator overloading in code! `glmaths` implements functions needed to overload these operators: `+ - * / % == ===`
 
 ```ts
-mat4.perspective(Math.PI / 2) * vec4(vec2(1, 2) / 4.0 + 2.0, 1.0, 1.0)
+const ndc = proj * view * vertex
+let model = mat4()
+model *= mat4.fromRotation(Math.PI / 2, vec3(0, 1, 0))
+vec4(vec2(1.0, 2.0) / 2.0 + 4.0, 0.0, 1.0) + vec4(1) * vec4(4, 2, 0, 0)
 ```
 _With this done, it totally looks like GLSL! :D_
 
 ## `out` argument
 
-Like `gl-matrix`, all functions have `out` argument, but it is located at the end as an optional argument.
+Like `gl-matrix`, all functions have `out` argument, but it is located at the end as an optional argument:
 ```ts
 const a = vec3(0, 1, 2)
 const b = vec3(2, 3, 4)
@@ -58,15 +61,14 @@ const c = vec3()
 a.plus(b, /* out = */ c)
 ```
 
-By default, default value of `out` is always a new clone of a structure. Not using `out` will create overhead to GC leading to worse performance, so for production pre-allocating structures and passing them in `out` argument is recommended.
-
-You can also opt for modifying existing structure when using instance methods, by setting `glmaths.ALWAYS_COPY = false`. This way every operation, by default, will update its own structure. This might bring confusion, when saving structures in variables, as it modifies itself, hence why this is not the default behaviour. Example below:
+The idea behind `glmaths` is to make tinkering fun — so by default every operation returns a new copy, and you can just write `a.plus(b)` without thinking about memory. But when you need performance, you can pre-allocate structures and pass them as `out`, just like you would in `gl-matrix`.
 
+You can also set `glmaths.ALWAYS_COPY = false` to make instance methods modify the structure in place by default, skipping the copy entirely. But this can bring confusion, hence why this is not the default:
 ```ts
 glmaths.ALWAYS_COPY = false
 const a = vec3(0, 1, 2)
 const b = a.plus(5)
-// a.x === 5
+// a.x === 5, a was modified in place
 ```
 
 ## Docs
@@ -899,7 +901,7 @@ Suprisingly, in most operations `glmaths` comes faster than its simpler `gl-matr
 
 This benchmark, though, doesn't tell the difference in loading up a library. When I started running benchmarks, I noticed how on first test `glmaths` was consistently slower, than `gl-matrix`; and I believe this is a setup cost for extending `Float32Array` with all methods and getters for swizzles. There is a hack in `bencmark.js` to overcome this.
 
-## Benchmark Results
+Benchmark is run with `glmaths.ALWAYS_COPY = false`.
 
 | Operation | gl-matrix | glmaths | Diff |
 |:---|---:|---:|---:|
@@ -945,8 +947,6 @@ This benchmark, though, doesn't tell the difference in loading up a library. Whe
 | Quat2 multiply | — | 89.9M ops/s ±2.2% | — |
 | Quat2 getTranslation | — | 42.5M ops/s ±1.1% | — |
 
-_Benchmark was run on my Macbook Pro M4._
-
 ### Tests
 
 You can run tests with `npm run test`

package/benchmark.js

@@ -196,7 +196,7 @@ function vec3Benchmarks() {
     glm.vec3.distance(a1, b1);
   });
   s8.add('glmaths  Vec3.distance(a, b)', () => {
-    glmaths.Vec3.distance(a2, b2);
+    const c = glmaths.Vec3.distance(a2, b2);
   });
 
   
@@ -207,7 +207,7 @@ function vec3Benchmarks() {
     glm.vec3.lerp(lerpOut1, a1, b1, 0.5);
   });
   s9.add('glmaths  Vec3.lerp(a, b, 0.5, out)', () => {
-    glmaths.Vec3.lerp(a2, b2, 0.5, lerpOut2);
+    const c = glmaths.Vec3.lerp(a2, b2, 0.5, lerpOut2);
   });
 
   return runSuite(s1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glmaths",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "scripts": {
     "build": "rollup -c",
     "test": "TS_NODE_PROJECT=tsconfig.test.json node --require ts-node/register --test tests/*.test.ts",