content: the HTML file | the XML file | the javascript | demo/download
A basic scene
Most GLGE scenes need three things: an HTML file, some javascript, and an XML file. You’ll also need to download GLGE.
I’m going to walk through setting up a simple scene with a flat triangle and a lighting source.
Lets start with the HTML file.
The HTML file
The HTML file does what you’d expect by setting up the basic structure of the web page. If you’re reading this tutorial you should have a solid grasp of HTML. Inside the body there is a canvas element with a width, height, and id, a script referencing GLGE and a place for our javascript.
<html>
<head>
<title>GLGE Demo</title>
</head>
<body>
<canvas id="canvas" width="400" height="300"></canvas>
<script type="text/javascript" src="/assets/js/lib/glge-compiled-min.js"></script>
<script type="text/javascript">
<!-- javascript goes here -->
</script>
</body>
</html>
And that’s it.
The XML file
The XML file defines the scene, lighting, cameras, and any objects. The very outside structure is this…
<?xml version="1.0"?>
<glge>
</glge>
Above is a bare GLGE document, which needs, at minimum, the following…
- At least one
<mesh>composed of…<positions>,<normals>,<uv1>and<faces>,
- At least one
<material>, - A
<camera>and - A
<scene>composed of…- At least one
<object> - Optional
<light>s.
- At least one
Mesh
A <mesh> is what defines an object’s shape. Meshes can be generated by 3rd party software, or can be created by hand, as shown in this example. The simplest object defined by a mesh is a flat triangle, the building block for any object. The <mesh> behind a flat triangle is very simple.
It has four components, <positions>, <normals>, <uv1>, and <faces>. <positions> define corners in 3D space. In the syntax I prefer to use, each line defines x, y and z coordinates of one corner. The <normals> define the perpendicular direction from the surface, which plays into how lighting is computed. In the syntax I use, each line defines x, y and z coordinates of one normal of a corner. The <uv1> defines how an (image) texture is applied to the object. The triangle we’re creating is a solid color, so a <uv1> is not strictly necessary. In my syntax, each line is an x and y coordinate on the flat triangle. The last part, the <faces>, define how each point is used. The renderer draws the 0th point first (position -1, 1, 0; normal 0, 0, 1; and uv1 0, 0) then moves to the 1st and so on.
<mesh id="triangle">
<positions>
-1, 1, 0,
-1, -1, 0,
1, -1, 0
</positions>
<normals>
0, 0, 1,
0, 0, 1,
0, 0, 1
</normals>
<uv1>
0, 0,
1, 0,
1, 1
</uv1>
<faces>
0, 1, 2
</faces>
</mesh>
Material
If the XML document only contained a mesh, we still wouldn’t see anything. It’s just the definition of an object, not the object itself. The next thing needed is a <material>. A <material> defines an image or color to apply to the object and how lighting affects it.
The simple <material> defined in my example has three parts. An id to identify the element, a specular shine value (think reflection), and a color. The specular value is a value from 0 to 1. The color can be a hexadecimal or rgb value.
<material id="triangleMat" specular="1" color="#aaa" />
Camera
Now we have the shape of an object and what it will look like defined. Next we need to create a <camera> to see it from.
The <camera> is composed of an id and the values for it’s location and angle. The location is defined by the attributes loc_x, loc_y, and loc_z. The rotation is defined by the attributes rot_x, rot_y, and rot_z in units of radians. In my example, I don’t need location or rotation attributes because they are at the origin, 0, the default. A default camera is at point 0, 0, 0 and is looking straight down.
<camera id="mainCamera" loc_x="0" loc_y="0" loc_z="0" rot_x="0" rot_y="0" rot_z="0" />
/* same as */
<camera id="mainCamera" />
Scene
Now we have an object and our frame of viewing reference. Next we can start setting up a scene, comprised of an id, a reference to the <camera> we set up and ambient lighting, defined by a color.
<scene id="mainScene" camera="#mainCamera" ambient_color="#fff">
</scene>
Inside our scene we can add <object>s and <light>s. My simple example has one <object> and one <light>, but the <light>’s is not necessary to see the object.
Object
The <object> has an id, a reference to the <mesh> set up earlier, location attributes (the same syntax as for the camera), rotation attributes, and scale attributes (scale_x, scale_y and scale_z). Again, the location and rotation attributes default to 0. The scale attributes default to 1. In my example, I’ve moved my triangle down (z axis) by 4 units so it’s not at the same location as the <camera>.
<object id="triangle" mesh="#triangle" material="#triangleMat" loc_x="0" loc_y="0" loc_z="-4" rot_x="0" rot_y="0" rot_z="0" scale_x="1" scale_y="1" scale_z="1" />
/* same as */
<object id="triangle" mesh="#triangle" material="#triangleMat" loc_z="-4" />
Light
Now we have a functioning scene that will work if we were to render it! But… I want to make it look a bit more three dimentional (we are using WebGL). So I’ll add a <light>. The light has an id, location, rotation, a color, and a type. Location and rotation are the same as <object>s and <camera>s. The type that I’m using is L_POINT for point lighting. A point light has a location and faces a certain direction.
<light id="mainlight" loc_x="10" loc_y="15" loc_z="10" rot_x="-1.3" color="#fff" type="L_POINT" />
Done!
So, that’s it for this basic GLGE XML document. Here’s it is in full.
<?xml version="1.0"?>
<glge>
<mesh id="triangle">
<positions>
-1, 1, 0,
-1, -1, 0,
1, -1, 0
</positions>
<normals>
0, 0, 1,
0, 0, 1,
0, 0, 1
</normals>
<uv1>
0, 0,
1, 0,
1, 1
</uv1>
<faces>
0, 1, 2
</faces>
</mesh>
<material id="triangleMat" specular="1" color="#aaa" />
<camera id="mainCamera" />
<scene id="mainScene" camera="#mainCamera" ambient_color="#fff">
<object id="triangle" mesh="#triangle" material="#triangleMat" loc_z="-4" />
<light id="mainlight" loc_x="10" loc_y="15" loc_z="10" rot_x="-1.3" color="#fff" type="L_POINT" />
</scene>
</glge>
The javascript
The javascript is pretty important. It sets up a GLGE environment, fetches all the data in the XML file, and renders it as a 3D scene. For this example, it’s pretty simple because there’s no action, movement or controls.
First, we need to get our canvas element.
var canvasElement = document.getElementById("canvas");
Then we create the GLGE environment.
var doc = new GLGE.Document();
Next we will load the XML file into the GLGE document.
doc.load("path/to/demo_xml.xml");
Now we set up a function to run once the XML file is loaded.
doc.onLoad = function() {
}
Inside this function we will create a renderer and scene.
var renderer = new GLGE.Renderer(canvasElement);
var scene = new GLGE.Scene();
Then we bind the scene in the javascript with the scene from the XML file.
scene = doc.getElement("mainScene");
Then we bind the renderer to the scene.
renderer.setScene(scene);
And finally, we render everything.
renderer.render();
Done!
Here’s all the javascript.
var canvasElement = document.getElementById("canvas");
var doc = new GLGE.Document();
doc.load("triangle.xml");
doc.onLoad = function() {
var renderer = new GLGE.Renderer(canvasElement);
var scene = new GLGE.Scene();
scene = doc.getElement("mainScene");
renderer.setScene(scene);
renderer.render();
}
Here it is – update, glge isn’t supported any more
This is the scene described above.