Matrix

class Matrix(*args, **kwargs)

A structure capable of holding a 4x4 matrix.

The contents of the Matrix structure are private and should never be accessed directly.

Constructors

class Matrix

classmethod alloc() → Matrix: Allocates a new Matrix.

Added in version 1.0.

Methods

class Matrix

decompose() → tuple[bool, Vec3, Vec3, Quaternion, Vec3, Vec4]

Decomposes a transformation matrix into its component transformations.

The algorithm for decomposing a matrix is taken from the CSS3 Transforms specification; specifically, the decomposition code is based on the equivalent code published in “Graphics Gems II”, edited by Jim Arvo, and available online.

determinant() → float: Computes the determinant of the given matrix.

Added in version 1.0.

equal(b: Matrix) → bool

Checks whether the two given Matrix matrices are equal.

Added in version 1.10.

Parameters:: b – a Matrix

equal_fast(b: Matrix) → bool

Checks whether the two given Matrix matrices are byte-by-byte equal.

While this function is faster than equal(), it can also return false negatives, so it should be used in conjuction with either equal() or near(). For instance:

if (graphene_matrix_equal_fast (a, b))
  {
    // matrices are definitely the same
  }
else
  {
    if (graphene_matrix_equal (a, b))
      // matrices contain the same values within an epsilon of FLT_EPSILON
    else if (graphene_matrix_near (a, b, 0.0001))
      // matrices contain the same values within an epsilon of 0.0001
    else
      // matrices are not equal
  }

Added in version 1.10.

Parameters:: b – a Matrix

free() → None: Frees the resources allocated by alloc().

Added in version 1.0.

get_row(index_: int) → Vec4

Retrieves the given row vector at @``index_`` inside a matrix.

Added in version 1.0.

Parameters:: index – the index of the row vector, between 0 and 3

get_value(row: int, col: int) → float

Retrieves the value at the given row and col index.

Added in version 1.0.

Parameters:

row – the row index
col – the column index

get_x_scale() → float: Retrieves the scaling factor on the X axis in m.

Added in version 1.0.

get_x_translation() → float: Retrieves the translation component on the X axis from m.

Added in version 1.10.

get_y_scale() → float: Retrieves the scaling factor on the Y axis in m.

Added in version 1.0.

get_y_translation() → float: Retrieves the translation component on the Y axis from m.

Added in version 1.10.

get_z_scale() → float: Retrieves the scaling factor on the Z axis in m.

Added in version 1.0.

get_z_translation() → float: Retrieves the translation component on the Z axis from m.

Added in version 1.10.

init_from_2d(xx: float, yx: float, xy: float, yy: float, x_0: float, y_0: float) → Matrix

Initializes a Matrix from the values of an affine transformation matrix.

The arguments map to the following matrix layout:

⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠

This function can be used to convert between an affine matrix type from other libraries and a Matrix.

Added in version 1.0.

Parameters:

xx – the xx member
yx – the yx member
xy – the xy member
yy – the yy member
x_0 – the x0 member
y_0 – the y0 member

init_from_float(v: Sequence[float]) → Matrix

Initializes a Matrix with the given array of floating point values.

Added in version 1.0.

Parameters:: v – an array of at least 16 floating point values

init_from_matrix(src: Matrix) → Matrix

Initializes a Matrix using the values of the given matrix.

Added in version 1.0.

Parameters:: src – a Matrix

init_from_vec4(v0: Vec4, v1: Vec4, v2: Vec4, v3: Vec4) → Matrix

Initializes a Matrix with the given four row vectors.

Added in version 1.0.

Parameters:

v0 – the first row vector
v1 – the second row vector
v2 – the third row vector
v3 – the fourth row vector

init_frustum(left: float, right: float, bottom: float, top: float, z_near: float, z_far: float) → Matrix

Initializes a Matrix compatible with Frustum.

Fields

class Matrix

value