SceneEngineGUI
Contents |
SceneEngine was designed to be a pure library without any graphical user interface. This allows a faster development of tools, an easier integration with existing applications and a faster portability of the libraries to other operating systems and/or compilers.
In the development of the 3D applications (CrackArt and MFCSceneViewer) a set of classes and structures was created as a communications layer between SceneEngine and the Graphical User Interface. This set of classes is know as the SceneEngineGUI.
[SceneEngine application]
| |
v v
[ScEngGUI] [ Lua ]
| |
v v
[ SceneEngine ]
Workflow
- When the application starts it creates a single instance of the classes derived from BlockGUI that are registered in the system.
- After the scene is loaded all block factories in SceneEngine are scanned and matched with the registered block_guis. At this time normally the Nodes are registered in the ViewportScene as ViewportBlocks.
- When a new node is created, or a modifier is applied, it is registered in the ViewportScene as a ViewportBlock.
- The ViewportScene receives a message when a ViewportBlock is added, modified or deleted. This message is processed in ViewportScene::DependancyChanged method, where it fills three lists with the entities that need to be updated, added or deleted in the viewports.
- Some blocks can be edited. For example modifiers like lattice can allow the user to move their points in the viewport. When these blocks are about to be edited, their ViewportBlock is moved to the active_viewport_blocks list in the document.
- The process of hit testing elements with the mouse in the viewport is done using the viewport_entities provided by the BlockGUIs.
- When the user selects elements in the viewport, the blocks are informed of these selection changes with the BlockGUI selection functions (ClearSelect, Select, SelectAll).
- The manipulation tools go through all active_viewport_blocks requesting the transform and center of the selection to display the current manipulation gizmo. These are generated by the BlockGUI.
- When the user moves the manipulation gizmo, the BlockGUI::StartMove, BlockGUI::Move and BlockGUI::EndMove methods are called.
Classes
The SceneEngineGUI uses the following classes:
BlockGUI
The main component of the SceneEngineGUI is the BlockGUI. This class is pure virtual, it has no members and all its methods receive as an argument the block that this class works with. This class implements all the methods needed to manipulate the block using the GUI. This includes selection methods, transformation methods, viewport display and dialog box display. Not all the blocks need to have a BlockGUI companion, but only those blocks with a BlockGUI class can be displayed in the viewports and edited using dialog boxes or manipulation tools. There is a one to one relationship between the Block and its BlockGUI. A Block cannot have more than one BlockGUI, and a BlockGUI can only work with one Block.
ViewportBlock
The ViewportBlock is a class that holds an instance of the Block, a Node (optional) and the BlockGUI. This class is used mainly as the argument that is sent to the BlockGUI methods, something like this
viewport_block->block_gui->SelectAll( viewport_block );
SceneEngineDoc
This is the main class in the SceneEngineGUI. This class has a vector member with all the ViewportBlock instances that have been registered to it. This class is derived from ScEng::BlockListener, and it keeps as dependencies all the blocks from the ViewportBlock elements (ViewportBlock::block). This way, when a block changes and it casts its message with ReportChange(0,0), this class receives the message and updates the viewports if necesary. This class works as the real connection between SceneEngine and the viewports (SceneEngineView).
SceneEngineView
All widgets that display the scene, either in 3D rendering, or in any other way that needs real-time update of viewports need to inherit from this class. The instances of this class should be registered in the SceneEngineDoc, so when the SceneEngineDoc receives a message that triggers an UpdateViewports, it can call the UpdateViewport of this class and update all the SceneEngineView instances.
ViewportEntity
This class defines an entity that is displayed in the viewports. This entity is just geometrical and can be a point, a line or a mesh. Depending on the rendering engine this entities can be located in the World 3D space o in viewport 2D space, and they can be either on occlusion or overlay mode.
The ViewportEntity represents an element that can be displayed in the viewport and that can be hit tested using the mosue in the viewport. These includes meshes, gizmos, manipulators, etc...
At the moment there are only 3 things that can be displayed in the viewport: Points, Lines and TriMeshes.
Complex entities can be built by mixing the three basic entities together. For this, the ViewportEntity class has a next pointer to the next viewport entity. Its very important to ensure that this next pointer is NULL in the next entity:
vb->viewport_entity -next-> ViewportLines -next-> ViewportPoints -next-> NULL
The ViewportEntity has a static counter that is incremented every time an entity is created. And this is set as the id for this entity. This unique id is used as the name for this element in ogre.
In the ViewportScene there are 3 lists:
std::list<ViewportEntity*> push_viewport_entities; std::list<ViewportEntity*> pop_viewport_entities; std::list<std::string> update_viewport_entities;
These list tell the views what to do:
Entities in the push_viewport_entities list have to be added to the OgreManager.
Entities in the pop_viewport_entities list have to be removed from the OgreManager.
Entities in the update_viewport_entities have to be updated.