# Base Math

Of course every scenegraph needs the basic math objects like Vectors, Points, Matrices, Quaternions etc., and OpenSG is no exception.

## Matrices

OpenSG matrices are similar to the OpenGL matrices in their storage structure
and conventions, i.e. a matrix is per default a 4x4 Real32 matrix, and the
multiplication convention is just like OpenGL's: v'=M*v.
The matrix is stored column major and access methods respect the storage
format, i.e. `matrix[0]` yields the first column. This is also true for the
vector-based constructor. However, the constructor taking 16 single elements
expects its parameters row-major like the matrix is written on paper.
The positive side effect of this setup is the ability to access the base
vectors of the matrix' coordinate space by accessing the vectors, i.e.
`matrix[3]` is the translation to the origin of the local coordinate space. This
is useful if you want to create your matrices from vectors, if you don't want
to do that, don't worry about it.

Setting the contents of a matrix is done by the `setValues()` methods, accessing
the values via `operator[]` for access to single columns or by using
TransformationMatrix::getValues to get a pointer to the first element. In general most classes in
OpenSG that keep an array of elements allow access to them via TransformationMatrix::getValues.
If you need to create a matrix for a specific transformation, use the
setTransform() methods, which create a matrix that executes the given
transformation.

Matrices also supply the standard set of matrix operations like TransformationMatrix::det, TransformationMatrix::det3, TransformationMatrix::invert, TransformationMatrix::transpose, TransformationMatrix::mult and TransformationMatrix::multLeft. There are some variants that change the matrix in place, return their results in a different matrix or get their source data from a different matrix, see the class docs for details. The default vector/point multiplication methods TransformationMatrix::multMatrixVec and TransformationMatrix::multMatrixPnt assume that the matrix only uses the standard 3x4 elements. To use the full 4x4 matrix use TransformationMatrix::multFullMatrixPnt. As Vectors have a w coordinate of 0, compared to points which have w = 1, they don't need a full transform.

*Note: As a 3-vector expands to a 4-vector with the 4th coordinate to zero, using matrix[3] = Vec3f(1,2,3)
will set matrix[3][3] to 0, even if it was 1 from the beginning.*

## Vectors/Points/Colors?

OpenSG is different from most other systems in differentiating between vectors, points and colors.

Vectors are the most common class, and they should behave like every other vector library on the planet. They are templated to simplify having variants, and the standard ones that are available are Vec4ub, Vec2us, Vec2s, Vec2f, Vec3s, Vec3f and Vec4f. They have operators for the scalar operations, and methods for everything else, see the doxygen docs for Vector for details. Conceptually, the 3 element vector has a w coordinate of 0, thus there is no full matrix multiplication for vectors.

Points represent positions in space, and as such they are more restricted than vectors. The available variants are Pnt2f, Pnt3f and Pnt4f. Some vector operations (Vector::dot, Vector::cross, etc.) don't make sense for points. Points can be subtracted (creating a vector), scaled and a vector can be added to or subtracted from them. If you want to represent a position, use a point. It helps keeping the concepts in order and not mix up everything just because it has the same data. When multiplied with a matrix, the w coordinate is set as 1 for 3 element points. If you really need to get from a point to a vector or vice versa, you can use

to cast a point to a vector and back.

Colors are RGB vectors, which also have access functions to the named components. They also allow access via the HSV color model and scalar multiplication, but no other operations.

## Quaternions

Quaternions are the standard way to represent rotations. OpenSG quaternions feature the standard set of methods to get and set the rotations, in variants for radians and degrees. The standard order of the components is x,y,z,w. The standard operations (length, normalize, mult) are available, as well as Quaternion::slerp and Quaternion::multVec.