Voxelent contains a rich set of classes to develop 3D web applications. To speed up and simplify the construction of Voxelent Apps, we have included a public API.

Simpler code in less time

As in any other library, it will take you a bit of time to learn and master Voxelent’s class hierarchy. This is one of the reasons why we find the public API so useful. It ireduces the learning time that many developers find discouraging when facing a new library.

Also, the public API contains many common operations that otherwise you would have to write by yourself. Using the public API means that the code that you write will be simpler, easier to debug and easier to maintain.

Example: setting up a view

Let’s take for instance a view setup:

If you were going to set up an HTML5 canvas to run a WebGL application you would have to:

1. Locate the canvas object using the Document Object Model tree
2. Obtain a WebGL context using canvas.getContext()
3. Make sure that  the context is available everywhere in your code where it can be needed
4. Control the error scenarios where the canvas does not exist or the WebGL context cannot be obtained

In Voxelent many of these steps occur inside the vxlView object. The vxlView object represents each canvas in a Voxelent Application. Using the public API we just need to do one call to setup a view like this:

function mySetUp(){
     vxl.api.setup('view-id'); //setting up a view
}

Example: shared views

Now, we could have the case where the same scene is being shared among multiple canvases. Think for example of a graphic design application where a 3D model is being represented using the superior, frontal and lateral view. In this case we are looking at the same scene through three different views. In Voxelent we represent a scene using the vxlScene object. Such as in the previous example, a vxlScene object can be shared by multiple vxlViews.

If you wanted to model an application such as the previous one, you would have to write your own objects which would completely take your programming efforts away from the your specific domain problem. You would be writing infrastructure code.

In the case where the view you want to setup needs to be connected to a pre-existing Voxelent scene you would write something like this:

var scene; //contains the Voxelent scene
function mySetUp(scene){
     vxl.api.setup('view-id',scene);
}

In the two previous cases (setting up a view and sharing a view) we have assumed that a canvas with id=’view-id’ exist somewhere in the page body:

<body onload='runVoxApp()'>
    <canvas id ='view-1' width=800 height=600>
    </canvas>
</body>

Good separation of concerns

One of the Voxelent design guidelines is to make sure that there is a good separation of concerns. This means, that the objects in the architecture are cohesive and their set of responsibilities is well defined. However following a separation of concerns approach means that you will have to navigate through the class hierarchy to achieve different tasks. This is another scenario where the public API can be helpful.

Example: accessing the current camera

For instance, if we wanted to get access to the current camera we would have to do something like this:

var view; //object of type vxlView
var camera  = view.cameraman.getCurrentCamera();

whereas using the public API one can access the current camera through the current namespace like this:

var camera  = vxl.c.camera;

Voxelent Namespaces

Voxelent class hierarchy is grouped in 4 main namespaces: vxl.api (public API), vxl.c (current objects), vxl.go (global objects), and vxl.def (definition/defaults). Let’s talk a bit about them.

vxl.api: public functions

All the functions of the public API reside in the vxl.api namespace.

In the Quick Start tutorial, you used two of these functions: vxl.api.setup to setup your view, and vxl.api.load to load the cone model.

In general, the public API contains functions to manipulate:

  • Views
  • Scenes
  • Actors
  • Cameras
  • Lookup Tables
  • Assets

There are three other namespaces that are used along with vxl.api:

  • vxl.c : current objects
  • vxl.go : global objects
  • vxl.def: definition/default objects

vxl.c: current objects

Voxelent supplies shorcuts to access objects that are considered the current (or active) ones using the vxl.c namespace. We have:

  • vxl.c.view : current view
  • vxl.c.scene: current scene
  • vxl.c.camera : current camera
  • vxl.c.scene: current scene

vxl.go: global objects

Along with the API, Voxelent provides the vxl.go namespace for global objects. These are objects that can be called from any context in your Voxelent application. Some of them are:

Object Type Description
vxl.go.notifier vxlNotifier Allows many-to-many event subscriptions. Any object can register with the notifier to receive updates of when Voxelent events happen. More about this mechanism in a subsequent tutorial 😉
vxl.go.modelManager vxlModelManager Responsible for loading models from the sever and delivering them to scenes.
vxl.go.lookupTableManager vxlLookupTableManager  Loads the list of lookup tables defined by the variable vxl.def.lut.tables
vxl.go.console(message, overrrideFlag) function Access the browser console to write a message. By default, many of Voxelent’s objects will write in the console when vxl.go.debug is set to True.
vxl.go.consolerequires two parameters:

  • message [String] : the message to be displayed
  • overrideFlag [Boolean]: This parameter is optional, if set to true, writes on the console even if vxl.go.debug is set to False.

 

vxl.def: definitions/defaults

These objects provide many of the default behaviours and configurations that Voxelent offers. The  vxl.def namespace contains all of them. Some of them are:

Object Type Description
vxl.def.view.background Array  The view’s background colour that will be used if no other colour has been specified.
vxl.def.actor.mode Array The type of representation that an Actor can have.Valid options are:
vxl.def.actor.mode.SOLID
vxl.def.actor.mode.WIREFRAME
vxl.def.actor.mode.POINTS
vxl.def.camera.type Array Camera types.Valid options are:
vxl.def.camera.mode.ORBITING
vxl.def.camera.mode.TRACKING

Using the public API interactively

Let’s see how we can use Voxelent’s public API interactively from the web browser JavaScript console.

Depending on your browser, the option to open the console will appear in a different menu:

Browser Menu Option Accelerator Key (Windows/Mac)
Firefox Tools > Web Developer > Web Console Ctr+Shift+K / Command+Alt+K
Safari Develop > Show Web Inspector Ctrl+Shift+C / Command+Alt+C
Chrome Tools > JavaScript Console Ctr+Shift+J / Command + Alt+J

Using the API let’s visualize the bounding box for this scene. The bounding box is a wireframe cube that encloses all the objects in your scene.

Let’s try it!

1. Load tutorial-1.html.
2. Open the JavaScript console using the respective menu option or accelerator keys.
3. write vxl.api.boundingBoxON(). You will notice as you type that the auto-complete feature for the JavaScript console gets into action.
4. Hit enter.
5. The bounding box appears. Rotate the cone so you can see its bounding box from different positions.

6. Experiment with other functions from the public API.

You can find the complete list of functions covered by the public API at
https://voxelent.com/html/docs/symbols/vxl.api.html