Loaders for Dynamic Elements
============================

This text is about following X3D prototypes, which are/will be provided by the 
sourceforge project http://sourceforge.net/projects/smuos (The Simple Multiuser
Online Scenes Project):

   - SmsLoader  (was implemented in step 0033.10 / A.4)
   - SmsModuleLoader (has been implemented in step 0033.10bf1 / A.4.bugfix1)
   - SscUboLoader (will be implemented in steps 0033.11/0033.12 or later)

All Loaders employ the Browser.createVrmlFromURL() method to load proto
instances from URLs.

The SmsLoader Prototype (finished in 0033.10)
=============================================
This prototype is the "base" of all loaders. It is already used by SscBase
to load or unload "Module Related SSC Dispatchers", always, when a module
has been registered or unregistered, respectively.

Now it is used by the SmsModuleLoader (see below), too and it will also be used
by the SscUboLoader (in steps 0033.11 / .12 or later)

The SmsModuleLoader Prototype (finished in 0033.10bf1)
======================================================

1.) External Loading/Unloading of Dynamic Modules (old style)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
In this case, the frame is completely responsible to load and unload the 
dynamic modules. The SMUOS Framework cannot distinguish static modules from
dynamic modules.

Optionally, the frame may
   - use module wrappers
   - use the "Explicit Registration" feature

SscBase provides following fields for this case:
   - commParam ........... SFNode - output, used to initialize the modules
   - registerModules ..... MFString - explicit registration of module name(s)
   - deregisterModules ... MFString - explicit deregistration of module name(s)
   - registeredModules ... MFString - all registered module names
   
Duties of the frame:
   - module names MUST be unique (static and dynamic modules)
   - if gravity shall be present in the modules, then module wrappers MUST be
     used
   - if a module name is deleted from "registeredModules", then the frame MUST
     unload the module
     
2.) Internal Loading/Unloading of Dynamic Modules (new since 0033.10bf1)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
The frame provides a <Script> node, whose fields hold the description of all
dynamic elements (currently all dynamic modules, later - in 0033.11/.12 - also
the dynamic object types - see below).
This <Script> node is the so-called "dynamic element description (DED)".

The modules are loaded by the SmsModuleLoader, which is integrated into the
SscBase. The SmsModuleLoader contains a <Group> node that holds the loaded
dynamic module wrappers.

The feature "explicit registration" is used internally by the SmsModuleLoader.

SscBase provides following fields for this case:
   - dynamicElementDescription ........ SFNode - provide a pointer to the DED
   - registeredModules .... MFString - indicates names of all modules
   - loadModuleWrappers ... MFString - module names, which shall be loaded
   - moduleWrapperLoaded .. SFNode - one module wrapper has been loaded and now
                            the frame is required to set the initial state
   - loadModule ........... SFNode - frame has set the initial state and mirrors
                            the moduleWrapperLoaded event to the SscBase.
                            Now the wrapper will be initialized and hence the
                            module will be actually loaded 
   - unloadModuleWrapper .. SFInt32 - frame requests to disable and unload a
                            module and his wrapper
   
Duties of the frame:
   - module names MUST be unique (DED and static modules must fit together)
   - after the SscBase has output the "moduleWrapperLoaded" Event (SFNode),
     the frame MUST set the initial state of the module wrapper, unless the
     module is not listed in the DED
     The "moduleWrapperLoaded" Event MUST be mirrored to the "loadModule" field
   - the frame MUST trigger the "normal" loading and unloading of dynamic
     modules, using the fields "loadModuleWrappers" and "unloadModuleWrappers"
     (global unloading of modules due to deregistration is handled automagically
     by the SscBase)
     
The SscUboLoader Prototype (planned for 0033.11 / .12 or later)
===============================================================
An "unbound object (UBO)" is an object that can be loaded or unloaded on demand

It can be attached to a module (in order to be rendered relative to the module's
coordinate system) or it can be detached (this may e.g. happen, when an UBO
is assigned to a module but that module is not loaded currently)

A "universal object class (UOC)" is a rough classification of UBOs, e.g.
   - "rail vehicle"
   - "train"
   - "racing car"
   - "military helicopter"
   - and so on
   
When a UBO is "created", then it is created relative to a UOC and it is created
at an index "objectIx".

A UBO can be identified globally (SMS wide) by
   - UOC name + objId
or locally (within a scene instance) by
   - universalObjectClass (SFNode) + objectIx (SFInt32)

1.) registerObjectType / unregisterObjectType (global)
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
An Object Type is a more narrow classification of UBOs than a UOC.

Where a UOC could be "military helicopters", an Object Type could be "Apache".

Each Object Type is related to URLs, where the object can be loaded from and
it may carry categories to filter model types for selection by the end user.

E.g. one model type could be defined by:
   - UOC Name = "railVehicle"
   - Model Type = "railVehicle.OeBB-1044"
   - Categories = "railVehicle.1435" + 
                  "railVehicle.electric" +
                  "railVehicle.Bo'Bo'"

The SscUboLoader provides following fields for the handling of object types
   - "dynamicObjectDescription" (SFNode)
   - "registerObjectType" (MFString),
   - "unregisterObjectType" (SFInt32) and
   - "registeredObjectTypes" (MFString)

2.) createObject / deleteObject (global)
- - - - - - - - - - - - - - - - - - - - -
Creating and deleting UBOs are global activities. UBOs are created and deleted
for the whole SMS (in all scene instances).

We need following information to create a UBO:
   - UOC Name
   - Object Type
   - optionally the initial state (including a module name) 
   - optionally a "desired objId"

3.) loadObject / unloadObject (local)
- - - - - - - - - - - - - - - - - - - -
The idea is to let the user (the programmer of the SSC Extension) decide,
when to actually load or unload the UBO.

Earliest, after the UBO has been created and after the initial state is
available, then a scene instance (the SSC Extension in this scene instance)
can decide to load the object.

Also the UBO can be unloaded locally, without deleting the UBO globally.

4.) DRAFT IDEAS
- - - - - - - -
We implement a new field at the external interface uiObj of MIDAS Objects

   - undefine (SFTime)

This field is similar to the "disable" field, but it is supported for globally
"undefining" the state of a UBO.

If the OSM of a MIDAS Object becomes attached AND
   - if the global state of the object is not present on the CS, OR
   - if the global state of the object has got the value UNDEFINED

then the state is taken from the local initial state

This would allow to "rewind BS Collaborate", when a UBO is deleted.

Otherwise a freshly created UBO that gets accidentally the same objId as an
already deleted UBO, would inherit the state from the already deleted UBO.