Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.ITransformable

The ITransformable property interface.

This interface provides the basis for transforming nodes within a virtual 2D or 3D space. Internally, this encapsulates a 4x4 transformation matrix. In general, transforms are applied according to the hierarchy in which they are specified.

Animation controllers may call the SetTransform() method when translation and/or rotation keys are present in a given Resource::IAnimation.


Table members

Methods


SetDepthOrder(depthOrder)

Set the depth order. For any geometry that gets sorted back-to-front (i.e. with disabled Z-Buffer writes), the depth order provides an additional means for sorting, useful when two or more objects share the same depth (or distance value, depending on the depth sorting mode applied by the currently active Graph::ICamera). In such a case, objects with a higher depth order will be drawn later, i.e. on top of others. Like the hierarchical behavior of the transformation matrix, depth orders are also applied relative to their parents.

Boolean SetDepthOrder(Integer depthOrder)

Parameters
depthOrderA signed 32bit integer
Returns
Boolean true if successful

GetDepthOrder()

Get the depth order.

Integer GetDepthOrder()

Returns
Integer The transform's depth order

SetTransform(transform)

Set the 4x4 transformation matrix. This method copies the given transformation matrix to the internal matrix as a whole.

Boolean SetTransform(Murl.Math.Matrix transform)

Parameters
transformThe transformation matrix to apply
Returns
Boolean true if successful

GetTransform()

Get a mutable reference to the internal 4x4 transformation matrix. This method may be called to directly modify the internal transformation matrix. Calling this will internally flag the transform as "modified" in any case, even if it was not actually modified.

Murl.Math.Matrix GetTransform()

Returns
Murl.Math.Matrix The transformation matrix

SetPosition(posX, posY, posZ)

Set the translation component of the transformation matrix. This method directly copies the individually given X, Y and Z position values to the XW, YW and ZW components of the matrix without modifying any other component.

Boolean SetPosition(Number posX, Number posY, Number posZ)

Parameters
posXThe X component to apply
posYThe Y component to apply
posZThe Z component to apply
Returns
Boolean true if successful

SetPosition(pos)

Set the translation component of the transformation matrix. This method directly copies the X, Y and Z values of the given position vector to the XW, YW and ZW components of the matrix without modifying any other component.

Boolean SetPosition(Murl.Math.Vector pos)

Parameters
posThe position vector to apply
Returns
Boolean true if successful

SetPositionX(pos)

Set the X component of the transformation matrix' translation. This method directly copies the given X position value to the XW component of the matrix without modifying any other component.

Boolean SetPositionX(Number pos)

Parameters
posThe X component to apply
Returns
Boolean true if successful

SetPositionY(pos)

Set the Y component of the transformation matrix' translation. This method directly copies the given Y position value to the YW component of the matrix without modifying any other component.

Boolean SetPositionY(Number pos)

Parameters
posThe Y component to apply
Returns
Boolean true if successful

SetPositionZ(pos)

Set the Z component of the transformation matrix' translation. This method directly copies the given Z position value to the ZW component of the matrix without modifying any other component.

Boolean SetPositionZ(Number pos)

Parameters
posThe Z component to apply
Returns
Boolean true if successful

GetPosition()

Get a constant reference to the internal position vector.

Murl.Math.Vector GetPosition()

Returns
Murl.Math.Vector The position vector.

GetPositionX()

Get the X component of the transformation matrix' translation.

Number GetPositionX()

Returns
Number The X component

GetPositionY()

Get the Y component of the transformation matrix' translation.

Number GetPositionY()

Returns
Number The Y component

GetPositionZ()

Get the Z component of the transformation matrix' translation.

Number GetPositionZ()

Returns
Number The Z component

SetRotation(angleX, angleY, angleZ)

Set the rotation component of the transformation matrix in Euler angles notation. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and subsequently applying individual X, Y and Z rotations (Euler angles). Uses the axis rotation order set by SetRotationOrder() or rotationOrder="" XML attribute. Angle values must be given in radians. Positive values result in a clockwise rotation when viewed along the unit X, Y and Z axes, respectively.

Boolean SetRotation(Number angleX, Number angleY, Number angleZ)

Parameters
angleXThe rotation angle around the X axis in radians
angleYThe rotation angle around the Y axis in radians
angleZThe rotation angle around the Z axis in radians
Returns
Boolean true if successful

SetRotation(q)

Set the rotation component of the transformation matrix by a quaternion. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating the rotation component from a given quaternion.

Boolean SetRotation(Murl.Math.Quaternion q)

Parameters
qThe quaternion.
Returns
Boolean true if successful

SetRotation(axis, angle)

Set the rotation component of the transformation matrix in axis-angle notation. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating the rotation component from a given axis and angle. The axis must be normalized (i.e. have unit length), and the angle must be given in radians. Positive angle values result in a clockwise rotation when viewed along the given axis.

Boolean SetRotation(Murl.Math.Vector axis, Number angle)

Parameters
axisThe normalized rotation axis
angleThe rotation angle around the axis in radians
Returns
Boolean true if successful

SetRotationOrder(rotationOrder)

Set the axis rotation order for Euler axis notation. The default axis rotation order is IEnums::ROTATION_ORDER_ZYX.

Boolean SetRotationOrder(Murl.IEnums.RotationOrder rotationOrder)

Parameters
rotationOrderThe axis rotation order.
Returns
Boolean true if successful

SetRotationXYZ(angleX, angleY, angleZ, rotationOrder)

Set the rotation component of the transformation matrix in Euler angles notation with a given rotation order. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and subsequently applying individual X, Y and Z rotations (Euler angles). Angle values must be given in radians. Positive values result in a clockwise rotation when viewed along the unit X, Y and Z axes, respectively.

Boolean SetRotationXYZ(Number angleX, Number angleY, Number angleZ, Murl.IEnums.RotationOrder rotationOrder)

Parameters
angleXThe rotation angle around the X axis in radians
angleYThe rotation angle around the Y axis in radians
angleZThe rotation angle around the Z axis in radians
rotationOrderThe axis rotation order.
Returns
Boolean true if successful

SetRotationX(angle)

Set the rotation component of the transformation matrix to only rotate around the X axis. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and applying a rotation around the unit X axis. The angle value must be given in radians. A positive value result in a clockwise rotation.

Boolean SetRotationX(Number angle)

Parameters
angleThe rotation angle around the X axis in radians
Returns
Boolean true if successful

SetRotationY(angle)

Set the rotation component of the transformation matrix to only rotate around the Y axis. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and applying a rotation around the unit Y axis. The angle value must be given in radians. A positive value result in a clockwise rotation.

Boolean SetRotationY(Number angle)

Parameters
angleThe rotation angle around the Y axis in radians
Returns
Boolean true if successful

SetRotationZ(angle)

Set the rotation component of the transformation matrix to only rotate around the Z axis. This method directly overwrites the upper 3x3 matrix of the internal transformation by calculating and applying a rotation around the unit Z axis. The angle value must be given in radians. A positive value result in a clockwise rotation.

Boolean SetRotationZ(Number angle)

Parameters
angleThe rotation angle around the Z axis in radians
Returns
Boolean true if successful

GetRotationOrder()

Get the axis rotation order for Euler axis notation.

Murl.IEnums.RotationOrder GetRotationOrder()

Returns
Murl.IEnums.RotationOrder The axis rotation order.

GetRotation()

Get a constant reference to the internal euler angles vector. This method returns the Euler angles set by XML attribute angleX/Y/Z="" or SetRotationX/Y/Z(), SetRotationXYZ() or SetRotation(Real angleX, Real angleY, Real angleZ) only.

Murl.Math.Vector GetRotation()

Returns
Murl.Math.Vector The rotation vector.

GetRotationX()

Get the rotation around the X axis. This method returns the Euler angle set by XML attribute angleX="" or SetRotationX(), SetRotationXYZ() or SetRotation(Real angleX, Real angleY, Real angleZ) only.
If the upper 3x3 matrix of the internal transformation matrix has been modified by other methods, the returned angle is incorrect. In this case Matrix::GetEulerRotation() can be used to calculate corresponding angles.

Number GetRotationX()

Returns
Number The rotation around the X axis.

GetRotationY()

Get the rotation around the Y axis. This method returns the Euler angle set by XML attribute angleY="" or SetRotationY(), SetRotationXYZ() or SetRotation(Real angleX, Real angleY, Real angleZ) only.
If the upper 3x3 matrix of the internal transformation matrix has been modified by other methods, the returned angle is incorrect. In this case Matrix::GetEulerRotation() can be used to calculate corresponding angles.

Number GetRotationY()

Returns
Number The rotation around the Y axis.

GetRotationZ()

Get the rotation around the Z axis. This method returns the Euler angle set by XML attribute angleZ="" or SetRotationZ(), SetRotationXYZ() or SetRotation(Real angleX, Real angleY, Real angleZ) only.
If the upper 3x3 matrix of the internal transformation matrix has been modified by other methods, the returned angle is incorrect. In this case Matrix::GetEulerRotation() can be used to calculate corresponding angles.

Number GetRotationZ()

Returns
Number The rotation around the Z axis.