ITransformShape
Functions
bool |
|
Detailed Description
-
class ITransformShape : public RED::IREDObject
This interface gives access to the shape’s transformation parameters.
@related Transform Shapes, Shapes Hierarchy , class RED::IShape
The CID_REDTransformShape that exposes this interface is the node (or transform) of the Red engine scene graph. It stores DAG nodes parameters:
A list of children of the transform shape,
A transformation matrix for the shape, that modify the position of all shape’s children.
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.
Public Functions
-
virtual bool 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.
-
virtual RED_RC AddChild(RED::Object *iShape, int iUpdate, 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 \ref wf_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.
-
virtual RED_RC RemoveChild(RED::Object *iShape, int iUpdate, 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 \ref wf_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.
-
virtual RED_RC RemoveChild(int iNumber, int iUpdate, 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.
-
virtual RED_RC RemoveChildren(const RED::Vector<int> &iChildNumList, int iUpdate, 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.
-
virtual RED_RC RemoveChildren(const RED::Vector<RED::Object*> &iChildList, int iUpdate, 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.
-
virtual RED_RC ClearChildren(int iUpdate, 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.
-
virtual RED_RC IsSubMaterialsOverride(bool &oOnOff, int iStateNumber = -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.
-
virtual RED_RC SetSubMaterialsOverride(bool iOnOff, 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: \ref bk_sg_shape_attributes, 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.
-
virtual RED_RC GetMatrix(const RED::Matrix *&oMatrix, int iStateNumber = -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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED::Vector3 GetRotationPivot(int iStateNumber = -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.
-
virtual RED_RC 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.
-
virtual RED::Vector3 GetScalingPivot(int iStateNumber = -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.
-
virtual RED_RC 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.
-
virtual RED::Matrix GetPivotAxis(int iStateNumber = -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).
-
virtual RED_RC BuildHLR(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
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 \ref wf_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.
-
virtual RED_RC BuildHLRLegacy(RED::Object *&oVisibleLines, RED::Object *&oHiddenLines, const RED::Object *iViewpoint, double iDistanceTolerance, const RED::State &iState, RED::ProgressCallback iProgressCallback = NULL, void *iUserData = NULL, RED::INTERRUPT_CALLBACK iInterruptCallback = NULL, void *iInterruptUserData = NULL) const = 0
Legacy REDsdk 5.0 HLR construction method.
This method behaves like RED::ITransformShape::BuildHLR, but it does not handle some specifics:
Manifold cases are not discarded the same way.
HLR segments are not clipped by the viewing frustum.
Triangle adjacency is not managed.
There’s no keep ID that can be used to identify back the source that has generated a HLR segment.
- 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.
