Requirements for 3.0

            Params classes are based on an XML tree representation (same as is used in a VAPOR session file).  The nodes in the tree are ParamNode’s, and each Params has a root ParamNode on which its XML tree is based.

            Class instances that are embedded in a Params instance must have an XML representation embedded in the Params XML tree.

            Undo and Redo: Supports any change in a Params instance.  All state changes that can be undone are representable as a pair (before, after) of Params instances.   

            Extensibility:  Outside parties can write their own Params classes, compiling and linking their code with the VAPOR code base.  These extension Params classes can be implemented without modifying the VAPOR code base (i.e. the code we distribute).  

            Backwards [and sideways] compatibility:  Newer versions of VAPOR must be able to read session files created by older versions of VAPOR.  Session files that were created by one extension of VAPOR are readable by another extension, provided the second extension is based on the same or a later version of the base VAPOR code.

            Params support multiple visualizers and multiple instances as in current GUI:

            --Params associated with renderers (RenderParams subclasses) can have any number of instances for each visualizer.

            --Params not associated with renderers can have local/global support. [e.g. viewpoint, region, animation, vizfeatures].

            --In addition there will be Params classes for other aspects of state that support undo/redo.  These may not be associated with a visualizer or a renderer instance.

Proposed developer API overview

Programmers will control the Params classes only through the ControlExecutive API, which manages Params instances as follows:

• Params instances are retained in a data structure “The ParamsMapping”  in the Params class, which maintains:

            Multiple RenderParams instances for each type of RenderParams and for each visualizer.

            Visualizer-based Params instances (one per visualizer)

            Global Params instances.

• The ControlExecutive API supports:
  • Creation and insertion of new Params instances into the ParamsMapping
  • Deletion of existing Params instances in ParamsMapping.
  • Replacement of existing Params (by new instances of the same type) in ParamsMapping.
• In addition Params instances will be created and deleted to support Undo and Redo; however these Params instances can only be accessed through the Command class API.
• The programmer API does not support creation or deletion of arbitrary Params instances other than as described above.

ParamsBase instances can be embedded in Params instances.  ParamsBase is the parent class of Params, and ParamsBase classes are based on an XML representation.  For example the Box, Viewpoint, and TransferFunction classes are derived from ParamsBase.  These are managed as follows:

• New ParamsBase instances are automatically instantiated and inserted in the XML tree when encountered during session parsing.
• During execution of Params::Validate() and Params::restart(), new ParamsBase instances are created and inserted as child nodes into the XML tree using the method ParamNode::AddRegisteredNode().  This is the responsibility of the programmer who implements a Params subclass.
• Existing ParamsBase instances (in a Params XML tree) must be deleted in the Params::Validate() method, if not consistent with the current DataMgr (e.g. if a TransferFunction is associated with a variable that is not present in the current DataMgr).
• ParamsBase instances are automatically created and deleted as a by-product of Params creation and deletion by the ControlExecutive and Command classes.
• Programmers may invoke the constructors and destructors of ParamsBase subclasses to create and delete additional instances that are not embedded in the XML trees of Params nodes.  In this case the programmer must call the destructor on any instances that (s)he creates. For example it is useful to create new Viewpoint classes that are not embedded in any Params instance during keyframe interpolation.

Extensibility programming

            Implementers of new Params and ParamsBase classes must do the following:

            Define a tag that uniquely identifies the class.

            Implement the necessary pure virtual methods.

            Provide a static method CreateDefaultInstance() which returns a default instance of the class.  This is necessary to allow extensions that were not available at the time the VAPOR code base was coded, enabling new Params and ParamsBase classes to be linked in.

            In the file “include/vapor/ExtensionClasses.h” insert a call to ParamsBase::RegisterParamsBaseClass() in the inline method InstallExtensions().  This identifies the tag with the Params or ParamsBase subclass, so that VAPOR can instantiate such class instances at run time.  VAPOR must be built with the modified ExtensionClasses.h file.  The newly coded Params or ParamsBase classes must be loaded at run time.