HDK

The fixedsize matrices come in many flavors: The HDK includes classes for 2x2, 3x3, and 4x4 matrices, with separate versions for singleprecision and doubleprecision floating point numbers. The singleprecision matrix classes are UT_Matrix2, UT_Matrix3, and UT_Matrix4. The doubleprecision versions are UT_DMatrix2, UT_DMatrix3, and UT_DMatrix4. The matrix classes interact with the fixedsize tuple classes UT_Vector2, UT_Vector3, and UT_Vector4.
The discussion below focuses on UT_Matrix4 and its interaction with UT_Vector3 and UT_Vector4. The classes UT_Matrix2 and UT_Matrix3 are mostly special cases of UT_Matrix4. The doubleprecision UT_DMatrix* versions have the same interface as their singleprecision UT_Matrix* counterparts.
The matrix class UT_Matrix4 is typically used to represent a change of coordinates, for example between object space and world space. UT_Matrix4 is also commonly used to represent transformations of objects within the same space, for example, scaling, shearing, translation and rotation.
The following conventions apply to the HDK matrix classes:
Positions and vectors can both be represented by UT_Vector3. Positions are using the rowVecMult function:
Please note that the left argument is the position and the right argument is the matrix. When your UT_Vector3 stores a vector (as opposed to a position), then you should use the method rowVecMult3 to transform it:
The rowVecMult3 method ignores everything but the upper left 3x3 submatrix, so that the translation part of the matrix is not applied.
It is important to realize that the fourth column of the matrix is ignored (considered zero) when UT_matrix4 operates on UT_Vector3 objects. This is fine when you only need to represent affine transformations such as rotation, scaling, shearing, and translation. However, if you do need to represent perspective transformations, then you should use UT_Matrix4 in combination with UT_Vector4. In that case, UT_Vector4 behaves as a tuple of homogeneous coordinates. An overloaded version of the rowVecMult method can then be used to transform both positions and vectors:
Setting the last coordinate of UT_Vector4 to 1 (the default) will create a point, setting it to 0 will create a vector.
The conventions for the HDK matrix classes imply that matrices work from left to right when they are multiplied:
The translate, scale and rotate methods can be used to construct transformation matrices. For example, the following code snippet constructs a transformation that first translates by (1, 2, 3) and then scales by (4, 5, 6):
Calling these members is the same as rightmultiplying t by a translation, scale, or rotation matrix. The methods pretranslate, prescale and prerotate are similar, but they have the effect of leftmultiplying t.
Transformation matrices can be constructed more explicitly by setting all of the matrix elements. Matrix indices are zerobased. The following code fragment constructs the transformation that scales a point by 0.5 and subsequently translates the point by (1, 2, 3).
The invert method can be used to find the inverse of a matrix without modifying the original matrix:
Note that the return value is 0 if invert was successful.
UT_Matrix can represent nonsquare matrices of higher dimensions. The representation is dense; all elements are stored, even if they're zero. UT_Matrix is best used when the the number of rows and columns is small, but higher than 4. Six by six UT_Matrix objects are commonly used in the physics simulation code.
Indexing UT_Matrix can be either 0based or 1based. This is controlled by the constructor parameters. The constructor expects inclusive ranges for row numbers and the column numbers. For example, the following code creates a UT_Matrix that has m rows and n columns, using 1based indices:
UT_Matrix objects can be multiplied with each other using the * operator. There are also various ways to multiply UT_Matrix object and UT_Vector objects:
The UT_MatrixSolver class declares utility methods that solve linear systems of equations that are represented using UT_Matrix. In particular, the LUdecomposition method LUDecomp can be used to express a matrix A as a product P L U of a permutation P, a unit lowertriangular matrix L and an uppertriangular matrix U. Once this decomposition has been computed, it can be reused to efficiently solve multiple linear systems A x = b that involve the same A.
The LUDecomp method stores the resulting matrices L and U in a single UT_Matrix. This is possible because the unit elements on the diagonal of L don't need to be explicitly stored. The associated permutation matrix P is stored in a UT_Permutation object, which takes up much less space than a UT_Matrix. The method LUBackSub performs a linear solve for A x = b, given a decomposition for A. It does this efficiently by doing two simple back substitutions: one for L and one for U. The use of LUDecomp with LUBackSub to solve a system of equations is demonstrated in the following code fragment:
Note that the LUDecomp method stores the resulting decomposition in the matrix that is passed in. For the sake of clarity, the above code fragment copies A over into a separate variable LU before calling LUDecomp. Similarly, the method LUBackSub stores the result of the linear solve in the UT_Vector parameter that's passed in.
The UT_SparseMatrix is used heavily in the physics simulation code. Like UT_Matrix, this class represents higherdimensional matrices. However, UT_SparseMatrix, is optimized for the case that the vast majority of matrix elements is zero. UT_SparseMatrix only stores the nonzero elements.
The constructor for UT_SparseMatrix creates a matrix that is zero everywhere (no actual elements are stored in this case). The addToElement method can be used to initialize the matrix's elements. The following code fragment constructs a sparse matrix that can be used to perform a backward Euler step for a system of springs between n point masses in 3D:
Note that in this code fragment, addElement is called twice for elements on the diagonal. The result will be that the diagonal contains the sum of the values that were passed to addElement.
A UT_SparseMatrix can be multiplied with a column vector of type UT_Vector like this:
UT_MatrixSolver.h contains numerical algorithms that approximate solutions for large sparse linear systems A x = b. The UT_MatrixIterSolver class implements the preconditioned conjugate gradient method (PCG). There are various methods with the name PCG in this class. Of these, the functorbased PCG interface is the cleanest and the most flexible one. Its use is demonstrated in the following code fragment:
Here multiply_A is a functor that multiplies A with a vector; it simply invokes multVec on A. The functor preconditioner_A is a preconditioner for A. The diagonal preconditioner could be implemented as follows:
The UT_Vector inside this is wrapped in a UT_SharedPtr because the DiagonalPreconditioner object is copied inside UT_Functor2. The functor keep_iterating is invoked by PCG to decide whether PCG should keep iterating, based on the current number of iterations and the residual r = A x  b. An implementation could look like this: