# Transformations

These functions are declared in the main Allegro header file:

    #include <allegro5/allegro.h>

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

* src - Source transformation
* dest - Destination transformation

## API: al_use_transform

Sets the transformation to be used for the the drawing operations. 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.

*Parameters:*

* trans - Transformation to use

## API: al_get_current_transform

Returns the current transformation, as set by [al_use_transform].

*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 assertain 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 0.001 being sufficient 
for most applications. 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. 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.

*Parameters:*

* trans - Transformation to alter

## API: al_build_transform

Builds a transformation given some parameters. This call is equivalent to
calling the transformations in this order: make identity, scale, rotate,
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

## API: al_translate_transform

Apply a translation to a transformation.

*Parameters:*

* trans - Transformation to alter
* x, y - Translation

## API: al_rotate_transform

Apply a rotation to a transformation.

*Parameters:*

* trans - Transformation to alter
* theta - Rotation angle

## API: al_scale_transform

Apply a scale to a transformation.

*Parameters:*

* trans - Transformation to alter
* sx, sy - Scale

## API: al_transform_coordinates

Transform a pair of coordinates.

*Parameters:*

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

## API: al_transform_transform

Transform a transformation.

*Parameters:*

* trans - Transformation to use
* trans2 - Transformation to transform
