Implements a 4x4 matrix transform used to define the position and orientation of an Actor. More...

#include <Transform.hpp>

Inheritance diagram for vl::Transform:

Public Member Functions
	Transform ()
	Constructor.
	Transform (const mat4 &matrix)
	Constructor.
	~Transform ()
	Destructor.
const Transform *	parent () const
	Returns the parent Transform.
Transform *	parent ()
	Returns the parent Transform.
void	translate (Real x, Real y, Real z)
	Utility function equivalent to `setLocalMatrix`( mat4::getTranslation(x,y,z)*localMatrix() ).
void	translate (const vec3 &t)
	Utility function equivalent to `setLocalMatrix`( mat4::getTranslation(t)*localMatrix() ).
void	scale (Real x, Real y, Real z)
	Utility function equivalent to `setLocalMatrix`( mat4::getScaling(x,y,z)*localMatrix() ).
void	rotate (Real degrees, Real x, Real y, Real z)
	Utility function equivalent to `setLocalMatrix`( mat4::getRotation(degrees,x,y,z)*localMatrix() ).
void	rotate (const vec3 &from, const vec3 &to)
	Utility function equivalent to `setLocalMatrix`( mat4::getRotation(from,to)*localMatrix() ).
void	preMultiply (const mat4 &m)
	Utility function equivalent to `setLocalMatrix`( m*localMatrix() ).
void	postMultiply (const mat4 &m)
	Utility function equivalent to `setLocalMatrix`( localMatrix()*m ).
void	setLocalMatrix (const mat4 &m)
	The matrix representing the transform's local space.
const mat4 &	localMatrix () const
	The matrix representing the transform's local space.
void	setWorldMatrix (const mat4 &matrix)
	Normally you should not use directly this function, call it only if you are sure you cannot do otherwise.
const mat4 &	worldMatrix () const
	Returns the world matrix used for rendering.
void	setLocalAndWorldMatrix (const mat4 &matrix)
	Sets both the local and the world matrices.
long long	worldMatrixUpdateTick () const
	Returns the internal update tick used to avoid unnecessary computations.
void	setAssumeIdentityWorldMatrix (bool assume_I)
	If set to true the world matrix of this transform will always be considered and identity.
bool	assumeIdentityWorldMatrix ()
	If set to true the world matrix of this transform will always be considered and identity.
virtual void	computeWorldMatrix (Camera *=NULL)
	Computes the world matrix by concatenating the parent's world matrix with its own local matrix.
void	computeWorldMatrixRecursive (Camera *camera=NULL)
	Computes the world matrix by concatenating the parent's world matrix with its local matrix, recursively descending to the children.
mat4	getComputedWorldMatrix ()
	Returns the matrix computed concatenating this Transform's local matrix with the local matrices of all its parents.
const ref< Transform > *	children () const
	Returns the array containing the child Transforms.
ref< Transform > *	children ()
	Returns the array containing the child Transforms.
size_t	childrenCount () const
	Returns the number of child Transform.
void	addChild (Transform *child)
	Adds a child transform.
void	addChildren (Transform const children, size_t count)
	Adds `count` children transforms.
void	addChildren (const ref< Transform > *children, size_t count)
void	addChildren (const std::vector< ref< Transform > > &children)
void	addChildren (const std::vector< Transform * > &children)
	Adds the specified `children` transforms.
void	setChild (int index, Transform *child)
	Sets the `index-th` child.
const Transform *	lastChild () const
	Returns the last child.
Transform *	lastChild ()
	Returns the last child.
void	eraseChild (const Transform *child)
	Removes the given `child` Transform.
void	eraseChildren (int index, int count)
	Removes `count` children Transforms starting at position `index`.
void	eraseAllChildren ()
	Removes all the children of a Transform.
void	eraseAllChildrenRecursive ()
	Removes all the children of a Transform recursively descending the hierarchy.
void	flattenHierarchy ()
	Disassembles a hierarchy of Transforms like eraseAllChildrenRecursive() does plus assigns the local matrix to equal the world matrix.
void	removeFromParent ()
	Erases a Transform from it's parent and sets the local matrix to be equal to the world matrix.
void	shrink ()
	Minimizes the amount of memory used to store the children Transforms.
void	shrinkRecursive ()
	Minimizes recursively the amount of memory used to store the children Transforms.
void	reserveChildren (size_t count)
	Reserves space for `count` children.
bool	hasDuplicatedChildren () const
	Checks whether there are duplicated entries in the Transform's children list.
Protected Attributes
mat4	mLocalMatrix
mat4	mWorldMatrix
long long	mWorldMatrixUpdateTick
bool	mAssumeIdentityWorldMatrix
std::vector< ref< Transform > >	mChildren
Transform *	mParent

Detailed Description

Implements a 4x4 matrix transform used to define the position and orientation of an Actor.

Transforms can be linked together to create a tree-like hierarchy.

Optimizing Your Transforms

Don't use them unless strictly necessary: if an Actor uses an I (identity) transform you do not need one, just call vl::Actor::setTransform(NULL).

Don't create Transform hierarchies if not needed. Just call setLocalAndWorldMatrix() per-Transform if you have a set of parent-less Transforms.

If the root of a hierarchy is an I (identity) transform, let VL know it by calling setAssumeIdentityWorldMatrix(true). This will save unnecessary matrix multiplications when calling computeWorldMatrix() / computeWorldMatrixRecursive().

Call computeWorldMatrix() / computeWorldMatrixRecursive() not at each frame but only if the local matrix has actually changed.

Do not add a Transform hierarchy to vl::Rendering::transform() if such Transforms are not animated every frame.

Remember: VL does not require your Actors to have a Transform or such Transforms to be part of any hierarchy, it just expect that the worldMatrix() of an Actor's Transform (if it has any) is up to date at rendering time. How and when they are updated can be fine tuned by the user according to the specific application needs.

See also:: setLocalAndWorldMatrix(), setAssumeIdentityWorldMatrix(), Rendering::transform(); Actor, Rendering, Effect, Renderable, Geometry

Definition at line 72 of file Transform.hpp.

Constructor & Destructor Documentation

vl::Transform::Transform ( ) [inline]

Constructor.

Definition at line 76 of file Transform.hpp.

References VL_DEBUG_SET_OBJECT_NAME.

vl::Transform::Transform ( const mat4 & matrix ) [inline]

Constructor.

The matrix parameter is used to set both the local and world matrix.

Definition at line 86 of file Transform.hpp.

References VL_DEBUG_SET_OBJECT_NAME.

Transform::~Transform ( )

Destructor.

Definition at line 44 of file Transform.cpp.

References mChildren, vl::Log::warning(), and worldMatrix().

Member Function Documentation

const Transform* vl::Transform::parent ( ) const [inline]

Returns the parent Transform.

Definition at line 102 of file Transform.hpp.

Referenced by vl::Billboard::computeWorldMatrix(), and getComputedWorldMatrix().

Transform* vl::Transform::parent ( ) [inline]

Returns the parent Transform.

Definition at line 105 of file Transform.hpp.

void Transform::translate	(	Real	x,
		Real	y,
		Real	z
	)

Utility function equivalent to setLocalMatrix( mat4::getTranslation(x,y,z)*localMatrix() ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 58 of file Transform.cpp.

References vl::Matrix4< float >::getTranslation(), localMatrix(), and setLocalMatrix().

void Transform::translate ( const vec3 & t )

Utility function equivalent to setLocalMatrix( mat4::getTranslation(t)*localMatrix() ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 63 of file Transform.cpp.

References vl::Matrix4< float >::getTranslation(), localMatrix(), and setLocalMatrix().

void Transform::scale	(	Real	x,
		Real	y,
		Real	z
	)

Utility function equivalent to setLocalMatrix( mat4::getScaling(x,y,z)*localMatrix() ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 68 of file Transform.cpp.

References vl::Matrix4< float >::getScaling(), localMatrix(), and setLocalMatrix().

void Transform::rotate	(	Real	degrees,
		Real	x,
		Real	y,
		Real	z
	)

Utility function equivalent to setLocalMatrix( mat4::getRotation(degrees,x,y,z)*localMatrix() ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 73 of file Transform.cpp.

References vl::Matrix4< float >::getRotation(), localMatrix(), and setLocalMatrix().

void Transform::rotate	(	const vec3 &	from,
		const vec3 &	to
	)

Utility function equivalent to setLocalMatrix( mat4::getRotation(from,to)*localMatrix() ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 78 of file Transform.cpp.

References vl::Matrix4< float >::getRotation(), localMatrix(), and setLocalMatrix().

void Transform::preMultiply ( const mat4 & m )

Utility function equivalent to setLocalMatrix( m*localMatrix() ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 83 of file Transform.cpp.

References localMatrix(), and setLocalMatrix().

void Transform::postMultiply ( const mat4 & m )

Utility function equivalent to setLocalMatrix( localMatrix()*m ).

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 88 of file Transform.cpp.

References localMatrix(), and setLocalMatrix().

void vl::Transform::setLocalMatrix ( const mat4 & m ) [inline]

The matrix representing the transform's local space.

After calling this you might want to call computeWorldMatrix() or computeWorldMatrixRecursive().

Definition at line 137 of file Transform.hpp.

Referenced by postMultiply(), preMultiply(), rotate(), scale(), vl::Billboard::setPosition(), and translate().

const mat4& vl::Transform::localMatrix ( ) const [inline]

The matrix representing the transform's local space.

Definition at line 143 of file Transform.hpp.

Referenced by getComputedWorldMatrix(), vl::Billboard::position(), postMultiply(), preMultiply(), rotate(), scale(), and translate().

void vl::Transform::setWorldMatrix ( const mat4 & matrix ) [inline]

Normally you should not use directly this function, call it only if you are sure you cannot do otherwise.

Usually you want to call computeWorldMatrix() or computeWorldMatrixRecursive(). Calling this function will also increment the worldMatrixUpdateTick().

Definition at line 151 of file Transform.hpp.

Referenced by vl::Billboard::computeWorldMatrix().

const mat4& vl::Transform::worldMatrix ( ) const [inline]

void vl::Transform::setLocalAndWorldMatrix ( const mat4 & matrix ) [inline]

Sets both the local and the world matrices.

This function is useful to quickly set those Transforms that do not have a parent, for which is equivalent to: setLocalMatrix(matrix); computeWorldMatrix(NULL);

Definition at line 166 of file Transform.hpp.

long long vl::Transform::worldMatrixUpdateTick ( ) const [inline]

Returns the internal update tick used to avoid unnecessary computations.

The world matrix thick gets incremented every time the setWorldMatrix() or setLocalAndWorldMatrix() functions are called.

Definition at line 174 of file Transform.hpp.

Referenced by vl::Actor::boundsDirty(), and vl::Actor::computeBounds().

void vl::Transform::setAssumeIdentityWorldMatrix ( bool assume_I ) [inline]

If set to true the world matrix of this transform will always be considered and identity.

Is usually used to save calculations for top Transforms with many sub-Transforms.

Definition at line 178 of file Transform.hpp.

bool vl::Transform::assumeIdentityWorldMatrix ( ) [inline]

If set to true the world matrix of this transform will always be considered and identity.

Is usually used to save calculations for top Transforms with many sub-Transforms.

Definition at line 182 of file Transform.hpp.

Referenced by vl::Billboard::computeWorldMatrix().

virtual void vl::Transform::computeWorldMatrix ( Camera * = NULL ) [inline, virtual]

Computes the world matrix by concatenating the parent's world matrix with its own local matrix.

Reimplemented in vl::Billboard.

Definition at line 185 of file Transform.hpp.

Referenced by vl::TrackballManipulator::adjustView().

void vl::Transform::computeWorldMatrixRecursive ( Camera * camera = NULL ) [inline]

Computes the world matrix by concatenating the parent's world matrix with its local matrix, recursively descending to the children.

Definition at line 202 of file Transform.hpp.

Referenced by vl::Rendering::render().

mat4 vl::Transform::getComputedWorldMatrix ( ) [inline]

Returns the matrix computed concatenating this Transform's local matrix with the local matrices of all its parents.

Definition at line 210 of file Transform.hpp.

References localMatrix(), and parent().

const ref<Transform>* vl::Transform::children ( ) const [inline]

Returns the array containing the child Transforms.

Definition at line 225 of file Transform.hpp.

ref<Transform>* vl::Transform::children ( ) [inline]

Returns the array containing the child Transforms.

Definition at line 228 of file Transform.hpp.

size_t vl::Transform::childrenCount ( ) const [inline]

Returns the number of child Transform.

Definition at line 231 of file Transform.hpp.

void vl::Transform::addChild ( Transform * child ) [inline]

Adds a child transform.

Definition at line 234 of file Transform.hpp.

References mParent, and VL_CHECK.

Referenced by vl::VolumePlot::setupLabels().

void vl::Transform::addChildren	(	Transform const	children,
		size_t	count
	)		`[inline]`

Adds count children transforms.

Definition at line 244 of file Transform.hpp.

References mParent, and VL_CHECK.

void vl::Transform::addChildren	(	const ref< Transform > *	children,
		size_t	count
	)		`[inline]`

Definition at line 262 of file Transform.hpp.

References VL_CHECK.

void vl::Transform::addChildren ( const std::vector< ref< Transform > > & children ) [inline]

Definition at line 280 of file Transform.hpp.

void vl::Transform::addChildren ( const std::vector< Transform * > & children ) [inline]

Adds the specified children transforms.

Definition at line 287 of file Transform.hpp.

void vl::Transform::setChild	(	int	index,
		Transform *	child
	)		`[inline]`

Sets the index-th child.

Definition at line 294 of file Transform.hpp.

References mParent, and VL_CHECK.

const Transform* vl::Transform::lastChild ( ) const [inline]

Returns the last child.

Definition at line 304 of file Transform.hpp.

Transform* vl::Transform::lastChild ( ) [inline]

Returns the last child.

Definition at line 307 of file Transform.hpp.

void vl::Transform::eraseChild ( const Transform * child ) [inline]

Removes the given child Transform.

Definition at line 310 of file Transform.hpp.

References VL_CHECK.

void vl::Transform::eraseChildren	(	int	index,
		int	count
	)		`[inline]`

Removes count children Transforms starting at position index.

Definition at line 324 of file Transform.hpp.

References VL_CHECK.

void vl::Transform::eraseAllChildren ( ) [inline]

Removes all the children of a Transform.

Definition at line 338 of file Transform.hpp.

void vl::Transform::eraseAllChildrenRecursive ( ) [inline]

Removes all the children of a Transform recursively descending the hierarchy.

Definition at line 346 of file Transform.hpp.

void vl::Transform::flattenHierarchy ( ) [inline]

Disassembles a hierarchy of Transforms like eraseAllChildrenRecursive() does plus assigns the local matrix to equal the world matrix.

Definition at line 357 of file Transform.hpp.

void vl::Transform::removeFromParent ( ) [inline]

Erases a Transform from it's parent and sets the local matrix to be equal to the world matrix.

Definition at line 369 of file Transform.hpp.

void vl::Transform::shrink ( ) [inline]

Minimizes the amount of memory used to store the children Transforms.

Definition at line 379 of file Transform.hpp.

void vl::Transform::shrinkRecursive ( ) [inline]

Minimizes recursively the amount of memory used to store the children Transforms.

Definition at line 386 of file Transform.hpp.

void vl::Transform::reserveChildren ( size_t count ) [inline]

Reserves space for count children.

This function is very useful when you need to add one by one a large number of children transforms.

Note:: This function does not affect the number of children, it only reallocates the buffer used to store them so that it's large enough to eventually contain count of them. This will make subsequent calls to addChild() quicker as fewer or no reallocations of the buffer will be needed.

Definition at line 397 of file Transform.hpp.

bool vl::Transform::hasDuplicatedChildren ( ) const [inline]

Checks whether there are duplicated entries in the Transform's children list.

Definition at line 400 of file Transform.hpp.