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. More...

	Transform (const mat4 &matrix)
	Constructor. More...

	~Transform ()
	Destructor. More...

const Transform *	parent () const
	Returns the parent Transform. More...

Transform *	parent ()
	Returns the parent Transform. More...

void	translate (real x, real y, real z)
	Utility function equivalent to `setLocalMatrix`( mat4::getTranslation(x,y,z)*localMatrix() ). More...

void	translate (const vec3 &t)
	Utility function equivalent to `setLocalMatrix`( mat4::getTranslation(t)*localMatrix() ). More...

void	scale (real x, real y, real z)
	Utility function equivalent to `setLocalMatrix`( mat4::getScaling(x,y,z)*localMatrix() ). More...

void	rotate (real degrees, real x, real y, real z)
	Utility function equivalent to `setLocalMatrix`( mat4::getRotation(degrees,x,y,z)*localMatrix() ). More...

void	rotate (const vec3 &from, const vec3 &to)
	Utility function equivalent to `setLocalMatrix`( mat4::getRotation(from,to)*localMatrix() ). More...

void	preMultiply (const mat4 &m)
	Utility function equivalent to `setLocalMatrix( m*localMatrix() )`. More...

void	postMultiply (const mat4 &m)
	Utility function equivalent to `setLocalMatrix( localMatrix()*m )`. More...

void	setLocalMatrix (const mat4 &m)
	The matrix representing the transform's local space. More...

const mat4 &	localMatrix () const
	The matrix representing the transform's local space. More...

mat4 &	localMatrix ()
	The matrix representing the transform's local space. More...

void	setWorldMatrix (const mat4 &matrix)
	Normally you should not use directly this function, call it only if you are sure you cannot do otherwise. More...

const mat4 &	worldMatrix () const
	Returns the world matrix used for rendering. More...

void	setLocalAndWorldMatrix (const mat4 &matrix)
	Sets both the local and the world matrices. More...

long long	worldMatrixUpdateTick () const
	Returns the internal update tick used to avoid unnecessary computations. More...

void	setAssumeIdentityWorldMatrix (bool assume_I)
	If set to true the world matrix of this transform will always be considered and identity. More...

bool	assumeIdentityWorldMatrix ()
	If set to true the world matrix of this transform will always be considered and identity. More...

virtual void	computeWorldMatrix (Camera *=NULL)
	Computes the world matrix by concatenating the parent's world matrix with its own local matrix. More...

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. More...

mat4	getComputedWorldMatrix ()
	Returns the matrix computed concatenating this Transform's local matrix with the local matrices of all its parents. More...

const ref< Transform > *	children () const
	Returns the array containing the child Transforms. More...

ref< Transform > *	children ()
	Returns the array containing the child Transforms. More...

size_t	childrenCount () const
	Returns the number of child Transform. More...

void	addChild (Transform *child)
	Adds a child transform. More...

void	addChildren (Transform const children, size_t count)
	Adds `count` children transforms. More...

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. More...

void	setChild (int index, Transform *child)
	Sets the `index-th` child. More...

const Transform *	lastChild () const
	Returns the last child. More...

Transform *	lastChild ()
	Returns the last child. More...

void	eraseChild (const Transform *child)
	Removes the given `child` Transform. More...

void	eraseChildren (int index, int count)
	Removes `count` children Transforms starting at position `index`. More...

void	eraseAllChildren ()
	Removes all the children of a Transform. More...

void	eraseAllChildrenRecursive ()
	Removes all the children of a Transform recursively descending the hierarchy. More...

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

void	removeFromParent ()
	Erases a Transform from it's parent and sets the local matrix to be equal to the world matrix. More...

void	shrink ()
	Minimizes the amount of memory used to store the children Transforms. More...

void	shrinkRecursive ()
	Minimizes recursively the amount of memory used to store the children Transforms. More...

void	reserveChildren (size_t count)
	Reserves space for `count` children. More...

bool	hasDuplicatedChildren () const
	Checks whether there are duplicated entries in the Transform's children list. More...

Public Member Functions inherited from vl::Object
	Object ()
	Constructor. More...

	Object (const Object &other)
	Copy constructor: copies the name, ref count mutex and user data. More...

Object &	operator= (const Object &other)
	Copy operator: copies the object's name, ref count mutex and user data. More...

const std::string &	objectName () const
	The name of the object, by default set to the object's class name. More...

void	setObjectName (const char *name)
	The name of the object, by default set to the object's class name in debug builds. More...

void	setObjectName (const std::string &name)
	The name of the object, by default set to the object's class name in debug builds. More...

void	setRefCountMutex (IMutex *mutex)
	The mutex used to protect the reference counting of an Object across multiple threads. More...

IMutex *	refCountMutex ()
	The mutex used to protect the reference counting of an Object across multiple threads. More...

const IMutex *	refCountMutex () const
	The mutex used to protect the reference counting of an Object across multiple threads. More...

int	referenceCount () const
	Returns the number of references of an object. More...

void	incReference () const
	Increments the reference count of an object. More...

void	decReference ()
	Decrements the reference count of an object and deletes it if both automaticDelete() is `true` the count reaches 0. More...

void	setAutomaticDelete (bool autodel_on)
	If set to true the Object is deleted when its reference count reaches 0. More...

bool	automaticDelete () const
	If set to true the Object is deleted when its reference count reaches 0. More...

template<class T >
T *	as ()
	Casts an Object to the specified class. More...

template<class T >
const T *	as () const
	Casts an Object to the specified class. More...

Protected Attributes
mat4	mLocalMatrix

mat4	mWorldMatrix

long long	mWorldMatrixUpdateTick

bool	mAssumeIdentityWorldMatrix

std::vector< ref< Transform > >	mChildren

Transform *	mParent

Protected Attributes inherited from vl::Object
std::string	mObjectName

IMutex *	mRefCountMutex

int	mReferenceCount

bool	mAutomaticDelete

Additional Inherited Members
Protected Member Functions inherited from vl::Object
virtual	~Object ()

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

◆ Transform() [1/2]

vl::Transform::Transform ( )

inline

Constructor.

Definition at line 78 of file Transform.hpp.

References NULL.

◆ Transform() [2/2]

vl::Transform::Transform ( const mat4 & matrix )

inline

Constructor.

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

Definition at line 88 of file Transform.hpp.

References NULL.

◆ ~Transform()

Transform::~Transform ( )

Destructor.

Definition at line 44 of file Transform.cpp.

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

Member Function Documentation

◆ addChild()

void vl::Transform::addChild ( Transform * child )

inline

Adds a child transform.

Definition at line 246 of file Transform.hpp.

References mParent, NULL, and VL_CHECK.

Referenced by vlX::VLXClassWrapper_Transform::importTransform(), and vl::VolumePlot::setupLabels().

◆ addChildren() [1/4]

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

inline

Adds count children transforms.

Definition at line 256 of file Transform.hpp.

References mParent, NULL, and VL_CHECK.

◆ addChildren() [2/4]

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

inline

Definition at line 274 of file Transform.hpp.

References NULL, and VL_CHECK.

◆ addChildren() [3/4]

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

inline

Definition at line 292 of file Transform.hpp.

◆ addChildren() [4/4]

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

inline

Adds the specified children transforms.

Definition at line 299 of file Transform.hpp.

◆ assumeIdentityWorldMatrix()

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 192 of file Transform.hpp.

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

◆ children() [1/2]

const ref<Transform>* vl::Transform::children ( ) const

inline

Returns the array containing the child Transforms.

Definition at line 237 of file Transform.hpp.

References NULL.

Referenced by vlX::VLXClassWrapper_Transform::exportTransform().

◆ children() [2/2]

ref<Transform>* vl::Transform::children ( )

inline

Returns the array containing the child Transforms.

Definition at line 240 of file Transform.hpp.

References NULL.

◆ childrenCount()

size_t vl::Transform::childrenCount ( ) const

inline

Returns the number of child Transform.

Definition at line 243 of file Transform.hpp.

Referenced by vlX::VLXClassWrapper_Transform::exportTransform().

◆ computeWorldMatrix()

virtual void vl::Transform::computeWorldMatrix ( Camera * = NULL )

inlinevirtual

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

Reimplemented in vl::Billboard.

Definition at line 195 of file Transform.hpp.

Referenced by vl::TrackballManipulator::adjustView(), vl::Billboard::computeWorldMatrix(), and vl::VolumePlot::setupLabels().

◆ computeWorldMatrixRecursive()

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 214 of file Transform.hpp.

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

◆ eraseAllChildren()

void vl::Transform::eraseAllChildren ( )

inline

Removes all the children of a Transform.

Definition at line 350 of file Transform.hpp.

References NULL.

◆ eraseAllChildrenRecursive()

void vl::Transform::eraseAllChildrenRecursive ( )

inline

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

Definition at line 358 of file Transform.hpp.

References NULL.

◆ eraseChild()

void vl::Transform::eraseChild ( const Transform * child )

inline

Removes the given child Transform.

Definition at line 322 of file Transform.hpp.

References NULL, and VL_CHECK.

◆ eraseChildren()

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

inline

Removes count children Transforms starting at position index.

Definition at line 336 of file Transform.hpp.

References NULL, and VL_CHECK.

◆ flattenHierarchy()

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 369 of file Transform.hpp.

References NULL.

◆ getComputedWorldMatrix()

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 222 of file Transform.hpp.

References localMatrix(), and parent().

◆ hasDuplicatedChildren()

bool vl::Transform::hasDuplicatedChildren ( ) const

inline

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

Definition at line 412 of file Transform.hpp.

◆ lastChild() [1/2]

const Transform* vl::Transform::lastChild ( ) const

inline

Returns the last child.

Definition at line 316 of file Transform.hpp.

◆ lastChild() [2/2]

Transform* vl::Transform::lastChild ( )

inline

Returns the last child.

Definition at line 319 of file Transform.hpp.

◆ localMatrix() [1/2]

const mat4& vl::Transform::localMatrix ( ) const

inline

The matrix representing the transform's local space.

Definition at line 145 of file Transform.hpp.

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

◆ localMatrix() [2/2]

mat4& vl::Transform::localMatrix ( )

inline

The matrix representing the transform's local space.

Use this non-const version to directly modify the local matrix. Call computeWorldMatrix() after modifying the local matrix.

Definition at line 153 of file Transform.hpp.

◆ parent() [1/2]

const Transform* vl::Transform::parent ( ) const

inline

Returns the parent Transform.

Definition at line 104 of file Transform.hpp.

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

◆ parent() [2/2]

Transform* vl::Transform::parent ( )

inline

Returns the parent Transform.

Definition at line 107 of file Transform.hpp.

References vl::degrees().

◆ postMultiply()

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().

◆ preMultiply()

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().

◆ removeFromParent()

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 381 of file Transform.hpp.

Referenced by vl::DaeLoader::load().

◆ reserveChildren()

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 409 of file Transform.hpp.

◆ rotate() [1/2]

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().

◆ rotate() [2/2]

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().

◆ scale()

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().

◆ setAssumeIdentityWorldMatrix()

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 188 of file Transform.hpp.

◆ setChild()

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

inline

Sets the index-th child.

Definition at line 306 of file Transform.hpp.

References mParent, NULL, and VL_CHECK.

◆ setLocalAndWorldMatrix()

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 176 of file Transform.hpp.

Referenced by vlX::VLXClassWrapper_Transform::importTransform(), and vl::Terrain::init().

◆ 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 139 of file Transform.hpp.

Referenced by vl::Molecule::atomsStyle(), vl::Molecule::ballAndStickStyle(), postMultiply(), preMultiply(), rotate(), scale(), vl::Billboard::setPosition(), vl::VolumePlot::setupLabels(), vl::Molecule::sticksStyle(), and translate().

◆ setWorldMatrix()

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 161 of file Transform.hpp.

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

◆ shrink()

void vl::Transform::shrink ( )

inline

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

Definition at line 391 of file Transform.hpp.

◆ shrinkRecursive()

void vl::Transform::shrinkRecursive ( )

inline

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

Definition at line 398 of file Transform.hpp.

◆ translate() [1/2]

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().

◆ translate() [2/2]

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().

◆ worldMatrix()

const mat4& vl::Transform::worldMatrix ( ) const

inline

◆ worldMatrixUpdateTick()

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 184 of file Transform.hpp.

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

Member Data Documentation

◆ mAssumeIdentityWorldMatrix

bool vl::Transform::mAssumeIdentityWorldMatrix

protected

Definition at line 434 of file Transform.hpp.

◆ mChildren

std::vector< ref<Transform> > vl::Transform::mChildren

protected

Definition at line 435 of file Transform.hpp.

Referenced by ~Transform().

◆ mLocalMatrix

mat4 vl::Transform::mLocalMatrix

protected

Definition at line 431 of file Transform.hpp.

◆ mParent

Transform* vl::Transform::mParent

protected

Definition at line 436 of file Transform.hpp.

Referenced by addChild(), addChildren(), and setChild().

◆ mWorldMatrix

mat4 vl::Transform::mWorldMatrix

protected

Definition at line 432 of file Transform.hpp.

◆ mWorldMatrixUpdateTick

long long vl::Transform::mWorldMatrixUpdateTick

protected

Definition at line 433 of file Transform.hpp.

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

C:/git/VL/src/vlCore/Transform.hpp
C:/git/VL/src/vlCore/Transform.cpp

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Transform() [1/2]

◆ Transform() [2/2]

◆ ~Transform()

Member Function Documentation

◆ addChild()

◆ addChildren() [1/4]

◆ addChildren() [2/4]

◆ addChildren() [3/4]

◆ addChildren() [4/4]

◆ assumeIdentityWorldMatrix()

◆ children() [1/2]

◆ children() [2/2]

◆ childrenCount()

◆ computeWorldMatrix()

◆ computeWorldMatrixRecursive()

◆ eraseAllChildren()

◆ eraseAllChildrenRecursive()

◆ eraseChild()

◆ eraseChildren()

◆ flattenHierarchy()

◆ getComputedWorldMatrix()

◆ hasDuplicatedChildren()

◆ lastChild() [1/2]

◆ lastChild() [2/2]

◆ localMatrix() [1/2]

◆ localMatrix() [2/2]

◆ parent() [1/2]

◆ parent() [2/2]

◆ postMultiply()

◆ preMultiply()

◆ removeFromParent()

◆ reserveChildren()

◆ rotate() [1/2]

◆ rotate() [2/2]

◆ scale()

◆ setAssumeIdentityWorldMatrix()

◆ setChild()

◆ setLocalAndWorldMatrix()

◆ setLocalMatrix()

◆ setWorldMatrix()

◆ shrink()

◆ shrinkRecursive()

◆ translate() [1/2]

◆ translate() [2/2]

◆ worldMatrix()

◆ worldMatrixUpdateTick()

Member Data Documentation

◆ mAssumeIdentityWorldMatrix

◆ mChildren

◆ mLocalMatrix

◆ mParent

◆ mWorldMatrix

◆ mWorldMatrixUpdateTick