IShape

Detailed Description

class IShape : public RED::IREDObject 

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::BoundingSphere	A 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::UserData	User 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::IMaterial	Every 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::LayerSet	Every 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 \ref bk_ba_life_cycle_of_redsdk_objects for all details on object destruction and scope of destruction orders that can occur in a scene graph.

Public Functions

virtual RED_RC GetBoundingSphere(RED::BoundingSphere *&oBoundingSphere, int iStateNumber = -1) const = 0

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

See also \ref bk_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.

virtual RED_RC 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 \ref bk_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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC UpdateBoundingSpheres(int iPropagationMode, 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:

RED_SHP_DAG_PROPAGATE_DOWNWARD: Update the entire sub-graph of the shape. leaves are NOT updated if this flag is not combined with RED_SHP_DAG_UPDATE_LEAVES.
(RED_SHP_DAG_PROPAGATE_DOWNWARD | RED_SHP_DAG_UPDATE_LEAVES): Updates the sub-graph of the shape, including all leaves of the graph. Leaves may contain a lot of geometry, and the operation may consume more time based on the number of updated items.
RED_SHP_DAG_PROPAGATE_UPWARD: Updates bounding spheres for all parents of the shape, recursively to the roots of the graph. This flag can’t be combined with RED_SHP_DAG_PROPAGATE_DOWNWARD.

See also \ref bk_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.

virtual RED_RC GetChildrenCount(int &oChildrenCount, int iStateNumber = -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.

virtual RED_RC GetChildren(const RED::Vector<RED::Object*> *&oChildList, int iStateNumber = -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.

virtual RED_RC GetChild(RED::Object *&oChild, int iChildNumber, int iStateNumber = -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.

virtual RED_RC GetChildByID(RED::Object *&oChild, unsigned int iChildID, int iStateNumber = -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.

virtual RED_RC GetChildByID(RED::Object *&oChild, const RED::String &iChildID, int iStateNumber = -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.

virtual RED_RC IsChildOf(bool &ioChildOf, const RED::Object *iShape, int iStateNumber = -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.

virtual RED_RC 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 \ref bk_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.

virtual RED_RC GetParentsCount(int &oParentsCount, int iStateNumber = -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.

virtual RED_RC GetParents(const RED::Vector<RED::Object*> *&oParentlist, int iStateNumber = -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.

virtual RED_RC GetParent(RED::Object *&oParent, int iParentNumber, int iStateNumber = -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.

virtual RED_RC GetParentViewpoints(RED::Vector<RED::Object*> &oViewpointList, int iStateNumber = -1) const = 0

Gets the list of viewpoints we’re anchored to.

This method ascends the list of parents of the shape up to look for all viewpoints instances we’re child of. A shape in a scene graph is linked to a root shape which is held by a viewpoint. This method looks upward to find all these root shapes and build a list of viewpoints that are “above” us.

Parameters

oViewpointList – List of viewpoints using this.
iStateNumber – Queried state number.

Returns

RED_OK when the operation has succeeded,

RED_ALLOC_FAILURE if an internal memory allocation has failed.

virtual RED_RC GetMaterial(RED::Object *&oMaterial, int iStateNumber = -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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC AddToLayer(unsigned int iLayer, 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.

virtual RED_RC RemoveFromLayer(unsigned int iLayer, 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.

virtual RED_RC GetLayerSet(const RED::LayerSet *&iLayerSet, int iStateNumber = -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.

virtual RED_RC 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 \ref wf_geometry_layers or \ref wf_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.

virtual RED_RC RemoveLayerSet(const RED::State &iState) = 0

Removes the current layerset of the shape.

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

See \ref wf_geometry_layers or \ref wf_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.

virtual RED_RC 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.

virtual RED_RC SetContextSwitchCallback(USER_SWITCH_CALLBACK iContextSwitchCB, 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 \ref wf_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.

virtual RED_RC GetContextSwitchCallback(USER_SWITCH_CALLBACK &oContextSwitchCB, void *&oUserData, int iStateNumber = -1) const = 0

Gets the context switch user callback.

See \ref wf_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.

virtual RED_RC SetVisibilitySwitchCallback(USER_SWITCH_CALLBACK iVisibilitySwitchCB, 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 \ref wf_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.

virtual RED_RC GetVisibilitySwitchCallback(USER_SWITCH_CALLBACK &oVisibilitySwitchCB, void *&oUserData, int iStateNumber = -1) const = 0

Gets the visibility switch user callback.

See \ref wf_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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC ForceUpdate(const RED::State &iState) = 0

Flag the shape as being modified without actually modifying it.

This method ‘marks’ the shape as being modified. Consequently an internal update event will be triggered for that shape on the next transaction being closed. This can for instance be used to force the update of instance counters without actually modifying the shape’s contents. If the shape is a node, all its children will be flagged as being modified too.

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.

virtual bool IsInDestroy() const = 0

Is the shape already registered for destruction?

A shape that has been released using RED::Factory::DeleteInstance or who is a child of a shape that has been deleted will have this method returns true while the transaction during which the operation has occurred has not been closed. After the transaction closing, the shape will be effectively deleted.

Returns: true if the shape is already registered for destruction, false otherwise.

Public Static Functions

static inline RED::CID GetClassID()

CID	`GetClassID`
`RED_RC`	`GetBoundingSphere`
`RED_RC`	`GetBoundingSphere`
`RED_RC`	`ComputeBoundingSphere`
`RED_RC`	`RemoveBoundingSphere`
`RED_RC`	`UpdateBoundingSpheres`
`RED_RC`	`GetChildrenCount`
`RED_RC`	`GetChildren`
`RED_RC`	`GetChild`
`RED_RC`	`GetChildByID`
`RED_RC`	`GetChildByID`
`RED_RC`	`IsChildOf`
`RED_RC`	`GetShapes`
`RED_RC`	`GetParentsCount`
`RED_RC`	`GetParents`
`RED_RC`	`GetParent`
`RED_RC`	`GetParentViewpoints`
`RED_RC`	`GetMaterial`
`RED_RC`	`SetMaterial`
`RED_RC`	`RemoveMaterial`
`RED_RC`	`AddToLayer`
`RED_RC`	`RemoveFromLayer`
`RED_RC`	`GetLayerSet`
`RED_RC`	`ApplyLayerSet`
`RED_RC`	`RemoveLayerSet`
`RED_RC`	`RemoveChildrenLayerSets`
`RED_RC`	`SetContextSwitchCallback`
`RED_RC`	`GetContextSwitchCallback`
`RED_RC`	`SetVisibilitySwitchCallback`
`RED_RC`	`GetVisibilitySwitchCallback`
`RED_RC`	`RemoveFromGPU`
`RED_RC`	`GetMemorySize`
`RED_RC`	`ForceUpdate`
bool	`IsInDestroy`

IShape

Functions

Detailed Description