igloo is a simple but powerful 3D library that you can use to create stunning experiences. igloo was originally written in JavaScript (using Jasic) to run on top of WebGL. We later ported the JavaScript code to C++ and included it as a built-in high performance 3D library for all Jasic developers. We intend to offer the source code for the original script implementation as a way to learn about the internals of igloo. (The scripting version is called gloo.js). In igloo, the visible world is represented as a scene. The scene is the root container for all sorts of objects such as mesh (geometry), lights, camera, and an overlay HUD. We have included a number of igloo samples in the Jasic samples folder and encourage you to read them for more details. The Jasic tutorial series also includes additional examples of using igloo.
Example
g = require("igloo");
root = new View("ipad-landscape");
root.setBackgroundColor(0,0,0,1);
v = root.createGlView(0,0,root.width,root.height);
v.setBackgroundColor(0,0,0,1);
gl = v.getContext();
main = g.scene(gl,root.width,root.height, function(s) {
t = s.triangle()
t.translation(-1.5,0,-7)
t.color(0.7,0.1,0.4);
t = s.triangle();
t.translation(1,1,-13);
t.scale(0.3,0.1,0.3);
t.color(s.green);
triangle = s.triangle();
triangle.translation(3,2,-10);
triangle.rotation(0,Math.PI/4,0);
square = s.quad();
square.translation(-5,2,-15);
square.rotation(0,0,0);
square.texture(s,"earth1.jpg");
t = s.pyramid();
t.translation(3,-2,-15);
t.color(s.red);
cube = s.cube();
cube.translation(8,2,-18);
cube.rotation(0,0,0);
cube.texture(s,"jasic.png");
});
function tick() {
triangle.rotate(0,0.1,0);
triangle.translate(0.01,0,0);
square.rotate(0.1,0,0);
cube.rotate(0.05,0.05,0.05);
main.draw();
}
window.requestAnimationFrame(tick);
document.wait();
object require("igloo")
This is the main mechanism to obtain an igloo object. You can then use this object to create one or more scenes.
igloo Methods
object scene(gl,width,height,constructor)
Create a new scene with a given GL context (see GLView class summary). Width and height typically match these used to create the WebGL view. The constructor function is passed the scene object and called more efficiently than creating objects in the scene outside of the scene construction.
Scene Methods
object camera()
Create a new camera to use in the scene and return it. If there is an existing camera, it's deleted.
void blending(boolean)
If blending is on, then depth testing is disabled and alpha blending is enabled. If blending is off, then depth testing is enabled and alpha blending is disabled. This controls the default setting for the entire scene. Individual mesh objects can override the default (see Mesh Class Summary)
void enablePicking()
This enables the scene to support object picking (selection). igloo uses an offscreen buffer and unique color coding of each mesh into the offscreen buffer to provide an efficient object selection mechanism.
object lines(count,thickness,color)
Create a line buffer with a given number of lines, the line thickness, and line color. The line buffer (lines object) contains an array of lines in 3D space. The line buffer is added to the scene.
object triangle()
Create a unit triangle mesh and add it to the scene.
object sphere(lats,longs,rad)
Create a sphere mesh with a number of horizontal (lats) and vertical (longs) subdivision and radius. The sphere is added to the scene.
object sprite(poses,frames)
A sprite is a quad mesh that is given a texture. The texture is divided into rows, one for each pose and columns one for each frame. The sprite is added to the scene and returned. Please make sure to set a texture on the sprite (using the texture method in mesh below)
object label(count,charWidth,charHeight[,parent])
A label is used to display a single text given a fixed width font as a texture. The count is the total number of characters in the label. The character width and height are given in units based on whether the label is in 3D space (a child of the scene) or 2D space (a child of the HUD). The parent if given allows the label to be a child of another object and inherit its transforms (location, scale, rotation).
object model(file[,scale[,parent]])
A JSON file is parsed and a 3D model is produced based on the file. The JSON object must contain a root object that contains the following properties: vertexPositions: a continuous array of x,y,z values. vertexNormals, vertexTextureCoords, and indices. The scale is used to rescale the model and the optional parent allows the model to be a child of the scene or another mesh object in the scene.
object objModel(file[,scale[,parent]])
Load a 3D OBJ file and return a 3D mesh object. The optional parent is handled the same way as model() above.
object quad([parent])
Quads are one of the most used objects in igloo. They represent a rectangle that can be placed in 3D (scene) or 2D (HUD) space. The quad can be given a texture. The optional parent controls if the quad is a child of the scene (null) or any other object in it (such as another mesh or the HUD)
void clearColor(red,green,blue)
Sets the background color for the scene.
object pyramid()
Create a pyramid mesh and return it.
object cube()
Create a unit cube mesh and return it.
object texture(file [,quality])
Load a texture object from a file. This texture is now "scene global" and can be shared across many mesh objects. The texture is deleted when the scene is deleted. Examples of shared textures are font textures used for labels or other images shared between mesh objects. igloo supports non power of two textures and any image format supported by iOS and Cocoa. The optional quality parameter allows control over texture filtering quality. The default quality is high, passing false for the third quality parameter will reduce texture filtering quality and improve rendering performance.
object ambient([r,g,b])
Create and set an ambient light in the scene with optional red, green, and blue color. Once an ambient light is created, it impacts the color of all objects in the scene uniformly. The ambient color can be changed later (see AmbientLight Methods). Only one ambient light is allowed in the scene.
object directional()
Create and set a directional light objtect. Once created, the directional light can be given a color and direction (see DirectionalLight Methods below). The light impacts all objects based on the angle of intersection of the light and the mesh object.. Only one directional light is allowed in the scene.
object pointLight()
Create and set point light. Once created, the point light can be given a position and color. The point light impacts the color of objects depending on their distance to the light and their position relative to it. Only one point light is allowed in the scene.
void update()
This is an important method that must be called on the scene if camera objects are used and if framerate calculations are required. Otherwise, it's safe to simply call draw in cases where no cameras are used.
void draw(wireframe)
Render the scene to the view. If wireframe rendering is required, pass true to the wireframe argument.
number pickDraw(x,y[,noDepthTest])
Return the index of a given mesh given the screen x and y coordinates. This is typically used to select objects in 3D space and is only supported if the scene has picking enabled. The index returned can be passed to the find method on the scene or individual mesh objects to find the picked mesh within them. The optional noDepthTest flag is used to perform pick draw of all meshes in order without performing depth testing. This would guarentee that objects rendered last will always be picked ahead of other objects regardless of Z position.
void addMesh(mesh)
Add a mesh as a child of the scene. This is not typically used since mesh objects are always added to the scene during their construction unless a parent mesh is provided.
void add(constructor)
Pass a function object that is called back with the scene as the only argument. The function can then create multiple objects in the scene more efficiently than creating them outside of the constructor.
object find(index)
Find an object in the scene (or mesh) given its index. null is returned if the object is not found.
number fps()
Return the current estimated frames per second in the scene. Update must be always called on each frame draw for this to be accurate. Please also note that debugging and setting breakpoints inside the render / tick function can dramatically impact the reported rate.
object elapsed()
Return the amount of time elapsed in milliseconds since the last time update was called on the scene.
object cam()
Return the current scene camera object. Please note that this is different than the camera() method which creates and sets the camera.
number width()
Return the scene width.
number height()
Return the scene height
void enableHud()
Enable the HUD. Once enabled, the hud() method can be used to return the HUD which can then be used as a parent for any mesh objects that need to be rendered in 2D space (camera facing orthographic projection).
object hud()
Return the current hud() object. enableHud() must have been called for hud to be valid.
void moveToFront(mesh)
Move child mesh to front. This means it will render last
void moveToBack(mesh)
Move child mesh to back. This means it will render first
void removeChild(mesh)
Remove child mesh from from the scene
Mesh Methods
void addChild(mesh)
Add another mesh as a child of this mesh. Care must be used to avoid the same child being a parent of multiple parent mesh objects. Typically, the parent is given during creation of a mesh and as a result, this method is not typically called.
void removeChild(mesh)
Remove a child mesh from a parent.
void rotation(x,y,z)
Set the absolute rotation of the mesh around the x,y, and z axis
void rotate(x,y,z)
Set the relative rotation of the mesh around the x,y, and z axis
void getRotation(index)
Return the x (index 0), y (index 1), or z (index 2) orientation of an object.
void translation(x,y,z)
Set the absolute position of the object in 3D space. igloo follows right handed scene orientation with positive z values pointing towards the camera.
void translate(x,y,z)
Set the relative position of the object in 3D space. igloo follows right handed scene orientation with positive z values pointing towards the camera.
void getTranslation(index)
Return the x (index 0), y (index 1), or z (index 2) position of an object.
void scale(x,y,z)
Set the absolute scale of an object on its x, y, or z axis. Scale is typically used to control the dimensions of unit objects such as quads, cubes, ..etc.
void color(r,g,b,a)
Set the color for a given mesh object. The color will be used if the object is un-textured. But the color also multiplies with the texture sampler colors. The default color is white.
void picking(boolean)
Controls whether a mesh participates in scene picking (pickDraw) or not. It is possible for a parent mesh to have picking disabled but its children to have it enabled.
void visibility(boolean)
Controls whether the object is visible or not. If an object is invisible all of its children are also not rendered.
void texture(texture | scene,file [,quality])
If a texture object is passed (it must have been created by the scene), its used to texture this mesh. Otherwise, a texture is created exclusively for this mesh and will be destroyed when the mesh is deleted. The optional quality parameter allows control over texture filtering quality. The default quality is high, passing false for the third quality parameter will reduce texture filtering quality and improve rendering performance.
object clone()
Create an return a clone of this mesh. The clone shares the same geometry buffers (vertex, texture, normals, indices) as this mesh and has a copy of all of this object transforms (translation, rotation, scale). The clone can then be transformed independently of this mesh.
void blending(boolean)
Controls whether the mesh participates in z (depth) testing (blending disabled) or alpha blending (blending enabled). The default is false and z testing is used.
void genWireframe()
Generate wireframe line buffers for this mesh. If the scene is then rendered with the wireframe argument set to true, this mesh will render its wireframe after it renders its geometry.
void alpha(a)
Control the transparency of the object in the scene. This is only effective if aha blending is enabled.
string name([string])
Gve the mesh a name. If the method is called with no arguments, the name is returned. Note: mesh objects are sealed so user methods and properties cannot be added to them. A a result, you can use the name to map the object to other related structures in your program.
void moveToFront(mesh)
Move child mesh to front. This means it will render last
void moveToBack(mesh)
Move child mesh to back. This means it will render first
AmbientLight Methods
void color(r,g,b)
Set the color for an ambient light.
DirectionalLight Methods
void color(r,g,b)
Set the color for a directional light.
void direction(x,y,z)
Set the direction for a directional light.
PointLight Methods
void color(r,g,b)
Set the color for a point light.
void position(x,y,z)
Set the position of a point light.
HUD Methods
void addChild(mesh)
Add a mesh s a child to the HUD. Typically this is not used, rather the hud() method is used to have the HUD be set as the parent of a mesh during the mesh creation in the scene.
Camera Methods
void position(x,y,z)
Place the camera in 3D space
void turn(pitchRate,yawRate)
Control the automatic pitch rate and yaw rate of the camera. Pitch is the rotation of the camera around the x axis (effectively looking up and down). Yaw is the to ration of the camera around the y axis (looking left and right). Once set, the pitch and yaw rates cause camera transformation if the scene's update method is called.
number speed([number])
If called with no arguments, this returns the current speed of the camera. If a number is passed, it is used as the speed value. Speed causes the camera to automatically move forward or backward along the z axis. Of course for this to happen, the scene update method must be called.
number yawRate([number])
If called with no arguments, returns the current yaw rate for the camera. Otherwise, the number passed is used to set the yaw rate for the camera. See the turn method.
number pitchRate([number])
If called with no arguments, returns the current pitch rate for the camera. Otherwise, the number is used to set thence rate. We the turn method.
number positionX([number])
Set or get the camera x axis position.
number positionY([number])
Set or get the camera y position.
number positionZ([number])
Set or get the camera z position.
Lines Methods
void add(x1,y1,z1,x2,y2,z2)
Add a line represented by two points to the lines object.
void set(index,x1,y1,z1,x2,y2,z2)
Set the start and end position for a line with a given index in the lines object. The indices start at 0 for the first line.
void clear()
Remove all lines from the line buffer. New lines can added again using the add method. This method can be used to allow shrinking a line buffer by removing all lines and adding the ones that are needed to be kept.
Label Methods
void text(string)
Set the text for a label. If the text is longer than the lowed character count (when the label was created), it is truncated.
Sprite Methods
void set(pose,frame)
Set the current pose and frame for a sprite
number frame([number])
Set or get current frame for a sprite
number pose([number])
Set or get current pose for a sprite.
number frames()
Return the number of frames for the sprite.
number poses()
Return the number of poses for the sprite.
Texture Methods
number width()
Return the width of a texture.
number height()
Return the height of a texture.