Graphene.Matrix¶

Fields¶

Name	Type	Access	Description
value	`Graphene.Simd4X4F`	r

Methods¶

class	`alloc` ()
	`decompose` ()
	`determinant` ()
	`equal` (b)
	`equal_fast` (b)
	`free` ()
	`get_row` (index_)
	`get_value` (row, col)
	`get_x_scale` ()
	`get_x_translation` ()
	`get_y_scale` ()
	`get_y_translation` ()
	`get_z_scale` ()
	`get_z_translation` ()
	`init_from_2d` (xx, yx, xy, yy, x_0, y_0)
	`init_from_float` (v)
	`init_from_matrix` (src)
	`init_from_vec4` (v0, v1, v2, v3)
	`init_frustum` (left, right, bottom, top, z_near, z_far)
	`init_identity` ()
	`init_look_at` (eye, center, up)
	`init_ortho` (left, right, top, bottom, z_near, z_far)
	`init_perspective` (fovy, aspect, z_near, z_far)
	`init_rotate` (angle, axis)
	`init_scale` (x, y, z)
	`init_skew` (x_skew, y_skew)
	`init_translate` (p)
	`interpolate` (b, factor)
	`inverse` ()
	`is_2d` ()
	`is_backface_visible` ()
	`is_identity` ()
	`is_singular` ()
	`multiply` (b)
	`near` (b, epsilon)
	`normalize` ()
	`perspective` (depth)
	`print_` ()
	`project_point` (p)
	`project_rect` (r)
	`project_rect_bounds` (r)
	`rotate` (angle, axis)
	`rotate_euler` (e)
	`rotate_quaternion` (q)
	`rotate_x` (angle)
	`rotate_y` (angle)
	`rotate_z` (angle)
	`scale` (factor_x, factor_y, factor_z)
	`skew_xy` (factor)
	`skew_xz` (factor)
	`skew_yz` (factor)
	`to_2d` ()
	`to_float` ()
	`transform_bounds` (r)
	`transform_box` (b)
	`transform_point` (p)
	`transform_point3d` (p)
	`transform_ray` (r)
	`transform_rect` (r)
	`transform_sphere` (s)
	`transform_vec3` (v)
	`transform_vec4` (v)
	`translate` (pos)
	`transpose` ()
	`unproject_point3d` (modelview, point)
	`untransform_bounds` (r, bounds)
	`untransform_point` (p, bounds)

Details¶

class Graphene.Matrix¶

A structure capable of holding a 4x4 matrix.

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

classmethod alloc()¶

Returns:: the newly allocated matrix
Return type:: Graphene.Matrix

Allocates a new Graphene.Matrix.

New in version 1.0.

decompose()¶

Returns:

true if the matrix could be decomposed

translate:: the translation vector
scale:: the scale vector
rotate:: the rotation quaternion
shear:: the shear vector
perspective:: the perspective vector

Return type:

(bool, translate: Graphene.Vec3, scale: Graphene.Vec3, rotate: Graphene.Quaternion, shear: Graphene.Vec3, perspective: 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.

determinant()¶

Returns:: the value of the determinant
Return type:: float

Computes the determinant of the given matrix.

New in version 1.0.

equal(b)¶

Parameters:: b (Graphene.Matrix) – a Graphene.Matrix
Returns:: true if the two matrices are equal, and false otherwise
Return type:: bool

Checks whether the two given Graphene.Matrix matrices are equal.

New in version 1.10.

equal_fast(b)¶

Parameters:: b (Graphene.Matrix) – a Graphene.Matrix
Returns:: true if the matrices are equal. and false otherwise
Return type:: bool

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

While this function is faster than Graphene.Matrix.equal(), it can also return false negatives, so it should be used in conjuction with either Graphene.Matrix.equal() or Graphene.Matrix.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
  }

New in version 1.10.

free()¶: Frees the resources allocated by Graphene.Matrix.alloc().

New in version 1.0.

get_row(index_)¶

Parameters:: index (int) – the index of the row vector, between 0 and 3
Returns:: return location for the Graphene.Vec4 that is used to store the row vector
Return type:: res: Graphene.Vec4

Retrieves the given row vector at index_ inside a matrix.

New in version 1.0.

get_value(row, col)¶

Parameters:

row (int) – the row index
col (int) – the column index

Returns:

the value at the given indices

Return type:

float

Retrieves the value at the given row and col index.

New in version 1.0.

get_x_scale()¶

Returns:: the value of the scaling factor
Return type:: float

Retrieves the scaling factor on the X axis in self.

New in version 1.0.

get_x_translation()¶

Returns:: the translation component
Return type:: float

Retrieves the translation component on the X axis from self.

New in version 1.10.

get_y_scale()¶

Returns:: the value of the scaling factor
Return type:: float

Retrieves the scaling factor on the Y axis in self.

New in version 1.0.

get_y_translation()¶

Returns:: the translation component
Return type:: float

Retrieves the translation component on the Y axis from self.

New in version 1.10.

get_z_scale()¶

Returns:: the value of the scaling factor
Return type:: float

Retrieves the scaling factor on the Z axis in self.

New in version 1.0.

get_z_translation()¶

Returns:: the translation component
Return type:: float

Retrieves the translation component on the Z axis from self.

New in version 1.10.

init_from_2d(xx, yx, xy, yy, x_0, y_0)¶

Parameters:

xx (float) – the xx member
yx (float) – the yx member
xy (float) – the xy member
yy (float) – the yy member
x_0 (float) – the x0 member
y_0 (float) – the y0 member

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.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 Graphene.Matrix.

New in version 1.0.

init_from_float(v)¶

Parameters:: v ([float]) – an array of at least 16 floating point values
Returns:: the initialized matrix
Return type:: Graphene.Matrix

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

New in version 1.0.

init_from_matrix(src)¶

Parameters:: src (Graphene.Matrix) – a Graphene.Matrix
Returns:: the initialized matrix
Return type:: Graphene.Matrix

Initializes a Graphene.Matrix using the values of the given matrix.

New in version 1.0.

init_from_vec4(v0, v1, v2, v3)¶

Parameters:

v0 (Graphene.Vec4) – the first row vector
v1 (Graphene.Vec4) – the second row vector
v2 (Graphene.Vec4) – the third row vector
v3 (Graphene.Vec4) – the fourth row vector

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.Matrix with the given four row vectors.

New in version 1.0.

init_frustum(left, right, bottom, top, z_near, z_far)¶

Parameters:

left (float) – distance of the left clipping plane
right (float) – distance of the right clipping plane
bottom (float) – distance of the bottom clipping plane
top (float) – distance of the top clipping plane
z_near (float) – distance of the near clipping plane
z_far (float) – distance of the far clipping plane

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.Matrix compatible with Graphene.Frustum.

New in version 1.2.

init_identity()¶

Returns:: the initialized matrix
Return type:: Graphene.Matrix

Initializes a Graphene.Matrix with the identity matrix.

New in version 1.0.

init_look_at(eye, center, up)¶

Parameters:

eye (Graphene.Vec3) – the vector describing the position to look from
center (Graphene.Vec3) – the vector describing the position to look at
up (Graphene.Vec3) – the vector describing the world’s upward direction; usually, this is the Graphene.Vec3.y_axis() vector

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a 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 self to transform a model of such a camera into world-space. However, it is more common to use the inverse of self 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.

New in version 1.0.

init_ortho(left, right, top, bottom, z_near, z_far)¶

Parameters:

left (float) – the left edge of the clipping plane
right (float) – the right edge of the clipping plane
top (float) – the top edge of the clipping plane
bottom (float) – the bottom edge of the clipping plane
z_near (float) – the distance of the near clipping plane
z_far (float) – the distance of the far clipping plane

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.Matrix with an orthographic projection.

New in version 1.0.

init_perspective(fovy, aspect, z_near, z_far)¶

Parameters:

fovy (float) – the field of view angle, in degrees
aspect (float) – the aspect value
z_near (float) – the near Z plane
z_far (float) – the far Z plane

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.Matrix with a perspective projection.

New in version 1.0.

init_rotate(angle, axis)¶

Parameters:

angle (float) – the rotation angle, in degrees
axis (Graphene.Vec3) – the axis vector as a Graphene.Vec3

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes self to represent a rotation of angle degrees on the axis represented by the axis vector.

New in version 1.0.

init_scale(x, y, z)¶

Parameters:

x (float) – the scale factor on the X axis
y (float) – the scale factor on the Y axis
z (float) – the scale factor on the Z axis

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.Matrix with the given scaling factors.

New in version 1.0.

init_skew(x_skew, y_skew)¶

Parameters:

x_skew (float) – skew factor, in radians, on the X axis
y_skew (float) – skew factor, in radians, on the Y axis

Returns:

the initialized matrix

Return type:

Graphene.Matrix

Initializes a Graphene.Matrix with a skew transformation with the given factors.

New in version 1.0.

init_translate(p)¶

Parameters:: p (Graphene.Point3D) – the translation coordinates
Returns:: the initialized matrix
Return type:: Graphene.Matrix

Initializes a Graphene.Matrix with a translation to the given coordinates.

New in version 1.0.

interpolate(b, factor)¶

Parameters:

b (Graphene.Matrix) – a Graphene.Matrix
factor (float) – the linear interpolation factor

Returns:

return location for the interpolated matrix

Return type:

res: Graphene.Matrix

Linearly interpolates the two given 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.

New in version 1.0.

inverse()¶

Returns:

true if the matrix is invertible

res:: return location for the inverse matrix

Return type:

(bool, res: Graphene.Matrix)

Inverts the given matrix.

New in version 1.0.

is_2d()¶

Returns:: true if the matrix is compatible with an affine transformation matrix
Return type:: bool

Checks whether the given Graphene.Matrix is compatible with an a 2D affine transformation matrix.

New in version 1.0.

is_backface_visible()¶

Returns:: true if the back face of the matrix is visible
Return type:: bool

Checks whether a Graphene.Matrix has a visible back face.

New in version 1.0.

is_identity()¶

Returns:: true if the matrix is the identity matrix
Return type:: bool

Checks whether the given Graphene.Matrix is the identity matrix.

New in version 1.0.

is_singular()¶

Returns:: true if the matrix is singular
Return type:: bool

Checks whether a matrix is singular.

New in version 1.0.

multiply(b)¶

Parameters:: b (Graphene.Matrix) – a Graphene.Matrix
Returns:: return location for the matrix result
Return type:: res: Graphene.Matrix

Multiplies two Graphene.Matrix.

Matrix multiplication is not commutative in general; the order of the factors matters. The product of this multiplication is (self × b)

New in version 1.0.

near(b, epsilon)¶

Parameters:

b (Graphene.Matrix) – a Graphene.Matrix
epsilon (float) – the threshold between the two matrices

Returns:

true if the two matrices are near each other, and false otherwise

Return type:

bool

Compares the two given Graphene.Matrix matrices and checks whether their values are within the given epsilon of each other.

New in version 1.10.

normalize()¶

Returns:: return location for the normalized matrix
Return type:: res: Graphene.Matrix

Normalizes the given Graphene.Matrix.

New in version 1.0.

perspective(depth)¶

Parameters:: depth (float) – the depth of the perspective
Returns:: return location for the perspective matrix
Return type:: res: Graphene.Matrix

Applies a perspective of depth to the matrix.

New in version 1.0.

print_()¶

Prints the contents of a matrix to the standard error stream.

This function is only useful for debugging; there are no guarantees made on the format of the output.

New in version 1.0.

project_point(p)¶

Parameters:: p (Graphene.Point) – a Graphene.Point
Returns:: return location for the projected point
Return type:: res: Graphene.Point

Projects a Graphene.Point using the matrix self.

New in version 1.0.

project_rect(r)¶

Parameters:: r (Graphene.Rect) – a Graphene.Rect
Returns:: return location for the projected rectangle
Return type:: res: Graphene.Quad

Projects all corners of a Graphene.Rect using the given matrix.

New in version 1.2.

project_rect_bounds(r)¶

Parameters:: r (Graphene.Rect) – a Graphene.Rect
Returns:: return location for the projected rectangle
Return type:: res: Graphene.Rect

Projects a Graphene.Rect using the given matrix.

The resulting rectangle is the axis aligned bounding rectangle capable of fully containing the projected rectangle.

New in version 1.0.

rotate(angle, axis)¶

Parameters:

angle (float) – the rotation angle, in degrees
axis (Graphene.Vec3) – the rotation axis, as a Graphene.Vec3

Adds a rotation transformation to self, using the given angle and axis vector.

This is the equivalent of calling Graphene.Matrix.init_rotate() and then multiplying the matrix self with the rotation matrix.

New in version 1.0.

rotate_euler(e)¶

Parameters:: e (Graphene.Euler) – a rotation described by a Graphene.Euler

Adds a rotation transformation to self, using the given Graphene.Euler.

New in version 1.2.

rotate_quaternion(q)¶

Parameters:: q (Graphene.Quaternion) – a rotation described by a Graphene.Quaternion

Adds a rotation transformation to self, using the given Graphene.Quaternion.

This is the equivalent of calling Graphene.Quaternion.to_matrix() and then multiplying self with the rotation matrix.

New in version 1.2.

rotate_x(angle)¶

Parameters:: angle (float) – the rotation angle, in degrees

Adds a rotation transformation around the X axis to self, using the given angle.

See also: Graphene.Matrix.rotate()

New in version 1.0.

scale(factor_x, factor_y, factor_z)¶

Parameters:

factor_x (float) – scaling factor on the X axis
factor_y (float) – scaling factor on the Y axis
factor_z (float) – scaling factor on the Z axis

Adds a scaling transformation to self, using the three given factors.

This is the equivalent of calling Graphene.Matrix.init_scale() and then multiplying the matrix self with the scale matrix.

New in version 1.0.

skew_xy(factor)¶

Parameters:: factor (float) – skew factor

Adds a skew of factor on the X and Y axis to the given matrix.

New in version 1.0.

skew_xz(factor)¶

Parameters:: factor (float) – skew factor

Adds a skew of factor on the X and Z axis to the given matrix.

New in version 1.0.

skew_yz(factor)¶

Parameters:: factor (float) – skew factor

Adds a skew of factor on the Y and Z axis to the given matrix.

New in version 1.0.

to_2d()¶

Returns:

true if the matrix is compatible with an affine transformation matrix

xx:: return location for the xx member
yx:: return location for the yx member
xy:: return location for the xy member
yy:: return location for the yy member
x_0:: return location for the x0 member
y_0:: return location for the y0 member

Return type:

(bool, xx: float, yx: float, xy: float, yy: float, x_0: float, y_0: float)

Converts a Graphene.Matrix to an affine transformation matrix, if the given matrix is compatible.

The returned values have the following layout:

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

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

New in version 1.0.

to_float()¶

Returns:: return location for an array of floating point values. The array must be capable of holding at least 16 values.
Return type:: v: [float]

Converts a Graphene.Matrix to an array of floating point values.

New in version 1.0.

transform_bounds(r)¶

Parameters:: r (Graphene.Rect) – a Graphene.Rect
Returns:: return location for the bounds of the transformed rectangle
Return type:: res: Graphene.Rect

Transforms each corner of a Graphene.Rect using the given matrix self.

The result is the axis aligned bounding rectangle containing the coplanar quadrilateral.

New in version 1.0.

transform_box(b)¶

Parameters:: b (Graphene.Box) – a Graphene.Box
Returns:: return location for the bounds of the transformed box
Return type:: res: Graphene.Box

Transforms the vertices of a Graphene.Box using the given matrix self.

The result is the axis aligned bounding box containing the transformed vertices.

New in version 1.2.

transform_point(p)¶

Parameters:: p (Graphene.Point) – a Graphene.Point
Returns:: return location for the transformed Graphene.Point
Return type:: res: Graphene.Point

Transforms the given Graphene.Point using the matrix self.

Unlike Graphene.Matrix.transform_vec3(), this function will take into account the fourth row vector of the Graphene.Matrix when computing the dot product of each row vector of the matrix.

See also: graphene_simd4x4f_point3_mul()

New in version 1.0.

transform_point3d(p)¶

Parameters:: p (Graphene.Point3D) – a Graphene.Point3D
Returns:: return location for the result
Return type:: res: Graphene.Point3D

Transforms the given Graphene.Point3D using the matrix self.

Unlike Graphene.Matrix.transform_vec3(), this function will take into account the fourth row vector of the Graphene.Matrix when computing the dot product of each row vector of the matrix.

See also: graphene_simd4x4f_point3_mul()

New in version 1.2.

transform_ray(r)¶

Parameters:: r (Graphene.Ray) – a Graphene.Ray
Returns:: return location for the transformed ray
Return type:: res: Graphene.Ray

Transform a Graphene.Ray using the given matrix self.

New in version 1.4.

transform_rect(r)¶

Parameters:: r (Graphene.Rect) – a Graphene.Rect
Returns:: return location for the transformed quad
Return type:: res: Graphene.Quad

Transforms each corner of a Graphene.Rect using the given matrix self.

The result is a coplanar quadrilateral.

New in version 1.0.

transform_sphere(s)¶

Parameters:: s (Graphene.Sphere) – a Graphene.Sphere
Returns:: return location for the bounds of the transformed sphere
Return type:: res: Graphene.Sphere

Transforms a Graphene.Sphere using the given matrix self. The result is the bounding sphere containing the transformed sphere.

New in version 1.2.

transform_vec3(v)¶

Parameters:: v (Graphene.Vec3) – a Graphene.Vec3
Returns:: return location for a Graphene.Vec3
Return type:: res: Graphene.Vec3

Transforms the given Graphene.Vec3 using the matrix self.

This function will multiply the X, Y, and Z row vectors of the matrix self with the corresponding components of the vector v. The W row vector will be ignored.