3d

Methods

inner ApplyMatrix(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.

inner Clip3D(type, min_z, max_z, v) → {Array.<V3D>}

Clips the polygon given in `v'. The frustum (viewing volume) is defined by -z<x<z, -z<y<z, 0<min_z<z<max_z. If max_z<=min_z, the z<max_z clipping is not done. As you can see, clipping is done in the camera space, with perspective in mind, so this routine should be called after you apply the camera matrix, but before the perspective projection. The routine will correctly interpolate u, v, and c in the vertex structure. However, no provision is made for high/truecolor GCOL.
Parameters:
Name Type Description
type POLYTYPE one of POLYTYPE.
min_z number minimum z value.
max_z number maximum z value.
v Array.<V3D> an array of vertices.
Returns:
Array.<V3D> - an array of vertices.

inner GetRotationMatrix(x, y, z)

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.
Returns:
- a Matrix.

inner GetTransformationMatrix(scale, xrot, yrot, zrot, x, y, z)

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.
Returns:
- a Matrix.

inner GetXRotateMatrix(r)

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.
Returns:
- a Matrix.

inner GetYRotateMatrix(r)

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.
Returns:
- a Matrix.

inner GetZRotateMatrix(r)

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.
Returns:
- a Matrix.

inner MatrixMul(m1, m2)

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).
Parameters:
Name Type Description
m1 Matrix first Matrix.
m2 Matrix second Matrix.
Returns:
- a new Matrix.

inner PerspProject(x, y, z)

Projects the 3d point (x, y, z) into 2d screen space and using the scaling parameters previously set by calling SetProjectionViewport(). This function projects from the normalized viewing pyramid, which has a camera at the origin and facing along the positive z axis. The x axis runs left/right, y runs up/down, and z increases with depth into the screen. The camera has a 90 degree field of view, ie. points on the planes x=z and -x=z will map onto the left and right edges of the screen, and the planes y=z and -y=z map to the top and bottom of the screen. If you want a different field of view or camera location, you should transform all your objects with an appropriate viewing matrix, eg. to get the effect of panning the camera 10 degrees to the left, rotate all your objects 10 degrees to the right.
Parameters:
Name Type Description
x * x value or vector as array.
y number y value.
z number y value.

inner Polygon3D(type, texture, v)

Draw 3d polygons using the specified rendering mode. Unlike the regular polygon() function, these routines don't support concave or self-intersecting shapes. The width and height of the texture bitmap must be powers of two, but can be different, eg. a 64x16 texture is fine How the vertex data is used depends on the rendering mode:

The `x' and `y' values specify the position of the vertex in 2d screen coordinates.

The `z' value is only required when doing perspective correct texture mapping, and specifies the depth of the point in 3d world coordinates.

The `u' and `v' coordinates are only required when doing texture mapping, and specify a point on the texture plane to be mapped on to this vertex. The texture plane is an infinite plane with the texture bitmap tiled across it. Each vertex in the polygon has a corresponding vertex on the texture plane, and the image of the resulting polygon in the texture plane will be mapped on to the polygon on the screen.

We refer to pixels in the texture plane as texels. Each texel is a block, not just a point, and whole numbers for u and v refer to the top-left corner of a texel. This has a few implications. If you want to draw a rectangular polygon and map a texture sized 32x32 on to it, you would use the texture coordinates (0,0), (0,32), (32,32) and (32,0), assuming the vertices are specified in anticlockwise order. The texture will then be mapped perfectly on to the polygon. However, note that when we set u=32, the last column of texels seen on the screen is the one at u=31, and the same goes for v. This is because the coordinates refer to the top-left corner of the texels. In effect, texture coordinates at the right and bottom on the texture plane are exclusive.

There is another interesting point here. If you have two polygons side by side sharing two vertices (like the two parts of folded piece of cardboard), and you want to map a texture across them seamlessly, the values of u and v on the vertices at the join will be the same for both polygons. For example, if they are both rectangular, one polygon may use (0,0), (0,32), (32,32) and (32,0), and the other may use (32,0), (32,32), (64,32), (64,0). This would create a seamless join. Of course you can specify fractional numbers for u and v to indicate a point part-way across a texel. In addition, since the texture plane is infinite, you can specify larger values than the size of the texture. This can be used to tile the texture several times across the polygon.
Parameters:
Name Type Description
type POLYTYPE one of POLYTYPE.
texture Bitmap texture Bitmap.
v Array.<V3D> an array of vertices.

inner PolygonZNormal(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.

inner Quad3D(type, texture, v1, v2, v3, v4)

Draw 3d quads using vertex.
Parameters:
Name Type Description
type POLYTYPE one of POLYTYPE.
texture Bitmap texture Bitmap.
v1 V3D a vertex.
v2 V3D a vertex.
v3 V3D a vertex.
v4 V3D a vertex.

inner SetSceneGap(gap)

This number (default value = 100.0) controls the behaviour of the z-sorting algorithm. When an edge is very close to another's polygon plane, there is an interval of uncertainty in which you cannot tell which object is visible (which z is smaller). This is due to cumulative numerical errors for edges that have undergone a lot of transformations and interpolations.
The default value means that if the 1/z values (in projected space) differ by only 1/100 (one percent), they are considered to be equal and the x-slopes of the planes are used to find out which plane is getting closer when we move to the right.
Larger values means narrower margins, and increasing the chance of missing true adjacent edges/planes. Smaller values means larger margins, and increasing the chance of mistaking close polygons for adjacent ones. The value of 100 is close to the optimum. However, the optimum shifts slightly with resolution, and may be application-dependent. It is here for you to fine-tune.
Parameters:
Name Type Description
gap number gap value.

inner Triangle3D(type, texture, v1, v2, v3)

Draw 3d triangles, using vertices.
Parameters:
Name Type Description
type POLYTYPE one of POLYTYPE.
texture Bitmap texture Bitmap.
v1 V3D a vertex.
v2 V3D a vertex.
v3 V3D a vertex.