K3D JavaScript Canvas Library/Tutorial
CanvasK3D tutorial
editK3D objects have user definable properties describing the object's relative position from the origin and allowing simple animations that increment one or more of the object's angles or position vector elements over time. There are also properties describing how the object should be rendered by the engine. Playing with these properties is a good way of getting used to how they control the rendering of the object.
Example 1: Minimum simple page set-up and Hello World example K3D object
editThis example show how to set-up a simple HTML5 page with the minimum required to initialise a simple cube as a K3D object on a canvas:
<!DOCTYPE html>
<html>
<head>
<title>K3D - Example 1</title>
<script src="scripts/mathlib.js"></script>
<script src="scripts/k3d_main.js"></script>
<script src="scripts/k3d_controller.js"></script>
<script src="scripts/k3d_object.js"></script>
<script src="scripts/k3d_light.js"></script>
<script src="scripts/k3d_renderer.js"></script>
<script>
// bind to window onload event
window.addEventListener('load', onloadHandler, false);
function onloadHandler()
{
// get the canvas DOM element
var canvas = document.getElementById('canvas');
// bind a K3D Controller object to the canvas
// - it is responsible for managing the K3D objects displayed within it
var k3d = new K3D.Controller(canvas);
// request 60 frames per second animation from the controller
k3d.fps = 60;
// create a K3D object for rendering
var obj = new K3D.K3DObject();
with (obj)
{
color = [255,0,0]; // colour used for wireframe edges and depthcues
drawmode = "wireframe"; // one of "point", "wireframe", "solid"
shademode = "plain"; // one of "plain", "depthcue",
// "lightsource" (solid drawing mode only)
addphi = 1.0; // 1 degree of rotation around Y axis per frame
scale = 50; // make fifty times bigger
init(
// describe the eight points of a simple unit cube
[{x:-1,y:1,z:-1}, {x:1,y:1,z:-1}, {x:1,y:-1,z:-1}, {x:-1,y:-1,z:-1},
{x:-1,y:1,z:1}, {x:1,y:1,z:1}, {x:1,y:-1,z:1}, {x:-1,y:-1,z:1}],
// describe the twelve edges of the cube
[{a:0,b:1}, {a:1,b:2}, {a:2,b:3}, {a:3,b:0}, {a:4,b:5}, {a:5,b:6},
{a:6,b:7}, {a:7,b:4}, {a:0,b:4}, {a:1,b:5}, {a:2,b:6}, {a:3,b:7}],
// describe the six polygon faces of the cube
[{color:[255,0,0],vertices:[0,1,2,3]}, {color:[0,255,0],vertices:[0,4,5,1]},
{color:[0,0,255],vertices:[1,5,6,2]}, {color:[255,255,0],vertices:[2,6,7,3]},
{color:[0,255,255],vertices:[3,7,4,0]}, {color:[255,0,255],vertices:[7,6,5,4]}]
);
}
// add the object to the controller
k3d.addK3DObject(obj);
// begin the rendering and animation immediately
k3d.paused = false;
k3d.frame();
}
</script>
</head>
<body style="background-color: #bfbfbf">
<canvas id="canvas" width="256" height="256"
style="background-color: #ffffff"></canvas>
</body>
</html>
How does it work?
editThe file sets up a basic HTML5 page structure with a single canvas element that K3D will used for rendering output. The K3D JavaScript libraries are imported. The inline JavaScript then gets the canvas DOM element to pass to K3D. A K3D.Controller object is created which is responsible for managing multiple K3D objects and rendering them onto the supplied canvas element. A simple 3D cube is then defined as a K3D.K3DObject, wireframe rendering mode is used. Various public properties are set to initialize the color, scaling (size) and animation properties. Finally the K3D object is added to the controller and the animation is started.
Example 2: Simple page set-up and bouncing light-sourced cube
editThis example builds on Example 1 and this time shows how to display the cube using the light-sourced rendering mode and use the built in simple animation to bounce the cube around a virtual bounding box:
<!DOCTYPE html>
<html>
<head>
<title>K3D - Example 2</title>
<script src="scripts/mathlib.js"></script>
<script src="scripts/k3d_main.js"></script>
<script src="scripts/k3d_controller.js"></script>
<script src="scripts/k3d_object.js"></script>
<script src="scripts/k3d_light.js"></script>
<script src="scripts/k3d_renderer.js"></script>
<script>
// bind to window onload event
window.addEventListener('load', onloadHandler, false);
function onloadHandler()
{
// get the canvas DOM element
var canvas = document.getElementById('canvas');
// bind a K3D Controller object to the canvas
// - it is responsible for managing the K3D objects displayed within it
var k3d = new K3D.Controller(canvas);
// request 60 frames per second animation from the controller
k3d.fps = 60;
// create a K3D object for rendering
var obj = new K3D.K3DObject();
with (obj)
{
color = [255,0,0]; // colour used for wireframe edges and depthcued rendering mode
drawmode = "solid"; // one of "point", "wireframe", "solid"
shademode = "lightsource"; // one of "plain", "depthcue", "lightsource" (solid mode only)
addtheta = addgamma = 1.0; // set rotation animation
scale = 25;
velx = 0.5; vely = velz = 1; // give the object some velocity in the 3 axes
// create a virtual "bounding box" within which the object will automatically bounce around
// the engine reverses the velocity of the axis when the mid point touches the edge of the box
bminx = bminy = bminz = -50;
bmaxx = bmaxy = bmaxz = 50;
init(
// describe the points of a simple unit cube
[{x:-1,y:1,z:-1}, {x:1,y:1,z:-1}, {x:1,y:-1,z:-1}, {x:-1,y:-1,z:-1},
{x:-1,y:1,z:1}, {x:1,y:1,z:1}, {x:1,y:-1,z:1}, {x:-1,y:-1,z:1}],
// describe the edges of the cube
[{a:0,b:1}, {a:1,b:2}, {a:2,b:3}, {a:3,b:0}, {a:4,b:5}, {a:5,b:6},
{a:6,b:7}, {a:7,b:4}, {a:0,b:4}, {a:1,b:5}, {a:2,b:6}, {a:3,b:7}],
// describe the polygon faces of the cube
[{color:[255,0,0],vertices:[0,1,2,3]},{color:[0,255,0],vertices:[0,4,5,1]},
{color:[0,0,255],vertices:[1,5,6,2]},{color:[255,255,0],vertices:[2,6,7,3]},
{color:[0,255,255],vertices:[3,7,4,0]},{color:[255,0,255],vertices:[7,6,5,4]}]
);
}
// add the object to the controller
k3d.addK3DObject(obj);
// begin the rendering and animation immediately
k3d.paused = false;
k3d.frame();
}
</script>
</head>
<body style="background-color: #bfbfbf">
<canvas id="canvas" width="256" height="256" style="background-color: #ffffff"></canvas>
</body>
</html>
How does it work?
editAs above in example 1, however this time drawmode = "solid" and shademode = "lightsource" are used to display the cube as solid polygons with default light-sourcing. In addition a virtual bouncing box is defined for the object, in which K3D uses to provide a simple animation of the cube bouncing around.
Example 3: Simple page set-up and texture mapped cube
editThis example builds on Example 2 and this time shows how to apply a texture to each side of the cube:
<!DOCTYPE html>
<html>
<head>
<title>K3D - Example 3</title>
<script src="scripts/mathlib.js"></script>
<script src="scripts/k3d_main.js"></script>
<script src="scripts/k3d_controller.js"></script>
<script src="scripts/k3d_object.js"></script>
<script src="scripts/k3d_light.js"></script>
<script src="scripts/k3d_renderer.js"></script>
<script>
// bind to window onload event
window.addEventListener('load', onloadHandler, false);
var bitmaps = [];
function onloadHandler()
{
// get the images loading
bitmaps.push(new Image());
var loader = new Preloader();
loader.addImage(bitmaps[0], 'images/texture5.png');
loader.onLoadCallback(init);
}
function init()
{
// get the canvas DOM element
var canvas = document.getElementById('canvas');
// bind a K3D Controller object to the canvas
// - it is responsible for managing the K3D objects displayed within it
var k3d = new K3D.Controller(canvas);
// request 60 frames per second animation from the controller
k3d.fps = 60;
// create a K3D object for rendering
var obj = new K3D.K3DObject();
obj.textures.push(bitmaps[0]);
with (obj)
{
drawmode = "solid"; // one of "point", "wireframe", "solid"
shademode = "lightsource"; // one of "plain", "depthcue", "lightsource" (solid drawing mode only)
addtheta = addgamma = 1.0;
scale = 65;
init(
// describe the points of a simple unit cube
[{x:-1,y:1,z:-1}, {x:1,y:1,z:-1}, {x:1,y:-1,z:-1}, {x:-1,y:-1,z:-1}, {x:-1,y:1,z:1}, {x:1,y:1,z:1}, {x:1,y:-1,z:1}, {x:-1,y:-1,z:1}],
// describe the edges of the cube
[{a:0,b:1}, {a:1,b:2}, {a:2,b:3}, {a:3,b:0}, {a:4,b:5}, {a:5,b:6}, {a:6,b:7}, {a:7,b:4}, {a:0,b:4}, {a:1,b:5}, {a:2,b:6}, {a:3,b:7}],
// describe the polygon faces of the cube
[{color:[255,0,0],vertices:[0,1,2,3],texture:0},{color:[0,255,0],vertices:[0,4,5,1],texture:0},{color:[0,0,255],vertices:[1,5,6,2],texture:0},{color:[255,255,0],vertices:[2,6,7,3],texture:0},{color:[0,255,255],vertices:[3,7,4,0],texture:0},{color:[255,0,255],vertices:[7,6,5,4],texture:0}]
);
}
// add the object to the controller
k3d.addK3DObject(obj);
// begin the rendering and animation immediately
k3d.paused = false;
k3d.frame();
}
</script>
</head>
<body style="background-color: #bfbfbf">
<canvas id="canvas" width="256" height="256" style="background-color: #ffffff"></canvas>
</body>
</html>
How does it work?
editAs above in example 2, however this time a texture image is loaded using the Preloader helper class. Once the image is loaded it is applied on each face of the cube object. K3D then texture maps the cube when rendered.
More advanced examples
editPlease study the files k3d_test.html along with scripts/k3ddemos.js and ultralight.html along with scripts/ultralight.js. Changing some of the parameters in the .js files and observing the results might be most useful. Using a JavaScript debugger (e.g. Firebug for Firefox, WebKit Inspector) may be useful once you have covered the basics of the library and how it works.