Hello, in this first tutorial we will download Voxelent and use it to create a simple 3D scene.

Prologue

Voxelent is built around WebGL. You can check if your browser supports WebGL by visiting this link: http://get.webgl.org/

If you are working with Google Chrome, make sure you set it up before runing this tutorial.

Downloading Voxelent

1. From the main menu, go to downloads

2. Select the most recent version to download. Click on the download link using the secondary button of your mouse and select the option save as.

3. You will be presented with a file dialog, which can be different depending on your browser and operative system. Select the location where you want to download the library and click on OK or Save.

Creating a simple scene

Next, we will create a demo scene. For this demo we will use one of the many 3D model that are packed with Voxelent. You will find them in the GitHub repository under /demos/assets.

1. From GitHub download the cone.json asset and save it in the same folder where you downloaded Voxelent.

To save individual files from GitHub make sure you click on the “raw’ button and then use the Save As… option in your browser.

Saving individual files from GitHub

Saving individual files from GitHub (click to maximize)

2. Copy and paste this code in a new text file and save it as tutorial-1.html.

<html>
<head>
<title>Hello 3D World!</title>
<script src="http://code.jquery.com/jquery-1.7.2.min.js" type="text/javascript"></script>
<script type='text/javascript' src='voxelent_v0.89.4.js'></script>

<script type='text/javascript'>
var view;
function runVoxApp(){
    view = vxl.api.setup('view-1');
    vxl.api.load('cone.json');
    view.start();
    view.cameraman.active.setPosition([0,0,8])
}
</script>
</head>
<body onload='runVoxApp()'>
    <canvas id ='view-1' width=800 height=600>
    </canvas>
</body>
</html>

Please notice that:

  • Voxelent requires JQuery.
  • the runVoxApp function is linked to the onload event of your webpage otherwise the app will not run when you load your webpage.
  • In this example uses the unminified Voxelent version. Voxelent is also available in a minified format. Check downloads.
  • Use the appropriate version number depending on the file that you downloaded.

3. Now open tutorial-1.html in your  browser. You should see a screen like this:

 

4. You can rotate the cone by clicking and dragging. You can also zoom in an out using Ctrl + mouse dragging (Command + mouse dragging for mac users). You can pan the camera left or

Code review

In this section we are going to examine the code that we wrote.

Adding JQuery and Voxelent to your page

<script src="http://code.jquery.com/jquery-1.7.2.min.js" type="text/javascript"></script>
<script type='text/javascript' src='voxelent_v0.89.4.js'></script>

Creating an HTML5 canvas

A page with a <canvas> element. The canvas code in your page should be similar to this:

<canvas id = 'view-1' width='800' height='600'>
<p>Sorry! Your browser does not support WebGL</p>
</canvas>

Writing a 3D application in 5 lines of code

function runVoxApp(){
    var view = vxl.api.setup('view-1');
    vxl.api.load('cone.json');
    view.start();
    vxl.c.camera.setPosition([0,0,8]);
}

vxl.api.setup: sets up an HTML5 canvas element to be used as a View. This function returns a reference to the View object.

vxl.api.load: this function downloads the model passed as a string parameter and adds it to the current Scene.

vxl.c.camera.setPosition(0,0,8):it obtains a reference to the current camera and sets its position to x=0, y=0, z=8.

That was easy! Next, let’s talk about the public API.