Canvastastic is a Javascript library for rendering 3D scenes, using the canvas element proposed by the WHATWG. Rendering a scene involves the following steps:
<script type="text/javascript" src="canvastastic.js"></script>
<canvas id="my_canvas" width="640" height="480"></canvas>
scene = new CT.Scene("my_canvas");
scene.append(new CT.primitives.Box({}, 0,0,2, 1,1,3)
scene.setCamera([0,0,0], [0,0,1], [0,10,0]);
scene.render();
Creates and returns a new Scene object.
| Name | Default value | Description |
|---|---|---|
| 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. |
Sets the position and orientation of the camera.
Adds the object obj - which may be a Light, a Model or a Transform - to the scene.
Removes the object obj from the scene. This object must have been added via the Scene object's append method.
Outputs the rendered image to the <canvas> element.
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.
Creates and returns a Light object positioned at coordinates (x, y, z).
Moves the light to coordinates (x, y, z).
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.
Creates and returns a new Model with the specified geometry.
| Name | Default value | Description |
|---|---|---|
| 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 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:
Adds the object obj to the transform.
Removes the child object obj from the transform.
The available types of transform are listed below.
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.
Updates the translation offsets in each direction to be x, y and z.
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.
Updates the angle of rotation to be a.
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:
| Name | Colour 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 |
In addition, a helper function to generate other colour functions is available:
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 are pre-defined Models that may be placed in a scene, avoiding the need to build up models at the polygon level.
Generates a cuboid of arbitrary dimensions, with edges parallel to the X, Y and Z axes.
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).