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
virtual const char *	className ()
	Returns the name of the class.
	Transform ()
	Constructor.
	Transform (const mat4 &matrix)
	Constructor.
const std::vector< ref < Transform > > &	children () const
	Returns the children Transforms.
void	addChild (Transform *child)
	Adds a child transform.
void	addChildren (Transform const , size_t count)
	Adds `count` children transforms.
void	addChildren (const ref< Transform > *, size_t count)
	Adds `count` children transforms.
void	addChildren (const std::vector< Transform * > &children)
	Adds the specified `children` transforms.
void	addChildren (const std::vector< ref< Transform > > &children)
	Adds the specified `children` transforms.
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.
void	setChild (int index, Transform *child)
	Sets the `index-th` child.
int	childCount () const
	Returns the number of children a Transform has.
Transform *	child (int i)
	Returns the i-th child Transform.
Transform *	lastChild ()
	Returns the last child.
void	eraseChild (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 hierachy.
const Transform *	parent () const
	Returns the parent of a Transform.
Transform *	parent ()
	Returns the parent of a Transform.
mat4	getComputedWorldMatrix ()
	Returns the matrix computed concatenating this Transform's local matrix with its parents' local matrices.
const mat4 &	localMatrix () const
	Returns the local matrix.
void	setLocalMatrix (const mat4 &matrix)
	Sets the local matrix.
void	translate (Real x, Real y, Real z)
	Utility function equivalent to `setLocalMatrix`( mat4::translation(x,y,z)*localMatrix() ).
void	translate (const vec3 &t)
	Utility function equivalent to `setLocalMatrix`( mat4::translation(t)*localMatrix() ).
void	scale (Real x, Real y, Real z)
	Utility function equivalent to `setLocalMatrix`( mat4::scaling(x,y,z)*localMatrix() ).
void	rotate (Real degrees, Real x, Real y, Real z)
	Utility function equivalent to `setLocalMatrix`( mat4::rotation(degrees,x,y,z)*localMatrix() ).
void	rotate (const vec3 &from, const vec3 &to)
	Utility function equivalent to `setLocalMatrix`( mat4::rotation(from,to)*localMatrix() ).
void	setLocalAndWorldMatrix (const mat4 &matrix)
	Sets both the local and the world matrices.
virtual void	computeWorldMatrix (Camera *camera=NULL)
	Computes the world matrix by concatenating the parent's world matrix with this' local matrix.
void	computeWorldMatrixRecursive (Camera *camera=NULL)
	Computes the world matrix by concatenating the parent's world matrix with this' local matrix, recursively descending to the children.
const mat4 &	worldMatrix () const
	Returns the world matrix used for rendering.
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.
bool	hasDuplicatedChildren () const
	Checks whether there are duplicated entries in the Transform's children list.
void	setWorldMatrix (const mat4 &matrix)
	Normally you should not use directly this function, call it only if you are sure you cannot do otherwise.
Protected Attributes
mat4	mWorldMatrix
mat4	mLocalMatrix
std::vector< ref< Transform > >	mChildren
Transform *	mParent
long long	mWorldMatrixUpdateTick
bool	mAssumeIdentityWorldMatrix

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 since multiplying by an identity matrix has no effect.

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, this will cause VL unnecessarily update the Transforms at each 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

Constructor & Destructor Documentation

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

Constructor.

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

Constructor.

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

Member Function Documentation

virtual const char* vl::Transform::className ( ) [inline, virtual]

Returns the name of the class.

Reimplemented from vl::Object.

Reimplemented in vl::Billboard.

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

Returns the children Transforms.

void Transform::addChild ( Transform * child )

Adds a child transform.

void Transform::addChildren	(	Transform const	children,
		size_t	count
	)

Adds count children transforms.

void Transform::addChildren	(	const ref< Transform > *	children,
		size_t	count
	)

Adds count children transforms.

void Transform::addChildren ( const std::vector< Transform * > & children )

Adds the specified children transforms.

void Transform::addChildren ( const std::vector< ref< Transform > > & children )

Adds the specified children transforms.

void Transform::shrink ( )

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

void Transform::shrinkRecursive ( )

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

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.

void Transform::setChild	(	int	index,
		Transform *	child
	)

Sets the index-th child.

int Transform::childCount ( ) const

Returns the number of children a Transform has.

Transform * Transform::child ( int i )

Returns the i-th child Transform.

Transform * Transform::lastChild ( )

Returns the last child.

void Transform::eraseChild ( Transform * child )

Removes the given child Transform.

void Transform::eraseChildren	(	int	index,
		int	count
	)

Removes count children Transforms starting at position index.

void Transform::eraseAllChildren ( )

Removes all the children of a Transform.

void Transform::eraseAllChildrenRecursive ( )

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

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

Returns the parent of a Transform.

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

Returns the parent of a Transform.

mat4 Transform::getComputedWorldMatrix ( )

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

const mat4 & Transform::localMatrix ( ) const

Returns the local matrix.

void Transform::setLocalMatrix ( const mat4 & matrix )

Sets the local matrix.

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

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

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

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

void Transform::translate ( const vec3 & t )

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

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

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

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

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

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

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

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

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

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

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

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);

void Transform::computeWorldMatrix ( Camera * camera = NULL ) [virtual]

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

Reimplemented in vl::Billboard.

void Transform::computeWorldMatrixRecursive ( Camera * camera = NULL )

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

const mat4 & Transform::worldMatrix ( ) const

Returns the world matrix used for rendering.

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.

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.

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.

bool Transform::hasDuplicatedChildren ( ) const

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

void Transform::setWorldMatrix ( const mat4 & matrix )

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

Calling this function will also increment the worldMatrixUpdateTick().

Member Data Documentation

mat4 vl::Transform::mWorldMatrix [protected]

mat4 vl::Transform::mLocalMatrix [protected]

std::vector< ref<Transform> > vl::Transform::mChildren [protected]

Transform* vl::Transform::mParent [protected]

long long vl::Transform::mWorldMatrixUpdateTick [protected]

bool vl::Transform::mAssumeIdentityWorldMatrix [protected]

The documentation for this class was generated from the following files:

C:/VL/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vl/Transform.hpp
C:/VL/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vl/Transform.cpp

Visualization Library

vl::Transform Class Reference

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation