# Module: `gears.matrix`

An implementation of matrices for describing and working with affine transformations.

### Info:

- Copyright: 2015 Uli Schlachter
- Originally authored by: Uli Schlachter
  (Full contributors list available on our github project)

## Constructors

gears.matrix.create (xx, yx, xy, yy, x0, y0) | Create a new matrix instance |
gears.matrix.create_translate (x, y) | Create a new translation matrix |
gears.matrix.create_scale (sx, sy) | Create a new scaling matrix |
gears.matrix.create_rotate (angle) | Create a new rotation matrix |
gears.matrix.create_rotate_at (x, y, angle) | Create a new rotation matrix rotating around a custom point |

## Fields

gears.matrix.identity | matrix | A constant for the identity matrix. |

## Methods

:translate (x, y) | Translate this matrix |
:scale (sx, sy) | Scale this matrix |
:rotate (angle) | Rotate this matrix |
:rotate_at (x, y, angle) | Rotate a shape from a custom point |
:invert () | Invert this matrix |
:multiply (other) | Multiply this matrix with another matrix. |
:equals (other) | Check if two matrices are equal. |
:tostring () | Get a string representation of this matrix |
:transform_distance (x, y) | Transform a distance by this matrix. |
:transform_point (x, y) | Transform a point by this matrix. |
:transform_rectangle (x, y, width, height) | Calculate a bounding rectangle for transforming a rectangle by a matrix. |
:to_cairo_matrix () | Convert to a cairo matrix |
:from_cairo_matrix (mat) | Convert to a cairo matrix |

## Constructors

🔗 gears.matrix.create (xx, yx, xy, yy, x0, y0)
  Create a new matrix instance

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  xx |  | number | The xx transformation part.
  yx |  | number | The yx transformation part.
  xy |  | number | The xy transformation part.
  yy |  | number | The yy transformation part.
  x0 |  | number | The x0 transformation part.
  y0 |  | number | The y0 transformation part.

  ### Returns:

  A new matrix describing the given transformation.
🔗 gears.matrix.create_translate (x, y)
  Create a new translation matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The translation in x direction.
  y |  | number | The translation in y direction.

  ### Returns:

  A new matrix describing the given transformation.
🔗 gears.matrix.create_scale (sx, sy)
  Create a new scaling matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  sx |  | number | The scaling in x direction.
  sy |  | number | The scaling in y direction.

  ### Returns:

  A new matrix describing the given transformation.
🔗 gears.matrix.create_rotate (angle)
  Create a new rotation matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  angle |  | number | The angle of the rotation in radians.

  ### Returns:

  A new matrix describing the given transformation.
🔗 gears.matrix.create_rotate_at (x, y, angle)
  Create a new rotation matrix rotating around a custom point

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The horizontal rotation point
  y |  | number | The vertical rotation point
  angle |  | number | The angle of the rotation in radians.

  ### Returns:

  A new matrix describing the given transformation.

## Fields

🔗 gears.matrix.identity matrix
  A constant for the identity matrix.

## Methods

🔗 :translate (x, y)
  Translate this matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The translation in x direction.
  y |  | number | The translation in y direction.

  ### Returns:

  A new matrix describing the new transformation.
🔗 :scale (sx, sy)
  Scale this matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  sx |  | number | The scaling in x direction.
  sy |  | number | The scaling in y direction.

  ### Returns:

  A new matrix describing the new transformation.
🔗 :rotate (angle)
  Rotate this matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  angle |  | number | The angle of the rotation in radians.

  ### Returns:

  A new matrix describing the new transformation.
🔗 :rotate_at (x, y, angle)
  Rotate a shape from a custom point

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The horizontal rotation point
  y |  | number | The vertical rotation point
  angle |  | number | The angle (in radiant: -2*math.pi to 2*math.pi)

  ### Returns:

  A transformation object
🔗 :invert ()
  Invert this matrix

  ### Returns:

  A new matrix describing the inverse transformation.
🔗 :multiply (other)
  Multiply this matrix with another matrix. The resulting matrix describes a transformation that is equivalent to first applying this transformation and then the transformation from `other`. Note that this function can also be called by directly multiplicating two matrix instances: `a * b == a:multiply(b)`.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  other |  | gears.matrix or cairo.Matrix | The other matrix to multiply with.

  ### Returns:

  The multiplication result.
🔗 :equals (other)
  Check if two matrices are equal. Note that this function cal also be called by directly comparing two matrix instances: `a == b`.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  other |  | gears.matrix or cairo.Matrix | The matrix to compare with.

  ### Returns:

  True if this and the other matrix are equal.
🔗 :tostring ()
  Get a string representation of this matrix

  ### Returns:

  A string showing this matrix in column form.
🔗 :transform_distance (x, y)
  Transform a distance by this matrix. The difference to matrix:transform_point is that the translation part of this matrix is ignored.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The x coordinate of the point.
  y |  | number | The y coordinate of the point.

  ### Returns:

  1. number The x coordinate of the transformed point.
  2. number The x coordinate of the transformed point.
🔗 :transform_point (x, y)
  Transform a point by this matrix.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The x coordinate of the point.
  y |  | number | The y coordinate of the point.

  ### Returns:

  1. number The x coordinate of the transformed point.
  2. number The y coordinate of the transformed point.
🔗 :transform_rectangle (x, y, width, height)
  Calculate a bounding rectangle for transforming a rectangle by a matrix.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | The x coordinate of the rectangle.
  y |  | number | The y coordinate of the rectangle.
  width |  | number | The width of the rectangle.
  height |  | number | The height of the rectangle.

  ### Returns:

  1. number X coordinate of the bounding rectangle.
  2. number Y coordinate of the bounding rectangle.
  3. number Width of the bounding rectangle.
  4. number Height of the bounding rectangle.
🔗 :to_cairo_matrix ()
  Convert to a cairo matrix

  ### Returns:

  cairo.Matrix A cairo matrix describing the same transformation.
🔗 :from_cairo_matrix (mat)
  Convert to a cairo matrix

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  mat |  | cairo.Matrix | A cairo matrix describing the sought transformation

  ### Returns:

  gears.matrix A matrix instance describing the same transformation.

generated by LDoc 1.5.0