tela.js 1.0.4 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # tela.js
 
-Experimental graphic library from scratch, with reference implementation of computer graphics algorithms.
+Experimental graphic library from scratch(software-only), with reference implementation of computer graphics algorithms.
 
 ## Purpose
 
@@ -29,25 +29,23 @@ Playground usage:
 
 </body>
 <script type="module">
-    import { Canvas, Animation, Color } from "https://cdn.jsdelivr.net/npm/tela.js/dist/web/index.js";
+    import { Canvas, Color, loop } from "https://cdn.jsdelivr.net/npm/tela.js/src/index.js";
 
     // You can also import from local file
-    // import { Canvas, Animation, Color} from "./node_modules/tela.js/dist/web/index.js";
+    // import { Canvas, Color, loop } from "./node_modules/tela.js/src/index.js";
 
     const width = 640;
     const height = 480;
     const canvas = Canvas.ofSize(640, 480);
-    Animation
-        .loop(({ time, dt }) => {
-            document.title = `FPS: ${(Math.floor(1 / dt))}`;
-            canvas.map((x, y) => {
-                return Color.ofRGB(
-                    ((x * time) / width) % 1,
-                    ((y * time) / height) % 1
-                )
-            })
+    loop(({ time, dt }) => {
+        document.title = `FPS: ${(Math.floor(1 / dt))}`;
+        canvas.map((x, y) => {
+            return Color.ofRGB(
+                ((x * time) / width) % 1,
+                ((y * time) / height) % 1
+            )
         })
-        .play();
+    }).play();
     document.body.appendChild(canvas.DOM);
 
 </script>
@@ -59,23 +57,22 @@ Playground usage:
 Install `tela.js` it using `npm install tela.js` / `bun add tela.js`.
 
 ```js
-import { Animation, Color } from "tela.js/dist/node/index.js";
+import { loop, Color } from "tela.js/src/index.node.js";
 import Window from "tela.js/src/Tela/Window.js";
 
 const width = 640;
 const height = 480;
 const window = Window.ofSize(640, 480);
-Animation
-    .loop(({ time, dt }) => {
-        window.setTitle(`FPS: ${Math.floor(1 / dt)}`);
-        window.map((x, y) => {
-            return Color.ofRGB(
-                ((x * time) / width) % 1,
-                ((y * time) / height) % 1
-            )
-        })
+loop(({ time, dt }) => {
+    window.setTitle(`FPS: ${Math.floor(1 / dt)}`);
+    window.map((x, y) => {
+        return Color.ofRGB(
+            ((x * time) / width) % 1,
+            ((y * time) / height) % 1
+        )
     })
-    .play();
+})
+.play();
 ```
 
 And run it: `node index.mjs` / `bun index.js`
@@ -90,7 +87,7 @@ Install `tela.js` it using `npm install tela.js` / `bun add tela.js`.
 Create a file:
 ```js
 // index.js
-import { Color, video } from "tela.js/dist/node/index.js";
+import { Color, video } from "tela.js/src/index.node.js";
 
 const width = 640;
 const height = 480;
@@ -111,7 +108,7 @@ video(
     animation,
     { width, height, FPS }
 )
-    .until(({ time }) => time < maxVideoTime);
+    .while(({ time }) => time < maxVideoTime);
 ```
 
 And run it: `node index.mjs` / `bun index.js`
@@ -127,6 +124,13 @@ ffmpeg -version
 
 ```
 
+## More examples
+
+You can find more examples of usage in:
+- [Playground (for web examples)](https://pedroth.github.io/tela.js)
+- [Test folder (for desktop)](/test/node/)
+
+
 # Dependencies
 
 - [`bun`][bun]/[`node`][node]
@@ -136,6 +140,13 @@ ffmpeg -version
 [Node][node] is preferred when running the demos (it is faster, [opened a bug in bun](https://github.com/oven-sh/bun/issues/9218)), [bun][bun] is needed to build the library.
 
 
+# TODOs
+
+- Fix parallel ray trace refresh bug
+- Parallel ray map
+- Serialize meshes not only triangles
+- Optimize data serialization in parallel ray tracer
+
 
 [ffmpeg]: https://ffmpeg.org/
 [bun]: https://bun.sh/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tela.js",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "author": "Pedroth",
   "repository": {
     "type": "git",
@@ -37,11 +37,9 @@
   ],
   "license": "Apache-2.0",
   "scripts": {
-    "build": "bun run clean; bun i; bun bundle.js",
-    "buildDev": "bun bundle.js --watch",
     "serve": "bunx http-server",
-    "clean": "rm -fr node_modules; rm -fr dist/; rm *.png *.jpeg *.ppm *.webm *.mp4",
-    "pub": "npm version patch; bun run build; npm publish"
+    "clean": "rm -fr node_modules; rm *.png *.jpeg *.ppm *.webm *.mp4",
+    "pub": "npm version patch; npm publish"
   },
   "type": "module"
 }

package/src/Camera/Camera.js

@@ -1,29 +1,22 @@
-import { Vec2, Vec3 } from "../Vector/Vector.js"
+import Vec, { Vec2, Vec3 } from "../Vector/Vector.js"
 import Ray from "../Ray/Ray.js";
-import { rayTrace } from "./raytrace.js";
+import { getRayTracer } from "./rayTrace.js";
 import { rasterGraphics } from "./raster.js";
 import { sdfTrace } from "./sdf.js";
 import { normalTrace } from "./normal.js";
-
-
+import { parallelWorkers } from "./parallel.js";
 
 export default class Camera {
   constructor(props = {}) {
-    const { lookAt, distanceToPlane, position } = props;
+    const { lookAt, distanceToPlane, position, orientCoords, orbitCoords } = props;
     this.lookAt = lookAt ?? Vec3(0, 0, 0);
     this.distanceToPlane = distanceToPlane ?? 1;
     this.position = position ?? Vec3(3, 0, 0);
-    this._orientCoords = Vec2();
-    this._orbitCoords = Vec3(this.position.length(), 0, 0);
-    this.orient();
-  }
-
-  clone() {
-    return new Camera({
-      lookAt: this.lookAt,
-      position: this.position,
-      distanceToPlane: this.distanceToPlane,
-    })
+    this._orientCoords = orientCoords ?? Vec2();
+    this._orbitCoords = orbitCoords;
+    if (this._orbitCoords) this.orbit(...this._orbitCoords.toArray());
+    else this.orient(...this._orientCoords.toArray());
+    this._orbitCoords = this._orbitCoords ?? Vec3(this.position.length());
   }
 
   look(at, up = Vec3(0, 0, 1)) {
@@ -91,11 +84,13 @@ export default class Camera {
     return {
       to: canvas => {
         const w = canvas.width;
+        const invW = 1 / w;
         const h = canvas.height;
+        const invH = 1 / h;
         const ans = canvas.map((x, y) => {
           const dirInLocal = [
-            (x / w - 0.5),
-            (y / h - 0.5),
+            (x * invW - 0.5),
+            (y * invH - 0.5),
             this.distanceToPlane
           ]
           const dir = Vec3(
@@ -112,11 +107,11 @@ export default class Camera {
     }
   }
 
-  sceneShot(scene, params = {}) {
-    return this.rayMap(rayTrace(scene, params));
+  sceneShot(scene, params) {
+    return this.rayMap(getRayTracer(scene, params));
   }
 
-  reverseShot(scene, params = {}) {
+  reverseShot(scene, params) {
     return {
       to: rasterGraphics(scene, this, params)
     }
@@ -130,6 +125,18 @@ export default class Camera {
     return this.rayMap(normalTrace(scene));
   }
 
+  parallelShot(scene, params) {
+    return {
+      to: canvas => {
+        return Promise
+          .all(parallelWorkers(this, scene, canvas, params))
+          .then(() => {
+            canvas.paint();
+          })
+      }
+    }
+  }
+
   toCameraCoord(x) {
     let pointInCamCoord = x.sub(this.position);
     pointInCamCoord = Vec3(
@@ -147,4 +154,45 @@ export default class Camera {
     }
     return x;
   }
+
+  rayFromImage(width, height) {
+    const w = width;
+    const invW = 1 / w;
+    const h = height;
+    const invH = 1 / h;
+    return (x, y) => {
+      const dirInLocal = [
+        (x * invW - 0.5),
+        (y * invH - 0.5),
+        this.distanceToPlane
+      ]
+      const dir = Vec3(
+        this.basis[0].x * dirInLocal[0] + this.basis[1].x * dirInLocal[1] + this.basis[2].x * dirInLocal[2],
+        this.basis[0].y * dirInLocal[0] + this.basis[1].y * dirInLocal[1] + this.basis[2].y * dirInLocal[2],
+        this.basis[0].z * dirInLocal[0] + this.basis[1].z * dirInLocal[1] + this.basis[2].z * dirInLocal[2]
+      )
+        .normalize()
+      return Ray(this.position, dir);
+    }
+  }
+
+  serialize() {
+    return {
+      lookAt: this.lookAt.toArray(),
+      distanceToPlane: this.distanceToPlane,
+      position: this.position.toArray(),
+      orientCoords: this._orientCoords.toArray(),
+      orbitCoords: this._orbitCoords.toArray(),
+    }
+  }
+
+  static deserialize(json) {
+    return new Camera({
+      lookAt: Vec.fromArray(json.lookAt),
+      distanceToPlane: json.distanceToPlane,
+      position: Vec.fromArray(json.position),
+      orientCoords: Vec.fromArray(json.orientCoords),
+      orbitCoords: Vec.fromArray(json.orbitCoords)
+    })
+  }
 }

package/src/Camera/common.js

@@ -0,0 +1,36 @@
+import Color from "../Color/Color.js";
+import { lerp } from "../Utils/Math.js";
+import { Vec2 } from "../Vector/Vector.js";
+
+export function getDefaultTexColor(texUV) {
+    texUV = texUV.scale(16).map(x => x % 1)
+    return texUV.x < 0.5 && texUV.y < 0.5 ?
+        Color.BLACK :
+        texUV.x > 0.5 && texUV.y > 0.5 ?
+            Color.BLACK :
+            Color.PURPLE;
+}
+
+export function getBiLinearTexColor(texUV, texture) {
+    const size = Vec2(texture.width, texture.height);
+    const texInt = texUV.mul(size);
+
+    const texInt0 = texInt.map(Math.floor);
+    const texInt1 = texInt0.add(Vec2(1, 0));
+    const texInt2 = texInt0.add(Vec2(0, 1));
+    const texInt3 = texInt0.add(Vec2(1, 1));
+
+    const color0 = texture.getPxl(...texInt0.toArray());
+    const color1 = texture.getPxl(...texInt1.toArray());
+    const color2 = texture.getPxl(...texInt2.toArray());
+    const color3 = texture.getPxl(...texInt3.toArray());
+
+    const x = texInt.sub(texInt0);
+    const bottomX = lerp(color0, color1)(x.x);
+    const topX = lerp(color2, color3)(x.x);
+    return lerp(bottomX, topX)(x.y);
+}
+
+export function getTexColor(texUV, texture) {
+    return texture.getPxl(texUV.x * texture.width, texUV.y * texture.height);
+}

package/src/Camera/parallel.js

@@ -0,0 +1,74 @@
+import { IS_NODE, NUMBER_OF_CORES } from "../Utils/Constants.js";
+import Color from "../Color/Color.js";
+import { CHANNELS } from "../Tela/Tela.js";
+
+//========================================================================================
+/*                                                                                      *
+ *                                         UTILS                                        *
+ *                                                                                      */
+//========================================================================================
+
+const __Worker = IS_NODE ? (await import("node:worker_threads")).Worker : Worker;
+class MyWorker {
+    constructor(path) {
+        this.path = path;
+        this.worker = new __Worker(path, { type: 'module' });
+    }
+
+    onMessage(lambda) {
+        if (IS_NODE) {
+            this.worker.removeAllListeners('message');
+            this.worker.on("message", lambda);
+        } else {
+            this.worker.onmessage = message => lambda(message.data);
+        }
+    }
+
+    postMessage(message) {
+        return this.worker.postMessage(message);
+    }
+}
+
+let WORKERS = [];
+let prevSceneHash = undefined;
+
+//========================================================================================
+/*                                                                                      *
+ *                                         MAIN                                         *
+ *                                                                                      */
+//========================================================================================
+
+export function parallelWorkers(camera, scene, canvas, params = {}) {
+    // lazy loading workers
+    if (WORKERS.length === 0) WORKERS = [...Array(NUMBER_OF_CORES)].map(() => new MyWorker(`/src/Camera/rayTraceWorker.js`));
+    const w = canvas.width;
+    const h = canvas.height;
+    const isNewScene = prevSceneHash !== scene.hash;
+    if (isNewScene) prevSceneHash = scene.hash;
+    return WORKERS.map((worker, k) => {
+        return new Promise((resolve) => {
+            worker.onMessage(message => {
+                const { image, startRow, endRow, } = message;
+                let index = 0;
+                const startIndex = CHANNELS * w * startRow;
+                const endIndex = CHANNELS * w * endRow;
+                for (let i = startIndex; i < endIndex; i += CHANNELS) {
+                    canvas.setPxlData(i, Color.ofRGB(image[index++], image[index++], image[index++], image[index++]));
+                }
+                resolve();
+            })
+            const ratio = Math.floor(h / WORKERS.length);
+
+            const message = {
+                width: w,
+                height: h,
+                params: params,
+                startRow: k * ratio,
+                endRow: Math.min(h, (k + 1) * ratio),
+                camera: camera.serialize(),
+                scene: isNewScene ? scene.serialize() : undefined
+            };
+            worker.postMessage(message);
+        });
+    })
+}

package/src/Camera/raster.js

@@ -1,14 +1,14 @@
 import Color from "../Color/Color.js";
 import Line from "../Geometry/Line.js";
-import Point from "../Geometry/Point.js";
+import Sphere from "../Geometry/Sphere.js";
 import Mesh from "../Geometry/Mesh.js";
 import Triangle from "../Geometry/Triangle.js";
-import { lerp } from "../Utils/Math.js";
 import { Vec2 } from "../Vector/Vector.js";
+import { getBiLinearTexColor, getDefaultTexColor, getTexColor } from "./common.js";
 
-export function rasterGraphics(scene, camera, params) {
+export function rasterGraphics(scene, camera, params = {}) {
     const type2render = {
-        [Point.name]: rasterPoint,
+        [Sphere.name]: rasterSphere,
         [Line.name]: rasterLine,
         [Triangle.name]: rasterTriangle,
         [Mesh.name]: rasterMesh,
@@ -52,7 +52,7 @@ export function rasterGraphics(scene, camera, params) {
 }
 
 
-function rasterPoint({ canvas, camera, elem, w, h, zBuffer }) {
+function rasterSphere({ canvas, camera, elem, w, h, zBuffer }) {
     const point = elem;
     const { distanceToPlane } = camera;
     const { texCoord, texture, position, color, radius } = point;
@@ -71,6 +71,7 @@ function rasterPoint({ canvas, camera, elem, w, h, zBuffer }) {
     y = Math.floor(y);
     if (x < 0 || x >= w || y < 0 || y >= h) return;
     const intRadius = Math.ceil((radius) * (distanceToPlane / z) * w);
+    const intRadiusSquare = intRadius * intRadius;
     let finalColor = color;
     if (
         texture &&
@@ -83,6 +84,8 @@ function rasterPoint({ canvas, camera, elem, w, h, zBuffer }) {
         for (let l = -intRadius; l < intRadius; l++) {
             const xl = Math.max(0, Math.min(w - 1, x + k));
             const yl = Math.floor(y + l);
+            const squareLength = k * k + l * l;
+            if (squareLength > intRadiusSquare) continue;
             const [i, j] = canvas.canvas2grid(xl, yl);
             const zBufferIndex = Math.floor(w * i + j);
             if (z < zBuffer[zBufferIndex]) {
@@ -227,7 +230,7 @@ function rasterTriangle({ canvas, camera, elem, w, h, zBuffer, params }) {
                 params.bilinearTexture ?
                     getBiLinearTexColor(texUV, texture) :
                     getTexColor(texUV, texture) :
-                getDefaultTexColor(texUV);
+                c ? c : getDefaultTexColor(texUV); // TODO: review this
             c = texColor;
         }
         const [i, j] = canvas.canvas2grid(x, y);
@@ -253,37 +256,4 @@ function lineCameraPlaneIntersection(vertexOut, vertexIn, camera) {
     const alpha = (distanceToPlane - vertexOut.z) / v.z;
     const p = vertexOut.add(v.scale(alpha));
     return p;
-}
-
-function getDefaultTexColor(texUV) {
-    texUV = texUV.scale(16).map(x => x % 1)
-    return texUV.x < 0.5 && texUV.y < 0.5 ?
-        Color.BLACK :
-        texUV.x > 0.5 && texUV.y > 0.5 ?
-            Color.BLACK :
-            Color.PURPLE;
-}
-
-function getBiLinearTexColor(texUV, texture) {
-    const size = Vec2(texture.width, texture.height);
-    const texInt = texUV.mul(size);
-
-    const texInt0 = texInt.map(Math.floor);
-    const texInt1 = texInt0.add(Vec2(1, 0));
-    const texInt2 = texInt0.add(Vec2(0, 1));
-    const texInt3 = texInt0.add(Vec2(1, 1));
-
-    const color0 = texture.getPxl(...texInt0.toArray());
-    const color1 = texture.getPxl(...texInt1.toArray());
-    const color2 = texture.getPxl(...texInt2.toArray());
-    const color3 = texture.getPxl(...texInt3.toArray());
-
-    const x = texInt.sub(texInt0);
-    const bottomX = lerp(color0, color1)(x.x);
-    const topX = lerp(color2, color3)(x.x);
-    return lerp(bottomX, topX)(x.y);
-}
-
-function getTexColor(texUV, texture) {
-    return texture.getPxl(texUV.x * texture.width, texUV.y * texture.height);
 }

package/src/Camera/rayTrace.js

@@ -0,0 +1,84 @@
+import Color from "../Color/Color.js";
+import Triangle from "../Geometry/Triangle.js";
+import Ray from "../Ray/Ray.js";
+import Vec from "../Vector/Vector.js";
+import { getBiLinearTexColor, getDefaultTexColor, getTexColor } from "./common.js";
+
+export function rayTrace(ray, scene, params) {
+    let { samplesPerPxl, bounces, variance, gamma, bilinearTexture } = params;
+    bounces = bounces ?? 10;
+    variance = variance ?? 0.001;
+    samplesPerPxl = samplesPerPxl ?? 1;
+    gamma = gamma ?? 0.5;
+    bilinearTexture = bilinearTexture ?? false;
+    const invSamples = (bounces ?? 1) / samplesPerPxl
+    let c = Color.BLACK;
+    for (let i = 0; i < samplesPerPxl; i++) {
+        const epsilon = Vec.RANDOM(3).scale(variance);
+        const epsilonOrtho = epsilon.sub(ray.dir.scale(epsilon.dot(ray.dir)));
+        const r = Ray(ray.init, ray.dir.add(epsilonOrtho).normalize());
+        c = c.add(trace(r, scene, { bounces, bilinearTexture }));
+    }
+    return c.scale(invSamples).toGamma(gamma);
+}
+
+export function getRayTracer(scene, params = {}) {
+    const lambda = ray => rayTrace(ray, scene, params);
+    return lambda;
+}
+
+export function trace(ray, scene, options) {
+    const { bounces, bilinearTexture } = options;
+    if (bounces < 0) return Color.BLACK;
+    const hit = scene.interceptWithRay(ray);
+    if (!hit) return Color.BLACK;
+    const [, p, e] = hit;
+    const color = getColorFromElement(e, ray, { bilinearTexture });
+    const mat = e.material;
+    let r = mat.scatter(ray, p, e);
+    let finalC = trace(
+        r,
+        scene,
+        { bounces: bounces - 1, bilinearTexture }
+    );
+    return e.emissive ? color.add(color.mul(finalC)) : color.mul(finalC);
+}
+
+function getColorFromElement(e, ray, params) {
+    if (Triangle.name === e.constructor.name) {
+        return getTriangleColor(e, ray, params);
+    }
+    return e.color ?? e.colors[0]
+}
+
+function getTriangleColor(triangle, ray, params) {
+    const { tangents, positions, texCoords, texture, colors } = triangle;
+
+    const haveTextures = texture &&
+        texCoords &&
+        texCoords.length > 0 &&
+        !texCoords.some(x => x === undefined);
+
+    const v = ray.init.sub(positions[0]);
+    const u1 = tangents[0];
+    const u2 = tangents[1];
+    const r = ray.dir;
+    const detInv = 1 / u1.cross(u2).dot(r);
+    const alpha = v.cross(u2).dot(r) * detInv
+    const beta = u1.cross(v).dot(r) * detInv;
+    if (haveTextures) {
+        const texUV = texCoords[0].scale(1 - alpha - beta)
+            .add(texCoords[1].scale(alpha))
+            .add(texCoords[2].scale(beta));
+        const texColor = texture ?
+            params.bilinearTexture ?
+                getBiLinearTexColor(texUV, texture) :
+                getTexColor(texUV, texture) :
+            getDefaultTexColor(texUV);
+        return texColor;
+    }
+    return colors[0]
+        .scale(alpha)
+        .add(colors[1].scale(beta))
+        .add(colors[2].scale(1 - alpha - beta))
+}

package/src/Camera/rayTraceWorker.js

@@ -0,0 +1,59 @@
+import Camera from "./Camera.js";
+import { rayTrace } from "./rayTrace.js";
+import { CHANNELS } from "../Tela/Tela.js";
+import { IS_NODE } from "../Utils/Constants.js";
+import { deserializeScene } from "../Scene/utils.js";
+import Color from "../Color/Color.js";
+
+const parentPort = IS_NODE ? (await import("node:worker_threads")).parentPort : undefined;
+
+let scene = undefined;
+
+function getScene(serializedScene) {
+    return deserializeScene(serializedScene).then(s => s.rebuild());
+}
+
+async function main(inputs) {
+    const {
+        startRow,
+        endRow,
+        width,
+        height,
+        params,
+        scene: serializedScene,
+        camera: serializedCamera,
+    } = inputs;
+    scene = serializedScene ? await getScene(serializedScene) : scene;
+    const camera = Camera.deserialize(serializedCamera);
+    const rayGen = camera.rayFromImage(width, height);
+    const bufferSize = width * (endRow - startRow + 1) * CHANNELS;
+    const image = new Float32Array(bufferSize);
+    let index = 0;
+    // the order does matter
+    for (let y = startRow; y < endRow; y++) {
+        for (let x = 0; x < width; x++) {
+            const ray = rayGen(x, height - 1 - y);
+            const color = scene ? rayTrace(ray, scene, params) : Color.random();
+            image[index++] = color.red;
+            image[index++] = color.green;
+            image[index++] = color.blue;
+            image[index++] = color.alpha;
+        }
+    }
+    return { image, startRow, endRow };
+}
+
+
+if (IS_NODE) {
+    parentPort.on("message", async message => {
+        const input = message;
+        const output = await main(input);
+        parentPort.postMessage(output);
+    });
+} else {
+    onmessage = async message => {
+        const input = message.data;
+        const output = await main(input);
+        postMessage(output);
+    };
+}

package/src/Color/Color.js

@@ -12,7 +12,7 @@ export default class Color {
   }
 
   toArray() {
-    return [this.red, this.green, this.blue, this.alpha];
+    return [this.rgb[0], this.rgb[1], this.rgb[2], this.alpha];
   }
 
   get red() {

package/src/Geometry/Box.js

@@ -141,6 +141,14 @@ export default class Box {
         return this.min.add(Vec.RANDOM(this.dim).mul(this.diagonal));
     }
 
+    serialize() {
+        // TODO
+    }
+
+    deserialize() {
+        // TODO
+    }
+
     static EMPTY = new Box();
 }
 

package/src/Geometry/Geometry.js

@@ -35,4 +35,20 @@ export default class Geometry {
     interceptWithRay(ray) {
         throw Error("Not implemented");
     }
+
+    sample() {
+        throw Error("Not implemented");
+    }
+
+    equals(obj) {
+        return this === obj;
+    }
+
+    serialize() {
+        throw Error("Not implemented");
+    }
+
+    static deserialize(json) {
+        throw Error("Not implemented");
+    }
 }