├── README.md
├── demos
    ├── README.md
    ├── ball.html
    ├── terrain.html
    └── tetrahedron.html
└── zengine.js


/README.md:
--------------------------------------------------------------------------------
  1 | zengine.js
  2 | ==========
  3 | 
  4 | #### A JavaScript 3D Rendering Engine
  5 | 
  6 | There are many JavaScript 3D libraries out there, such as [THREE.js](https://threejs.org/), but I wanted to challenge myself to write the neatest, most simple code that accomplishes rendering objects in 3D to a 2D screen. Ignoring comments, all the code that was necessary to build this to its current functionality is under 100 lines!
  7 | 
  8 | ---
  9 | 
 10 | ### Installation
 11 | 
 12 | Simply include the source in your application's HTML, no downloading required:
 13 | 
 14 | ```html
 15 | <script src='https://joeiddon.github.io/zengine/zengine.js'></script>
 16 | ```
 17 | 
 18 | or you can use the shorter `git.io` redirect:
 19 | 
 20 | ```html
 21 | <script src='https://git.io/zengine.js'></script>
 22 | ```
 23 | 
 24 | ---
 25 | 
 26 | ### Usage
 27 | 
 28 | The main use of this library is obviously the rendering capabilities. This is covered below. However functions that are required to render are also available for use as part of the library. Some examples of these include: a dot product function, transformation matricies and distance functions. Feel free to use these but at the time of writing, no documentation has been made for them.
 29 | 
 30 | **Prerequisites:**
 31 | 
 32 | - All angles are in **degrees**.
 33 | - All distances are in arbitary units - relative to each other.
 34 | - The coordinate system has the `y-axis` going straight ahead, `x-axis` to the right and `z-axis` going straight up.
 35 | 
 36 | The main function - `zengine.render()` - renders a world from the perspective of a camera to a HTML5 Canvas Element.
 37 | 
 38 | It has the format:
 39 | 
 40 | ```javascript
 41 | zengine.render(world, cam, canvas, wireframe, horizon, light);
 42 | ```
 43 | 
 44 | *Note that `wireframe`, `horizon` and `light` can be set to their default values of: `false`, `Infinity` (not actually because the filtering step is skipped for efficiency) and the camera's point of view's vector by not passing them or through `undefined`*.
 45 | 
 46 | The `world` is described by an array of faces.
 47 | 
 48 | Each face is itself an object with attributes:
 49 | 
 50 | Attribute  | Meaning
 51 | ---------- | -------------------------------------
 52 | `verts`    | array of vertexes as objecs (e.g. `{x: 0, y: 0, z: 0}`)
 53 | `vect`     | the face's unit vector (e.g. `{x: 0, y: 1, z: 0}`)
 54 | `col`      | color - if using shading, an object with attributes `h, s, l` else any CSS string
 55 | 
 56 | This can be summarised by the following general-case format.
 57 | 
 58 | ```javascript
 59 | world = [{verts: [{x: ,y: ,z: }, {x: ,y: ,z: }, ...], vect: {x: ,y: ,z: }, col: }, ...]
 60 | ```
 61 | 
 62 | The `cam` parameter is an object with attributes:
 63 | 
 64 | Attribute     | Meaning
 65 | ------------- | ------------------------------------------
 66 | `x`, `y`, `z` | cooridinate in 3D Cartesian Geometry
 67 | `yaw`         | rotation left to right
 68 | `pitch`       | rotation up and down
 69 | `roll`        | rotation about the "forward" axis
 70 | `fov`         | the, horizontal, field of view, in degrees
 71 | 
 72 | This can be seen in the following general-case format.
 73 | 
 74 | ```javascript
 75 | cam = {x: ,y: ,z: ,yaw: ,pitch: ,roll: ,fov: }
 76 | ```
 77 | 
 78 | The `canvas` parameter should be a HTML Canvas Element Object.
 79 | 
 80 | *Calling this function will blank the canvas before drawing to it.*
 81 | 
 82 | The `wireframe` parameter takes a boolean indicating whether or not to draw just the outlines of each face. This also speeds up the rendering as face ordering is no longer required, and drawing to the Canvas is marginally faster.
 83 | 
 84 | The `horizon` parameter takes a distance, in units relative to the world, for how far you can see. The purpose of this is to speed up rendering. If left `undefined`, defaults to infinity.
 85 | 
 86 | The `light` parameter is an object with attributes:
 87 | 
 88 | Attribute        | Meaning
 89 | -----------------|-------------------------------------------
 90 | `yaw`, `pitch`    | components of a spherical direction vector
 91 | `min_saturation` | minimum saturation percent
 92 | `min_lightness`  | minimum lightness percent
 93 | 
 94 | Where the `min_*` attributes are to be given as decimals in the range `0` to `1`.
 95 | 
 96 | ---
 97 | 
 98 | ### Examples
 99 | 
100 | The [demo folder](https://github.com/joeiddon/zengine/tree/master/demos) contains example code. You can view the code either by cloning this whole repository with
101 | 
102 | ```shell
103 | git clone https://github.com/joeiddon/zengine.git
104 | ```
105 | or just use the GitHub web app.
106 | 
107 | To actually view each example, host locally, or view in GitHub Pages [here](https://joeiddon.github.io/zengine/demos).
108 | 
109 | ---
110 | 
111 | ### Known Bugs
112 | 
113 | Some bugs that need fixing, but I haven't got around to:
114 | 
115 | - Proper face ordering - currently done by distance to face centroids; should be done by casting a ray through the two faces. Or could use a more low level canvas rendering context, like WebGL, in order to implement a simple z-buffer.
116 | - Rotation around the x-axis is not right-hand for some reason - probably a dodgy rotation matrix calculation. Can't easily be flipped as now lots of code relies on it being wrong! Ha!
117 | 
118 | ---
119 | 
120 | ### Uses
121 | 
122 | These are some applications of this library:
123 | 
124 | - [the demos](https://joeiddon.github.io/zengine/demos)
125 | - [maze game](https://joeiddon.github.io/3d_maze_game)
126 | - [apocalombie](https://joeiddon.github.io/apocalombie)
127 | - [blocks](https://joeiddon.github.io/blocks)
128 | 
129 | If you would like to read about these projects more, I have posts on each of them [here on my website](https://joeiddon.github.io/projects/javascript).
130 | 


--------------------------------------------------------------------------------
/demos/README.md:
--------------------------------------------------------------------------------
1 | demos
2 | =====
3 | 
4 | View the result of the above code by following their respective links:
5 | 
6 | - [ball.html](https://joeiddon.github.io/zengine/demos/ball)
7 | - [terrain.html](https://joeiddon.github.io/zengine/demos/terrain)
8 | - [tetrahedron.html](https://joeiddon.github.io/zengine/demos/tetrahedron)
9 | 


--------------------------------------------------------------------------------
/demos/ball.html:
--------------------------------------------------------------------------------
  1 | <html>
  2 | <head>
  3 | <script src='../zengine.js'></script>
  4 | <style>
  5 | html, body {
  6 |     margin: 0;
  7 |     padding: 0;
  8 | }
  9 | 
 10 | #cnvs {
 11 |     background-color: black;
 12 |     cursor: -webkit-grab;
 13 | }
 14 | 
 15 | </style>
 16 | </head>
 17 | <body>
 18 | <canvas id='cnvs'></canvas>
 19 | <script>
 20 | 'use strict';
 21 | 
 22 | /**************
 23 |   VARIABLES
 24 | ***************/
 25 | 
 26 | //retrieve canvas and 2d context
 27 | let cnvs = document.getElementById('cnvs');
 28 | let ctx = cnvs.getContext('2d');
 29 | 
 30 | //array to store ball (sphere) faces
 31 | let ball = [];
 32 | //size of a segment (in radians)
 33 | let seg_rad = Math.PI / 32;
 34 | //general
 35 | let wireframe = false;
 36 | //cam position
 37 | let cam = {x:0, y:-5, z: 0, yaw: 0, pitch: 0, roll: 0, fov: 60};
 38 | //dapening for mapping mouse movement pixel deltas to rotation deltas
 39 | let dapening = 400;
 40 | //tthe light has the normal attributes as well as:
 41 | // - r:   the 2d draggable light circle radius
 42 | // - sf:  the scale factor used when calculatinh the light's angle
 43 | // - x,y: these attributes describe where to render the draggable
 44 | //        circle on the 2d canvas - updated by `light_drag`
 45 | let light = {sf: 2, r: 32, min_saturation: 0, min_lightness: 0.2};
 46 | 
 47 | //resize the canvas to the screen
 48 | function fit_to_screen(){
 49 |     cnvs.width = innerWidth;
 50 |     cnvs.height = innerHeight;
 51 |     //centre the light position
 52 |     light.x = cnvs.width / 4;
 53 |     light.y = cnvs.height / 4;
 54 |     //re-render the ball (as canvas is cleared when resized)
 55 | }
 56 | 
 57 | //returns the 3d cartesian coordinate at yaw, pitch angles on a unit sphee
 58 | function sphere_to_cartesian(y, p){
 59 |     return {x: Math.sin(y) * Math.cos(p),
 60 |             y: Math.cos(y) * Math.cos(p),
 61 |             z: Math.sin(p)};
 62 | }
 63 | 
 64 | //generate the ball's faces
 65 | function init_ball(){
 66 |     for (let y = 0; y < Math.PI * 2; y += seg_rad){
 67 |         for (let p = -Math.PI/2; p < Math.PI/2; p += seg_rad){
 68 |             ball.push({verts: [sphere_to_cartesian(y,        p       ),
 69 |                                sphere_to_cartesian(y,        p + seg_rad),
 70 |                                sphere_to_cartesian(y + seg_rad, p + seg_rad),
 71 |                                sphere_to_cartesian(y + seg_rad, p       )],
 72 |                        vect: sphere_to_cartesian(y + seg_rad/2, p + seg_rad/2),
 73 |                        col: {h: 0, s: 0, l: 100}});
 74 |         }
 75 |     }
 76 | }
 77 | 
 78 | //renders the current ball using zengine.js
 79 | function update(){
 80 |     zengine.render(ball, cam, cnvs, wireframe, Infinity, light);
 81 |     draw_circle(light.x, light.y, light.r);
 82 |     requestAnimationFrame(update)
 83 | }
 84 | 
 85 | 
 86 | /*********
 87 |    START
 88 | **********/
 89 | 
 90 | //create faces of the ball
 91 | init_ball();
 92 | //fit the canvas to screen, and tell the browser to automatically do this when
 93 | //the window is resized
 94 | fit_to_screen();
 95 | window.addEventListener('resize', fit_to_screen);
 96 | //calculate the inital light yaw and pitch angles
 97 | update_light_vect();
 98 | //render first frame
 99 | update();
100 | 
101 | /*******************
102 |     EVENT HANDLERS
103 | ********************/
104 | 
105 | //initialise first mouse press listener
106 | document.addEventListener('mousedown', mouse_down);
107 | 
108 | //when pressed: start listening for button release and for light movements if
109 | //click within the circle else ball movements and stop listening for mouse downs
110 | function mouse_down(e){
111 |     cnvs.style.cursor = '-webkit-grabbing';
112 |     let selected_light = dist({x: e.offsetX, y: e.offsetY}, light) < light.r;
113 |     document.addEventListener('mouseup', mouse_up);
114 |     document.addEventListener('mousemove', selected_light ? light_drag : ball_drag);
115 |     document.removeEventListener('mousedown', mouse_down);
116 | }
117 | 
118 | //on mouse up: stop listening for everything except mouse down
119 | function mouse_up(){
120 |     cnvs.style.cursor = '-webkit-grab';
121 |     document.addEventListener('mousedown', mouse_down);
122 |     document.removeEventListener('mousemove', light_drag);
123 |     document.removeEventListener('mousemove', ball_drag);
124 |     document.removeEventListener('mouseup', mouse_up);
125 | }
126 | 
127 | //handler for dragging of ball
128 | function ball_drag(e){
129 |     let dx = e.movementX / dapening;
130 |     let dy = e.movementY / dapening;
131 |     rotate_ball(dx, -dy);
132 | }
133 | 
134 | //handler for dragging of light
135 | function light_drag(e){
136 |     light.x = e.offsetX;
137 |     light.y = e.offsetY;
138 |     update_light_vect()
139 | }
140 | 
141 | /*****************
142 |  UTILITY FUNCTIONS
143 | *****************/
144 | 
145 | //rotates all the faces currently described by the ball array
146 | //yaw refers to the angle about the z-axis, pitch to the y-axis
147 | function rotate_ball(yaw, pitch){
148 |     ball = ball.map(f=>({verts: f.verts.map(zengine.z_axis_rotate(yaw))
149 |                                        .map(zengine.x_axis_rotate(pitch)),
150 |                          vect: zengine.x_axis_rotate(pitch)(
151 |                                zengine.z_axis_rotate(yaw)(f.vect)),
152 |                          col: f.col}));
153 | }
154 | 
155 | //draws a circle centred at (x,y) with radius r
156 | function draw_circle(x, y, r){
157 |     ctx.strokeStyle = 'white';
158 |     ctx.beginPath();
159 |     ctx.arc(x, y, r, 0, Math.PI * 2);
160 |     ctx.stroke();
161 | }
162 | 
163 | //takes the 2d (x,y) coordinate of the light and calculates the spherical
164 | //(yaw, pitch) coordinate
165 | function update_light_vect(){
166 |     //calculate by taking offset from centre and then scaling by how many
167 |     //pixels there are per degree (fov / width)
168 |     light.yaw = (cnvs.width/2 - light.x) * light.sf * cam.fov / cnvs.width;
169 |     light.pitch = (cnvs.height/2 - light.y) * -light.sf * cam.fov / cnvs.width;
170 | }
171 | 
172 | //returns distance between two 2d coordinates
173 | let dist = (a,b) => ((a.x-b.x)**2+(a.y-b.y)**2)**0.5;
174 | 
175 | </script>
176 | </body>
177 | 


--------------------------------------------------------------------------------
/demos/terrain.html:
--------------------------------------------------------------------------------
  1 | <html>
  2 | <head>
  3 |     <script src='../zengine.js'></script>
  4 |     <script src='https://git.io/perlin.js'></script>
  5 |     <style>
  6 |     body {
  7 |         margin: 0;
  8 |         padding: 0;
  9 |     }
 10 |     #cnvs {
 11 |         background-color: black; 
 12 |         position: fixed;
 13 |         float: top;
 14 |         z-index: -1;
 15 |     }
 16 |     #inpt_cont{
 17 |         padding: 10px;
 18 |         width: 200px;
 19 |     }
 20 |     p {
 21 |         text-align: center;
 22 |         font-family: monospace;
 23 |         margin: 0;
 24 |         color: white;
 25 |     }
 26 |     input {
 27 |         margin: 0;
 28 |         width: 100%;
 29 |     }
 30 |     button {
 31 |         margin: 0;
 32 |         width: 100%;
 33 |     }
 34 |     </style>
 35 | </head>
 36 | 
 37 | <body>
 38 | 
 39 | <!--
 40 |     WARNING:
 41 |     This is *NOT* the best code, in fact it is quite messy and needs
 42 |     tidying. When I last updated it, I was playing with the lights,
 43 |     and didn't get around to tidying the inputs, etc. I will do when 
 44 |     I get the time!
 45 | -->
 46 | 
 47 | <canvas id='cnvs'></canvas>
 48 | <p id='cam'></p>
 49 | <div id='inpt_cont'>
 50 | <!---these inputs are quite messy, but they are easy enough to understand for now (will transfer into the main <script> later)-->
 51 | <p id='p_cells' >hills: 2</p>
 52 | <input min=0 value=2  max=10  type='range' oninput="document.getElementById('p_cells' ).innerText='hills: '       +this.value;cells      =parseInt(this.value);init();"></input>
 53 | <p id='p_width' >width: 32</p>
 54 | <input min=1 value=32 max=100 type='range' oninput="document.getElementById('p_width' ).innerText='width: '       +this.value;grid.width =parseInt(this.value);init();"></input>
 55 | <p id='p_length'>length: 32</p>
 56 | <input min=1 value=32 max=100 type='range' oninput="document.getElementById('p_length').innerText='length: '      +this.value;grid.length=parseInt(this.value);init();"></input>
 57 | <p id='p_height'>hill height: 8</p>
 58 | <input min=0 value=8  max=20  type='range' oninput="document.getElementById('p_height').innerText='hill height: ' +this.value;hill_height=parseInt(this.value);init();"></input>
 59 | <p id='p_speed' >speed: 256</p>
 60 | <input min=0 value=256 max=400 type='range' oninput="document.getElementById('p_speed' ).innerText='speed: '       +this.value;speed      =parseInt(this.value);"></input>
 61 | <p id='p_yaw'  >light yaw speed: 0</p>
 62 | <input min=0   value=0 max=60 type='range' oninput="document.getElementById('p_yaw').innerText   ='light yaw speed: '  +this.value;light.yaw_speed=parseFloat(this.value);"></input>
 63 | <p id='p_pitch'>light pitch speed: 0</p>
 64 | <input min=-90 value=0 max=60 type='range' oninput="document.getElementById('p_pitch' ).innerText='light pitch speed: '+this.value;light.pitch_speed=parseFloat(this.value);"></input>
 65 | <br></br>
 66 | <p id='fps'></p>
 67 | </div>
 68 | 
 69 | <script>
 70 | 'use strict';
 71 | 
 72 | /*** VARIABLES ***/
 73 | 
 74 | //get canvas
 75 | let cnvs = document.getElementById('cnvs');
 76 | 
 77 | //size of grid
 78 | let grid = {width: 32, length: 32};
 79 | //how many perlin cells (across the shortest length of the rectangle)
 80 | let cells = 2
 81 | //how much to scale the output of perlin.js (- ranges from -1 to 1)
 82 | let hill_height = 8;
 83 | //defines millisecond delay between renders (delay = 400 - speed)
 84 | let speed = 256;
 85 | //some initial attrs. for the cam (position defined in fit_to_screen)
 86 | let cam = {yaw: 0,
 87 |            pitch: -30,
 88 |            roll: 0,
 89 |            fov: 80};
 90 | //yaw and pitch angles of the light (in degrees)
 91 | let light = {yaw: 30,
 92 |              pitch: -20,
 93 |              yaw_speed: 0,
 94 |              pitch_speed: 0,
 95 |              min_saturation: 0,
 96 |              min_lightness: 0.2};
 97 | 
 98 | //initialise a global heights array
 99 | let heights;
100 | //variable to store the number of rows we have shifted/scrolled through
101 | let row_shift;
102 | //time (in millis) for next shift
103 | let next_shift_ms;
104 | //array of times (in millis) for fps display
105 | let times = [];
106 | //define faces of light cube
107 | let col = {h: 0, s: 0, l: 100};
108 | let cube = [{verts: [{x:0, y:0, z:0}, {x:0, y:1, z:0}, {x:0, y:1, z:1}, {x:0, y:0, z:1}], col: col, vect: {x:-1, y: 0, z: 0}},
109 |             {verts: [{x:0, y:0, z:0}, {x:1, y:0, z:0}, {x:1, y:0, z:1}, {x:0, y:0, z:1}], col: col, vect: {x: 0, y:-1, z: 0}},
110 |             {verts: [{x:0, y:0, z:0}, {x:1, y:0, z:0}, {x:1, y:1, z:0}, {x:0, y:1, z:0}], col: col, vect: {x: 0, y: 0, z:-1}},
111 |             {verts: [{x:1, y:0, z:0}, {x:1, y:1, z:0}, {x:1, y:1, z:1}, {x:1, y:0, z:1}], col: col, vect: {x: 1, y: 0, z: 0}},
112 |             {verts: [{x:0, y:1, z:0}, {x:1, y:1, z:0}, {x:1, y:1, z:1}, {x:0, y:1, z:1}], col: col, vect: {x: 0, y: 1, z: 0}},
113 |             {verts: [{x:0, y:0, z:1}, {x:1, y:0, z:1}, {x:1, y:1, z:1}, {x:0, y:1, z:1}], col: col, vect: {x: 0, y: 0, z: 1}}];
114 | 
115 | 
116 | /**** START ***/
117 | 
118 | //resize canvas to the size of the screen and init listening for resizes
119 | fit_to_screen();
120 | window.addEventListener('resize', fit_to_screen);
121 | 
122 | //initialise heights and set camera pos
123 | init();
124 | //call first render
125 | requestAnimationFrame(update);
126 | 
127 | //handles the update to the next frame
128 | function update(time){
129 |     if (!next_shift_ms) next_shift_ms = time;
130 |     if (speed && next_shift_ms < time){
131 |         next_shift_ms = time + 400 - speed;
132 |         shift_heights_arr();
133 |     }
134 |     zengine.render(gen_world(), cam, cnvs, false, Infinity, light);
135 |     light.yaw += light.yaw_speed;
136 |     light.pitch += light.pitch_speed;
137 |     update_fps_p(time)
138 |     requestAnimationFrame(update);
139 | }
140 | 
141 | //returns an array of faces (triangles) that follow the surface described by the array of heights
142 | function gen_world(){
143 |     let world = [];
144 |     for (let r = 0; r < grid.length; r++){
145 |         for (let c = 0; c < grid.width; c++){
146 |             //hue is just a scaled version of the height of this triangle for its colour
147 |             let hue = parseInt((heights[r][c] / hill_height) * 360 + 180);
148 |             let hsl = {h: hue, s: 50, l: 40};
149 |             /* format for tile (two triangles):
150 |              *   [2] (c,r+1) *---* (c+1,r+1) [3]
151 |              *               | \ |
152 |              *   [0]   (c,r) *---* (c+1,r)   [1]
153 |              */
154 |             let vs = [{x: c,   y: r,   z: heights[r  ][c  ]},
155 |                       {x: c+1, y: r,   z: heights[r  ][c+1]},
156 |                       {x: c,   y: r+1, z: heights[r+1][c  ]},
157 |                       {x: c+1, y: r+1, z: heights[r+1][c+1]}];
158 |             //gives vector betweent two points
159 |             let vec = (p1, p2) => ({x: p2.x-p1.x, y: p2.y-p1.y, z: p2.z-p1.z});
160 |             world.push(
161 |                 {verts: [vs[0], vs[1], vs[2]],
162 |                  vect: zengine.cross_prod(vec(vs[0],vs[1]), vec(vs[0],vs[2])),
163 |                  col: hsl},
164 |                 {verts: [vs[1], vs[2], vs[3]],
165 |                  vect: zengine.cross_prod(vec(vs[3],vs[2]), vec(vs[3],vs[1])),
166 |                  col: hsl}
167 |             );
168 |         }
169 |     }
170 |     return world;
171 | }
172 | 
173 | //removes first row from heights array and pushes the next one to the end
174 | function shift_heights_arr(){
175 |     heights.shift(1);
176 |     heights.push(get_row(row_shift++));
177 | }
178 | 
179 | //get row using perlin.js lib at index: ind
180 | function get_row(ind){
181 |     let row = [];
182 |     for (let c = 0; c < grid.width + 1; c++){
183 |         row.push(perlin.get(c * (cells/Math.min(grid.width, grid.length)),
184 |                           ind * (cells/Math.min(grid.width, grid.length))) * hill_height);
185 |     }
186 |     return row;
187 | }
188 | 
189 | //initialises heights array using perlin.js lib and resets/centres cam
190 | function init(){
191 |     perlin.seed();
192 |     heights = [];
193 |     for (row_shift = 0; row_shift < grid.length + 1; row_shift++){
194 |         heights.push(get_row(row_shift));
195 |     }
196 |     cam.x = grid.width/2;
197 |     cam.y = -20;
198 |     cam.z = 20;
199 | }
200 | 
201 | //resizes canvas to fill full screen
202 | function fit_to_screen(){
203 |     cnvs.width = innerWidth;
204 |     cnvs.height = innerHeight;
205 | }
206 | 
207 | //updates the frames per second display
208 | function update_fps_p(time){
209 |     times.push(time);
210 |     times = times.filter(t => time - 1000 < t);
211 |     document.getElementById('fps').innerText = 'fps: '+times.length;
212 | }
213 | 
214 | </script>
215 | </body>
216 | </head>
217 | 


--------------------------------------------------------------------------------
/demos/tetrahedron.html:
--------------------------------------------------------------------------------
 1 | <html>
 2 | <head>
 3 | <script src='https://git.io/zengine.js'></script>
 4 | <style>
 5 |     body {
 6 |         margin: 0;
 7 |         padding: 0;
 8 |     }
 9 |     canvas {
10 |         background-color: black;
11 |     }
12 | </style>
13 | </head>
14 | 
15 | <body>
16 | <canvas id='cnvs'></canvas>
17 | <script>
18 | 'use strict';
19 | //get out canvas DOM
20 | let cnvs = document.getElementById('cnvs');
21 | 
22 | //resize the canvas to fill the screen
23 | //if I could be bothered, I'd add a
24 | //'resize' event listener to fill on page resize
25 | cnvs.width = innerWidth;
26 | cnvs.height = innerHeight;
27 | 
28 | //define the verticies of the tetrahedron (the diaganols of a cube ;) )
29 | let verts = [{x: -0.5, y: -0.5, z: -0.5},
30 |              {x:  0.5, y:  0.5, z: -0.5},
31 |              {x: -0.5, y:  0.5, z:  0.5},
32 |              {x:  0.5, y: -0.5, z:  0.5}];
33 | 
34 | //define the tetrahedron's faces (verticies need to be ordered anti-clockwise looking at face
35 | let tetrahedron = [
36 |     {verts: [verts[0], verts[2], verts[1]], col: {h: 0, s: 0, l: 70}},
37 |     {verts: [verts[1], verts[2], verts[3]], col: {h: 0, s: 0, l: 70}},
38 |     {verts: [verts[0], verts[1], verts[3]], col: {h: 0, s: 0, l: 70}},
39 |     {verts: [verts[0], verts[3], verts[2]], col: {h: 0, s: 0, l: 70}},
40 | ];
41 | 
42 | //should we render with wireframe
43 | //(this is my stackoverflow.com profile pic! it actually has thicker `ctx.lineWidth`)
44 | let wireframe = true;
45 | //define our viewpoint
46 | let cam = {x: 0, y: -3, z: 1, yaw: 0, pitch: -18, roll: 0, fov: 70};
47 | //current z-axis rotation angle of 
48 | let angle = 0;
49 | //rotation speed in radians / second
50 | let rot_speed =  0.5;
51 | //global to store the time of the last frame so
52 | //we can calculate a time delta to keep a constant
53 | //rotation speed
54 | let last_time_ms;
55 | 
56 | //init
57 | requestAnimationFrame(update);
58 | 
59 | //this is our main update function to do one render
60 | function update(time){
61 |     //the `if` is necessarry as no `last_time_ms` on first call
62 |     if (last_time_ms){
63 |         //increment our angle by the speed times the time delta (converted to seconds)
64 |         //also mod (`%`) by the angles around a circle
65 |         angle = (angle + rot_speed * (time-last_time_ms) / 1000) % (Math.PI * 2);
66 |     }
67 |     //store the time for the next update
68 |     last_time_ms = time;
69 |     //render the tetragedron; rotated by the right amount (both the verticies and the unit vector need to be rotated)
70 |     zengine.render(tetrahedron.map(f => ({verts: f.verts.map(zengine.z_axis_rotate(angle)),
71 |                                            vect: zengine.z_axis_rotate(angle)(get_unit_vect(f.verts)),
72 |                                             col: f.col})), cam, cnvs);
73 |     //call ourselves for the next frame
74 |     requestAnimationFrame(update);
75 | }
76 | 
77 | //function to get unit vector using right-hand-rule
78 | function get_unit_vect(verts){
79 |     let cp = zengine.cross_prod({x: verts[1].x - verts[0].x, y: verts[1].y - verts[0].y, z: verts[1].z - verts[0].z},
80 |                                 {x: verts[2].x - verts[1].x, y: verts[2].y - verts[1].y, z: verts[2].z - verts[1].z});
81 |     let l = zengine.distance({x: 0, y: 0, z: 0}, cp);
82 |     return {x: cp.x / l, y: cp.y / l, z: cp.z / l};
83 | }
84 | </script>
85 | </body>
86 | </html>
87 | 


--------------------------------------------------------------------------------
/zengine.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  zengine.js - 3D Rendering Software designed to work with the HTML5 Canvas
  3 |  Copyright (c) 2018 Joe Iddon. All right reserved.
  4 | 
  5 |  This library is free software; you are free to redistribute it and/or
  6 |  modify it provided appropriate credit is given to the original author.
  7 | 
  8 |  GitHub Repository (includes README.md w/documentation):
  9 |  https://github.com/joeiddon/zengine
 10 | 
 11 |  Author's website:
 12 |  http://joeiddon.github.io/
 13 | */
 14 | 
 15 | 'use strict';
 16 | 
 17 | let zengine = {
 18 |     render: function(world, cam, canvas, wireframe, horizon, light){
 19 |         let ctx = canvas.getContext('2d');
 20 |         ctx.clearRect(0, 0, canvas.width, canvas.height);
 21 | 
 22 |         //create cartesian unit vector representations from polar light and cam vects
 23 |         let cam_vect = this.polar_to_cart(this.to_rad(cam.yaw), this.to_rad(cam.pitch));
 24 |         let light_vect = light ? this.polar_to_cart(this.to_rad(light.yaw), this.to_rad(light.pitch)) : 0;
 25 | 
 26 |         //temporary inclusion until all current uses are updated to include unit vects
 27 |         let has_vects = world[0].vect != undefined;
 28 | 
 29 |         //add some extra attrs. to each face
 30 |         for (var f = 0; f < world.length; f++){
 31 |             world[f].centr = this.centroid(world[f].verts);
 32 |             world[f].dist = this.distance(cam, world[f].centr);
 33 |             world[f].c_vect = {x: (world[f].centr.x - cam.x) / world[f].dist,
 34 |                                y: (world[f].centr.y - cam.y) / world[f].dist,
 35 |                                z: (world[f].centr.z - cam.z) / world[f].dist};
 36 |         }
 37 | 
 38 |         //only keep faces that are:
 39 |         // - before the horizon
 40 |         // - facing the camera
 41 |         // - have at least one vertex in front of camera.
 42 |         world = world.filter(f =>
 43 |             (!horizon || f.dist < horizon) &&
 44 |             (wireframe || !has_vects || this.dot_prod(f.c_vect, f.vect) < 0) &&
 45 |             f.verts.some(c => this.dot_prod({x: c.x-cam.x,
 46 |                                              y: c.y-cam.y,
 47 |                                              z: c.z-cam.z}, cam_vect) > 0));
 48 | 
 49 |         //order the faces in the world (furthest to closest)
 50 |         if (!wireframe) world.sort((a, b) => b.dist - a.dist);
 51 | 
 52 |         for (let f = 0; f < world.length; f++){
 53 |             //todo: just have more stacked .map calls rather than chunk it
 54 | 
 55 |             //align 3d coordinates to camera view angle
 56 |             let acs = world[f].verts.map(this.translate(-cam.x, -cam.y, -cam.z))
 57 |                                     .map(this.z_axis_rotate(this.to_rad(cam.yaw)))
 58 |                                     .map(this.y_axis_rotate(this.to_rad(cam.roll)))
 59 |                                     .map(this.x_axis_rotate(this.to_rad(cam.pitch)))
 60 |                                     .map(this.translate(cam.x, cam.y, cam.z));
 61 | 
 62 |             //convert the 3d coordinates to yaw, pitch angles from cam center line
 63 |             let cas = acs.map(c => ({y: this.to_deg(Math.atan2(c.x - cam.x, c.y - cam.y)),
 64 |                                      p: this.to_deg(Math.atan2(c.z - cam.z, c.y - cam.y))}));
 65 | 
 66 |             //convert angles to 2d canvas coordinates
 67 |             let cos = cas.map(a => ({x: canvas.width/2  + (a.y * (canvas.width/cam.fov)),
 68 |                                      y: canvas.height/2 - (a.p * (canvas.width/cam.fov))}));
 69 | 
 70 |             //draw the face on the canvas
 71 |             ctx.strokeStyle = wireframe ? 'white' : 'black';
 72 |             ctx.beginPath();
 73 |             ctx.moveTo(cos[0].x, cos[0].y);
 74 |             for (let i = 1; i < cos.length; i++){
 75 |                 ctx.lineTo(cos[i].x, cos[i].y);
 76 |             }
 77 |             ctx.closePath(); ctx.stroke();
 78 |             if (!wireframe){
 79 |                 if (has_vects){
 80 |                     let angle = -this.dot_prod(light_vect || world[f].c_vect /*cam_vect*/, world[f].vect);
 81 |                     if (angle < 0) angle = 0;
 82 |                     let s = world[f].col.s * (light ? (light.min_saturation+ (1 -light.min_saturation) * angle) : angle);
 83 |                     let l = world[f].col.l * (light ? (light.min_lightness + (1 -light.min_lightness ) * angle) : angle);
 84 |                     ctx.fillStyle = 'hsl('+world[f].col.h+','+s+'%,'+l+'%)';
 85 |                 } else {
 86 |                     ctx.fillStyle = world[f].col;
 87 |                 }
 88 |                 ctx.fill();
 89 |             }
 90 |         }
 91 |     },
 92 | 
 93 |     centroid: function(verts){
 94 |         let l = verts.length;
 95 |         let c = {x: 0, y: 0, z: 0};
 96 |         for (let i = 0; i < l; i++)
 97 |         for (let k in c) c[k] += verts[i][k];
 98 |         return {x: c.x/l, y: c.y/l, z: c.z/l};
 99 |     },
100 | 
101 |     translate: (x, y, z) => (v => ({x: v.x + x, y: v.y + y, z: v.z + z})),
102 |     to_deg: (r) => r * (180 / Math.PI),
103 |     to_rad: (d) => d * (Math.PI / 180),
104 |     distance: (c1, c2) => ((c2.x - c1.x)**2 + (c2.y - c1.y)**2 + (c2.z - c1.z)**2) ** 0.5,
105 |     dot_prod: (v1, v2) => v1.x * v2.x + v1.y * v2.y + v1.z * v2.z,
106 |     polar_to_cart: (y, p) => ({x: Math.sin(y) * Math.cos(p),
107 |                                y: Math.cos(y) * Math.cos(p),
108 |                                z: Math.sin(p)}),
109 |     cross_prod: (v1, v2) => ({x: v1.y * v2.z - v1.z * v2.y,
110 |                               y: v1.z * v2.x - v1.x * v2.z,
111 |                               z: v1.x * v2.y - v1.y * v2.x}),
112 |     x_axis_rotate: (r) => (v => ({x:  v.x,
113 |                                   y:  v.y * Math.cos(r) + v.z * Math.sin(r),
114 |                                   z: -v.y * Math.sin(r) + v.z * Math.cos(r)})),
115 |     y_axis_rotate: (r) => (v => ({x:  v.x * Math.cos(r) + v.z * Math.sin(r),
116 |                                   y:  v.y,
117 |                                   z: -v.x * Math.sin(r) + v.z * Math.cos(r)})),
118 |     z_axis_rotate: (r) => (v => ({x:  v.x * Math.cos(r) - v.y * Math.sin(r),
119 |                                   y:  v.x * Math.sin(r) + v.y * Math.cos(r),
120 |                                   z:  v.z}))
121 | };
122 | 


--------------------------------------------------------------------------------