Tutorial #2: A Scene and a Cube

Before we begin

This tutorial will demonstrate the basics of using the Canvas 3D JS Libary. Before you begin this tutorial, make sure you have a browser with the canvas 3d addon installed and enabled. Tutorial #1 describes how to do this. Download the canvas 3d JS api. It is recommended that you download the latest release as it will likely contain the latest changes and updates.

Where to put the api

The canvas3d JS API is a javascript library that will make it easier to create and manage 3d content using Canvas 3D.  To use it as part of your website, simply expand the zip file and place the entire folder on your website’s host where the rest of your site’s content sits.  If you wish to try it out locally simply unzip it some place on your local machine.

Your first app

Inside the canvas3d JS API folder, create a javascript file named Main.js with the following code. The explanation of the code can be found later in this tutorial: 
function canvasMain(canvasName){
  var scn = new Scene();
  if(scn.createScene(canvasName)){
    var n= new Cube();
    var cam = new FreeCamera();
    cam.setPosition(new Array(5.0, 0.0, -5.0));
    cam.setLookAtPoint(new Array(-5.0, 0.0, 5.0));
    scn.addObjectToScene(n);
    scn.addCameraToScene(cam);
    scn.startScene();
  }
}
Next, create a web page containing the following code: 
<html>
<head>
<title>Cavas3D test</title>
<script type="application/javascript">var SCRIPT_PATH = ''</script>
<script type="application/javascript" src="C3DAPI.js" ></script>
<script type="application/javascript"  src="Main.js"></script>
</head>
<body onload="canvasMain('canvas');">
<canvas id="canvas" style="border: 2px solid blue" width="500" height="500">
</canvas>
</body>
</html>
Opening the web page from a canvas 3d enabled browser should have the following result:

3D Coordinates

Before we begin to look at the code it is important to look at the 3d coordinate system. open gl is a right handed coordinate system. Some 3d systems are left handed (directX for example). By right handed coordinate system, we mean that the positive x points to the right of the screen, positive y points to the top of the screen and positive z points out of the screen. It is called the right handed system because you can use your right hand to remember which way is positive z.

Code Explanation

//the function that will be called by the web page canvasName is the name
//of the canvas where the scene will show.
function canvasMain(canvasName){
  //create a new Scene object
  var scn = new Scene(); //check that it was successful
  if(scn.createScene(canvasName)){
    //create a cube. by default, this cube is centred at 0,0,0
    var n= new Cube();
    //create a camera
    var cam = new FreeCamera();
    //set the camera position (behind back right corner of cube)
    cam.setPosition(new Array(5.0, 0.0, -5.0));
    // make the camera look at the cube (look towards the front left corner)
    cam.setLookAtPoint(new Array(-5.0, 0.0, 5.0));
    //Add the object to the scene
    scn.addObjectToScene(n);
    //add the camera to the scene
    scn.addCameraToScene(cam);
    //start the scene
    scn.startScene();
  }
}
<html>
<head>
<title>Cavas3D test</title>

<!-- set up the script inside a web page. The next line
  of code is used to set up a search path for the api. For our simple
  project we are putting the html source inside the library directory
  and thus the search path is empty. For more complex projects, you
  may wish to separate the project code into a different directory.
  In that case, the SCRIPT_PATH should be set as a relative directory to
  the api-->
<script type="application/javascript">var SCRIPT_PATH = ''</script>

<!--Load the js library files -->
<script type="application/javascript" src="C3DAPI.js" ></script>

<!--Load our main file. If you called it something else, simply
  substitute your file name here-->
<script type="application/javascript" src="Main.js"></script>

</head>

<!-- when this page's body gets loaded, the canvasMain() function
  from Main.js will get called-->
<body onload="canvasMain('canvas');">

<!-- the actual canvas. Note the id of this canvas is "canvas" which is
  what we are passing to canvasMain()-->
<canvas id="canvas" style="border: 2px solid blue" width="500" height="500">
</canvas>
</body>
</html>