# Transformations

These functions are declared in the main Allegro header file:

~~~~c
 #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:

~~~~c
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:

~~~~c
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:

~~~~c
al_identity_transform(&T);
al_scale_transform(&T, 2, 2);
al_translate_transform(&T, 100, 0);
al_use_transform(T);
~~~~

## API: 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

## API: al_copy_transform

Makes a copy of a transformation.

*Parameters:*

* dest - Source transformation
* src - Destination transformation

## API: al_use_transform

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.

~~~~c
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]

## API: al_get_current_transform

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.

## API: al_invert_transform

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]

## API: al_check_inverse

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]

## API: al_identity_transform

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.

~~~~c
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]

## API: al_build_transform

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]

## API: al_translate_transform

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]

## API: al_rotate_transform

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]

## API: al_scale_transform

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]

## API: al_transform_coordinates

Transform a pair of coordinates.

*Parameters:*

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

See also: [al_use_transform]

## API: al_compose_transform

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`
