class RED::IShape

This interface gives access to the shape's properties. More...

#include <REDIShape.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddToLayer ( unsigned int iLayer, const RED::State & iState ) = 0
virtual RED_RCApplyLayerSet ( const RED::LayerSet * iLayerSet, const RED::State & iState ) = 0
virtual RED_RCComputeBoundingSphere ( const RED::State & iState ) = 0
virtual RED_RCGetBoundingSphere ( RED::BoundingSphere *& oBoundingSphere, const RED::State & iState ) = 0
virtual RED_RCGetBoundingSphere ( RED::BoundingSphere *& oBoundingSphere, int iStateNumber = -1 ) const = 0
virtual RED_RCGetChild ( RED::Object *& oChild, int iChildNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetChildByID ( RED::Object *& oChild, unsigned int iChildID, int iStateNumber = -1 ) const = 0
virtual RED_RCGetChildByID ( RED::Object *& oChild, const RED::String & iChildID, int iStateNumber = -1 ) const = 0
virtual RED_RCGetChildren ( const RED::Vector< RED::Object * > *& oChildList, int iStateNumber = -1 ) const = 0
virtual RED_RCGetChildrenCount ( int & oChildrenCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetContextSwitchCallback ( USER_SWITCH_CALLBACK & oContextSwitchCB, void *& oUserData, int iStateNumber = -1 ) const = 0
virtual RED_RCGetLayerSet ( const RED::LayerSet *& iLayerSet, int iStateNumber = -1 ) const = 0
virtual RED_RCGetMaterial ( RED::Object *& oMaterial, int iStateNumber = -1 ) const = 0
virtual RED_RCGetMemorySize ( RED::uint64 & oByteSize ) const = 0
virtual RED_RCGetParent ( RED::Object *& oParent, int iParentNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetParents ( const RED::Vector< RED::Object * > *& oParentlist, int iStateNumber = -1 ) const = 0
virtual RED_RCGetParentsCount ( int & oParentsCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetShapes ( RED::Map< RED::Object *, unsigned int > & oShapes, const RED::CID & iCID ) = 0
virtual RED_RCGetVisibilitySwitchCallback ( USER_SWITCH_CALLBACK & oVisibilitySwitchCB, void *& oUserData, int iStateNumber = -1 ) const = 0
virtual RED_RCIsChildOf ( bool & ioChildOf, const RED::Object * iShape, int iStateNumber = -1 ) const = 0
virtual RED_RCRemoveBoundingSphere ( const RED::State & iState ) = 0
virtual RED_RCRemoveChildrenLayerSets ( const RED::State & iState ) = 0
virtual RED_RCRemoveFromGPU ( const RED::State & iState ) = 0
virtual RED_RCRemoveFromLayer ( unsigned int iLayer, const RED::State & iState ) = 0
virtual RED_RCRemoveLayerSet ( const RED::State & iState ) = 0
virtual RED_RCRemoveMaterial ( const RED::State & iState ) = 0
virtual RED_RCSetContextSwitchCallback ( USER_SWITCH_CALLBACK iContextSwitchCB, void * iUserData, const RED::State & iState ) = 0
virtual RED_RCSetMaterial ( RED::Object * iMaterial, const RED::State & iState ) = 0
virtual RED_RCSetVisibilitySwitchCallback ( USER_SWITCH_CALLBACK iVisibilitySwitchCB, void * iUserData, const RED::State & iState ) = 0
virtual RED_RCUpdateBoundingSpheres ( int iPropagationMode, const RED::State & iState ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

This interface gives access to the shape's properties.

Shapes are scene graph elements: Shape class ids available from the RED::Factory define all objects that compose the scene graph for a rendering.

Shape objects share these default attributes:

Attribute Description
RED::BoundingSphereA shape bounding sphere encloses all geometrical data that can be found in all children of the shape. It's defined in the object space of the shape itself, meaning that if the shape has a transformation matrix, the bounding sphere is already transformed by that matrix.
A shape may have no bounding sphere, indicating that it's always visible unless it's a child of a shape that has a bounding sphere, and that is culled out.
Children of a shape that has no bounding sphere may have a bounding sphere, and may be culled out during the rendering.
List of parent shapes
(RED::IShape)
Every shape has at least one parent, or is the root of the scene graph (the Direct Acyclic Graph - DAG).
The list of parents can't be changed. Edition of the scene graph shape relations is made by edition of a shape's children.
List of children shapes
(RED::IShape)
Every shape may have children. The CID_REDTransformShape object must be used to add or remove children to a shape.
RED::UserDataUser data associated to a shape may be managed through the RED::IUserData interface. This interface is exposed by all shapes in the scene graph.
RED::IMaterialEvery shape has a material containing all rendering information needed to visualize the shape.
A shape may have no material. In this case, material inheritance rules apply.
RED::LayerSetEvery shape may have a RED::LayerSet, that defines the visibility mask applied to the shape for a variety of rendering purposes: primary visibility, lighting, shadowing and indirect lighting. A shape may have no layer set. In this case, layer set inheritance rules apply. A shape that has no layer set after application of the inheritance rule is considered to belong to RED::LayerSet::ALL_LAYERS.

Please see Life cycle of REDsdk objects for all details on object destruction and scope of destruction orders that can occur in a scene graph.

Functions documentation

public virtual RED_RC RED::IShape::AddToLayer(unsigned intiLayer,
const RED::State &iState
) = 0

Adds the shape to the given layer.

If the shape already belongs to iLayer, RED_OK is returned and nothing is done.
The ID of a layer is retrieved from the RED::IResourceManager interface.

Parameters:

iLayer:ID of the layer.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::ApplyLayerSet(const RED::LayerSet *iLayerSet,
const RED::State &iState
) = 0

Applies the given layer set to the shape.

The provided iLayerSet may be NULL to invalidate the shape's current layer set.

See Geometry layers or Material layers for usage examples of layersets.

Parameters:

iLayerSet:Pointer to the new shape's layer set.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::ComputeBoundingSphere(const RED::State &iState) = 0

Bounding sphere calculation for a shape.

This method calculates the bounding sphere of the shape. Any old bounding sphere is deleted by the call. Note that this does not include any hierarchical propagation of the calculation of the bounding sphere. Therefore, if the called shape is for example a mesh shape, only the mesh's bounding sphere is to be calculated. The call won't modify the bounding sphere of the parents of the shape. If the called shape is a transform shape, the calculated shape will rely on the bounding sphere of the children of the transform shape.
See RED::IShape::UpdateBoundingSpheres to propagate local changes in the scene bounding spheres to a hierarchy.

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK when the bounding sphere could be calculated,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::GetBoundingSphere(RED::BoundingSphere *&oBoundingSphere,
const RED::State &iState
) = 0

Read-write access to the shape's bounding sphere.

Returns the existing shape's bounding sphere, or creates a new one (uninitialized) that is returned for edition purposes.

See also Improving CAD graphics.

Parameters:

oBoundingSphere:The shape's bounding sphere, always valid on success.
iState:Current transaction parameter.

Returns:

RED_OK when the bounding sphere could be accessed,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::GetBoundingSphere(RED::BoundingSphere *&oBoundingSphere,
intiStateNumber = -1
)const = 0

Read-only access to the shape's bounding sphere.

See also Improving CAD graphics.

Parameters:

oBoundingSphere:The shape actual bounding sphere address if it was defined, NULL if it was not.
iStateNumber:Queried state number.

Returns:

RED_OK when the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetChild(RED::Object *&oChild,
intiChildNumber,
intiStateNumber = -1
)const = 0

Gets a child by its number.

Parameters:

oChild:Pointer to the returned child. NULL if no child exists.
iChildNumber:Number of the child shape.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetChildByID(RED::Object *&oChild,
unsigned intiChildID,
intiStateNumber = -1
)const = 0

Gets a child shape by its ID.

This method explores the scene graph below the callee to find the requested shape. Due to the recursive nature of the exploration, the search may take some time.

Parameters:

oChild:Pointer to the returned child. May be returned set to NULL if the search did not succeed.
iChildID:ID of the child shape.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetChildByID(RED::Object *&oChild,
const RED::String &iChildID,
intiStateNumber = -1
)const = 0

Gets a child shape by its ID.

This is a helper method and calls RED::IShape::GetChildByID( oChild, iChildID.ToID(), iStateNumber ) under the hood.

Parameters:

oChild:Pointer to the returned child. May be returned set to NULL if the search did not succeed.
iChildID:string ID of the child shape.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IShape::GetChildren(const RED::Vector< RED::Object * > *&oChildList,
intiStateNumber = -1
)const = 0

Read-only access to the child list of a shape.

Read-write functions on the child list are only available through the RED::ITransformShape interface of the CID_REDTransformShape object.
Note that this method returns the internal list of children of the shape. Therefore, adding or removing children to the shape will change the contents of this list.

Parameters:

oChildList:Address of the list of children.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetChildrenCount(int &oChildrenCount,
intiStateNumber = -1
)const = 0

Gets the number of children of a shape.

Return the number of children the shape has. Only CID_REDTransformShape instances may have children.

Parameters:

oChildrenCount:The number of children in the shape.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetContextSwitchCallback(USER_SWITCH_CALLBACK &oContextSwitchCB,
void *&oUserData,
intiStateNumber = -1
)const = 0

Gets the context switch user callback.

See Using culling callbacks for visibility control for a practical example.

Parameters:

oContextSwitchCB:Reference to the returned user callback.
oUserData:Returned user data associated with the callback.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded.
public virtual RED_RC RED::IShape::GetLayerSet(const RED::LayerSet *&iLayerSet,
intiStateNumber = -1
)const = 0

Read-only access to the layer set of the shape.

Parameters:

iLayerSet:Pointer to the returned layer set address. May be NULL if the shape has no proprietary layer set.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
public virtual RED_RC RED::IShape::GetMaterial(RED::Object *&oMaterial,
intiStateNumber = -1
)const = 0

Read-only access to the material of a shape.

Parameters:

oMaterial:The address of the shape material if it exists, NULL if the shape has no proprietary material.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetMemorySize(RED::uint64 &oByteSize) const = 0

Gets the memory size of the data contained in a shape.

This method provides a rough evaluation of the CPU memory size of the data that is stored in a shape. This is only an evaluation of the real memory cost consumed by the shape:

  • We consider a fixed operating system memory cost per dynamic memory allocation used by the shape.
  • We consider all data stored in the shape itself. The data is divided into two categories: the RED::IShape related data (this is the base memory cost of a REDsdk shape in a scene graph) and the real shape class data (RED::IMeshShape, RED::ILineShape, etc...).
  • We consider the transactional database extra cost that may let us keep a copy of the data for multi-threaded edition needs. Note that these costs are related to a regular operation 'in transaction' and can be bypassed using the RED::State::GetZeroState method - for experienced users only.
  • We ignore RED::IUserData objects that may be associated to shapes: we can't know their size.
  • We ignore the engine internal cost that may result of the processing of the shape at the time it has to be rendered.

There's no transaction number associated to this query as it'll search all existing database states for the shape.

Also note that this does not concern the GPU. The amount of video memory that is used is definitely difficult to calculate:

  • Graphic card drivers keep a local copy of the data that is stored on the graphic card. Depending on the cleverness of the driver itself and the graphic card manufacturer, this copy can be removed or not. For example, a copy will be stored anyway if the graphic card is paging and has not enough memory to store all the data in its on board local graphic memory.
  • Then, there may be extra data formatting cost stored in the graphic card video (for example using short data formats that are turned into floats by the driver for hardware compatibility reasons). We can't estimate these costs easily.

Parameters:

oByteSize:Size of the shape in bytes.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::GetParent(RED::Object *&oParent,
intiParentNumber,
intiStateNumber = -1
)const = 0

Gets a parent by its number.

Parameters:

oParent:Pointer to the returned parent. NULL if no parent exists.
iParentNumber:Number of the parent shape.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetParents(const RED::Vector< RED::Object * > *&oParentlist,
intiStateNumber = -1
)const = 0

Read-only access to the shape's list of parents.

The list of parents of a shape is never directly modified. Only children lists may be edited through the RED::ITransformShape interface of the CID_REDTransformShape object.

Parameters:

oParentlist:Address of the list of parents.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetParentsCount(int &oParentsCount,
intiStateNumber = -1
)const = 0

Returns the number of parents of the shape.

Parameters:

oParentsCount:The number of parents of the shape.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::GetShapes(RED::Map< RED::Object *, unsigned int > &oShapes,
const RED::CID &iCID
) = 0

Returns a map of all the shapes implementing the given interface.

This call parses recursively the DAG starting from this. Each time a shape implementing the provided iCID interface is encountered, it's added to the oShapes map. Each matching shape is stored only once in the map. However, the second map value indicates the number of times the shape has been found (case of multiple instances).

For example, here is the code to get all the meshes below a given 'root' shape in a scene graph:

  RED::Map< RED::Object*, unsigned int > meshes;
  RED_RC rc = root->GetShapes( meshes, RED::IMeshShape::GetClassID() );

See also Improving CAD graphics.

Parameters:

oShapes:map of the returned shapes.
iCID:CID of the searched shapes.

Returns:

RED_OK when addition has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error.
public virtual RED_RC RED::IShape::GetVisibilitySwitchCallback(USER_SWITCH_CALLBACK &oVisibilitySwitchCB,
void *&oUserData,
intiStateNumber = -1
)const = 0

Gets the visibility switch user callback.

See Using culling callbacks for visibility control for a practical example.

Parameters:

oVisibilitySwitchCB:Reference to the returned user callback.
oUserData:Returned user data associated with the callback.
iStateNumber:Queried state number.

Returns:

RED_OK when the operation has succeeded.
public virtual RED_RC RED::IShape::IsChildOf(bool &ioChildOf,
const RED::Object *iShape,
intiStateNumber = -1
)const = 0

Asks if a shape is a child of another.

Parameters:

ioChildOf:Result of the operation.
iShape:Address of the shape potentially being a parent.
iStateNumber:Queried state number.

Returns:

RED_OK when addition has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::IShape::RemoveBoundingSphere(const RED::State &iState) = 0

Removes the bounding sphere of a shape.

Set the internal object's bounding sphere to NULL. This makes the shape visible if it's not culled out by one of its ancestors.

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK when the bounding sphere could be removed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::RemoveChildrenLayerSets(const RED::State &iState) = 0

Removes all layersets in the sub-graph of this shape.

This method removes the layerset of the callee AND all layersets of all its children, recursively down to the bottom of the scene graph. It's used to clean all layer information in a portion of scene graph.

Parameters:

iState:Current transaction parameter,

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::RemoveFromGPU(const RED::State &iState) = 0

Removes all instances of this shape from the GPU's memory.

This method reduces the amount of memory used on the graphic card. It removes all instances of this shape and of its children from the GPU memory, saving the amount of bytes needed to store all data.

Memory is released for the frame that'll render the transaction that is specified in iState.

The shape and all its children must be removed from all scene graphs used in the cluster for the method to succeed. If any shape of the sub-graph of this is still used for the rendering, then the engine may return a rendering error.

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK when the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::RemoveFromLayer(unsigned intiLayer,
const RED::State &iState
) = 0

Removes the shape from the given layer.

If the shape does not belong to iLayer, RED_OK is returned and nothing is done.

Parameters:

iLayer:ID of the layer.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::RemoveLayerSet(const RED::State &iState) = 0

Removes the current layerset of the shape.

Equivalent to RED::IShape::ApplyLayerSet( NULL, state ).

See Geometry layers or Material layers for usage examples of layersets.

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::RemoveMaterial(const RED::State &iState) = 0

Removes the material of a shape.

Is equivalent to:

  REDIShape::SetMaterial( NULL, iState ).

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::SetContextSwitchCallback(USER_SWITCH_CALLBACKiContextSwitchCB,
void *iUserData,
const RED::State &iState
) = 0

Sets the context switch user callback.

The context switch callback is called at the culling startup. It can be used to eliminate portions of the scene graph from any further processing.

The context switch callback for a shape is called after the application of the viewpoint's layer filter.

See Using culling callbacks for visibility control for a practical example.

Parameters:

iContextSwitchCB:Pointer to the user callback.
iUserData:Optional custom user data associated to the callback.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::SetMaterial(RED::Object *iMaterial,
const RED::State &iState
) = 0

Assigns a material to a shape.

Sets the shape's own material. Consequently, all instances of this shape will be rendered using iMaterial in accordance to the scene graph construction rules. If the shape is a transform shape, iMaterial may be overriden down the scene graph by children materials.

Any old material in the shape is replaced, but not deleted, as it may be shared by many shapes. The resource manager controls the life cycle of materials; see RED::IResourceManager::CreateMaterial or RED::IResourceManager::DeleteMaterial.

The method does nothing if iMaterial is equal to the material actually set in the shape already.

Note that it's not possible to call this method with a NULL value for iMaterial for a root shape of a scene graph. The root shape of a scene graph must always have a valid material.

Parameters:

iMaterial:New shape material address, NULL to unassign the material from the shape.
iState:Current transaction parameter.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if iMaterial is not a material,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_WORKFLOW_ERROR if an attempt to remove the material of a scene graph root has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::SetVisibilitySwitchCallback(USER_SWITCH_CALLBACKiVisibilitySwitchCB,
void *iUserData,
const RED::State &iState
) = 0

Sets the visibility switch user callback.

The visibility switch callback is called during frustum culling, after application of the bounding box vs. frustum tests. It can be used to control the way elements are displayed.

A node that has lights in its children can filter them. A light filtered through a visibility callback is considered outside of the frustum and will be skipped from all lighting passes as if it had for example a bounding sphere that was found outside of the viewing pyramid. This is true even if the light has a bounding sphere that intersects the viewing pyramid: in this case, the callback decides.

See Using culling callbacks for visibility control for a practical example.

Parameters:

iVisibilitySwitchCB:Pointer to the user callback.
iUserData:Optional custom user data associated to the callback.
iState:Current transaction parameter.

Returns:

RED_OK when the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IShape::UpdateBoundingSpheres(intiPropagationMode,
const RED::State &iState
) = 0

Launches a DAG bounding sphere update operation.

Bounding spheres update operations are explicit. A iPropagationMode must be selected to specify the behavior of that call:

See also Improving CAD graphics.

Parameters:

iPropagationMode:RED_SHP_DAG_PROPAGATE_DOWNWARD with or without RED_SHP_DAG_UPDATE_LEAVES or RED_SHP_DAG_PROPAGATE_UPWARD.
iState:Current transaction parameter.

Returns:

RED_OK when the update succeeded,
RED_BAD_PARAM if the flag combination was incorrect,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.