MatrixKit

class HPS::MatrixKit

The MatrixKit class is a user space object, useful for carrying a group attribute settings.

Public Functions

MatrixKit &Adjoint()

Replaces this matrix with it’s matrix adjoint. The adjoint is similar to the inverse but is always guaranteed to exist, even for singular matrices.

Returns

A reference to this object.

bool Compose(Vector const &in_translation, Vector const &in_scale, Quaternion const &in_rotation)

Composes this matrix from translation, scale, and rotation components.

Parameters
  • in_translation – The translation Vector to use.

  • in_scale – The scale Vector to use.

  • in_rotation – The translation Quaternion to use.

Returns

true if the matrix was successfully composed, false otherwise.

MatrixKit &Concatenate(MatrixKit const &in_kit)

Replaces this matrix with the matrix product of itself multiplied by another matrix.

Parameters

in_kit – the right side operand of the matrix multiplication.

Returns

A reference to this object.

bool Decompose(Vector &out_translation, Vector &out_scale, Quaternion &out_rotation) const

Decomposes this matrix into translation, scale, and rotation components.

Parameters
  • out_translation – The translation Vector extracted from this matrix.

  • out_scale – The scale Vector extracted from this matrix.

  • out_scale – The out_rotation Quaternion extracted from this matrix.

Returns

true if the matrix was successfully decomposed, false otherwise.

bool Empty() const

Indicates whether this object has any values set on it.

Deprecated:

This function exists for compatibility and will always return false.

Returns

true if no values are set on this object, false otherwise.

bool Equals(MatrixKit const &in_kit) const

Check if the source MatrixKit is equivalent to this object.

Parameters

in_kit – The source MatrixKit to compare to this object.

Returns

true if the objects are equivalent, false otherwise.

MatrixKit &Invert()

Replaces this matrix with it’s matrix inverse. If this matrix is singular (determinant = 0), it will be unchanged.

Returns

A reference to this object.

bool IsIdentity() const

Indicates whether or not this matrix is an identity matrix

Returns

Whether this matrix is an identity matrix.

MatrixKit()

Initializes an identity matrix.

MatrixKit(float const in_matrix_source[])

This constructor allows implicit construction from an array of floats.

Parameters

in_matrix_source – An array of floats that will be used to construct a new matrix. This array is assumed to be at least 16 elements in length. If it is not, the behavior is undefined.

MatrixKit(FloatArray const &in_matrix_source)

This constructor allows implicit construction from an array of floats.

Parameters

in_matrix_source – An array of floats that will be used to construct a new matrix. If this array is not at least 16 elements in length, only the valid members will be used, leaving the remainder initialized as the identity matrix.

MatrixKit(MatrixKit const &in_other)

The copy constructor creates a new MatrixKit object that contains the same settings as the source object.

Parameters

in_kit – The source object to copy.

MatrixKit(Quaternion const &in_quaternion)

This constructor allows implicit construction from a quaternion.

Parameters

in_quaternion – A quaternion used to construct a new matrix.

MatrixKit Multiply(float in_scalar) const

Performs a scalar multiplication of this matrix.

Parameters

in_scalar – A scalar to multiply this object by.

Returns

A new MatrixKit representing the product.

MatrixKit Multiply(MatrixKit const &in_right) const

Performs a matrix multiplication with this object as the left operand.

Parameters

in_right – A matrix used as the right operand of a matrix multiplication.

Returns

A new MatrixKit representing the product.

MatrixKit &MultiplyAndAssign(float in_scalar)

Performs a scalar multiplication of this matrix and then assigns it to this object.

Parameters

in_scalar – A scalar to multiply this object by.

Returns

A reference to this object after the multiplication.

MatrixKit &MultiplyAndAssign(MatrixKit const &in_right)

Performs a matrix multiplication with this object as the left operand and then assigns it to this object.

Parameters

in_right – A matrix used as the right operand of a matrix multiplication.

Returns

A reference to this object after the multiplication.

MatrixKit &Normalize()

Divides this matrix by its determinant. If this matrix is singular (determinant = 0), it will be unchanged.

Returns

A reference to this object.

bool operator!=(MatrixKit const &in_kit) const

Check if the source MatrixKit is not equivalent to this object.

Parameters

in_kit – The source MatrixKit to compare to this object.

Returns

true if the objects are not equivalent, false otherwise.

MatrixKit operator*(float in_scalar) const

Performs a scalar multiplication of this matrix.

Parameters

in_scalar – A scalar to multiply this object by.

Returns

A new MatrixKit representing the product.

MatrixKit operator*(MatrixKit const &in_right) const

Performs a matrix multiplication with this object as the left operand.

Parameters

in_right – A matrix used as the right operand of a matrix multiplication.

Returns

A new MatrixKit representing the product.

MatrixKit const &operator*=(float in_scalar)

Performs a scalar multiplication of this matrix and then assigns it to this object.

Parameters

in_scalar – A scalar to multiply this object by.

Returns

A reference to this object after the multiplication.

MatrixKit const &operator*=(MatrixKit const &in_right)

Performs a matrix multiplication with this object as the left operand and then assigns it to this object.

Parameters

in_right – A matrix used as the right operand of a matrix multiplication.

Returns

A reference to this object after the multiplication.

MatrixKit &operator=(MatrixKit const &in_kit)

Copies the source MatrixKit into this object.

Parameters

in_kit – The source MatrixKit to copy.

Returns

A reference to this object.

bool operator==(MatrixKit const &in_kit) const

Check if the source MatrixKit is equivalent to this object.

Parameters

in_kit – The source MatrixKit to compare to this object.

Returns

true if the objects are equivalent, false otherwise.

void Reset()

Sets this kit to an identity matrix.

MatrixKit &Rotate(float in_x, float in_y, float in_z)

Concatenates a rotation matrix to this matrix with rotation around the primary axes.

Parameters
  • in_x – The number of degrees to rotate around the x-axis.

  • in_y – The number of degrees to rotate around the y-axis.

  • in_z – The number of degrees to rotate around the z-axis.

Returns

A reference to this object.

MatrixKit &RotateOffAxis(Vector const &in_vector, float in_theta)

Concatenates a rotation matrix to this matrix with rotation around an arbitrary vector.

Parameters
  • in_vector – The vector to rotate around.

  • in_theta – the number of degrees to rotate around the specified vector

Returns

A reference to this object.

MatrixKit &Scale(float in_x, float in_y, float in_z)

Concatenates a scale matrix to this matrix that represents a uniform scaling of the scene.

Parameters
  • in_x – The scale multiplier along the x-axis.

  • in_y – The scale multiplier along the y-axis.

  • in_z – The scale multiplier along the z-axis.

Returns

A reference to this object.

void Set(MatrixKit const &other)

Copies the data from the source MatrixKit into this object.

Parameters

in_other – The source MatrixKit to copy.

MatrixKit &SetElement(size_t in_ordinal_zero_to_fifteen, float in_value)

Sets a single matrix element, indexed as a linear array in row-major order.

Parameters
  • in_ordinal_zero_to_fifteen – The offset into the matrix. Valid range is [0, 15].

  • in_value – The matrix element.

Returns

A reference to this object.

MatrixKit &SetElement(size_t in_row, size_t in_column, float in_value)

Sets a single matrix element.

Parameters
  • in_row – The row index. Valid range is [0, 3].

  • in_column – The column index. Valid range is [0, 3].

  • in_value – The matrix element.

Returns

A reference to this object.

MatrixKit &SetElements(FloatArray const &in_values)

Sets some or all elements in the matrix from an array, starting with the first element.

Parameters

in_values – An array of float values in row-major order that should replace the values in the matrix.

Returns

A reference to this object.

MatrixKit &SetElements(size_t in_value_count, float const in_values[])

Sets some or all elements in the matrix from an array, starting with the first element.

Parameters
  • in_value_count – the number of elements in the input array. Valid range is [0, 16].

  • in_values – An array of float values in row-major order that should replace the values in the matrix.

Returns

A reference to this object.

bool ShowAdjoint(MatrixKit &out_matrix) const

Computes the matrix adjoint of this matrix. The adjoint is similar to the inverse but is always guaranteed to exist, even for singular matrices.

Parameters

out_matrix – The matrix adjoint of this matrix.

Returns

true if the setting is valid, false otherwise.

bool ShowDeterminant(float &out_determinant) const

Computes the matrix determinant of this matrix.

Parameters

out_determinant – The matrix determinant.

Returns

true if the setting is valid, false otherwise.

bool ShowElement(size_t in_ordinal_zero_to_fifteen, float &out_value) const

Shows a single matrix element, indexed as a linear array in row-major order.

Parameters
  • in_ordinal_zero_to_fifteen – The offset into the matrix. Valid range is [0, 15].

  • out_value – The matrix element.

Returns

true if the setting is valid, false otherwise.

bool ShowElement(size_t in_row, size_t in_column, float &out_value) const

Shows a single matrix element.

Parameters
  • in_row – The row index. Valid range is [0, 3].

  • in_column – The column index. Valid range is [0, 3].

  • out_value – The matrix element.

Returns

true if the setting is valid, false otherwise.

bool ShowElements(float out_matrix[]) const

Shows all elements of this matrix as an array.

Parameters

out_matrix – The contents of the matrix arranged as a linear array in row-major order.

Returns

true if the setting is valid, false otherwise.

bool ShowElements(FloatArray &out_matrix) const

Shows all elements of this matrix as an array.

Parameters

out_matrix – The contents of the matrix arranged as a linear array in row-major order.

Returns

true if the setting is valid, false otherwise.

bool ShowInverse(MatrixKit &out_matrix) const

Computes the matrix inverse of this matrix. Fails if this matrix is singular (determinant = 0).

Parameters

out_matrix – The matrix inverse of this matrix.

Returns

true if the setting is valid, false otherwise.

Plane Transform(Plane const &in_source) const

Transform a plane through this matrix.

Parameters

in_source – The plane to apply a transformation to.

Returns

A new plane representing the transformed plane.

PlaneArray Transform(PlaneArray const &in_source) const

Transform an array of planes through this matrix.

Parameters

in_source – An array of planes to apply a transformation to.

Returns

A new plane array representing the transformed planes.

Point Transform(Point const &in_source) const

Transform a point through this matrix.

Parameters

in_source – The point to apply a transformation to.

Returns

A new point representing the transformed point.

PointArray Transform(PointArray const &in_source) const

Transform an array of points through this matrix.

Parameters

in_source – An array of points to apply a transformation to.

Returns

A new point array representing the transformed points.

SimpleCuboid Transform(SimpleCuboid const &in_source) const

Transform a SimpleCuboid through this matrix.

Parameters

in_source – The cuboid to apply a transformation to.

Returns

A new SimpleCuboid representing the transformed cuboid.

SimpleSphere Transform(SimpleSphere const &in_source) const

Transform a SimpleSphere through this matrix.

Parameters

in_source – The sphere to apply a transformation to.

Returns

A new SimpleSphere representing the transformed sphere.

PlaneArray Transform(size_t in_count, Plane const in_source[]) const

Transform an array of planes through this matrix.

Parameters
  • in_count – The number of elements in the source array.

  • in_source – An array of planes to apply a transformation to.

Returns

A new plane array representing the transformed planes.

PointArray Transform(size_t in_count, Point const in_source[]) const

Transform an array of points through this matrix.

Parameters
  • in_count – The number of elements in the source array.

  • in_source – An array of points to apply a transformation to.

Returns

A new point array representing the transformed points.

VectorArray Transform(size_t in_count, Vector const in_source[]) const

Transform an array of vectors through this matrix.

Parameters
  • in_count – The number of elements in the source array.

  • in_source – An array of vectors to apply a transformation to.

Returns

A new vector array representing the transformed vectors.

Vector Transform(Vector const &in_source) const

Transform a vector through this matrix.

Parameters

in_source – The vector to apply a transformation to.

Returns

A new vector representing the transformed vector.

VectorArray Transform(VectorArray const &in_source) const

Transform an array of vectors through this matrix.

Parameters

in_source – An array of vectors to apply a transformation to.

Returns

A new vector array representing the transformed vectors.

MatrixKit &Translate(float in_x, float in_y, float in_z)

Concatenates a translation matrix to this matrix that moves geometry.

Parameters
  • in_x – The number of units to translate along the x-axis.

  • in_y – The number of units to translate along the y-axis.

  • in_z – The number of units to translate along the z-axis.

Returns

A reference to this object.

MatrixKit &Translate(Vector const &in_translation)

Concatenates a translation matrix to this matrix that moves geometry.

Parameters

in_translation – A vector distance to translate by.

Returns

A reference to this object.

MatrixKit &UnsetEverything()

Sets this kit to an identity matrix.

Deprecated:

This function exists for compatibility and Reset should be preferred.

Returns

A reference to this kit.

virtual ~MatrixKit()

Destroy this kit.

Public Members

float data[16]

Public Static Functions

static MatrixKit CreateNormalisationTransformation(int in_width, int in_height)

Creates a MatrixKit representing the transformation matrix from an arbitary 2D space to a normalized space.

Parameters
  • in_width – The current space width.

  • in_heigth – The current space height.

Returns

A new transformation MatrixKit.

static MatrixKit GetDefault()

Creates a MatrixKit representing the identity matrix.

Returns

An identity MatrixKit.