Transformations
- ALLEGRO_TRANSFORM
- al_copy_transform
- al_use_transform
- al_get_current_transform
- al_get_current_inverse_transform
- al_invert_transform
- al_check_inverse
- al_identity_transform
- al_build_transform
- al_translate_transform
- al_rotate_transform
- al_scale_transform
- al_transform_coordinates
- al_compose_transform
- al_orthographic_transform
- al_perspective_transform
- al_translate_transform_3d
- al_scale_transform_3d
- al_rotate_transform_3d
- al_get_projection_transform
- al_set_projection_transform
- al_horizontal_shear_transform
- al_vertical_shear_transform
These functions are declared in the main Allegro header file:
#include <allegro5/allegro.h>
The transformations are combined in the order of the function invocations. Thus to create a transformation that first rotates a point and then translates it, you would (starting with an identity transformation) call al_rotate_transform and then al_translate_transform. This approach is opposite of what OpenGL uses but similar to what Direct3D uses.
For those who known the matrix algebra going behind the scenes, what the transformation functions in Allegro do is "pre-multiply" the successive transformations. So, for example, if you have code that does:
al_identity_transform(&T);
al_compose_transform(&T, &T1);
al_compose_transform(&T, &T2);
al_compose_transform(&T, &T3);
al_compose_transform(&T, &T4);
The resultant matrix multiplication expression will look like this:
T4 * T3 * T2 * T1
Since the point coordinate vector term will go on the right of that sequence of factors, the transformation that is called first, will also be applied first.
This means if you have code like this:
al_identity_transform(&T1);
al_scale_transform(&T1, 2, 2);
al_identity_transform(&T2);
al_translate_transform(&T2, 100, 0);
al_identity_transform(&T);
al_compose_transform(&T, &T1);
al_compose_transform(&T, &T2);
al_use_transform(T);
it does exactly the same as:
al_identity_transform(&T);
al_scale_transform(&T, 2, 2);
al_translate_transform(&T, 100, 0);
al_use_transform(T);
ALLEGRO_TRANSFORM
typedef struct ALLEGRO_TRANSFORM ALLEGRO_TRANSFORM;
Defines the generic transformation type, a 4x4 matrix. 2D transforms use only a small subsection of this matrix, namely the top left 2x2 matrix, and the right most 2x1 matrix, for a total of 6 values.
Fields:
- m - A 4x4 float matrix
al_copy_transform
void al_copy_transform(ALLEGRO_TRANSFORM *dest, const ALLEGRO_TRANSFORM *src)
Makes a copy of a transformation.
Parameters:
- dest - Source transformation
- src - Destination transformation
al_use_transform
void al_use_transform(const ALLEGRO_TRANSFORM *trans)
Sets the transformation to be used for the the drawing operations on the target bitmap (each bitmap maintains its own transformation). Every drawing operation after this call will be transformed using this transformation. Call this function with an identity transformation to return to the default behaviour.
This function does nothing if there is no target bitmap.
The parameter is passed by reference as an optimization to avoid the overhead of stack copying. The reference will not be stored in the Allegro library so it is safe to pass references to local variables.
void setup_my_transformation(void)
{
ALLEGRO_TRANSFORM transform;
al_translate_transform(&transform, 5, 10);
al_use_transform(&transform);
}
Parameters:
- trans - Transformation to use
See also: al_get_current_transform, al_transform_coordinates
al_get_current_transform
const ALLEGRO_TRANSFORM *al_get_current_transform(void)
Returns the transformation of the current target bitmap, as set by al_use_transform. If there is no target bitmap, this function returns NULL.
Returns: A pointer to the current transformation.
al_get_current_inverse_transform
const ALLEGRO_TRANSFORM *al_get_current_inverse_transform(void)
Returns the inverse of the current transformation of the target bitmap. If there is no target bitmap, this function returns NULL.
This is similar to calling al_invert_transform(al_get_current_transform())
but the result of this function is cached.
Since: 5.1.0
al_invert_transform
void al_invert_transform(ALLEGRO_TRANSFORM *trans)
Inverts the passed transformation. If the transformation is nearly singular (close to not having an inverse) then the returned transformation may be invalid. Use al_check_inverse to ascertain if the transformation has an inverse before inverting it if you are in doubt.
Parameters:
- trans - Transformation to invert
See also: al_check_inverse
al_check_inverse
int al_check_inverse(const ALLEGRO_TRANSFORM *trans, float tol)
Checks if the transformation has an inverse using the supplied tolerance. Tolerance should be a small value between 0 and 1, with 1e-7 being sufficient for most applications.
In this function tolerance specifies how close the determinant can be to 0 (if the determinant is 0, the transformation has no inverse). Thus the smaller the tolerance you specify, the "worse" transformations will pass this test. Using a tolerance of 1e-7 will catch errors greater than 1/1000's of a pixel, but let smaller errors pass. That means that if you transformed a point by a transformation and then transformed it again by the inverse transformation that passed this check, the resultant point should less than 1/1000's of a pixel away from the original point.
Note that this check is superfluous most of the time if you never touched the transformation matrix values yourself. The only thing that would cause the transformation to not have an inverse is if you applied a 0 (or very small) scale to the transformation or you have a really large translation. As long as the scale is comfortably above 0, the transformation will be invertible.
Parameters:
- trans - Transformation to check
- tol - Tolerance
Returns: 1 if the transformation is invertible, 0 otherwise
See also: al_invert_transform
al_identity_transform
void al_identity_transform(ALLEGRO_TRANSFORM *trans)
Sets the transformation to be the identity transformation. This is the default transformation. Use al_use_transform on an identity transformation to return to the default.
ALLEGRO_TRANSFORM t;
al_identity_transform(&t);
al_use_transform(&t);
Parameters:
- trans - Transformation to alter
See also: al_translate_transform, al_rotate_transform, al_scale_transform
al_build_transform
void al_build_transform(ALLEGRO_TRANSFORM *trans, float x, float y,
float sx, float sy, float theta)
Builds a transformation given some parameters. This call is equivalent to calling the transformations in this order: make identity, rotate, scale, translate. This method is faster, however, than actually calling those functions.
Parameters:
- trans - Transformation to alter
- x, y - Translation
- sx, sy - Scale
- theta - Rotation angle in radians
Note: this function was previously documented to be equivalent to a different (and more useful) order of operations: identity, scale, rotate, translate.
See also: al_translate_transform, al_rotate_transform, al_scale_transform, al_compose_transform
al_translate_transform
void al_translate_transform(ALLEGRO_TRANSFORM *trans, float x, float y)
Apply a translation to a transformation.
Parameters:
- trans - Transformation to alter
- x, y - Translation
See also: al_rotate_transform, al_scale_transform, al_build_transform
al_rotate_transform
void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta)
Apply a rotation to a transformation.
Parameters:
- trans - Transformation to alter
- theta - Rotation angle in radians
See also: al_translate_transform, al_scale_transform, al_build_transform
al_scale_transform
void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy)
Apply a scale to a transformation.
Parameters:
- trans - Transformation to alter
- sx, sy - Scale
See also: al_translate_transform, al_rotate_transform, al_build_transform
al_transform_coordinates
void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float *y)
Transform a pair of coordinates.
Parameters:
- trans - Transformation to use
- x, y - Pointers to the coordinates
See also: al_use_transform
al_compose_transform
void al_compose_transform(ALLEGRO_TRANSFORM *trans, const ALLEGRO_TRANSFORM *other)
Compose (combine) two transformations by a matrix multiplication.
trans := trans other
Note that the order of matrix multiplications is important. The effect of applying the combined transform will be as if first applying trans
and then applying other
and not the other way around.
Parameters:
- trans - Transformation to alter
- other - Transformation used to transform
trans
See also: al_translate_transform, al_rotate_transform, al_scale_transform
al_orthographic_transform
void al_orthographic_transform(ALLEGRO_TRANSFORM *trans,
float left, float top, float n,
float right, float bottom, float f)
Combines the given transformation with an orthographic transformation which maps the screen rectangle to the given left/top and right/bottom coordinates. near/far is the z-buffer range, if there is no z-buffer you can set it to -1/1.
Since: 5.1.3
See also: al_set_projection_transform, al_perspective_transform
al_perspective_transform
void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
float left, float top, float n,
float right, float bottom, float f)
Like al_orthographic_transform but honors perspective. If everything is at a z-position of -near it will look the same as with an orthographic transformation.
To use a specific horizontal field of view you can use the relation:
tan(hfov / 2) = (right - left) / 2 / near
Since: 5.1.3
See also: al_set_projection_transform, al_orthographic_transform
al_translate_transform_3d
void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y,
float z)
Combines the given transformation with a transformation which translates coordinates by the given vector.
Since: 5.1.3
See also: al_set_projection_transform
al_scale_transform_3d
void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy,
float sz)
Combines the given transformation with a transformation which scales coordinates by the given vector.
Since: 5.1.3
See also: al_set_projection_transform
al_rotate_transform_3d
void al_rotate_transform_3d(ALLEGRO_TRANSFORM *trans,
float x, float y, float z, float angle)
Combines the given transformation with a transformation which rotates coordinates around the given vector by the given angle in radians.
Since: 5.1.3
See also: al_set_projection_transform
al_get_projection_transform
ALLEGRO_TRANSFORM *al_get_projection_transform(ALLEGRO_DISPLAY *display)
Returns the projection transformation of the display as set with al_set_projection_transform.
Since: 5.1.0
See also: al_set_projection_transform
al_set_projection_transform
void al_set_projection_transform(ALLEGRO_DISPLAY *display, ALLEGRO_TRANSFORM *t)
Replaces the projection transformation of the given display.
Note: Unlike the regular 2D transformations, the projection transformation affects all drawing operations done to the current display. This means for example that it is not affected by calls to al_set_target_bitmap (if the bitmap belongs to the same display).
Note: Drawing to memory bitmaps is not affected by the projection transformation.
Since: 5.1.0
See also: al_get_projection_transform
al_horizontal_shear_transform
void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)
Apply a horizontal shear to the transform
Parameters:
- trans - Transformation to alter
- theta - Rotation angle in radians
Since: 5.1.7
See also: al_vertical_shear_transform
al_vertical_shear_transform
void al_vertical_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)
Apply a vertical shear to the transform
Parameters:
- trans - Transformation to alter
- theta - Rotation angle in radians
Since: 5.1.7
See also: al_horizontal_shear_transform