These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Transformations allow you to transform the coordinates you use for drawing operations without additional overhead. Scaling, rotating, translating, and combinations of these are possible as well as using custom transformations. There are two types of transformations that you can set, ‘regular’ transformations and projection transformations. The projection transform is rarely used in 2D games, but is common in 3D games to set up the projection from the 3D world to the 2D screen. Typically, you would use the regular transform for non-projective types of transformations (that is, translations, rotations, scales, skews… i.e. transformations that are linear), while the projection transform will be used for setting up perspective and possibly more advanced effects. It is possible to do everything with just using the projection transformation (that is, you’d compose the projection transformation with the non-projection transformations that, e.g., move the camera in the world), but it is more convenient to use both for two reasons:

• Regular transformations can be changed while the bitmap drawing is held (see al_hold_bitmap_drawing).

• Regular transformations work with memory bitmaps.

As a result, if you’re making a 2D game, it’s best to leave the projection transformations at their default values.

Both types of transformations are set per target-bitmap, i.e. a change of the target bitmap will also change the active transformation.

Allegro provides convenience functions to construct transformations in 2D and 3D variants (the latter with a _3d suffix), so you don’t have to deal with the underlying matrix algebra yourself.

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 know 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;

Source Code

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

Examples:

• ex_shader.cpp
• ex_shader_target.c
• ex_audio_timer.c

al_copy_transform

void al_copy_transform(ALLEGRO_TRANSFORM *dest, const ALLEGRO_TRANSFORM *src)

Source Code

Makes a copy of a transformation.

Parameters:

• dest - Source transformation
• src - Destination transformation

Examples:

• ex_shader.cpp

al_use_transform

void al_use_transform(const ALLEGRO_TRANSFORM *trans)

Source Code

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

Examples:

• ex_shader.cpp
• ex_shader_target.c
• ex_audio_timer.c

al_get_current_transform

const ALLEGRO_TRANSFORM *al_get_current_transform(void)

Source Code

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.

See also: al_get_current_projection_transform

Examples:

• ex_shader.cpp
• ex_color_gradient.c

al_use_projection_transform

void al_use_projection_transform(const ALLEGRO_TRANSFORM *trans)

Source Code

Sets the projection transformation to be used for the drawing operations on the target bitmap (each bitmap maintains its own projection transformation). Every drawing operation after this call will be transformed using this transformation. To return default behavior, call this function with an orthographic transform like so:

ALLEGRO_TRANSFORM trans;
al_identity_transform(&trans);
al_orthographic_transform(&trans, 0, 0, -1.0, al_get_bitmap_width(bitmap),
                          al_get_bitmap_height(bitmap), 1.0);

al_set_target_bitmap(bitmap);
al_use_projection_transform(&trans);

The orthographic transformation above is the default projection transform.

This function does nothing if there is no target bitmap. This function also does nothing if the bitmap is a memory bitmap (i.e. memory bitmaps always use an orthographic transform like the snippet above). Note that the projection transform will be reset to default if a video bitmap is converted to a memory bitmap. Additionally, if the bitmap in question is the backbuffer, it’s projection transformation will be reset to default if it is resized. Lastly, when you draw a memory bitmap to a video bitmap with a custom projection transform, this transformation will be ignored (i.e. it’ll be as if the projection transform of the target bitmap was temporarily reset to default).

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.

Since: 5.1.9

See also: al_get_current_projection_transform, al_perspective_transform, al_orthographic_transform

Examples:

• ex_projection.c
• ex_depth_target.c
• ex_projection2.c

al_get_current_projection_transform

const ALLEGRO_TRANSFORM *al_get_current_projection_transform(void)

Source Code

If there is no target bitmap, this function returns NULL.

Returns: A pointer to the current transformation.

Since: 5.1.9

See also: al_use_projection_transform

Examples:

• ex_camera.c

al_get_current_inverse_transform

const ALLEGRO_TRANSFORM *al_get_current_inverse_transform(void)

Source Code

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.

Note: Allegro’s transformation inversion functions work correctly only with 2D transformations.

Since: 5.1.0

al_invert_transform

void al_invert_transform(ALLEGRO_TRANSFORM *trans)

Source Code

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

Note: Allegro’s transformation inversion functions work correctly only with 2D transformations.

See also: al_check_inverse

al_transpose_transform

void al_transpose_transform(ALLEGRO_TRANSFORM *trans)

Source Code

Transposes the matrix of the given transform. This can be used for inversing a rotation transform. For example:

al_build_camera_transform(camera, 0, 0, 0, x, y, z, xu, yu, zu)
al_copy_transform(inverse, camera)
al_transpose_transform(camera)
// Now "inverse" will be a transformation rotating in the opposite
// direction from "camera". Note that this only works if the camera
// position is 0/0/0 as in the example.

Since: 5.2.5

al_check_inverse

int al_check_inverse(const ALLEGRO_TRANSFORM *trans, float tol)

Source Code

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

Note: Allegro’s transformation inversion functions work correctly only with 2D transformations.

See also: al_invert_transform

al_identity_transform

void al_identity_transform(ALLEGRO_TRANSFORM *trans)

Source Code

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

Examples:

• ex_shader.cpp
• ex_shader_target.c
• ex_audio_timer.c

al_build_transform

void al_build_transform(ALLEGRO_TRANSFORM *trans, float x, float y,
   float sx, float sy, float theta)

Source Code

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

Examples:

• ex_threads.c
• ex_color_gradient.c
• ex_prim.c

al_build_camera_transform

void al_build_camera_transform(ALLEGRO_TRANSFORM *trans,
   float position_x, float position_y, float position_z,
   float look_x, float look_y, float look_z,
   float up_x, float up_y, float up_z)

Source Code

Builds a transformation which can be used to transform 3D coordinates in world space to camera space. This involves translation and a rotation. The function expects three coordinate triplets: The camera’s position, the position the camera is looking at and an up vector. The up vector does not need to be of unit length and also does not need to be perpendicular to the view direction - it can usually just be the world up direction (most commonly 0/1/0).

For example:

al_build_camera_transform(&t,
    1, 1, 1,
    5, 5, 5,
    0, 1, 0);

This create a transformation for a camera standing at 1/1/1 and looking towards 5/5/5.

Note: If the position and look parameters are identical, or if the up direction is parallel to the view direction, an identity matrix is created.

Another example which will simply re-create the identity matrix:

al_build_camera_transform(&t,
    0, 0, 0,
    0, 0, -1,
    0, 1, 0);

An example where the up vector will cause the camera to lean (roll) by 45 degrees:

al_build_camera_transform(&t,
    1, 1, 1,
    5, 5, 5,
    1, 1, 0);

Since 5.1.9

See also: al_translate_transform_3d, al_rotate_transform_3d, al_scale_transform_3d, al_compose_transform, al_use_transform

Examples:

• ex_camera.c

al_translate_transform

void al_translate_transform(ALLEGRO_TRANSFORM *trans, float x, float y)

Source Code

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

Examples:

• ex_shader.cpp
• ex_shader_target.c
• ex_polygon.c

al_rotate_transform

void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta)

Source Code

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

Examples:

• ex_depth_mask.c
• ex_projection.c
• ex_depth_target.c

al_scale_transform

void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy)

Source Code

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

Examples:

• ex_shader_target.c
• ex_audio_timer.c
• ex_polygon.c

al_transform_coordinates

void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float *y)

Source Code

Transform a pair of coordinates.

Parameters:

• trans - Transformation to use
• x, y - Pointers to the coordinates

See also: al_use_transform, al_transform_coordinates_3d

Examples:

• ex_camera.c

al_transform_coordinates_3d

void al_transform_coordinates_3d(const ALLEGRO_TRANSFORM *trans,
   float *x, float *y, float *z)

Source Code

Transform x, y, z coordinates.

Parameters:

• trans - Transformation to use
• x, y, z - Pointers to the coordinates

Note: If you are using a projection transform you most likely will want to use al_transform_coordinates_3d_projective instead.

Since 5.1.9

See also: al_use_transform, al_transform_coordinates

Examples:

• ex_camera.c

al_transform_coordinates_4d

void al_transform_coordinates_4d(const ALLEGRO_TRANSFORM *trans,
   float *x, float *y, float *z, float *w)

Source Code

Transform x, y, z, w coordinates.

Parameters:

• trans - Transformation to use
• x, y, z, w - Pointers to the coordinates

Since 5.2.4

See also: al_use_transform, al_transform_coordinates, al_transform_coordinates_3d

al_transform_coordinates_3d_projective

void al_transform_coordinates_3d_projective(const ALLEGRO_TRANSFORM *trans,
   float *x, float *y, float *z)

Source Code

Transform x, y, z as homogeneous coordinates. This is the same as using al_transform_coordinates_4d with the w coordinate set to 1, then dividing x, y, z by the resulting w. This will provide the same normalized coordinates Allegro will draw to when a projective transform is in effect as set with al_use_projection_transform. To get the actual pixel coordinates from those translate and scale like so (w and h would be the pixel dimensions of the target bitmap):

x = w / 2 + x * w / 2
y = h / 2 - y * h / 2

Parameters:

• trans - Transformation to use
• x, y, z - Pointers to the coordinates

Example:

ALLEGRO_TRANSFORM t2;
al_copy_transform(&t2, al_get_current_transform());
al_compose_transform(&t2, al_get_current_projection_transform());

ALLEGRO_TRANSFORM t3;
al_identity_transform(&t3);
al_scale_transform(&t3, 0.5, -0.5);
al_translate_transform(&t3, 0.5, 0.5);
al_scale_transform(&t3, al_get_bitmap_width(al_get_target_bitmap()),
                   al_get_bitmap_height(al_get_target_bitmap()));

al_transform_coordinates_3d_projective(&t2, &x, &y, &z);
// x, y now contain normalized coordinates
al_transform_coordinates(&t3, &x, &y);
// x, y now contain pixel coordinates

Since 5.2.4

See also: al_use_transform, al_transform_coordinates, al_transform_coordinates_3d, al_use_projection_transform

al_compose_transform

void al_compose_transform(ALLEGRO_TRANSFORM *trans, const ALLEGRO_TRANSFORM *other)

Source Code

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

Examples:

• ex_color_gradient.c

al_orthographic_transform

void al_orthographic_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)

Source Code

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 range, coordinates outside of that range will get clipped. Normally -1/1 is fine because all 2D graphics will have a z coordinate of 0. However if you for example do al_draw_rectangle(0, 0, 100, 100) and rotate around the x axis (“towards the screen”) make sure your z range allows values from -100 to 100 or the rotated rectangle will get clipped.

Also, if you are using a depth buffer the z range decides the depth resolution. For example if you have a 16 bit depth buffer there are only 65536 discrete depth values. So if your near/far is set to -1000000/1000000 most of the z positions would not result in separate depth values which could lead to artifacts.

The result of applying this transformation to coordinates will be to normalize visible coordinates into the cube from -1/-1/-1 to 1/1/1. Such a transformation is mostly useful for passing it to al_use_projection_transform - see that function for an example use.

Since: 5.1.3

See also: al_use_projection_transform, al_perspective_transform

Examples:

• ex_depth_target.c

al_perspective_transform

void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)

Source Code

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

and therefore

near = (right - left) / 2 / tan(hfov / 2)

Example 1:

   float w = 800, h = 450; // assume our display is 800 x 450
   float fov = tan(90 * ALLEGRO_PI / 180 / 2); // 90 degree field of view

   // Our projection goes from 0/0 to w/h with the near parameter set
   // for a 90 degree horizontal viewing angle.
   ALLEGRO_TRANSFORM projection;
   al_identity_transform(&projection);
   al_perspective_transform(&projection, 0, 0,
    w / 2 / fov,
    w, h,
    2000);
   al_use_projection_transform(&projection);

   // Set the camera z to +400 (which is exactly the near distance)
   ALLEGRO_TRANSFORM camera;
   al_build_camera_transform(&camera, 0, 0, 400, 0, 0, 0, 0, 1, 0);
   al_use_transform(&camera);

   // This will draw two rectangles at the left and right edge of the
   // screen and vertically centered. The x distance between them is 800
   // units, but the camera transform moves them 400 along z, so with
   // a 90° viewing angle both are visible.
   al_draw_filled_rectangle(0, 200, 50, 250, red;
   al_draw_filled_rectangle(750, 200, 800, 250, red);

Example 2:

   float w = 800, h = 450; // assume our display is 800 x 450
   float fov = tan(90 * ALLEGRO_PI / 180 / 2); // 90 degree field of view
   float aspect = h / w;
   float zoom = 2; // enlarge x 2

   // This projection is very different from the one in the first example.
   // Here we map the left and right edge of the screen to -1 and +1. And
   // the y axis goes from -1 at the bottom to +1 at the top, scaled by
   // the aspect ratio. We also add a zoom parameter so we can control
   // the visible portion of the scene independent of the field of view.
   ALLEGRO_TRANSFORM projection;
   al_identity_transform(&projection);
   al_perspective_transform(&projection,
      -1 / zoom, aspect / zoom,
      1 / fov,
      1 / zoom, -aspect / zoom,
      2000);
   al_use_projection_transform(&projection);

   // Moves everything by -4 in the z direction.
   ALLEGRO_TRANSFORM camera;
   al_build_camera_transform(&camera, 0, 0, 4, 0, 0, 0, 0, 1, 0);
   al_use_transform(&camera);

   // At a z distance of 4 with a 90° hfov everything would be scaled
   // down to 25%. However we also zoom 2-fold, so the final scaling is
   // 50%. This rectangle therefore will appear at a size of 400 x 225
   // pixel (assuming the display is 800 x 450).
   al_draw_filled_rectangle(-1, -1, 1, 1, red);

Since: 5.1.3

See also: al_use_projection_transform, al_orthographic_transform

Examples:

• ex_projection.c
• ex_projection2.c
• ex_camera.c

al_translate_transform_3d

void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y,
    float z)

Source Code

Combines the given transformation with a transformation which translates coordinates by the given vector.

Since: 5.1.3

See also: al_use_projection_transform

Examples:

• ex_projection.c
• ex_depth_target.c
• ex_projection2.c

al_scale_transform_3d

void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy,
    float sz)

Source Code

Combines the given transformation with a transformation which scales coordinates by the given vector.

Since: 5.1.3

See also: al_use_projection_transform

al_rotate_transform_3d

void al_rotate_transform_3d(ALLEGRO_TRANSFORM *trans,
   float x, float y, float z, float angle)

Source Code

Combines the given transformation with a transformation which rotates coordinates around the given vector by the given angle in radians.

Note: The vector is assumed to be of unit length (otherwise it will also incur a scale).

Since: 5.1.3

Examples:

• ex_projection.c
• ex_depth_target.c
• ex_projection2.c

al_horizontal_shear_transform

void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)

Source Code

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)

Source Code

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

Allegro version 5.2.10 (20231119) - Last updated: 2024-11-26 05:31:15 UTC