:right-sidebar: True
Matrix
===================================================================
.. currentmodule:: gi.repository.Graphene
.. class:: Matrix(*args, **kwargs)
:no-contents-entry:
A structure capable of holding a 4x4 matrix.
The contents of the :obj:`~gi.repository.Graphene.Matrix` structure are private and
should never be accessed directly.
Constructors
------------
.. rst-class:: interim-class
.. class:: Matrix
:no-index:
.. classmethod:: alloc() -> ~gi.repository.Graphene.Matrix
Allocates a new :obj:`~gi.repository.Graphene.Matrix`\.
.. versionadded:: 1.0
Methods
-------
.. rst-class:: interim-class
.. class:: Matrix
:no-index:
.. method:: decompose() -> ~typing.Tuple[bool, ~gi.repository.Graphene.Vec3, ~gi.repository.Graphene.Vec3, ~gi.repository.Graphene.Quaternion, ~gi.repository.Graphene.Vec3, ~gi.repository.Graphene.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 `__\.
.. method:: determinant() -> float
Computes the determinant of the given matrix.
.. versionadded:: 1.0
.. method:: equal(b: ~gi.repository.Graphene.Matrix) -> bool
Checks whether the two given :obj:`~gi.repository.Graphene.Matrix` matrices are equal.
.. versionadded:: 1.10
:param b: a :obj:`~gi.repository.Graphene.Matrix`
.. method:: equal_fast(b: ~gi.repository.Graphene.Matrix) -> bool
Checks whether the two given :obj:`~gi.repository.Graphene.Matrix` matrices are
byte-by-byte equal.
While this function is faster than :func:`~gi.repository.Graphene.Matrix.equal`, it
can also return false negatives, so it should be used in
conjuction with either :func:`~gi.repository.Graphene.Matrix.equal` or
:func:`~gi.repository.Graphene.Matrix.near`. For instance:
.. code-block:: C
:dedent:
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
}
.. versionadded:: 1.10
:param b: a :obj:`~gi.repository.Graphene.Matrix`
.. method:: free() -> None
Frees the resources allocated by :func:`~gi.repository.Graphene.Matrix.alloc`.
.. versionadded:: 1.0
.. method:: get_row(index_: int) -> ~gi.repository.Graphene.Vec4
Retrieves the given row vector at ``index_`` inside a matrix.
.. versionadded:: 1.0
:param index_: the index of the row vector, between 0 and 3
.. method:: get_value(row: int, col: int) -> float
Retrieves the value at the given ``row`` and ``col`` index.
.. versionadded:: 1.0
:param row: the row index
:param col: the column index
.. method:: get_x_scale() -> float
Retrieves the scaling factor on the X axis in ``m``\.
.. versionadded:: 1.0
.. method:: get_x_translation() -> float
Retrieves the translation component on the X axis from ``m``\.
.. versionadded:: 1.10
.. method:: get_y_scale() -> float
Retrieves the scaling factor on the Y axis in ``m``\.
.. versionadded:: 1.0
.. method:: get_y_translation() -> float
Retrieves the translation component on the Y axis from ``m``\.
.. versionadded:: 1.10
.. method:: get_z_scale() -> float
Retrieves the scaling factor on the Z axis in ``m``\.
.. versionadded:: 1.0
.. method:: get_z_translation() -> float
Retrieves the translation component on the Z axis from ``m``\.
.. versionadded:: 1.10
.. method:: init_from_2d(xx: float, yx: float, xy: float, yy: float, x_0: float, y_0: float) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` from the values of an affine
transformation matrix.
The arguments map to the following matrix layout:
.. code-block:: plain
:dedent:
⎛ 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 :obj:`~gi.repository.Graphene.Matrix`\.
.. versionadded:: 1.0
:param xx: the xx member
:param yx: the yx member
:param xy: the xy member
:param yy: the yy member
:param x_0: the x0 member
:param y_0: the y0 member
.. method:: init_from_float(v: list[float]) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with the given array of floating
point values.
.. versionadded:: 1.0
:param v: an array of at least 16 floating
point values
.. method:: init_from_matrix(src: ~gi.repository.Graphene.Matrix) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` using the values of the
given matrix.
.. versionadded:: 1.0
:param src: a :obj:`~gi.repository.Graphene.Matrix`
.. method:: init_from_vec4(v0: ~gi.repository.Graphene.Vec4, v1: ~gi.repository.Graphene.Vec4, v2: ~gi.repository.Graphene.Vec4, v3: ~gi.repository.Graphene.Vec4) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with the given four row
vectors.
.. versionadded:: 1.0
:param v0: the first row vector
:param v1: the second row vector
:param v2: the third row vector
:param v3: the fourth row vector
.. method:: init_frustum(left: float, right: float, bottom: float, top: float, z_near: float, z_far: float) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` compatible with :obj:`~gi.repository.Graphene.Frustum`\.
See also: :func:`~gi.repository.Graphene.Frustum.init_from_matrix`
.. versionadded:: 1.2
:param left: distance of the left clipping plane
:param right: distance of the right clipping plane
:param bottom: distance of the bottom clipping plane
:param top: distance of the top clipping plane
:param z_near: distance of the near clipping plane
:param z_far: distance of the far clipping plane
.. method:: init_identity() -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with the identity matrix.
.. versionadded:: 1.0
.. method:: init_look_at(eye: ~gi.repository.Graphene.Vec3, center: ~gi.repository.Graphene.Vec3, up: ~gi.repository.Graphene.Vec3) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` so that it positions the "camera"
at the given ``eye`` coordinates towards an object at the ``center``
coordinates. The top of the camera is aligned to the direction
of the ``up`` vector.
Before the transform, the camera is assumed to be placed at the
origin, looking towards the negative Z axis, with the top side of
the camera facing in the direction of the Y axis and the right
side in the direction of the X axis.
In theory, one could use ``m`` to transform a model of such a camera
into world-space. However, it is more common to use the inverse of
``m`` to transform another object from world coordinates to the view
coordinates of the camera. Typically you would then apply the
camera projection transform to get from view to screen
coordinates.
.. versionadded:: 1.0
:param eye: the vector describing the position to look from
:param center: the vector describing the position to look at
:param up: the vector describing the world's upward direction; usually,
this is the :func:`~gi.repository.Graphene.Vec3.y_axis` vector
.. method:: init_ortho(left: float, right: float, top: float, bottom: float, z_near: float, z_far: float) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with an orthographic projection.
.. versionadded:: 1.0
:param left: the left edge of the clipping plane
:param right: the right edge of the clipping plane
:param top: the top edge of the clipping plane
:param bottom: the bottom edge of the clipping plane
:param z_near: the distance of the near clipping plane
:param z_far: the distance of the far clipping plane
.. method:: init_perspective(fovy: float, aspect: float, z_near: float, z_far: float) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with a perspective projection.
.. versionadded:: 1.0
:param fovy: the field of view angle, in degrees
:param aspect: the aspect value
:param z_near: the near Z plane
:param z_far: the far Z plane
.. method:: init_rotate(angle: float, axis: ~gi.repository.Graphene.Vec3) -> ~gi.repository.Graphene.Matrix
Initializes ``m`` to represent a rotation of ``angle`` degrees on
the axis represented by the ``axis`` vector.
.. versionadded:: 1.0
:param angle: the rotation angle, in degrees
:param axis: the axis vector as a :obj:`~gi.repository.Graphene.Vec3`
.. method:: init_scale(x: float, y: float, z: float) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with the given scaling factors.
.. versionadded:: 1.0
:param x: the scale factor on the X axis
:param y: the scale factor on the Y axis
:param z: the scale factor on the Z axis
.. method:: init_skew(x_skew: float, y_skew: float) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with a skew transformation
with the given factors.
.. versionadded:: 1.0
:param x_skew: skew factor, in radians, on the X axis
:param y_skew: skew factor, in radians, on the Y axis
.. method:: init_translate(p: ~gi.repository.Graphene.Point3D) -> ~gi.repository.Graphene.Matrix
Initializes a :obj:`~gi.repository.Graphene.Matrix` with a translation to the
given coordinates.
.. versionadded:: 1.0
:param p: the translation coordinates
.. method:: interpolate(b: ~gi.repository.Graphene.Matrix, factor: float) -> ~gi.repository.Graphene.Matrix
Linearly interpolates the two given :obj:`~gi.repository.Graphene.Matrix` by
interpolating the decomposed transformations separately.
If either matrix cannot be reduced to their transformations
then the interpolation cannot be performed, and this function
will return an identity matrix.
.. versionadded:: 1.0
:param b: a :obj:`~gi.repository.Graphene.Matrix`
:param factor: the linear interpolation factor
.. method:: inverse() -> ~typing.Tuple[bool, ~gi.repository.Graphene.Matrix]
Inverts the given matrix.
.. versionadded:: 1.0
.. method:: is_2d() -> bool
Checks whether the given :obj:`~gi.repository.Graphene.Matrix` is compatible with an
a 2D affine transformation matrix.
.. versionadded:: 1.0
.. method:: is_backface_visible() -> bool
Checks whether a :obj:`~gi.repository.Graphene.Matrix` has a visible back face.
.. versionadded:: 1.0
.. method:: is_identity() -> bool
Checks whether the given :obj:`~gi.repository.Graphene.Matrix` is the identity matrix.
.. versionadded:: 1.0
.. method:: is_singular() -> bool
Checks whether a matrix is singular.
.. versionadded:: 1.0
.. method:: multiply(b: ~gi.repository.Graphene.Matrix) -> ~gi.repository.Graphene.Matrix
Multiplies two :obj:`~gi.repository.Graphene.Matrix`\.
Matrix multiplication is not commutative in general; the order of the factors matters.
The product of this multiplication is (``a`` × ``b``\)
.. versionadded:: 1.0
:param b: a :obj:`~gi.repository.Graphene.Matrix`
.. method:: near(b: ~gi.repository.Graphene.Matrix, epsilon: float) -> bool
Compares the two given :obj:`~gi.repository.Graphene.Matrix` matrices and checks
whether their values are within the given ``epsilon`` of each
other.
.. versionadded:: 1.10
:param b: a :obj:`~gi.repository.Graphene.Matrix`
:param epsilon: the threshold between the two matrices
.. method:: normalize() -> ~gi.repository.Graphene.Matrix
Normalizes the given :obj:`~gi.repository.Graphene.Matrix`\.
.. versionadded:: 1.0
.. method:: perspective(depth: float) -> ~gi.repository.Graphene.Matrix
Applies a perspective of ``depth`` to the matrix.
.. versionadded:: 1.0
:param depth: the depth of the perspective
.. method:: print_() -> None
.. method:: project_point(p: ~gi.repository.Graphene.Point) -> ~gi.repository.Graphene.Point
Projects a :obj:`~gi.repository.Graphene.Point` using the matrix ``m``\.
.. versionadded:: 1.0
:param p: a :obj:`~gi.repository.Graphene.Point`
.. method:: project_rect(r: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Quad
Projects all corners of a :obj:`~gi.repository.Graphene.Rect` using the given matrix.
See also: :func:`~gi.repository.Graphene.Matrix.project_point`
.. versionadded:: 1.2
:param r: a :obj:`~gi.repository.Graphene.Rect`
.. method:: project_rect_bounds(r: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Rect
Projects a :obj:`~gi.repository.Graphene.Rect` using the given matrix.
The resulting rectangle is the axis aligned bounding rectangle capable
of fully containing the projected rectangle.
.. versionadded:: 1.0
:param r: a :obj:`~gi.repository.Graphene.Rect`
.. method:: rotate(angle: float, axis: ~gi.repository.Graphene.Vec3) -> None
Adds a rotation transformation to ``m``\, using the given ``angle``
and ``axis`` vector.
This is the equivalent of calling :func:`~gi.repository.Graphene.Matrix.init_rotate` and
then multiplying the matrix ``m`` with the rotation matrix.
.. versionadded:: 1.0
:param angle: the rotation angle, in degrees
:param axis: the rotation axis, as a :obj:`~gi.repository.Graphene.Vec3`
.. method:: rotate_euler(e: ~gi.repository.Graphene.Euler) -> None
Adds a rotation transformation to ``m``\, using the given
:obj:`~gi.repository.Graphene.Euler`\.
.. versionadded:: 1.2
:param e: a rotation described by a :obj:`~gi.repository.Graphene.Euler`
.. method:: rotate_quaternion(q: ~gi.repository.Graphene.Quaternion) -> None
Adds a rotation transformation to ``m``\, using the given
:obj:`~gi.repository.Graphene.Quaternion`\.
This is the equivalent of calling :func:`~gi.repository.Graphene.Quaternion.to_matrix` and
then multiplying ``m`` with the rotation matrix.
.. versionadded:: 1.2
:param q: a rotation described by a :obj:`~gi.repository.Graphene.Quaternion`
.. method:: rotate_x(angle: float) -> None
Adds a rotation transformation around the X axis to ``m``\, using
the given ``angle``\.
See also: :func:`~gi.repository.Graphene.Matrix.rotate`
.. versionadded:: 1.0
:param angle: the rotation angle, in degrees
.. method:: rotate_y(angle: float) -> None
Adds a rotation transformation around the Y axis to ``m``\, using
the given ``angle``\.
See also: :func:`~gi.repository.Graphene.Matrix.rotate`
.. versionadded:: 1.0
:param angle: the rotation angle, in degrees
.. method:: rotate_z(angle: float) -> None
Adds a rotation transformation around the Z axis to ``m``\, using
the given ``angle``\.
See also: :func:`~gi.repository.Graphene.Matrix.rotate`
.. versionadded:: 1.0
:param angle: the rotation angle, in degrees
.. method:: scale(factor_x: float, factor_y: float, factor_z: float) -> None
Adds a scaling transformation to ``m``\, using the three
given factors.
This is the equivalent of calling :func:`~gi.repository.Graphene.Matrix.init_scale` and then
multiplying the matrix ``m`` with the scale matrix.
.. versionadded:: 1.0
:param factor_x: scaling factor on the X axis
:param factor_y: scaling factor on the Y axis
:param factor_z: scaling factor on the Z axis
.. method:: skew_xy(factor: float) -> None
Adds a skew of ``factor`` on the X and Y axis to the given matrix.
.. versionadded:: 1.0
:param factor: skew factor
.. method:: skew_xz(factor: float) -> None
Adds a skew of ``factor`` on the X and Z axis to the given matrix.
.. versionadded:: 1.0
:param factor: skew factor
.. method:: skew_yz(factor: float) -> None
Adds a skew of ``factor`` on the Y and Z axis to the given matrix.
.. versionadded:: 1.0
:param factor: skew factor
.. method:: to_2d() -> ~typing.Tuple[bool, float, float, float, float, float, float]
Converts a :obj:`~gi.repository.Graphene.Matrix` to an affine transformation
matrix, if the given matrix is compatible.
The returned values have the following layout:
.. code-block:: plain
:dedent:
⎛ xx yx ⎞ ⎛ a b 0 ⎞
⎜ xy yy ⎟ = ⎜ c d 0 ⎟
⎝ x0 y0 ⎠ ⎝ tx ty 1 ⎠
This function can be used to convert between a :obj:`~gi.repository.Graphene.Matrix`
and an affine matrix type from other libraries.
.. versionadded:: 1.0
.. method:: to_float() -> list[float]
Converts a :obj:`~gi.repository.Graphene.Matrix` to an array of floating point
values.
.. versionadded:: 1.0
.. method:: transform_bounds(r: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Rect
Transforms each corner of a :obj:`~gi.repository.Graphene.Rect` using the given matrix ``m``\.
The result is the axis aligned bounding rectangle containing the coplanar
quadrilateral.
See also: :func:`~gi.repository.Graphene.Matrix.transform_point`
.. versionadded:: 1.0
:param r: a :obj:`~gi.repository.Graphene.Rect`
.. method:: transform_box(b: ~gi.repository.Graphene.Box) -> ~gi.repository.Graphene.Box
Transforms the vertices of a :obj:`~gi.repository.Graphene.Box` using the given matrix ``m``\.
The result is the axis aligned bounding box containing the transformed
vertices.
.. versionadded:: 1.2
:param b: a :obj:`~gi.repository.Graphene.Box`
.. method:: transform_point(p: ~gi.repository.Graphene.Point) -> ~gi.repository.Graphene.Point
Transforms the given :obj:`~gi.repository.Graphene.Point` using the matrix ``m``\.
Unlike :func:`~gi.repository.Graphene.Matrix.transform_vec3`, this function will take into
account the fourth row vector of the :obj:`~gi.repository.Graphene.Matrix` when computing
the dot product of each row vector of the matrix.
See also: graphene_simd4x4f_point3_mul()
.. versionadded:: 1.0
:param p: a :obj:`~gi.repository.Graphene.Point`
.. method:: transform_point3d(p: ~gi.repository.Graphene.Point3D) -> ~gi.repository.Graphene.Point3D
Transforms the given :obj:`~gi.repository.Graphene.Point3D` using the matrix ``m``\.
Unlike :func:`~gi.repository.Graphene.Matrix.transform_vec3`, this function will take into
account the fourth row vector of the :obj:`~gi.repository.Graphene.Matrix` when computing
the dot product of each row vector of the matrix.
See also: graphene_simd4x4f_point3_mul()
.. versionadded:: 1.2
:param p: a :obj:`~gi.repository.Graphene.Point3D`
.. method:: transform_ray(r: ~gi.repository.Graphene.Ray) -> ~gi.repository.Graphene.Ray
Transform a :obj:`~gi.repository.Graphene.Ray` using the given matrix ``m``\.
.. versionadded:: 1.4
:param r: a :obj:`~gi.repository.Graphene.Ray`
.. method:: transform_rect(r: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Quad
Transforms each corner of a :obj:`~gi.repository.Graphene.Rect` using the given matrix ``m``\.
The result is a coplanar quadrilateral.
See also: :func:`~gi.repository.Graphene.Matrix.transform_point`
.. versionadded:: 1.0
:param r: a :obj:`~gi.repository.Graphene.Rect`
.. method:: transform_sphere(s: ~gi.repository.Graphene.Sphere) -> ~gi.repository.Graphene.Sphere
Transforms a :obj:`~gi.repository.Graphene.Sphere` using the given matrix ``m``\. The
result is the bounding sphere containing the transformed sphere.
.. versionadded:: 1.2
:param s: a :obj:`~gi.repository.Graphene.Sphere`
.. method:: transform_vec3(v: ~gi.repository.Graphene.Vec3) -> ~gi.repository.Graphene.Vec3
Transforms the given :obj:`~gi.repository.Graphene.Vec3` using the matrix ``m``\.
This function will multiply the X, Y, and Z row vectors of the matrix ``m``
with the corresponding components of the vector ``v``\. The W row vector will
be ignored.
See also: graphene_simd4x4f_vec3_mul()
.. versionadded:: 1.0
:param v: a :obj:`~gi.repository.Graphene.Vec3`
.. method:: transform_vec4(v: ~gi.repository.Graphene.Vec4) -> ~gi.repository.Graphene.Vec4
Transforms the given :obj:`~gi.repository.Graphene.Vec4` using the matrix ``m``\.
See also: graphene_simd4x4f_vec4_mul()
.. versionadded:: 1.0
:param v: a :obj:`~gi.repository.Graphene.Vec4`
.. method:: translate(pos: ~gi.repository.Graphene.Point3D) -> None
Adds a translation transformation to ``m`` using the coordinates
of the given :obj:`~gi.repository.Graphene.Point3D`\.
This is the equivalent of calling :func:`~gi.repository.Graphene.Matrix.init_translate` and
then multiplying ``m`` with the translation matrix.
.. versionadded:: 1.0
:param pos: a :obj:`~gi.repository.Graphene.Point3D`
.. method:: transpose() -> ~gi.repository.Graphene.Matrix
Transposes the given matrix.
.. versionadded:: 1.0
.. method:: unproject_point3d(modelview: ~gi.repository.Graphene.Matrix, point: ~gi.repository.Graphene.Point3D) -> ~gi.repository.Graphene.Point3D
Unprojects the given ``point`` using the ``projection`` matrix and
a ``modelview`` matrix.
.. versionadded:: 1.2
:param modelview: a :obj:`~gi.repository.Graphene.Matrix` for the modelview matrix; this is
the inverse of the modelview used when projecting the point
:param point: a :obj:`~gi.repository.Graphene.Point3D` with the coordinates of the point
.. method:: untransform_bounds(r: ~gi.repository.Graphene.Rect, bounds: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Rect
Undoes the transformation on the corners of a :obj:`~gi.repository.Graphene.Rect` using the
given matrix, within the given axis aligned rectangular ``bounds``\.
.. versionadded:: 1.0
:param r: a :obj:`~gi.repository.Graphene.Rect`
:param bounds: the bounds of the transformation
.. method:: untransform_point(p: ~gi.repository.Graphene.Point, bounds: ~gi.repository.Graphene.Rect) -> ~typing.Tuple[bool, ~gi.repository.Graphene.Point]
Undoes the transformation of a :obj:`~gi.repository.Graphene.Point` using the
given matrix, within the given axis aligned rectangular ``bounds``\.
.. versionadded:: 1.0
:param p: a :obj:`~gi.repository.Graphene.Point`
:param bounds: the bounds of the transformation
Fields
------
.. rst-class:: interim-class
.. class:: Matrix
:no-index:
.. attribute:: value