# Visualization Library

A lightweight C++ OpenGL middleware for 2D/3D graphics

[Home] [Tutorials] [All Classes] [Grouped Classes]

Public Member Functions | Protected Attributes

# vl::Transform Class Reference

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

`#include <Transform.hpp>`

Inheritance diagram for vl::Transform:

List of all members.

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

References NULL, and 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 88 of file Transform.hpp.

References NULL, and VL_DEBUG_SET_OBJECT_NAME.

Transform::~Transform | ( | ) |

Destructor.

Definition at line 44 of file Transform.cpp.

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

## Member Function Documentation

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

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

Returns the parent Transform.

Definition at line 107 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 139 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 145 of file Transform.hpp.

Referenced by vl::VLXClassWrapper_Transform::exportTransform(), 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 153 of file Transform.hpp.

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

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

Returns the world matrix used for rendering.

Definition at line 160 of file Transform.hpp.

Referenced by vl::TrackballManipulator::adjustView(), vl::ClipPlane::apply(), vl::Text::boundingRectTransformed(), vl::Billboard::computeWorldMatrix(), vl::PixelLODEvaluator::evaluate(), vl::DistanceLODEvaluator::evaluate(), vl::RayIntersector::intersectGeometry(), vl::DaeLoader::load(), vl::SlicedVolume::onActorRenderStarted(), vl::EdgeUpdateCallback::onActorRenderStarted(), vl::DepthSortCallback::onActorRenderStarted(), vl::DrawPixels::render_Implementation(), vl::EdgeRenderer::renderLines(), vl::EdgeRenderer::renderSolids(), vl::Text::renderText(), vl::RenderQueue::sort(), vl::ProjViewTransfCallback::updateMatrices(), vl::SlicedVolume::updateUniforms(), vl::RaycastVolume::updateUniforms(), and ~Transform().

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

Referenced by vl::VLXClassWrapper_Transform::importTransform().

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 176 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 180 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 184 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 187 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 204 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 212 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 227 of file Transform.hpp.

References NULL.

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

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

Returns the array containing the child Transforms.

Definition at line 230 of file Transform.hpp.

References NULL.

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

Returns the number of child Transform.

Definition at line 233 of file Transform.hpp.

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

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

Adds a child transform.

Definition at line 236 of file Transform.hpp.

References mParent, NULL, and VL_CHECK.

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

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

Adds `count` children transforms.

Definition at line 246 of file Transform.hpp.

References mParent, NULL, and VL_CHECK.

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

Definition at line 264 of file Transform.hpp.

References NULL, and VL_CHECK.

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

Definition at line 282 of file Transform.hpp.

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

Adds the specified `children` transforms.

Definition at line 289 of file Transform.hpp.

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

Sets the `index-th` child.

Definition at line 296 of file Transform.hpp.

References mParent, NULL, and VL_CHECK.

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

Returns the last child.

Definition at line 306 of file Transform.hpp.

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

Returns the last child.

Definition at line 309 of file Transform.hpp.

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

Removes the given `child` Transform.

Definition at line 312 of file Transform.hpp.

References NULL, and VL_CHECK.

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

Removes `count` children Transforms starting at position `index`.

Definition at line 326 of file Transform.hpp.

References NULL, and VL_CHECK.

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

Removes all the children of a Transform.

Definition at line 340 of file Transform.hpp.

References NULL.

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

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

Definition at line 348 of file Transform.hpp.

References NULL.

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

References NULL.

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

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

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

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

Definition at line 381 of file Transform.hpp.

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

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

Definition at line 388 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 399 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 402 of file Transform.hpp.

## Member Data Documentation

mat4 vl::Transform::mLocalMatrix`[protected]`

Definition at line 421 of file Transform.hpp.

mat4 vl::Transform::mWorldMatrix`[protected]`

Definition at line 422 of file Transform.hpp.

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

Definition at line 423 of file Transform.hpp.

bool vl::Transform::mAssumeIdentityWorldMatrix`[protected]`

Definition at line 424 of file Transform.hpp.

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

Definition at line 425 of file Transform.hpp.

Referenced by ~Transform().

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

Definition at line 426 of file Transform.hpp.

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

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

- D:/VL/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vlCore/Transform.hpp
- D:/VL/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vlCore/Transform.cpp

Visualization Library v2011.09.1162 Reference Documentation
Copyright 2005-2011 Michele Bosi. All rights reserved.
Updated on Thu Jan 26 2012 00:44:15.
Permission is granted to use this page to write and publish articles regarding Visualization Library.