Studierstube Design Notes

Some ideas for Studierstube design and development.

Short Term Issues

• make file names more useable / workable in studierstube/inventor. This could be done by embedding the path of an application in the scenegraph data (SoApplicationKit). Then we can provide an API to load files relative to the application. Moreover we could set input paths for construction from a node buffer to enable reading of data relative to the old one, if possible.

Studierstube 4.0

Some design wishes - ideas for Studierstube 4.0

• Full representation of Studierstube objects as OpenInventor objects.
• Unified event bus for all kinds of data : tracking events, system events, distribution events
• symmetrical distribution mechanism
• make DIV correct by substituting name search for path caching
• full Python binding
• make Python the start up environment ? -> turns Studierstube into scripting application :)

User abstraction

The userkit and the data stored there is an abstraction of the focus concept. To implement a focus mechanism, we need to bring together information about the focus of a window a designated input device to set and control the focus and a designated PIP that displays the pip sheet for the application providing the focused window. The UserKit is exactly the structure to do that. Moreover it defines that the focus of the window will only be rendered on a certain display (or output device). Because we may have several users we can define several UserKits.

The userkit and userid however pervades the whole studierstube code. This stems probably from the fact that the current system was developed for configurations with defined users which where equipped with a full set of input device, PIP and display. This assumption does not hold anymore for the kind of setups we envision.

Some detailed design issues :

• 3D events cannot generally be assigned to a user. There are a lot of other event sources that are not for explicit user interaction. Examples are marker tracking for windows, user location etc.
• a display might not be assigned to a single user anymore, or a user may have any number of displays (including none).
• users will not always have one input device and one PIP again, different combinations are thinkable
• applications cannot assume that their environment of users, pips and input devices does not change. Pervasive use of migration will move the application to very different setups.
• applications may use other resources than pip sheets on a per user basis. Providing a common facility to store per user information and retrieve it as necessary will simplify application development and help developers to cope with the needed flexibility of applications.

I propose to develop a more general abstraction for the focus and user mechanism that sits on top of the basic Studierstube API and structure. The typical 'managers' in the STB API should not be concerned with users at all (as long as they don't need to). The user mechanism should then be an orthogonal API provided to the applications.

STB API - The Managers

The Studierstube API consists of two types of classes. On the one hand there are pure OIV objects that can be handled as the default ones. Such objects can be read and written to files, scripted in content directly and conveniently manipulated using standard OIV methods. On the other hand there is a set of classes (the Manager classes or Class :) that provide central functionality to the Studierstube such as loading, starting, stopping, sharing applications, handling checkin / checkout of users, providing rendering for multiple, different displays and so on. The latter classes are typically implemented as singletons and are not OIV objects. They can only be manipulated using C++ method calls, implement their own data structures to store information and use a special mechanism to communicate (the message manager).

In the spirit of a fully scriptable Studierstube environment (Dieter...) the Manager Class needs to be refactored into pure OIV objects. There are some examples already. The SoLocaleManagerKit is purely scriptable and uses only OIV operations on the special scenegraph it manages to implement is helper methods. In this way the API it provides is fully compatible with any direct interaction with its data structures. Indeed, these data structures are only a scene graph and therefore can be manipulated in a standard way.

The SoContextManagerKit is currently half way there. It only uses OIV structures to store its information, thus allowing to be scripted as well. However the real interesting part of its API is still only available via C++ method calls. It will be an interesting exercise to work out a way to translate its interface to a more OIV like way.The same applies to the rest of the managers.

Again some detailed design issues :

• managers are singleton and that makes sense. the singleton status can be enforced by a special scene graph build from kits with defined parts. Thus we would have a central Workspace kit containing the singleton manager kits (see Dieters design ideas).
• Managers should provide feedback when certain events happened in the system. For example, the SoContextManagerKit should provide a way to inform any interested party that an application was started or stopped. (Could be done via an added event ...)
• Managers still need to rely on each other. However, we should try to impose a hierarchical use of the interfaces provided by the different managers. That way changing or removing a more high level manager object does not force changes in all the other manager implementations.

Layered Approach

Another idea is to restructure Studierstube to provide more separated layers and components that stand next to each other. Right now we have a pretty strict application and runtime environment concept and two methods to escape that : a) inventing clever work arounds, b) slowly changing and extending the system. a) is not desireable as it makes applications even less portable, b) might not leed to a simpler system. Therefore I think we should strive for a more modularized approach :

• Break Studierstube into layers and components such as
  • output setup (windows, camera, render options)
  • input setup - OpenTracker interface
  • 3D event distribution
  • DIV
  • application loading, saving
  • Pivy script node
  • user management (more like context management for applications)
  Some are very separated all ready (DIV), others are tightly coupled to the overall framework (3D events)
• build frameworks on top of that such as
  • current collaborative application setup with symetric users, pips, pens, devices for each user
  • a simpler framework with less constraints for other uses
  • a dedicated client framework for cluster rendering

The goal would be to have services implemented as distingt APIs and furthermore provide more complex and powerful frameworks tailored towards different types and areas of applications and setups. This would allow easier development of non standard applications while retaining the power of the full framework.

Disadvantages are: developers might be tempted to use the direct, do-it-your-self approach instead of using the proper framework. Development of setup independend applications will also depend on the proper framework now !

3D Events

Besides the discussion about general types of data transported by event types, there could be another issue regarding the use of events. Let me explain that with a problem I encountered. In the recent demonstrations I set up we used markers to move windows and do some application management. A SoDragKit sitting in the middle of a tracked application window would grab the events of the tracking marker as soon as the marker moved the window to its position. After that no event would be available anymore to the window mover.

This illustrates how an event used for implicit user interaction (moving a window) is used (and even grabbed) by a widget designed and used for explicit user interaction (manipulation by a user input device). It is possible in the current system to mask events based on stations. However in a constantly changing environment as envisioned by locales and large scale application migration, the task of keeping these masks up to date is daunting. To avoid this problem, we might need to add classifications of events according to their intended use.Extending the gestures from Zsolt Marx gesture system should be a nice way to do that.

Some possible event types :

• explicit user interaction - everything coming from input devices assigned to a user or accessible to applications via standard interfaces
• tracking input for everything else - a sort of implicit user interaction like moving the marker to a more convenient place. Where does the pip and head tracking fall ?

Inventor Pitfalls

• export defines should not be hardcoded in the dll header file or anywhere else ! (Windows specific)
• SO_KIT_ADD_CATALOG_ENTRY ->rightChild must be \x0 to work correctly ! (not NULL, 0, "", ...)
• SO_KIT_INIT_CLASS(SoBAUInstanceKit, SoBaseKit, "BaseKit")
  for Inventor nodes last parameter is without So
  for all other nodes just a copy of the second parameter
• Do not call SoGroup->getChild(0) and test for NULL !
  This can create an empty child with value NULL and subsequently crash OpenInventor !
  Use (SoGroup->getNumChildren() > 0) and then retrieve the node
• Do not make intermediary parts of a node kit public ! This will not work generally and is against the construction of a node kit. Only leaf nodes can be public. If you need to access fields of an internal part, you need to mirror them with dedicated fields on the nodekit and setup connections between them. Be sure to use the setupConnection method to do so, to make this work across distributed inventor as well.
• Do not use the whichChild field of an SoSwitch without the necessary children -> crashes may occur !

Proper use of data sensors :

• Every FieldSensor can only monitor one field !
• Sensors are not derived from SoBase, therefore they are not reference counted. The client must take care of deleting sensor when they are not needed anymore, or make them part of something else !
• nodekits should implement setupConnections to attach and detach sensors properly !

Studierstube classes use :

• Base3D : the Base3D macros for building new 3D event aware classes must be used only in direct subclasses of Base3D !

General observations :

• Does path design preclude the use of node fields as children to traverse ?

Python Integration

Integration of Python as a script language can take several forms :

1. an embedded closed environment such as script nodes and protos to be able to have several instances of a script functionality. This is the topic of Tamers work.
2. a Python console. A concurrent Python environment that is accessed via the console, an additional console window etc.
3. embedding Studierstube as a library into the Python environment.

While 1) is the simplest solution and quite interesting the other two lend itself to an even more prototype based working style (which is what we want !). The intermediary goal of a python console would provide such features as runtime, interactive scene graph manipulations, advanced debugging, etc. On the other hand using Studierstube as a Python extension library would probably simplify all of this.

Correct DIV

There are two big issues with DIV that I think should be corrected :

Nodes are indexed by node names which are not unique ! This can lead div to change the wrong node. It usually happens with user named nodes as the node names DIV assignes are pretty unique. However, I believe a correct way of using paths and some proper optimization and storage of these is a better solution. It would make DIV work correctly in any situation.

Changes in subtrees of Node fields are treated as changes to the field ! This is a general limitation of the OpenInventor node sensor. If a child of an entry in a node field is changed, OpenInventor reports a new entry with a subscene graph that contains the change. It leads to large amounts of data transmitted and can also break links between nodes in such fields. I believe a dedicated implementation of a new DIVSensor which is capable of catching in storing the required information is the best solution. Maybe OpenInventor is not the best medium anymore, but Coin could be a proper base.

Field connection graph optimization is sometimes bad ! Not in every case is the pruning of updates depending on field connections correct. field connections might not exist on the slave side etc, or do not fire ?