- apply_matrix — Multiplies a point by a transformation matrix.
- apply_matrix_f — Multiplies a point by a transformation matrix.
- cross_product — Calculates the cross product.
- cross_product_f — Calculates the cross product.
- dot_product — Calculates the dot product.
- dot_product_f — Calculates the dot product.
- get_align_matrix — Rotates a matrix to align it along specified coordinate vectors.
- get_align_matrix_f — Floating point version of get_align_matrix().
- get_camera_matrix — Constructs a camera matrix for perspective projection.
- get_camera_matrix_f — Floating point version of get_camera_matrix().
- get_rotation_matrix — Constructs X, Y, Z rotation matrices.
- get_rotation_matrix_f — Constructs X, Y, Z rotation matrices.
- get_scaling_matrix — Constructs a scaling matrix.
- get_scaling_matrix_f — Constructs a scaling matrix.
- get_transformation_matrix — Constructs X, Y, Z rotation matrices with an angle and scaling.
- get_transformation_matrix_f — Floating point version of get_transformation_matrix().
- get_translation_matrix — Constructs a translation matrix.
- get_translation_matrix_f — Constructs a translation matrix.
- get_vector_rotation_matrix — Constructs X, Y, Z rotation matrices with an angle.
- get_vector_rotation_matrix_f — Constructs X, Y, Z rotation matrices with an angle.
- get_x_rotate_matrix — Construct X axis rotation matrices.
- get_x_rotate_matrix_f — Construct X axis rotation matrices.
- get_y_rotate_matrix — Construct Y axis rotation matrices.
- get_y_rotate_matrix_f — Construct Y axis rotation matrices.
- get_z_rotate_matrix — Construct Z axis rotation matrices.
- get_z_rotate_matrix_f — Construct Z axis rotation matrices.
- identity_matrix — Global containing the identity matrix.
- identity_matrix_f — Global containing the identity matrix.
- matrix_mul — Multiplies two matrices.
- matrix_mul_f — Multiplies two matrices.
- normalize_vector — Converts the vector to a unit vector.
- normalize_vector_f — Converts the vector to a unit vector.
- persp_project — Projects a 3d point into 2d screen space.
- persp_project_f — Projects a 3d point into 2d screen space.
- polygon_z_normal — Finds the Z component of the normal vector to three vertices.
- polygon_z_normal_f — Finds the Z component of the normal vector to three vertices.
- qscale_matrix — Optimised routine for scaling an already generated matrix.
- qscale_matrix_f — Optimised routine for scaling an already generated matrix.
- qtranslate_matrix — Optimised routine for translating an already generated matrix.
- qtranslate_matrix_f — Optimised routine for translating an already generated matrix.
- set_projection_viewport — Sets the viewport used to scale the output of persp_project().
- vector_length — Calculates the length of a vector.
- vector_length_f — Calculates the length of a vector.

Allegro contains some 3d helper functions for manipulating vectors, constructing and using transformation matrices, and doing perspective projections from 3d space onto the screen. It is not, and never will be, a fully fledged 3d library (the goal is to supply generic support routines, not shrink-wrapped graphics code :-) but these functions may be useful for developing your own 3d code.

Allegro uses a right-handed coordinate system, i.e. if you point the thumb of your right hand along the x axis, and the index finger along the y axis, your middle finger points in the direction of the z axis.

Allegro's world coordinate system typically has the positive x axis right, the positive y axis up, and the positive z axis out of the screen. What all this means is this: Assume, the viewer is located at the origin (0/0/0) in world space, looks along the negative z axis (0/0/-1), and is oriented so up is along the positive y axis (0/1/0). Then something located at (100/200/-300) will be 100 to the right, 200 above, and 300 in front of the viewer. Just like in OpenGL. (Of course, both OpenGL and Allegro allow to use a different system.) Here's a short piece of code demonstrating the transformation pipeline of a point from world space to the screen.

/* First, set up the projection viewport. */ set_projection_viewport (0, 0, SCREEN_W, SCREEN_H); /* Next, get a camera matrix, depending on the * current viewer position and orientation. */ get_camera_matrix_f (&m, 0, 0, 0, /* Viewer position, in this case, 0/0/0. */ 0, 0, -1, /* Viewer direction, in this case along negative z. */ 0, 1, 0, /* Up vector, in this case positive y. */ 32, /* The FOV, here 45°. */ (float)SCREEN_W / (float)SCREEN_H)); /* Aspect ratio. */ /* Applying the matrix transforms the point 100/200/-300 * from world space into camera space. The transformation * moves and rotates the point so it is relative to the * camera, scales it according to the FOV and aspect * parameters, and also flips up and front direction - * ready to project the point to the viewport. */ apply_matrix_f (&m, 100, 200, -300, &x, &y, &z); /* Finally, the point is projected from * camera space to the screen. */ persp_project_f (cx, cy, cz, &sx, &sy);

For more details, look at the function descriptions of set_projection_viewport(), get_camera_matrix(), and persp_project(), as well as the relevant example programs.

All the 3d math functions are available in two versions: one which uses fixed point arithmetic, and another which uses floating point. The syntax for these is identical, but the floating point functions and structures are postfixed with '_f', eg. the fixed point function cross_product() has a floating point equivalent cross_product_f(). If you are programming in C++, Allegro also overloads these functions for use with the 'fix' class.

3d transformations are accomplished by the use of a modelling matrix. This is a 4x4 array of numbers that can be multiplied with a 3d point to produce a different 3d point. By putting the right values into the matrix, it can be made to do various operations like translation, rotation, and scaling. The clever bit is that you can multiply two matrices together to produce a third matrix, and this will have the same effect on points as applying the original two matrices one after the other. For example, if you have one matrix that rotates a point and another that shifts it sideways, you can combine them to produce a matrix that will do the rotation and the shift in a single step. You can build up extremely complex transformations in this way, while only ever having to multiply each point by a single matrix.

Allegro actually cheats in the way it implements the matrix structure. Rotation and scaling of a 3d point can be done with a simple 3x3 matrix, but in order to translate it and project it onto the screen, the matrix must be extended to 4x4, and the point extended into 4d space by the addition of an extra coordinate, w=1. This is a bad thing in terms of efficiency, but fortunately an optimisation is possible. Given the 4x4 matrix:

a pattern can be observed in which parts of it do what. The top left 3x3 grid implements rotation and scaling. The three values in the top right column (d, h, and l) implement translation, and as long as the matrix is only used for affine transformations, m, n and o will always be zero and p will always be 1. If you don't know what affine means, read Foley & Van Damme: basically it covers scaling, translation, and rotation, but not projection. Since Allegro uses a separate function for projection, the matrix functions only need to support affine transformations, which means that there is no need to store the bottom row of the matrix. Allegro implicitly assumes that it contains (0,0,0,1), and optimises the matrix manipulation functions accordingly. Read chapter "Structures and types defined by Allegro" for an internal view of the MATRIX/_f structures.( a, b, c, d ) ( e, f, g, h ) ( i, j, k, l ) ( m, n, o, p )

Global variables containing the 'do nothing' identity matrix. Multiplying by the identity matrix has no effect.

Constructs a translation matrix, storing it in m. 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.

apply_matrix, get_transformation_matrix, qtranslate_matrix.See also:

exstars.Examples using this:

Constructs a scaling matrix, storing it in m. 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.

apply_matrix, get_transformation_matrix, qscale_matrix.See also:

Construct X axis rotation matrices, storing them in m. When applied to a point, these matrices will rotate it about the X axis by the specified angle (given in binary, 256 degrees to a circle format).

apply_matrix, get_rotation_matrix, get_y_rotate_matrix, get_z_rotate_matrix.See also:

Construct Y axis rotation matrices, storing them in m. When applied to a point, these matrices will rotate it about the Y axis by the specified angle (given in binary, 256 degrees to a circle format).

apply_matrix, get_rotation_matrix, get_x_rotate_matrix, get_z_rotate_matrix.See also:

Construct Z axis rotation matrices, storing them in m. When applied to a point, these matrices will rotate it about the Z axis by the specified angle (given in binary, 256 degrees to a circle format).

apply_matrix, get_rotation_matrix, get_x_rotate_matrix, get_y_rotate_matrix.See also:

Constructs a transformation matrix which will rotate points around all three axes by the specified amounts (given in binary, 256 degrees to a circle format). 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.

apply_matrix, get_transformation_matrix, get_vector_rotation_matrix, get_x_rotate_matrix, get_y_rotate_matrix, get_z_rotate_matrix, get_align_matrix.See also:

ex12bit, exquat, exstars.Examples using this:

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.

apply_matrix, get_camera_matrix.See also:

Floating point version of get_align_matrix().

get_align_matrix.See also:

Constructs a transformation matrix which will rotate points around the specified x,y,z vector by the specified angle (given in binary, 256 degrees to a circle format).

apply_matrix, get_rotation_matrix, get_align_matrix.See also:

excamera.Examples using this:

Constructs a transformation matrix which will rotate points around all three axes by the specified amounts (given in binary, 256 degrees to a circle format), scale the result by the specified amount (pass 1 for no change of scale), and then translate to the requested x, y, z position.

apply_matrix, get_rotation_matrix, get_scaling_matrix, get_translation_matrix.See also:

ex3d, exstars.Examples using this:

Floating point version of get_transformation_matrix().

get_transformation_matrix.See also:

exzbuf.Examples using this:

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 binary, 256 degrees to the circle format. 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.

Note that versions prior to 4.1.0 multiplied this aspect ratio by 4/3.

apply_matrix, get_align_matrix, set_projection_viewport, persp_project.See also:

Floating point version of get_camera_matrix().

get_camera_matrix.See also:

excamera, exquat.Examples using this:

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.

get_translation_matrix.See also:

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.

get_scaling_matrix.See also:

Multiplies two matrices, storing the result in out (this may be a duplicate of one of the input matrices, but it is faster when the inputs and output are all different). 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).

apply_matrix.See also:

exquat, exscn3d.Examples using this:

Calculates the length of the vector (x, y, z), using that good 'ole Pythagoras theorem.

normalize_vector.See also:

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.

vector_length, dot_product, cross_product.See also:

exstars.Examples using this:

Calculates the dot product (x1, y1, z1) . (x2, y2, z2), returning the result.

cross_product, normalize_vector.See also:

exstars.Examples using this:

Calculates the cross product (x1, y1, z1) x (x2, y2, z2), storing the result in (*xout, *yout, *zout). The cross product is perpendicular to both of the input vectors, so it can be used to generate polygon normals.

dot_product, polygon_z_normal, normalize_vector.See also:

exstars.Examples using this:

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 persp_project() (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.

cross_product.See also:

ex3d.Examples using this:

Multiplies the point (x, y, z) by the transformation matrix m, storing the result in (*xout, *yout, *zout).

matrix_mul.See also:

ex12bit, ex3d, exstars.Examples using this:

Sets the viewport used to scale the output of the persp_project() function. Pass the dimensions of the screen area you want to draw onto, which will typically be 0, 0, SCREEN_W, and SCREEN_H. Also don't forget to pass an appropriate aspect ratio to get_camera_matrix 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.

persp_project, get_camera_matrix.See also:

ex3d, excamera, exquat, exscn3d, exstars, exzbuf.Examples using this:

Projects the 3d point (x, y, z) into 2d screen space, storing the result in (*xout, *yout) and using the scaling parameters previously set by calling set_projection_viewport(). 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.

set_projection_viewport, get_camera_matrix.See also:

ex3d, exstars.Examples using this: