About

In 3D graphics a matrix is used to represent the transformation from one coordinate system to another. The typical use case is the transformation matrix that defines the position, rotation and scale of an object in 3D space.

The Cinema API matrix classes available:

::Matrix32: A matrix composed of Vector32 elements.
::Matrix64: A matrix composed of Vector64 elements.
::Matrix: Defined as Matrix64.

Access

To retrieve and modify ::Matrix objects stored in a BaseObject respectively use:

BaseObject::GetMg(): Returns the world (global) matrix representing the object's position, scale and rotation.
BaseObject::SetMg(): Sets the world (global) matrix representing the object's position, scale and rotation.

For more object related matrices see BaseObject.

To retrieve and modify ::Matrix objects stored in a BaseContainer respectively use:

BaseContainer::GetMatrix(): Returns the ::Matrix stored at the given ID.
BaseContainer::SetMatrix(): Sets the ::Matrix stored at the given ID.

Components

A matrix is composed of four vector components:

Matrix::off: The translation vector.
Matrix::sqmat::v1: The X-axis coordinate in a left-handed coordinate system of a transformed X-axis aligned unit-vector.
Matrix::sqmat::v2: The Y-axis coordinate in a left-handed coordinate system of a transformed Y-axis aligned unit-vector.
Matrix::sqmat::v3: The Z-axis coordinate in a left-handed coordinate system of a transformed Z-axis aligned unit-vector.

  // This example prints the world space position of the given object.
 
  const Matrix mg = object->GetMg();
  ApplicationOutput("World Space Position: @"_s, mg.off);

Functionality

Apply Transformation

A matrix is typically used to transform a given vector.

Matrix::operator*() const: Transforms the given vector.

  // This example loops through all points of the given point object.
  // For each point the coordinates are transferred into world space
  // and a sphere is created at that location.
 
  const Vector* const points = pointObject->GetPointR();
  const Int32         pointCount = pointObject->GetPointCount();
  const Matrix        mg = pointObject->GetMg();
 
  for (Int32 i = 0; i < pointCount; ++i)
  {
    if (points)
    {
      const Vector point = points[i];
      const Vector worldSpacePosition = mg * point;
 
      BaseObject* const sphere = BaseObject::Alloc(Osphere);
      if (sphere != nullptr)
      {
        sphere->SetMg(MatrixMove(worldSpacePosition));
        doc->InsertObject(sphere, nullptr, nullptr);
      }
    }
  }

Edit Matrix

Basic operations to edit a matrix are done using operators or special functions:

Matrix::operator~(): Inverts the matrix.
Matrix::operator/(): Divides each vector in matrix with the given scalar.

  // This example calculates the position of objectB in the local space of objectA.
 
  const Matrix mgA = objectA->GetMg();
  const Matrix inverse = ~mgA;
 
  const Vector worldSpacePos = objectB->GetMg().off;
  const Vector localSpacePos = inverse * worldSpacePos;
 
  const maxon::String objectBName { objectB->GetName() };
  const maxon::String objectAName { objectA->GetName() };
 
  ApplicationOutput("Object "_s + objectBName);
  ApplicationOutput("Position @ in the local space of @"_s, localSpacePos, objectAName);

Compare

Two matrices can be compared using the usual operators:

Matrix::operator==(): Returns true if the two matrices are equal.
Matrix::operator!=(): Returns true if the two matrices are not equal.

Note: For save comparison of floating point values see Compare.

Disc I/O

Matrix objects can be stored in a BaseFile or a HyperFile using:

BaseFile::ReadMatrix32(): Reads the Matrix32 from the BaseFile.
BaseFile::WriteMatrix32(): Writes the Matrix32 to the BaseFile.
BaseFile::ReadMatrix64(): Reads the Matrix64 from the BaseFile.
BaseFile::WriteMatrix64(): Writes the Matrix64 to the BaseFile.

  // This example writes the Matrix into a new BaseFile.
 
  AutoAlloc<BaseFile> bf;
  if (bf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open BaseFile to write
  if (bf->Open(filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
  {
    bf->WriteMatrix64(matrix);
    bf->Close();
  }

  // This example reads a Matrix form the given BaseFile.
 
  AutoAlloc<BaseFile> bf;
  if (bf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open BaseFile to read
  if (bf->Open(filename, FILEOPEN::READ, FILEDIALOG::ANY))
  {
    Matrix matrix;
    bf->ReadMatrix64(&matrix);

HyperFile::ReadMatrix(): Reads the ::Matrix from the HyperFile.
HyperFile::WriteMatrix(): Writes the ::Matrix to the HyperFile.
HyperFile::ReadMatrix32(): Reads the Matrix32 from the HyperFile.
HyperFile::WriteMatrix32(): Writes the Matrix32 to the HyperFile.
HyperFile::ReadMatrix64(): Reads the Matrix64 from the HyperFile.
HyperFile::WriteMatrix64(): Writes the Matrix64 to the HyperFile.

  // This example writes the Matrix into a new HyperFile.
 
  AutoAlloc<HyperFile> hf;
  if (hf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open HyperFile to write
  if (hf->Open('matr', filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
  {
    hf->WriteMatrix(matrix);
    hf->Close();
  }

  // This example reads a Matrix from the given HyperFile.
 
  AutoAlloc<HyperFile> hf;
  if (hf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open HyperFile to read
  if (hf->Open('matr', filename, FILEOPEN::READ, FILEDIALOG::ANY))
  {
    Matrix matrix;
    hf->ReadMatrix(&matrix);

See also BaseFile Manual on Matrix and HyperFile Manual on Matrix.

Utility Functions

Several utility functions can be used to easily create matrices:

MatrixMove(): Creates a translation matrix.
MatrixScale(): Creates a scaling matrix.
MatrixRotX(): Creates a rotation matrix on the X axis.
MatrixRotY(): Creates a rotation matrix on the Y axis.
MatrixRotZ(): Creates a rotation matrix on the Z axis.

Matrices also represent rotations. Several functions can be used to change and obtain the rotation stored in a matrix:

MatrixToHPB(): Calculates Euler angles from the given ::Matrix
Matrix64ToHPB(): Calculates Euler angles from the given ::Matrix64.
HPBToMatrix(): Constructs a matrix from Euler angles.
LHPBToMatrix(): A double precision version of HPBToMatrix().
MatrixToRotAxis(): Calculates rotation axis and angle from a matrix.
RotAxisToMatrix(): Calculates matrix from rotation axis and angle.

Note: Rotations are represented by vectors, see also Vector Manual (Cinema API).

Matrix utility:

RebuildMatrix(): Recalculates a matrix making it orthogonal if one or more of its vectors is collapsed

  // This example creates a rotation matrix based on a direction vector
  // and applies it to the given object.
 
  const Vector vec { 100, 100, 100 };
  const Vector rotation = VectorToHPB(vec);
  const Matrix mg = HPBToMatrix(rotation, ROTATIONORDER::DEFAULT);
 
  object->SetMg(mg);

Table of Contents