class RED::ITransformShape

This interface gives access to the shape's transformation parameters. More...

#include <REDITransformShape.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddChild ( RED::Object * iShape, int iUpdate, const RED::State & iState ) = 0
virtual RED_RCBuildHLR ( RED::Object *& oVisibleLines, RED::Object *& oHiddenLines, const RED::Object * iViewpoint, double iDistanceTolerance, bool iKeepSourceIDs, const RED::State & iState, RED::ProgressCallback iProgressCallback = NULL, void * iUserData = NULL, RED::INTERRUPT_CALLBACK iInterruptCallback = NULL, void * iInterruptUserData = NULL ) const = 0
virtual RED_RCClearChildren ( int iUpdate, const RED::State & iState ) = 0
virtual RED_RCGetMatrix ( const RED::Matrix *& oMatrix, int iStateNumber = -1 ) const = 0
virtual RED_RCGetMatrix ( RED::Matrix *& oMatrix, const RED::State & iState ) = 0
virtual RED::MatrixGetPivotAxis ( int iStateNumber = -1 ) const = 0
virtual RED::Vector3GetRotationPivot ( int iStateNumber = -1 ) const = 0
virtual RED::Vector3GetScalingPivot ( int iStateNumber = -1 ) const = 0
virtual boolIsSceneGraphRoot ( ) const = 0
virtual RED_RCIsSubMaterialsOverride ( bool & oOnOff, int iStateNumber = -1 ) const = 0
virtual RED_RCRemoveChild ( int iNumber, int iUpdate, const RED::State & iState ) = 0
virtual RED_RCRemoveChild ( RED::Object * iShape, int iUpdate, const RED::State & iState ) = 0
virtual RED_RCRemoveChildren ( const RED::Vector< int > & iChildNumList, int iUpdate, const RED::State & iState ) = 0
virtual RED_RCRemoveChildren ( const RED::Vector< RED::Object * > & iChildList, int iUpdate, const RED::State & iState ) = 0
virtual RED_RCSetMatrix ( const RED::Matrix * iMatrix, const RED::State & iState ) = 0
virtual RED_RCSetPivotAxis ( const RED::Matrix & iMatrix, const RED::State & iState ) = 0
virtual RED_RCSetRotationPivot ( const RED::Vector3 & iRotationPivot, const RED::State & iState ) = 0
virtual RED_RCSetScalingPivot ( const RED::Vector3 & iScalingPivot, const RED::State & iState ) = 0
virtual RED_RCSetSubMaterialsOverride ( bool iOnOff, const RED::State & iState ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

This interface gives access to the shape's transformation parameters.

The CID_REDTransformShape that exposes this interface is the node (or transform) of the Red engine scene graph. It stores DAG nodes parameters:

The bounding sphere of a transform shape encloses the geometry of all children of the shape. Therefore, it's calculated based on the transformed children's spatial positions. There's no need to apply a node's matrix to the bounding sphere of this node itself, as the node has coordinates set to enclosed all transformed vertices of all its children geometries.

It's a state sensitive object.

Note that the root of a scene graph returned by the RED::IViewpoint interface is a special node that can't be added as child of another shape. Similarly, it's not possible to destroy the root of a scene graph. Destruction of such shapes is performed by the camera when it ceases to exist.

Functions documentation

public virtual RED_RC RED::ITransformShape::AddChild(RED::Object *iShape,
intiUpdate,
const RED::State &iState
) = 0

Adds a child shape to the transform shape.

This method adds the provided child shape to the node (the shape is appened at the end of the list of existing children). iShape must be a valid shape instance address. 'iShape' is modified to record its new parent, performing a two sided link.

There's no duplicate insertion check made as this could cause scene graph manipulation performances losses. Nevertheless, it's an error to add the same iShape twice or more as the child of the same parent.

The scene graph's bounding spheres may be updated based on the value of iUpdate.

It's not possible to add a scene graph root as a child of anyone.

Please refer to the Shapes hierarchy tutorial for details on scene graph manipulation.

Parameters:

iShape:The shape added to the node.
iUpdate:RED_SHP_DAG_UPDATE or RED_SHP_DAG_NO_UPDATE to enable or to disable the bounding sphere update.
iState:Current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if the added shape is a scene graph root,
RED_WORKFLOW_ERROR if the added shape is this,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::BuildHLR(RED::Object *&oVisibleLines,
RED::Object *&oHiddenLines,
const RED::Object *iViewpoint,
doubleiDistanceTolerance,
booliKeepSourceIDs,
const RED::State &iState,
RED::ProgressCallbackiProgressCallback = NULL,
void *iUserData = NULL,
RED::INTERRUPT_CALLBACKiInterruptCallback = NULL,
void *iInterruptUserData = NULL
)const = 0

Construct the hidden lines removal view of the scene graph held by this shape.

This method can be used to build the HLR view (Hidden Lines Removal) of the entire scene graph stored by this shape. The method returns two sets of lines in two shapes: visible lines that are above hidden lines. The calculation is performed for the specified iViewpoint.

Note that visible or hidden contour edges may be incorrect for manifold shapes.

Please see Hidden Lines Removal for a practical example of using this method.

Parameters:

oVisibleLines:The visible lines segments shape, created by the method. Can be NULL if the method returns an error.
oHiddenLines:The hidden lines segments shape, created by the method. Can be NULL if the method returns an error.
iViewpoint:The camera source, from which visibility is checked.
iDistanceTolerance:The numerical distance tolerancy to use for the HLR calculations. This value is used to call the RED::IMeshShape::Collapse methods to prepare data for HLR calculations. If meshes in the scene graph under this are already clean, use 0.0 as value for the distance tolerance. This speeds up calculations.
iKeepSourceIDs:If true, Object IDs (from RED::Object::GetID) from the source scene graph are preserved and oVisibleLines and oHiddenLines are set with a RED::MCL_TEX0 channel that contains the unsigned int value filled with the ID of the shape they are coming from.
iState:The current transaction parameter.
iProgressCallback:Optional progress indicator callback. Several steps are sent to the callback that corresponds to the internal calculation phases. Note that the progress ratio may significantly move back and forth during some calculation phases due to the recursive and progressive nature of the calculations whose amount to perform can vary during the processing.
iUserData:User data for iProgressCallback.
iInterruptCallback:Optional interruption callback. If the method gets interrupted, then oVisibleLines and oHiddenLines will be returned NULL.
iInterruptUserData:User data for iInterruptCallback.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if iViewpoint is not valid,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::ClearChildren(intiUpdate,
const RED::State &iState
) = 0

Removes all children of a shape.

This methods behaves like RemoveChild, except that is removes all children of the transform shape. As for RemoveChild, only links are removed. Child shapes are not deleted.

The scene graph's bounding spheres may be updated based on the value of iUpdate.

Parameters:

iUpdate:RED_SHP_DAG_UPDATE or RED_SHP_DAG_NO_UPDATE to enable or to disable the bounding sphere update.
iState:Current transaction parameter.

Returns:

RED_OK when the children list was successfully cleared,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::GetMatrix(const RED::Matrix *&oMatrix,
intiStateNumber = -1
)const = 0

Read only access to the node matrix.

Returns a const pointer to the stored matrix. The returned matrix is read-only. To modify the matrix use RED::ITransformShape::GetMatrix.

Parameters:

oMatrix:Address of the requested matrix if it exists, NULL otherwise.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
public virtual RED_RC RED::ITransformShape::GetMatrix(RED::Matrix *&oMatrix,
const RED::State &iState
) = 0

Read write access to the node matrix.

Returns a pointer to the stored matrix. If the shape has no matrix, the routine creates a new one that is returned for edition. This created matrix becomes the new node matrix. This matrix is managed by the object instance that will take care of destroying it.

Parameters:

oMatrix:Pointer to the returned matrix.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED::Matrix RED::ITransformShape::GetPivotAxis(intiStateNumber = -1) const = 0

Gets the pivot's three axis.

Parameters:

iStateNumber:Queried state number.

Returns:

A matrix defining the pivot's three axis (translation is set to zero).
public virtual RED::Vector3 RED::ITransformShape::GetRotationPivot(intiStateNumber = -1) const = 0

Returns the origin of local rotation transforms.

Return the node's rotation pivot origin. Transforms applied to shape's children can use this point as transformation invariant.

A pivot based rotation can be done using the following code:

  RED::Matrix *nodematx;
  RED::Matrix mpivot;
  RED::Vector3 ploc,pobj;
  
  node->GetMatrix( &nodematx, state );
  ploc = node->GetRotationPivot();
  pobj = *nodematx * ploc;
  
  mpivot.RotationAxisMatrix( pobj, RED::Vector3(x,y,z), angle );
  mpivot *= nodematx;
  *nodematx = mpivot;

We store and return the pivot in the local object space. A correct pivot rotation must be applied as a left handed matrix multiplication, with the pivot point converted in the object's space.

Parameters:

iStateNumber:Queried state number.

Returns:

The rotation pivot point in the object's local space.
public virtual RED::Vector3 RED::ITransformShape::GetScalingPivot(intiStateNumber = -1) const = 0

Returns the origin of local scaling transforms.

Return the node's scaling pivot origin. Transforms applied to shape's children can use this point as transformation invariant.

A pivot based scaling can be done using the following code:

  RED::Matrix *nodematx;
  RED::Matrix mpivot;
  RED::Vector3 ploc,pobj;
  
  node->GetMatrix((void **)&nodematx,state);
  ploc = node->GetScalingPivot();
  pobj = *nodematx * ploc;
  
  mpivot.ScalingAxisMatrix(pobj,RED::Vector3(x,y,z));
  mpivot *= nodematx;
  *nodematx = mpivot;

We store and return the pivot in the local object space. A correct pivot scaling must be applied as a left handed matrix multiplication, with the pivot point converted in the object's space.

Parameters:

iStateNumber:Queried state number.

Returns:

The scaling pivot point.
public virtual bool RED::ITransformShape::IsSceneGraphRoot() const = 0

Is the transform shape a scene graph root?

A node shape that is a scene graph root can't be added as a child of another shape. Such nodes are created by the REDsdk as root shapes of the scene graph held by a viewpoint, and are accessed through the RED::IViewpoint interface.

Returns:

true if the shape is a scene graph root.
public virtual RED_RC RED::ITransformShape::IsSubMaterialsOverride(bool &oOnOff,
intiStateNumber = -1
)const = 0

Are we overriding materials of children shapes?

See RED::ITransformShape::SetSubMaterialsOverride for details.

Parameters:

oOnOff:true if our material overrides any sub material found in the scene graph, false otherwise.
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::RemoveChild(intiNumber,
intiUpdate,
const RED::State &iState
) = 0

Removes a child by its number from the transform shape.

This method removes the child whose number is iNumber from the list stored by the transform shape.

Parameters:

iNumber:Number of the shape in the transform's list.
iUpdate:RED_SHP_DAG_UPDATE or RED_SHP_DAG_NO_UPDATE to enable or to disable the bounding sphere update.
iState:Current transaction parameter.

Returns:

RED_OK when the shape was successfully removed,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::RemoveChild(RED::Object *iShape,
intiUpdate,
const RED::State &iState
) = 0

Removes a child shape from the transform shape.

This methods removes all occurrences of the given shape from the list of children stored by the node. iShape's parent list is modified to reflect this change in the DAG structure.

iShape is not deleted by that call. Only the link between the two shapes is broken.

The scene graph's bounding spheres may be updated based on the value of iUpdate.

Please refer to the Shapes hierarchy tutorial for details on scene graph manipulation.

Parameters:

iShape:The REDShape to be removed from the node.
iUpdate:RED_SHP_DAG_UPDATE or RED_SHP_DAG_NO_UPDATE to enable or to disable the bounding sphere update.
iState:Current transaction parameter.

Returns:

RED_OK when the shape was successfully removed,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::RemoveChildren(const RED::Vector< int > &iChildNumList,
intiUpdate,
const RED::State &iState
) = 0

Removes a list of children by their number from the transform shape.

This method removes a list of children in one operation from the list stored by the transform shape. This method is faster than the equivalent RED::ITransformShape::RemoveChild method for 1 child called several times.

Parameters:

iChildNumList:List of children numbers.
iUpdate:RED_SHP_DAG_UPDATE or RED_SHP_DAG_NO_UPDATE to enable or to disable the bounding sphere update.
iState:Current transaction parameter.

Returns:

RED_OK when the shape was successfully removed,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::RemoveChildren(const RED::Vector< RED::Object * > &iChildList,
intiUpdate,
const RED::State &iState
) = 0

Removes a list of children by their addresses from the transform shape.

This method removes a list of children in one operation from the list stored by the transform shape. This method is faster than the equivalent RED::ITransformShape::RemoveChild method for 1 child called several times.

Parameters:

iChildList:List of children shapes.
iUpdate:RED_SHP_DAG_UPDATE or RED_SHP_DAG_NO_UPDATE to enable or to disable the bounding sphere update.
iState:Current transaction parameter.

Returns:

RED_OK when the shape was successfully removed,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::SetMatrix(const RED::Matrix *iMatrix,
const RED::State &iState
) = 0

Sets a new matrix for the transform shape.

Sets iMatrix as the new matrix for the transform shape. The value of iMatrix can be NULL, indicating that the node has no matrix influence over its children and only applies the transform matrix inherited from its parents.

The matrix of a transform shape has an effect over all its children. It can be accessed as a whole transformation for each shaded shape (the cumulative transform from the root down to the shaded shape instance will be accessed) in shader programs:

  • The matrix will be part of the modelview, model-view-projection transformations.
  • In ARB assembly shader programs, the model transformation can be accessed if it has been declared in the RED::RenderCode specification of the shader. In this case, the model matrix of the shaded geometry is stored in 'state.matrix.program[1]'.
  • In GLSL shader programs, similarly, once declared in the render code, the model matrix of the shaded geometry is stored in 'gl_TextureMatrix[1]'.

Parameters:

iMatrix:New matrix for the transform shape. If 'iMatrix' is NULL, the matrix is removed from the transform shape. Otherwise, the specified matrix is duplicated into the object.
iState:Current transaction parameter.

Returns:

RED_OK when the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::SetPivotAxis(const RED::Matrix &iMatrix,
const RED::State &iState
) = 0

Sets the pivot's three axis.

Those axis added to a custom rotation or scaling pivot position can be used to define a whole new transform basis for the shape.

Parameters:

iMatrix:Matrix defining the pivot's three axis (translation is ignored).
iState:Current transaction parameter.

Returns:

RED_OK on success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::SetRotationPivot(const RED::Vector3 &iRotationPivot,
const RED::State &iState
) = 0

Defines the origin of local rotation transforms.

Defines the rotation pivot for all children of the object. The pivot can be used as origin for all rotations applied to children of the node.

Parameters:

iRotationPivot:Object local space pivot point.
iState:Current transaction parameter.

Returns:

RED_OK on success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::SetScalingPivot(const RED::Vector3 &iScalingPivot,
const RED::State &iState
) = 0

Defines the origin of local scaling transforms.

Defines the scaling pivot for all children of the object. The pivot can be used as origin for all scalings applied to children of the node.

Parameters:

iScalingPivot:Object local space pivot point.
iState:Current transaction parameter.

Returns:

RED_OK on success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITransformShape::SetSubMaterialsOverride(booliOnOff,
const RED::State &iState
) = 0

Change the scene graph material inheritance rules for this part of the scene graph.

The default inheritance rule for materials in a scene graph, detailed here: Attributes of a shape, states that the material of a child shape has precedence over the material of a parent shape. This is the "last on path" rule.

This rule can be locally overriden in a scene graph using this method. Setting the sub material override flag on cause all materials of children shapes of a shape using this to be ignored.

Parameters:

iOnOff:If turned on, all materials of all children shapes of this will have their material overriden by the material we own.
iState:Current transaction.

Returns:

RED_OK if the method has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.