Canvastastic: API documentation

Version: beta_1, 2006-09-11
Matt Westcott (matt@west.co.tt)
  1. Overview
  2. Core interfaces
    1. The Scene object
    2. The Light object
    3. The Model object
    4. Transforms
      1. Translate
      2. RotateX, RotateY, RotateZ
  3. Colours
  4. Primitives
    1. Box
    2. Sphere

Overview

Canvastastic is a Javascript library for rendering 3D scenes, using the canvas element proposed by the WHATWG. Rendering a scene involves the following steps:

Core interfaces

The Scene object

new CT.Scene(canvas [, opts = {}])

Creates and returns a new Scene object.

canvas
The canvas element onto which the scene is to be drawn. If this is a string, it is assumed to be an ID and passed to document.getElementById() before proceeding.
opts
An object containing various fields to control various aspects of how the scene is displayed. Available fields are:
NameDefault valueDescription
viewAngle 1.5 The tangent of the angle covered by the viewport, from extreme left to extreme right; the default of 1.5 is roughly equivalent to 56 degrees. Larger values will produce a 'fish-eye lens' effect.
backgroundColour (or backgroundColor) #000000 The colour of the canvas background, to show through where no objects are present; specified as any valid CSS colour.
hideEdges true If true, causes each polygon to be drawn slightly larger than its correct size. This is a workaround to avoid the edges between adjacent polygons being visible due to anti-aliasing effects, but may result in inaccuracies in the outline of shapes.

setCamera(position, target [, up = [0,1,0] ])

Sets the position and orientation of the camera.

position
The position of the camera within the scene, specified as a 3-element array indicating the [x,y,z] coordinates.
target
The [x,y,z] coordinates of a point which the camera is looking directly at.
up
The [x,y,z] coordinates of a point to be treated as the 'up' direction (that is, the camera will be rolled such that this point is above the midpoint of the viewport).

append(obj)

Adds the object obj - which may be a Light, a Model or a Transform - to the scene.

remove(obj)

Removes the object obj from the scene. This object must have been added via the Scene object's append method.

render()

Outputs the rendered image to the <canvas> element.

The Light object

Lights may be placed at any point in the scene and determine how Models in the scene are to be illuminated; the lights themselves are not visible. A scene may contain any number of lights, but all are treated as having the same intensity.

new CT.Light(x, y, z)

Creates and returns a Light object positioned at coordinates (x, y, z).

setPosition(x, y, z)

Moves the light to coordinates (x, y, z).

The Model object

Models are the visible solid objects in the scene, and consist of a list of polygons. A number of ready-made models are available as primitives, but if you're feeling hardcore enough you can construct them yourself...

Back-face culling is applied to the polygons; that is, they are only visible from one side.

new CT.Model(vertices, normals, polys, opts)

Creates and returns a new Model with the specified geometry.

vertices
An array containing the vertices used in this model, where each vertex is a 3-element array indicating the x, y and z coordinates.
normals
An array containing the surface normals used in this model - that is, normalised vectors which are perpendicular to the surface at some vertex. (Note that a single vertex shared by several polygons may use a different normal for each polygon - for example, the corner of a cube will have one normal for each of the three faces that meet at that corner.) Each normal is given as a 3-element array representing a three-dimensional vector.
polys
An array listing the polygons which make up this model. Each polygon is a triangle, specified as a 6-element array. The first three elements are indexes into the vertices array, indicating the three vertices that are joined to form this triangle; these must be given in anti-clockwise order as viewed from the visible side. The remaining three elements are indexes into the normals array, indicating the surface normals to use at the respective vertices. If the polygon is flat (rather than being used to approximate a curved surface), then all three vertices will use the same normal.
opts
An object containing various fields to control various aspects of how the model is displayed. Available fields are:
NameDefault valueDescription
colour (or color) CT.colour.white A function used to colour the model. See Colour.
ambient 0.2 The ambient lighting level; that is, the base amount of illumination that all surfaces will receive regardless of the effects of positioned lights, where 0 is no light and 1 is the maximum possible intensity.
diffuse 0.8 The diffuse lighting intensity - that is, the intensity of light a surface would receive from a single light illuminating it face-on - given as a fraction of the maximum possible intensity, from 0 to 1.

Transforms

Transforms provide a way for elements of the scene to be built in their own localised coordinate system - if a complex model is made a child of a transform, then it is possible to translate or rotate that model en masse by adjusting the parameters of the transform, avoiding the need to recalculate the position of every point in the model.

Transforms may be chained together, making one transform a child of another to allow greater flexibility in positioning scene elements. In this situation the child transform will operate within the already-transformed coordinate system - for example, a Translate(1,0,0) with a RotateY(Math.PI/4) as a child will have the combined result of rotating about the point (1,0,0) rather than the true origin, whereas a RotateY(Math.PI/4) with a Translate(1,0,0) as a child will cause a translation of one unit in the direction of the rotated X axis - that is, a direction mid-way between the true X and Z axes.

Child objects (Light, Model or Transform) may be added to a transform in the same way as for the top-level Scene object:

append(obj)

Adds the object obj to the transform.

remove(obj)

Removes the child object obj from the transform.

The available types of transform are listed below.

Translate

new CT.Translate(x, y, z)

Creates and returns a new transform which causes any child elements to be translated by x,y and z offsets given by x, y, z.

setPosition(x, y, z)

Updates the translation offsets in each direction to be x, y and z.

RotateX, RotateY, RotateZ

new CT.RotateX(a)

new CT.RotateY(a)

new CT.RotateZ(a)

Creates and returns a new transform which causes any child elements to be rotated about the X, Y or Z axis (respectively) by an angle a, specified in radians.

setRotation(a)

Updates the angle of rotation to be a.

Colours

A colour is defined as a function which takes an intensity value between 0 and 1 (inclusive) as a parameter, and returns a valid CSS colour string. The following colours are defined as standard:

NameColour at maximum intensity
CT.colour.white#ffffff
CT.colour.red#ff0000
CT.colour.green#00ff00
CT.colour.blue#0000ff
CT.colour.yellow#ffff00
CT.colour.magenta#ff00ff
CT.colour.cyan#00ffff
CT.colour.silver#c0c0c0
CT.colour.grey, CT.colour.gray#808080
As with all other occurrences throughout the library, the name color may be used in place of colour.

In addition, a helper function to generate other colour functions is available:

CT.util.makeColour(r, g, b)

Returns a colour function which, at maximum intensity, yields the colour "rgb(r, g, b)".

Users may also choose to define their own colour functions satisfying this general contract; however, be aware that the library uses gradient fills internally to interpolate colours, so functions which vary the colour components in a non-linear way may produce erroneous effects.

Primitives

Primitives are pre-defined Models that may be placed in a scene, avoiding the need to build up models at the polygon level.

Box

new CT.primitives.Box(opts, x0, y0, z0 [, x1, y1, z1 ] )

Generates a cuboid of arbitrary dimensions, with edges parallel to the X, Y and Z axes.

opts
An object containing the display parameters for the box - valid fields are the same as for the Model object.
x0, y0, z0
The coordinates of one corner of the box.
x1, y1, z1
The coordinates of the corner of the box diametrically opposite to (x0, y0, z0); if unspecified, (0, 0, 0) is used.

Sphere

new CT.primitives.Sphere(r, m, n [, opts = {} ] )

Generates an approximation to a sphere, centred on (0, 0, 0). The approximation is formed by placing vertices at equally-spaced latitude and longitude divisions, then joining these with triangles (to form a 'cap' at each pole) and quadrilaterals (covering the remainder of the model - these are subsequently subdivided into triangles).

r
The radius of the sphere.
m
The number of latitude subdivisions to make. (More subdivisions result in a more accurate approximation to a sphere, but take more time to render.)
n
The number of longitude subdivisions to make. (Ditto.)
opts
An object containing the display parameters for the box - valid fields are the same as for the Model object.