-
-
Initializes a scene.
-
-
Allocates memory for a scene, `nedge' and `npoly' are your estimates of how many edges and how many polygons you will render (you cannot get over the limit specified here).
Parameters:
Name |
Type |
Description |
nedge |
number
|
max number of edges. |
npoly |
number
|
max number of polygons. |
-
inner CrossProduct(x1, y1, z1, x2, y2, z2) → {Array.<number>}
-
Calculates the cross product (x1, y1, z1) x (x2, y2, z2).
The cross product is perpendicular to both of the input vectors, so it can be used to generate polygon normals.
Parameters:
Name |
Type |
Description |
x1 |
*
|
x value or first vector as array. |
y1 |
*
|
y value or second vector as array. |
z1 |
number
|
z value. |
x2 |
number
|
x value. |
y2 |
number
|
y value. |
z2 |
number
|
z value. |
Returns:
Array.<number>
- a new vector.
-
-
Deallocate memory previously allocated by CreateScene. Use this to avoid memory leaks in your program.
-
inner DotProduct(x1, y1, z1, x2, y2, z2) → {number}
-
Calculates the dot product (x1, y1, z1) . (x2, y2, z2), returning the result.
Parameters:
Name |
Type |
Description |
x1 |
*
|
x value or first vector as array. |
y1 |
*
|
y value or second vector as array. |
z1 |
number
|
z value. |
x2 |
number
|
x value. |
y2 |
number
|
y value. |
z2 |
number
|
z value. |
Returns:
number
- dot product.
-
inner GetAlignMatrix(xfront, yfront, zfront, xup, yup, zup)
-
Rotates a matrix so that it is aligned along the specified coordinate vectors (they need not be normalized or perpendicular, but the up and front must not be equal).
A front vector of 0,0,-1 and up vector of 0,1,0 will return the identity matrix.
Parameters:
Name |
Type |
Description |
xfront |
number
|
|
yfront |
number
|
|
zfront |
number
|
|
xup |
number
|
|
yup |
number
|
|
zup |
number
|
|
-
inner GetCameraMatrix(x, y, z, xfront, yfront, zfront, xup, yup, zup, fov, aspect) → {Matrix}
-
Constructs a camera matrix for translating world-space objects into a normalised view space, ready for the perspective projection.
The x, y, and z parameters specify the camera position, xfront, yfront, and zfront are the 'in front' vector specifying which way the camera is facing (this can be any length: normalisation is not required), and xup, yup, and zup are the 'up' direction vector.
The fov parameter specifies the field of view (ie. width of the camera focus) in radians.
For typical projections, a field of view in the region 32-48 will work well. 64 (90°) applies no extra scaling - so something which is one unit away from the viewer will be directly scaled to the viewport.
A bigger FOV moves you closer to the viewing plane, so more objects will appear. A smaller FOV moves you away from the viewing plane, which means you see a smaller part of the world.
Finally, the aspect ratio is used to scale the Y dimensions of the image relative to the X axis, so you can use it to adjust the proportions of the output image (set it to 1 for no scaling - but keep in mind that the projection also performs scaling according to the viewport size).
Typically, you will pass (float)w/(float)h, where w and h are the parameters you passed to set_projection_viewport.
Parameters:
Name |
Type |
Description |
x |
number
|
x camera position. |
y |
number
|
y camera position. |
z |
number
|
y camera position. |
xfront |
number
|
x camera facing. |
yfront |
number
|
y camera facing. |
zfront |
number
|
z camera facing. |
xup |
number
|
x of 'up direction'. |
yup |
number
|
y of 'up direction'. |
zup |
number
|
z of 'up direction'. |
fov |
number
|
field of view in radians. |
aspect |
number
|
aspect ratio. |
-
-
Use to create an empty matrix.
Returns:
- an empty matrix and empty translation
Matrix.
-
-
Return the identity matrix the 'do nothing' identity matrix. Multiplying by the identity matrix has no effect.
-
-
Constructs a scaling matrix. When applied to the point (px, py, pz), this matrix will produce the point (px*x, py*y, pz*z).
In other words, it stretches or shrinks things.
Parameters:
Name |
Type |
Description |
x |
*
|
x value or a vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
-
-
Constructs a translation matrix. When applied to the point (px, py, pz), this matrix will produce the point (px+x, py+y, pz+z).
In other words, it moves things sideways.
Parameters:
Name |
Type |
Description |
x |
*
|
x value or a vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
-
inner GetVectorRotationMatrix(x, y, z, a)
-
Constructs a transformation matrix which will rotate points around the specified x,y,z vector by the specified angle (given in radians).
Parameters:
Name |
Type |
Description |
x |
*
|
x value or a vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
a |
number
|
rotation value. |
-
inner NApplyMatrix(m, x, y, z) → {Array.<number>}
-
Multiplies the point (x, y, z) by the transformation matrix m.
Parameters:
Name |
Type |
Description |
m |
Matrix
|
the matrix |
x |
*
|
x value or vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
Returns:
Array.<number>
- a new vector.
-
-
Constructs a transformation matrix which will rotate points around all three axes by the specified amounts (given in radians).
The direction of rotation can simply be found out with the right-hand rule: Point the dumb of your right hand towards the origin along the axis of rotation, and the fingers will curl in the positive direction of rotation.
E.g. if you rotate around the y axis, and look at the scene from above, a positive angle will rotate in clockwise direction.
Parameters:
Name |
Type |
Description |
x |
*
|
x value or a vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
-
-
Constructs a transformation matrix which will rotate points around all three axes by the specified amounts (given in radians), scale the result by the specified amount (pass 1 for no change of scale), and then translate to the requested x, y, z position.
Parameters:
Name |
Type |
Description |
scale |
number
|
scaling value. |
xrot |
number
|
x-rotation value. |
yrot |
number
|
y-rotation value. |
zrot |
number
|
z-rotation value. |
x |
number
|
x value. |
y |
number
|
y value. |
z |
number
|
y value. |
-
-
Construct X axis rotation matrices. When applied to a point, these matrices will rotate it about the X axis by the specified angle (given in radians).
Parameters:
Name |
Type |
Description |
r |
number
|
rotation in radians. |
-
-
Construct Y axis rotation matrices. When applied to a point, these matrices will rotate it about the Y axis by the specified angle (given in radians).
Parameters:
Name |
Type |
Description |
r |
number
|
rotation in radians. |
-
-
Construct Z axis rotation matrices. When applied to a point, these matrices will rotate it about the Z axis by the specified angle (given in radians).
Parameters:
Name |
Type |
Description |
r |
number
|
rotation in radians. |
-
-
Multiplies two matrices.
The resulting matrix will have the same effect as the combination of m1 and m2, ie. when applied to a point p, (p * out) = ((p * m1) * m2).
Any number of transformations can be concatenated in this way.
Note that matrix multiplication is not commutative, ie. matrix_mul(m1, m2) != matrix_mul(m2, m1).
-
inner NormalizeVector(x, y, z) → {Array.<number>}
-
Converts the vector (x, y, z) to a unit vector.
This points in the same direction as the original vector, but has a length of one.
Parameters:
Name |
Type |
Description |
x |
*
|
x value or vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
Returns:
Array.<number>
- a new vector.
-
inner NPolygonZNormal(v1, v2, v3) → {number}
-
Finds the Z component of the normal vector to the specified three vertices (which must be part of a convex polygon).
This is used mainly in back-face culling. The back-faces of closed polyhedra are never visible to the viewer, therefore they never need to be drawn.
This can cull on average half the polygons from a scene.
If the normal is negative the polygon can safely be culled. If it is zero, the polygon is perpendicular to the screen.
However, this method of culling back-faces must only be used once the X and Y coordinates have been projected into screen space using PerspProject() (or if an orthographic (isometric) projection is being used).
Note that this function will fail if the three vertices are co-linear (they lie on the same line) in 3D space.
Parameters:
Name |
Type |
Description |
v1 |
Array.<number>
|
first vector. |
v2 |
Array.<number>
|
second vector. |
v3 |
Array.<number>
|
third vector. |
Returns:
number
- z component.
-
-
Optimised routine for scaling an already generated matrix: this simply adds in the scale factor, so there is no need to build two temporary matrices and then multiply them together.
Parameters:
Name |
Type |
Description |
m |
number
|
a Matrix. |
scale |
number
|
scale factor |
-
-
Optimised routine for translating an already generated matrix: this simply adds in the translation offset, so there is no need to build two temporary matrices and then multiply them together.
Parameters:
Name |
Type |
Description |
m |
number
|
a Matrix. |
x |
number
|
x-offset or a vector as array. |
y |
number
|
y-offset. |
z |
number
|
z-offset. |
-
-
Renders all the specified ScenePolygon3D()'s on the current bitmap. Rendering is done one scanline at a time, with no pixel being processed more than once.
Note that between ClearScene() and RenderScene() you shouldn't change the clip rectangle of the destination bitmap. For speed reasons, you should set the clip rectangle to the minimum.
-
inner ScenePolygon3D(type, texture, vtx)
-
Puts a polygon in the rendering list. Nothing is really rendered at this moment. Should be called between ClearScene() and RenderScene().
Arguments are the same as for Polygon3D().
Unlike Polygon3D(), the polygon may be concave or self-intersecting. Shapes that penetrate one another may look OK, but they are not really handled by this code.
Parameters:
Name |
Type |
Description |
type |
*
|
|
texture |
*
|
|
vtx |
*
|
|
-
-
Sets the viewport used to scale the output of the PerspProject() function.
Pass the dimensions of the screen area you want to draw onto, which will typically be 0, 0, SizeX(), and SizeY().
Also don't forget to pass an appropriate aspect ratio to GetCameraMatrix() later.
The width and height you specify here will determine how big your viewport is in 3d space.
So if an object in your 3D space is w units wide, it will fill the complete screen when you run into it (i.e., if it has a distance of 1.0 after the camera matrix was applied.
The fov and aspect-ratio parameters to get_camera_matrix also apply some scaling though, so this isn't always completely true).
If you pass -1/-1/2/2 as parameters, no extra scaling will be performed by the projection.
-
-
Calculates the length of the vector (x, y, z), using that good 'ole Pythagoras theorem.
Parameters:
Name |
Type |
Description |
x |
*
|
x value or vector as array. |
y |
number
|
y value. |
z |
number
|
y value. |
Returns:
number
- vector length.