CAD Exchanger SDK
Scene managment

ModelPrs_Scene encapsulates a scene, connects with a viewport, and manages object display and interactive selection. One viewport only can be attached to a scene.

Adding and removing scene nodes

Once a scene graph has been constructed (see Creating a scene graph) its top node can be added to a scene as a new root:

ModelPrs_SceneNode aRootNode = …;
ModelPrs_Scene aScene;
aScene.AddRoot (aRootNode);
aScene.Update();

A root node can be removed from the scene using ModelPrs_Scene::RemoveRoot().

Update the scene

To enforce visual update of the scene in the attached viewport, the ModelPrs_Scene::Update() method must be called.

Updating the scene can be time-consuming and therefore should be delayed until changes to the underlying scene node’s data have been applied. For instance, the following example demonstrates multiple geometrical changes and single scene update:

ModelPrs_SceneNode aRootNode;
aRootNode.SetDisplayMode (ModelPrs_DM_Shaded);
ModelPrs_Scene aScene;
aScene.AddRoot (aRootNode);
aRootNode.AddChildNode (aFirstNode);
aRootNode.AddChildNode (aSecondNode);
aFirstNode.SetGeometry (...);
aFirstNode.SetSelectionMode (ModelPrs_SM_Shape);
aSecondNode.SetGeometry (...);
aSecondNode.SetAppearance (ModelData_Appearance(...));
aScene.Update(); // multiple changes but one update

Displaying scene nodes

An object on a scene can be displayed in various display modes, for instance:

  • Wireframe
  • Shading
  • Shading with boundaries
  • Shading with surface boundaries
vis_as1_wireframe_display_mode.png
Wireframe display mode
vis_as1_shaded_display_mode.png
Shaded display mode
vis_as1_mixed_display_mode.png
Mixed display mode (Shaded with boundaries & Wireframe)

A display mode can be defined per each scene node using ModelPrs_SceneNode::SetDisplayMode(). See also Node attributes inheritance to check how distinct display modes apply in the scene graph.

The following code snippet demonstrates how to create a mixed shading and wireframe display modes:

ModelPrs_SceneNode aRoot;
ModelPrs_SceneNodeFactory aFactory;
auto aFirstNode = aFactory.Create (aFirstBody);
aRoot.AddChildNode (aFirstNode);
auto aSecondNode = aFactory.Create (aSecondBody);
aRoot.AddChildNode (aSecondNode);
aRoot.SetDisplayMode (ModelPrs_DM_Shaded);
aFirstNode.SetDisplayMode (ModelPrs_DM_Wireframe);
// aSecondNode inherits parent's display mode - ModelPrs_DM_Shaded

Hidding scene nodes

A hidden scene node (but not removed from the scene) can be either fully hidden or displayed as semi-transparent:

vis_as1_ghost_hidden.jpg
Ghost hidden visibility mode
vis_as1_hidden.jpg
Hidden visibility mode

This behavior is controlled with ModelPrs_SceneNode::SetVisibilityMode().

Hover and selection

Objects are selected upon mouse clicks (or tap events on touch screens). Upon selection selected objects are highlighted on a screen. Selection on entire 3D scene can be enabled/disabled using the SetSelectionEnabled() of the viewport.

The 3D scene notifies about changed selection using a call-back mechanism. To receive such notifications, a subclass of ModelPrs_SceneSelectionChangesObserver must be defined with the redefined Accept() method and registered in the scene as follows:

class CustomSelectionChangesObserver : public ModelPrs_SceneSelectionChangesObserver
{
public:
void Accept (const ModelPrs_Selection& theSelection) override
{
// your code here
}
};
...
CustomSelectionChangesObserver anObserver;
ModelPrs_Scene aScene;
aScene.Register (anObserver);

When a scene node is selected on the scene, an instance of the ModelPrs_Selection class will be automatically created and passed to the observer's Accept() method.

A selection object encapsulates the scene node which has been selected, or in the case of B-Rep representation, the B-Rep subshapes. To access this data a subclass of ModelPrs_SelectionVisitor() must be sent to selection's Accept() method:

class CustomSelectionVisitor : public ModelPrs_SelectionVisitor
{
public:
void Visit (const ModelPrs_SceneNode& theNode) override
{
// the node itself is selected
}
void Visit (const ModelPrs_SceneNode& theNode, const std::vector<ModelData_Shape>& theShapes)
{
// subshapes of the node are selected
}
};
class CustomSelectionChangesObserver : public ModelPrs_SceneSelectionChangesObserver
{
public:
void Accept (const ModelPrs_Selection& theSelection) override
{
theSelection.Accept (myVisitor);
}
private:
CustomSelectionVisitor myVisitor;
};

Refer to Selection Handling Example

Selection modes

A selection mode is represented by ModelPrs_SelectionMode enumeration and can be specified for each scene node with ModelPrs_SceneNode::SetSelectionMode(). For instance:

ModelPrs_SceneNode aRootNode = ...;
aRootNode.SetSelectionMode (ModelPrs_SM_Face);

ModelPrs_SelectionMode enumeration values are represented with binary flags and thus selection modes can be combined with each other as follows:

ModelPrs_SceneNode aNode;
aNode.SetSelectonMode (ModelPrs_SM_Vertex | ModelPrs_SM_Edge); // activate selection of vertices and edges

Values from ModelPrs_SM_Vertex to ModelPrs_SM_Solid apply for B-Rep representations only (and are ignored for polygonal representatinos):

ModelData_Body aBody = ...;
ModelData_PolyVertexSet aPVS = ..;
ModelPrs_SceneNode aRoot;
aRoot.SetSelectionMode (ModelPrs_SM_Face);
ModelPrs_SceneNodeFactroy aFactory;
aRoot.AddChildNode (aFactory.Create (aBRep));
aRoot.AddChildNode (aFactory.Create (aBody));
aRoot.AddChildNode (aFactory.Create (aPVS)); // no active selection - ModelPrs_SM_Face does not apply for PVS
See also
Topological Shapes

When combining selection modes of the same dimension, the value representing a finer type will dominate. For instance, when combining edge and wire selection the former will dominate (because any wire consists of edges).

ModelPrs_SceneNode aNode;
aNode.SetSelectionMode (ModelPrs_SM_Wire | ModelPrs_SM_Edge); // edge selection mode will dominate

The following list explains dominating modes in such combinations:

  • ModelPrs_SM_Solid when combined with ModelPrs_SM_Node (whenever the node has a solid inside);
  • ModelPrs_SM_Shell when combined with ModelPrs_SM_Node or ModelPrs_SM_Solid;
  • ModelPrs_SM_Face when combined with ModelPrs_SM_Node, ModelPrs_SM_Shell or ModelPrs_SM_Solid;
  • ModelPrs_SM_Edge when combined with ModelPrs_SM_Wire.

Selection filters

When selecting B-Rep edges and faces, additional filters can be specified in order to restrict selection to specific geometries. For instance, to restrict selection of faces lying on planar surfaces (such as real planes or planar NURBS-surfaces), the following filter can be specified:

ModelPrs_Scene aScene;
aScene.SetFilter (ModelPrs_SFT_PlanarFaceFilter);

ModelPrs_SelectionFilterType enumeration values are represented by binary flags and thus several filters can be combined. The following example demonstrates how to limit selection to circular edges or surfaces of revolution (e.g. cylinders or cones):

ModelPrs_Scene aScene;
See also
ModelPrs_SelectionFilterType

Hover

A 3D viewport can support hover - highlighting a selectable object when mouse coursor moves over it. This behavior is controlled with the method SetHighlightingEnabled() of a respective viewport.

Note
Future versions of CAD Exchanger SDK will enable support of user-defined callbacks which will be invoked upon hover detection similar to selection callbacks. Currently no callbacks are supported.