Package ch.bailu.gtk.graphene

Class Matrix

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.type.Record
ch.bailu.gtk.graphene.Matrix
All Implemented Interfaces:
PointerInterface
public class Matrix extends Record
A structure capable of holding a 4x4 matrix.

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

https://ebassi.github.io/graphene/docs/

  • Constructor Details

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • allocMatrix

      public static Matrix allocMatrix()
      Allocates a new #graphene_matrix_t.
      Returns:
      the newly allocated matrix

    • decompose

      public boolean decompose(@Nonnull Vec3 translate, @Nonnull Vec3 scale, @Nonnull Quaternion rotate, @Nonnull Vec3 shear, @Nonnull Vec4 perspective)
      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://web.archive.org/web/20150512160205/http://tog.acm.org/resources/GraphicsGems/gemsii/unmatrix.c).
      Parameters:
      translate - the translation vector
      scale - the scale vector
      rotate - the rotation quaternion
      shear - the shear vector
      perspective - the perspective vector
      Returns:
      `true` if the matrix could be decomposed

    • determinant

      public float determinant()
      Computes the determinant of the given matrix.
      Returns:
      the value of the determinant

    • equal

      public boolean equal(@Nonnull Matrix b)
      Checks whether the two given #graphene_matrix_t matrices are equal.
      Parameters:
      b - a #graphene_matrix_t
      Returns:
      `true` if the two matrices are equal, and `false` otherwise

    • equalFast

      public boolean equalFast(@Nonnull Matrix b)
      Checks whether the two given #graphene_matrix_t 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: 
      <!-- language="C" -->
   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
     }
      Parameters:
      b - a #graphene_matrix_t
      Returns:
      `true` if the matrices are equal. and `false` otherwise

    • free

      public void free()
      Frees the resources allocated by graphene_matrix_alloc().

    • getXScale

      public float getXScale()
      Retrieves the scaling factor on the X axis in @m.
      Returns:
      the value of the scaling factor

    • getXTranslation

      public float getXTranslation()
      Retrieves the translation component on the X axis from @m.
      Returns:
      the translation component

    • getYScale

      public float getYScale()
      Retrieves the scaling factor on the Y axis in @m.
      Returns:
      the value of the scaling factor

    • getYTranslation

      public float getYTranslation()
      Retrieves the translation component on the Y axis from @m.
      Returns:
      the translation component

    • getZScale

      public float getZScale()
      Retrieves the scaling factor on the Z axis in @m.
      Returns:
      the value of the scaling factor

    • getZTranslation

      public float getZTranslation()
      Retrieves the translation component on the Z axis from @m.
      Returns:
      the translation component

    • initFrom2d

      public Matrix initFrom2d(double xx, double yx, double xy, double yy, double x_0, double y_0)
      Initializes a #graphene_matrix_t from the values of an affine
      transformation matrix.

      The arguments map to the following matrix layout: 
      <!-- language="plain" -->
   ⎛ 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_t.
      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
      Returns:
      the initialized matrix

    • initFromMatrix

      public Matrix initFromMatrix(@Nonnull Matrix src)
      Initializes a #graphene_matrix_t using the values of the
      given matrix.
      Parameters:
      src - a #graphene_matrix_t
      Returns:
      the initialized matrix

    • initFromVec4

      public Matrix initFromVec4(@Nonnull Vec4 v0, @Nonnull Vec4 v1, @Nonnull Vec4 v2, @Nonnull Vec4 v3)
      Initializes a #graphene_matrix_t with the given four row
      vectors.
      Parameters:
      v0 - the first row vector
      v1 - the second row vector
      v2 - the third row vector
      v3 - the fourth row vector
      Returns:
      the initialized matrix

    • initFrustum

      public Matrix initFrustum(float left, float right, float bottom, float top, float z_near, float z_far)
      Initializes a #graphene_matrix_t compatible with #graphene_frustum_t.

      See also: graphene_frustum_init_from_matrix()
      Parameters:
      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
      Returns:
      the initialized matrix

    • initIdentity

      public Matrix initIdentity()
      Initializes a #graphene_matrix_t with the identity matrix.
      Returns:
      the initialized matrix

    • initLookAt

      public Matrix initLookAt(@Nonnull Vec3 eye, @Nonnull Vec3 center, @Nonnull Vec3 up)
      Initializes a #graphene_matrix_t 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.
      Parameters:
      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
      Returns:
      the initialized matrix

    • initOrtho

      public Matrix initOrtho(float left, float right, float top, float bottom, float z_near, float z_far)
      Initializes a #graphene_matrix_t with an orthographic projection.
      Parameters:
      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
      Returns:
      the initialized matrix

    • initPerspective

      public Matrix initPerspective(float fovy, float aspect, float z_near, float z_far)
      Initializes a #graphene_matrix_t with a perspective projection.
      Parameters:
      fovy - the field of view angle, in degrees
      aspect - the aspect value
      z_near - the near Z plane
      z_far - the far Z plane
      Returns:
      the initialized matrix

    • initRotate

      public Matrix initRotate(float angle, @Nonnull Vec3 axis)
      Initializes @m to represent a rotation of @angle degrees on
      the axis represented by the @axis vector.
      Parameters:
      angle - the rotation angle, in degrees
      axis - the axis vector as a #graphene_vec3_t
      Returns:
      the initialized matrix

    • initScale

      public Matrix initScale(float x, float y, float z)
      Initializes a #graphene_matrix_t with the given scaling factors.
      Parameters:
      x - the scale factor on the X axis
      y - the scale factor on the Y axis
      z - the scale factor on the Z axis
      Returns:
      the initialized matrix

    • initSkew

      public Matrix initSkew(float x_skew, float y_skew)
      Initializes a #graphene_matrix_t with a skew transformation
      with the given factors.
      Parameters:
      x_skew - skew factor, in radians, on the X axis
      y_skew - skew factor, in radians, on the Y axis
      Returns:
      the initialized matrix

    • initTranslate

      public Matrix initTranslate(@Nonnull Point3D p)
      Initializes a #graphene_matrix_t with a translation to the
      given coordinates.
      Parameters:
      p - the translation coordinates
      Returns:
      the initialized matrix

    • interpolate

      public void interpolate(@Nonnull Matrix b, double factor, @Nonnull Matrix res)
      Linearly interpolates the two given #graphene_matrix_t 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.
      Parameters:
      b - a #graphene_matrix_t
      factor - the linear interpolation factor
      res - return location for the interpolated matrix

    • inverse

      public boolean inverse(@Nonnull Matrix res)
      Inverts the given matrix.
      Parameters:
      res - return location for the inverse matrix
      Returns:
      `true` if the matrix is invertible

    • is2d

      public boolean is2d()
      Checks whether the given #graphene_matrix_t is compatible with an
      a 2D affine transformation matrix.
      Returns:
      `true` if the matrix is compatible with an affine transformation matrix

    • isBackfaceVisible

      public boolean isBackfaceVisible()
      Checks whether a #graphene_matrix_t has a visible back face.
      Returns:
      `true` if the back face of the matrix is visible

    • isIdentity

      public boolean isIdentity()
      Checks whether the given #graphene_matrix_t is the identity matrix.
      Returns:
      `true` if the matrix is the identity matrix

    • isSingular

      public boolean isSingular()
      Checks whether a matrix is singular.
      Returns:
      `true` if the matrix is singular

    • multiply

      public void multiply(@Nonnull Matrix b, @Nonnull Matrix res)
      Multiplies two #graphene_matrix_t.

      Matrix multiplication is not commutative in general; the order of the factors matters.
      The product of this multiplication is (@a × @b)
      Parameters:
      b - a #graphene_matrix_t
      res - return location for the matrix result

    • near

      public boolean near(@Nonnull Matrix b, float epsilon)
      Compares the two given #graphene_matrix_t matrices and checks
      whether their values are within the given @epsilon of each
      other.
      Parameters:
      b - a #graphene_matrix_t
      epsilon - the threshold between the two matrices
      Returns:
      `true` if the two matrices are near each other, and `false` otherwise

    • normalize

      public void normalize(@Nonnull Matrix res)
      Normalizes the given #graphene_matrix_t.
      Parameters:
      res - return location for the normalized matrix

    • perspective

      public void perspective(float depth, @Nonnull Matrix res)
      Applies a perspective of @depth to the matrix.
      Parameters:
      depth - the depth of the perspective
      res - return location for the perspective matrix

    • print

      public void 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.

    • projectPoint

      public void projectPoint(@Nonnull Point p, @Nonnull Point res)
      Projects a #graphene_point_t using the matrix @m.
      Parameters:
      p - a #graphene_point_t
      res - return location for the projected point

    • projectRect

      public void projectRect(@Nonnull Rect r, @Nonnull Quad res)
      Projects all corners of a #graphene_rect_t using the given matrix.

      See also: graphene_matrix_project_point()
      Parameters:
      r - a #graphene_rect_t
      res - return location for the projected rectangle

    • projectRectBounds

      public void projectRectBounds(@Nonnull Rect r, @Nonnull Rect res)
      Projects a #graphene_rect_t using the given matrix.

      The resulting rectangle is the axis aligned bounding rectangle capable
      of fully containing the projected rectangle.
      Parameters:
      r - a #graphene_rect_t
      res - return location for the projected rectangle

    • rotate

      public void rotate(float angle, @Nonnull Vec3 axis)
      Adds a rotation transformation to @m, using the given @angle
      and @axis vector.

      This is the equivalent of calling graphene_matrix_init_rotate() and
      then multiplying the matrix @m with the rotation matrix.
      Parameters:
      angle - the rotation angle, in degrees
      axis - the rotation axis, as a #graphene_vec3_t

    • rotateEuler

      public void rotateEuler(@Nonnull Euler e)
      Adds a rotation transformation to @m, using the given
      #graphene_euler_t.
      Parameters:
      e - a rotation described by a #graphene_euler_t

    • rotateQuaternion

      public void rotateQuaternion(@Nonnull Quaternion q)
      Adds a rotation transformation to @m, using the given
      #graphene_quaternion_t.

      This is the equivalent of calling graphene_quaternion_to_matrix() and
      then multiplying @m with the rotation matrix.
      Parameters:
      q - a rotation described by a #graphene_quaternion_t

    • rotateX

      public void rotateX(float angle)
      Adds a rotation transformation around the X axis to @m, using
      the given @angle.

      See also: graphene_matrix_rotate()
      Parameters:
      angle - the rotation angle, in degrees

    • rotateY

      public void rotateY(float angle)
      Adds a rotation transformation around the Y axis to @m, using
      the given @angle.

      See also: graphene_matrix_rotate()
      Parameters:
      angle - the rotation angle, in degrees

    • rotateZ

      public void rotateZ(float angle)
      Adds a rotation transformation around the Z axis to @m, using
      the given @angle.

      See also: graphene_matrix_rotate()
      Parameters:
      angle - the rotation angle, in degrees

    • scale

      public void scale(float factor_x, float factor_y, float factor_z)
      Adds a scaling transformation to @m, using the three
      given factors.

      This is the equivalent of calling graphene_matrix_init_scale() and then
      multiplying the matrix @m with the scale matrix.
      Parameters:
      factor_x - scaling factor on the X axis
      factor_y - scaling factor on the Y axis
      factor_z - scaling factor on the Z axis

    • skewXy

      public void skewXy(float factor)
      Adds a skew of @factor on the X and Y axis to the given matrix.
      Parameters:
      factor - skew factor

    • skewXz

      public void skewXz(float factor)
      Adds a skew of @factor on the X and Z axis to the given matrix.
      Parameters:
      factor - skew factor

    • skewYz

      public void skewYz(float factor)
      Adds a skew of @factor on the Y and Z axis to the given matrix.
      Parameters:
      factor - skew factor

    • toFloat

      public void toFloat(@Nonnull Flt v)
      Converts a #graphene_matrix_t to an array of floating point
      values.
      Parameters:
      v - return location for an array of floating point values. The array must be capable of holding at least 16 values.

    • transformBounds

      public void transformBounds(@Nonnull Rect r, @Nonnull Rect res)
      Transforms each corner of a #graphene_rect_t using the given matrix @m.

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

      See also: graphene_matrix_transform_point()
      Parameters:
      r - a #graphene_rect_t
      res - return location for the bounds of the transformed rectangle

    • transformBox

      public void transformBox(@Nonnull Box b, @Nonnull Box res)
      Transforms the vertices of a #graphene_box_t using the given matrix @m.

      The result is the axis aligned bounding box containing the transformed
      vertices.
      Parameters:
      b - a #graphene_box_t
      res - return location for the bounds of the transformed box

    • transformPoint

      public void transformPoint(@Nonnull Point p, @Nonnull Point res)
      Transforms the given #graphene_point_t using the matrix @m.

      Unlike graphene_matrix_transform_vec3(), this function will take into
      account the fourth row vector of the #graphene_matrix_t when computing
      the dot product of each row vector of the matrix.

      See also: graphene_simd4x4f_point3_mul()
      Parameters:
      p - a #graphene_point_t
      res - return location for the transformed #graphene_point_t

    • transformPoint3d

      public void transformPoint3d(@Nonnull Point3D p, @Nonnull Point3D res)
      Transforms the given #graphene_point3d_t using the matrix @m.

      Unlike graphene_matrix_transform_vec3(), this function will take into
      account the fourth row vector of the #graphene_matrix_t when computing
      the dot product of each row vector of the matrix.

      See also: graphene_simd4x4f_point3_mul()
      Parameters:
      p - a #graphene_point3d_t
      res - return location for the result

    • transformRay

      public void transformRay(@Nonnull Ray r, @Nonnull Ray res)
      Transform a #graphene_ray_t using the given matrix @m.
      Parameters:
      r - a #graphene_ray_t
      res - return location for the transformed ray

    • transformRect

      public void transformRect(@Nonnull Rect r, @Nonnull Quad res)
      Transforms each corner of a #graphene_rect_t using the given matrix @m.

      The result is a coplanar quadrilateral.

      See also: graphene_matrix_transform_point()
      Parameters:
      r - a #graphene_rect_t
      res - return location for the transformed quad

    • transformSphere

      public void transformSphere(@Nonnull Sphere s, @Nonnull Sphere res)
      Transforms a #graphene_sphere_t using the given matrix @m. The
      result is the bounding sphere containing the transformed sphere.
      Parameters:
      s - a #graphene_sphere_t
      res - return location for the bounds of the transformed sphere

    • transformVec3

      public void transformVec3(@Nonnull Vec3 v, @Nonnull Vec3 res)
      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()
      Parameters:
      v - a #graphene_vec3_t
      res - return location for a #graphene_vec3_t

    • transformVec4

      public void transformVec4(@Nonnull Vec4 v, @Nonnull Vec4 res)
      Transforms the given #graphene_vec4_t using the matrix @m.

      See also: graphene_simd4x4f_vec4_mul()
      Parameters:
      v - a #graphene_vec4_t
      res - return location for a #graphene_vec4_t

    • translate

      public void translate(@Nonnull Point3D pos)
      Adds a translation transformation to @m using the coordinates
      of the given #graphene_point3d_t.

      This is the equivalent of calling graphene_matrix_init_translate() and
      then multiplying @m with the translation matrix.
      Parameters:
      pos - a #graphene_point3d_t

    • transpose

      public void transpose(@Nonnull Matrix res)
      Transposes the given matrix.
      Parameters:
      res - return location for the transposed matrix

    • unprojectPoint3d

      public void unprojectPoint3d(@Nonnull Matrix modelview, @Nonnull Point3D point, @Nonnull Point3D res)
      Unprojects the given @point using the @projection matrix and
      a @modelview matrix.
      Parameters:
      modelview - a #graphene_matrix_t 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

    • untransformBounds

      public void untransformBounds(@Nonnull Rect r, @Nonnull Rect bounds, @Nonnull Rect res)
      Undoes the transformation on the corners of a #graphene_rect_t using the
      given matrix, within the given axis aligned rectangular @bounds.
      Parameters:
      r - a #graphene_rect_t
      bounds - the bounds of the transformation
      res - return location for the untransformed rectangle

    • untransformPoint

      public boolean untransformPoint(@Nonnull Point p, @Nonnull Rect bounds, @Nonnull Point res)
      Undoes the transformation of a #graphene_point_t using the
      given matrix, within the given axis aligned rectangular @bounds.
      Parameters:
      p - a #graphene_point_t
      bounds - the bounds of the transformation
      res - return location for the untransformed point
      Returns:
      `true` if the point was successfully untransformed

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()