About all my projects
NO_TITLE

NO_TITLE

Gnome::Graphene::N-Matrix

Description

A structure capable of holding a 4x4 matrix.

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

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

alloc

Allocates a new Gnome::Graphene::N-Matrix.

method alloc ( --> Gnome::Graphene::Matrix \)

Methods

decompose

Decomposes a transformation matrix into its component transformations.

The algorithm for decomposing a matrix is taken from the [CSS3 Transforms specification](http://dev.w3.org/csswg/css-transforms/); specifically, the decomposition code is based on the equivalent code published in "Graphics Gems II", edited by Jim Arvo, and [available online](http://tog.acm.org/resources/GraphicsGems/gemsii/unmatrix.c).

method decompose ( N-Object $translate, N-Object $scale, N-Object $rotate, N-Object $shear, N-Object $perspective --> gboolean )

  • $translate; the translation vector

  • $scale; the scale vector

  • $rotate; the rotation quaternion

  • $shear; the shear vector

  • $perspective; the perspective vector

Return value; true if the matrix could be decomposed.

determinant

Computes the determinant of the given matrix.

method determinant (--> Num )

Return value; the value of the determinant.

equal

Checks whether the two given Gnome::Graphene::N-Matrix matrices are equal.

method equal ( N-Object $b --> gboolean )

  • $b; a Gnome::Graphene::N-Matrix

Return value; true if the two matrices are equal, and false otherwise.

equal-fast

Checks whether the two given Gnome::Graphene::N-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:

method equal-fast ( N-Object $b --> gboolean )

  • $b; a Gnome::Graphene::N-Matrix

Return value; true if the matrices are equal. and false otherwise.

free

Frees the resources allocated by .alloc().

method free ( )

get-row This function is not yet available

Retrieves the given row vector at $index- inside a matrix.

method get-row ( …, N-Object $res )

  • index; the index of the row vector, between 0 and 3. Note that each argument must be specified as a type followed by its value!

  • $res; return location for the graphene_vec4_t that is used to store the row vector

get-value This function is not yet available

Retrieves the value at the given $row and $col index.

method get-value ( …, … --> Num )

  • row; the row index. Note that each argument must be specified as a type followed by its value!

  • col; the column index. Note that each argument must be specified as a type followed by its value!

Return value; the value at the given indices.

get-x-scale

Retrieves the scaling factor on the X axis in $m.

method get-x-scale (--> Num )

Return value; the value of the scaling factor.

get-x-translation

Retrieves the translation component on the X axis from $m.

method get-x-translation (--> Num )

Return value; the translation component.

get-y-scale

Retrieves the scaling factor on the Y axis in $m.

method get-y-scale (--> Num )

Return value; the value of the scaling factor.

get-y-translation

Retrieves the translation component on the Y axis from $m.

method get-y-translation (--> Num )

Return value; the translation component.

get-z-scale

Retrieves the scaling factor on the Z axis in $m.

method get-z-scale (--> Num )

Return value; the value of the scaling factor.

get-z-translation

Retrieves the translation component on the Z axis from $m.

method get-z-translation (--> Num )

Return value; the translation component.

init-from-2d

Initializes a Gnome::Graphene::N-Matrix from the values of an affine transformation matrix.

The arguments map to the following matrix layout:

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

method init-from-2d ( Num() $xx, Num() $yx, Num() $xy, Num() $yy, Num() $x0, Num() $y0 --> N-Object )

  • $xx; the xx member.

  • $yx; the yx member.

  • $xy; the xy member.

  • $yy; the yy member.

  • $x0; the x0 member.

  • $y0; the y0 member.

Return value; the initialized matrix.

init-from-float

Initializes a Gnome::Graphene::N-Matrix with the given array of floating point values.

method init-from-float ( Num() $v --> N-Object )

  • $v; an array of at least 16 floating point values.

Return value; the initialized matrix.

init-from-matrix

Initializes a Gnome::Graphene::N-Matrix using the values of the given matrix.

method init-from-matrix ( N-Object $src --> N-Object )

  • $src; a Gnome::Graphene::N-Matrix

Return value; the initialized matrix.

init-from-vec4

Initializes a Gnome::Graphene::N-Matrix with the given four row vectors.

method init-from-vec4 ( N-Object $v0, N-Object $v1, N-Object $v2, N-Object $v3 --> N-Object )

  • $v0; the first row vector

  • $v1; the second row vector

  • $v2; the third row vector

  • $v3; the fourth row vector

Return value; the initialized matrix.

init-frustum

Initializes a Gnome::Graphene::N-Matrix compatible with Gnome::Graphene::N-Frustum.

See also: graphene_frustum_init_from_matrix()

method init-frustum ( Num() $left, Num() $right, Num() $bottom, Num() $top, Num() $z-near, Num() $z-far --> N-Object )

  • $left; distance of the left clipping plane.

  • $right; distance of the right clipping plane.

  • $bottom; distance of the bottom clipping plane.

  • $top; distance of the top clipping plane.

  • $z-near; distance of the near clipping plane.

  • $z-far; distance of the far clipping plane.

Return value; the initialized matrix.

init-identity

Initializes a Gnome::Graphene::N-Matrix with the identity matrix.

method init-identity (--> N-Object )

Return value; the initialized matrix.

init-look-at

Initializes a Gnome::Graphene::N-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.

method init-look-at ( N-Object $eye, N-Object $center, N-Object $up --> N-Object )

  • $eye; the vector describing the position to look from

  • $center; the vector describing the position to look at

  • $up; the vector describing the world's upward direction; usually, this is the graphene_vec3_y_axis() vector

Return value; the initialized matrix.

init-ortho

Initializes a Gnome::Graphene::N-Matrix with an orthographic projection.

method init-ortho ( Num() $left, Num() $right, Num() $top, Num() $bottom, Num() $z-near, Num() $z-far --> N-Object )

  • $left; the left edge of the clipping plane.

  • $right; the right edge of the clipping plane.

  • $top; the top edge of the clipping plane.

  • $bottom; the bottom edge of the clipping plane.

  • $z-near; the distance of the near clipping plane.

  • $z-far; the distance of the far clipping plane.

Return value; the initialized matrix.

init-perspective

Initializes a Gnome::Graphene::N-Matrix with a perspective projection.

method init-perspective ( Num() $fovy, Num() $aspect, Num() $z-near, Num() $z-far --> N-Object )

  • $fovy; the field of view angle, in degrees.

  • $aspect; the aspect value.

  • $z-near; the near Z plane.

  • $z-far; the far Z plane.

Return value; the initialized matrix.

init-rotate

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

method init-rotate ( Num() $angle, N-Object $axis --> N-Object )

  • $angle; the rotation angle, in degrees.

  • $axis; the axis vector as a graphene_vec3_t

Return value; the initialized matrix.

init-scale

Initializes a Gnome::Graphene::N-Matrix with the given scaling factors.

method init-scale ( Num() $x, Num() $y, Num() $z --> N-Object )

  • $x; the scale factor on the X axis.

  • $y; the scale factor on the Y axis.

  • $z; the scale factor on the Z axis.

Return value; the initialized matrix.

init-skew

Initializes a Gnome::Graphene::N-Matrix with a skew transformation with the given factors.

method init-skew ( Num() $x-skew, Num() $y-skew --> N-Object )

  • $x-skew; skew factor, in radians, on the X axis.

  • $y-skew; skew factor, in radians, on the Y axis.

Return value; the initialized matrix.

init-translate

Initializes a Gnome::Graphene::N-Matrix with a translation to the given coordinates.

method init-translate ( N-Object $p --> N-Object )

  • $p; the translation coordinates

Return value; the initialized matrix.

interpolate

Linearly interpolates the two given Gnome::Graphene::N-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.

method interpolate ( N-Object $b, Num() $factor, N-Object $res )

  • $b; a Gnome::Graphene::N-Matrix

  • $factor; the linear interpolation factor.

  • $res; return location for the interpolated matrix

inverse

Inverts the given matrix.

method inverse ( N-Object $res --> gboolean )

  • $res; return location for the inverse matrix

Return value; true if the matrix is invertible.

is-2d

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

method is-2d (--> gboolean )

Return value; true if the matrix is compatible with an affine transformation matrix.

is-backface-visible

Checks whether a Gnome::Graphene::N-Matrix has a visible back face.

method is-backface-visible (--> gboolean )

Return value; true if the back face of the matrix is visible.

is-identity

Checks whether the given Gnome::Graphene::N-Matrix is the identity matrix.

method is-identity (--> gboolean )

Return value; true if the matrix is the identity matrix.

is-singular

Checks whether a matrix is singular.

method is-singular (--> gboolean )

Return value; true if the matrix is singular.

multiply

Multiplies two Gnome::Graphene::N-Matrix.

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

method multiply ( N-Object $b, N-Object $res )

  • $b; a Gnome::Graphene::N-Matrix

  • $res; return location for the matrix result

near

Compares the two given Gnome::Graphene::N-Matrix matrices and checks whether their values are within the given $epsilon of each other.

method near ( N-Object $b, Num() $epsilon --> gboolean )

  • $b; a Gnome::Graphene::N-Matrix

  • $epsilon; the threshold between the two matrices.

Return value; true if the two matrices are near each other, and false otherwise.

normalize

Normalizes the given Gnome::Graphene::N-Matrix.

method normalize ( N-Object $res )

  • $res; return location for the normalized matrix

perspective

Applies a perspective of $depth to the matrix.

method perspective ( Num() $depth, N-Object $res )

  • $depth; the depth of the perspective.

  • $res; return location for the perspective matrix

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.

method print ( )

project-point

Projects a Gnome::Graphene::N-Point using the matrix $m.

method project-point ( N-Object $p, N-Object $res )

  • $p; a Gnome::Graphene::N-Point

  • $res; return location for the projected point

project-rect

Projects all corners of a Gnome::Graphene::N-Rect using the given matrix.

See also: .project-point()

method project-rect ( N-Object $r, N-Object $res )

  • $r; a Gnome::Graphene::N-Rect

  • $res; return location for the projected rectangle

project-rect-bounds

Projects a Gnome::Graphene::N-Rect using the given matrix.

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

method project-rect-bounds ( N-Object $r, N-Object $res )

  • $r; a Gnome::Graphene::N-Rect

  • $res; return location for the projected rectangle

rotate

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

This is the equivalent of calling .init-rotate() and then multiplying the matrix $m with the rotation matrix.

method rotate ( Num() $angle, N-Object $axis )

  • $angle; the rotation angle, in degrees.

  • $axis; the rotation axis, as a graphene_vec3_t

rotate-euler

Adds a rotation transformation to $m, using the given Gnome::Graphene::N-Euler.

method rotate-euler ( N-Object $e )

  • $e; a rotation described by a Gnome::Graphene::N-Euler

rotate-quaternion

Adds a rotation transformation to $m, using the given Gnome::Graphene::N-Quaternion.

This is the equivalent of calling graphene_quaternion_to_matrix() and then multiplying $m with the rotation matrix.

method rotate-quaternion ( N-Object $q )

  • $q; a rotation described by a Gnome::Graphene::N-Quaternion

rotate-x

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

See also: .rotate()

method rotate-x ( Num() $angle )

  • $angle; the rotation angle, in degrees.

rotate-y

Adds a rotation transformation around the Y axis to $m, using the given $angle.

See also: .rotate()

method rotate-y ( Num() $angle )

  • $angle; the rotation angle, in degrees.

rotate-z

Adds a rotation transformation around the Z axis to $m, using the given $angle.

See also: .rotate()

method rotate-z ( Num() $angle )

  • $angle; the rotation angle, in degrees.

scale

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

This is the equivalent of calling .init-scale() and then multiplying the matrix $m with the scale matrix.

method scale ( Num() $factor-x, Num() $factor-y, Num() $factor-z )

  • $factor-x; scaling factor on the X axis.

  • $factor-y; scaling factor on the Y axis.

  • $factor-z; scaling factor on the Z axis.

skew-xy

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

method skew-xy ( Num() $factor )

  • $factor; skew factor.

skew-xz

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

method skew-xz ( Num() $factor )

  • $factor; skew factor.

skew-yz

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

method skew-yz ( Num() $factor )

  • $factor; skew factor.

to-2d

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

The returned values have the following layout:

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

method to-2d ( Num() $xx, Num() $yx, Num() $xy, Num() $yy, Num() $x0, Num() $y0 --> gboolean )

  • $xx; (transfer ownership: full) return location for the xx member.

  • $yx; (transfer ownership: full) return location for the yx member.

  • $xy; (transfer ownership: full) return location for the xy member.

  • $yy; (transfer ownership: full) return location for the yy member.

  • $x0; (transfer ownership: full) return location for the x0 member.

  • $y0; (transfer ownership: full) return location for the y0 member.

Return value; true if the matrix is compatible with an affine transformation matrix.

to-float

Converts a Gnome::Graphene::N-Matrix to an array of floating point values.

method to-float ( Num() $v )

  • $v; return location for an array of floating point values. The array must be capable of holding at least 16 values..

transform-bounds

Transforms each corner of a Gnome::Graphene::N-Rect using the given matrix $m.

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

See also: .transform-point()

method transform-bounds ( N-Object $r, N-Object $res )

  • $r; a Gnome::Graphene::N-Rect

  • $res; return location for the bounds of the transformed rectangle

transform-box

Transforms the vertices of a Gnome::Graphene::N-Box using the given matrix $m.

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

method transform-box ( N-Object $b, N-Object $res )

  • $b; a Gnome::Graphene::N-Box

  • $res; return location for the bounds of the transformed box

transform-point

Transforms the given Gnome::Graphene::N-Point using the matrix $m.

Unlike .transform-vec3(), this function will take into account the fourth row vector of the Gnome::Graphene::N-Matrix when computing the dot product of each row vector of the matrix.

See also: graphene_simd4x4f_point3_mul()

method transform-point ( N-Object $p, N-Object $res )

  • $p; a Gnome::Graphene::N-Point

  • $res; return location for the transformed Gnome::Graphene::N-Point

transform-point3d

Transforms the given graphene_point3d_t using the matrix $m.

Unlike .transform-vec3(), this function will take into account the fourth row vector of the Gnome::Graphene::N-Matrix when computing the dot product of each row vector of the matrix.

See also: graphene_simd4x4f_point3_mul()

method transform-point3d ( N-Object $p, N-Object $res )

  • $p; a graphene_point3d_t

  • $res; return location for the result

transform-ray

Transform a Gnome::Graphene::N-Ray using the given matrix $m.

method transform-ray ( N-Object $r, N-Object $res )

  • $r; a Gnome::Graphene::N-Ray

  • $res; return location for the transformed ray

transform-rect

Transforms each corner of a Gnome::Graphene::N-Rect using the given matrix $m.

The result is a coplanar quadrilateral.

See also: .transform-point()

method transform-rect ( N-Object $r, N-Object $res )

  • $r; a Gnome::Graphene::N-Rect

  • $res; return location for the transformed quad

transform-sphere

Transforms a Gnome::Graphene::N-Sphere using the given matrix $m. The result is the bounding sphere containing the transformed sphere.

method transform-sphere ( N-Object $s, N-Object $res )

  • $s; a Gnome::Graphene::N-Sphere

  • $res; return location for the bounds of the transformed sphere

transform-vec3

Transforms the given graphene_vec3_t 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()

method transform-vec3 ( N-Object $v, N-Object $res )

  • $v; a graphene_vec3_t

  • $res; return location for a graphene_vec3_t

transform-vec4

Transforms the given graphene_vec4_t using the matrix $m.

See also: graphene_simd4x4f_vec4_mul()

method transform-vec4 ( N-Object $v, N-Object $res )

  • $v; a graphene_vec4_t

  • $res; return location for a graphene_vec4_t

translate

Adds a translation transformation to $m using the coordinates of the given graphene_point3d_t.

This is the equivalent of calling .init-translate() and then multiplying $m with the translation matrix.

method translate ( N-Object $pos )

  • $pos; a graphene_point3d_t

transpose

Transposes the given matrix.

method transpose ( N-Object $res )

  • $res; return location for the transposed matrix

unproject-point3d

Unprojects the given $point using the $projection matrix and a $modelview matrix.

method unproject-point3d ( N-Object $modelview, N-Object $point, N-Object $res )

  • $modelview; a Gnome::Graphene::N-Matrix for the modelview matrix; this is the inverse of the modelview used when projecting the point

  • $point; a graphene_point3d_t with the coordinates of the point

  • $res; return location for the unprojected point

untransform-bounds

Undoes the transformation on the corners of a Gnome::Graphene::N-Rect using the given matrix, within the given axis aligned rectangular $bounds.

method untransform-bounds ( N-Object $r, N-Object $bounds, N-Object $res )

  • $r; a Gnome::Graphene::N-Rect

  • $bounds; the bounds of the transformation

  • $res; return location for the untransformed rectangle

untransform-point

Undoes the transformation of a Gnome::Graphene::N-Point using the given matrix, within the given axis aligned rectangular $bounds.

method untransform-point ( N-Object $p, N-Object $bounds, N-Object $res --> gboolean )

  • $p; a Gnome::Graphene::N-Point

  • $bounds; the bounds of the transformation

  • $res; return location for the untransformed point

Return value; true if the point was successfully untransformed.