MatrixKit

class HPS::MatrixKit

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

Public Functions

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.