Provides API for VAPOR visualizer User Interfaces (UIs) More...

#include <ControlExecutive.h>

Inheritance diagram for VAPoR::ControlExec:

Public Member Functions
	ControlExec ()

	~ControlExec ()

int	SaveSession (string file)

int	RestoreSession (string file)

Params *	Undo ()

Params *	Redo ()

string	GetCommandText (int n)

bool	CommandExists (int offset)

Static Public Member Functions
static ControlExec *	getInstance ()
	Obtain the singleton ControlExec object. More...

static int	NewVisualizer (int vizNum=-1)

static int	RemoveVisualizer (int viz)

static void	InitializeViz (int viz, int width, int height)

static void	ResizeViz (int viz, int width, int height)

static int	Paint (int viz, bool force=false)

static int	ActivateRender (int viz, std::string type, int instance, bool on)

static Params *	GetParams (int viz, string type, int instance)

static int	SetParams (int viz, string type, int instance, Params *p)

static int	RemoveParams (int viz, string type, int instance)

static int	AddParams (int viz, string type, Params *p)

static int	FindInstanceIndex (int viz, RenderParams *p)

static int	GetNumParamsInstances (int viz, string type)

static int	GetNumBasicParamsClasses ()

static int	GetNumParamsClasses ()

static int	GetNumTabParamsClasses ()

static const std::string	GetShortName (string &typetag)

static int	SetCurrentParamsInstance (int viz, string type, int instance)

static int	GetCurrentRenderParamsInstance (int viz, string type)

static Params *	GetCurrentParams (int viz, string type)

static Params *	GetActiveParams (string type)

static RegionParams *	GetActiveRegionParams ()

static ViewpointParams *	GetActiveVPParams ()

static AnimationParams *	GetActiveAnimationParams ()

static Params *	GetDefaultParams (string type)

static int	GetNumVisualizers ()

static Visualizer *	GetVisualizer (int viz)

static int	GetActiveVizIndex ()

static int	SetActiveVizIndex (int index)

static DataMgrV3_0 *	LoadData (vector< string > files, bool deflt=true)

static DataMgrV3_0 *	GetDataMgr ()

static int	DrawText (int viz, int x, int y, string font, int size, string text)

static int	EnableCapture (string filename, int viz)

static int	SetErrorHandler (ErrorHandler *handler)

static void	SetToDefault ()

static int	ValidateParams (Params *p)

static ViewpointParams *	GetViewpointParams (int winNum)

static RegionParams *	GetRegionParams (int winNum)

static AnimationParams *	GetAnimationParams (int winNum)

Detailed Description

Provides API for VAPOR visualizer User Interfaces (UIs)

Definition at line 32 of file ControlExecutive.h.

Constructor & Destructor Documentation

VAPoR::ControlExec::ControlExec ( )

Initialize the control executive

Note: what, if any, arguments are needed?

VAPoR::ControlExec::~ControlExec ( )

Member Function Documentation

static int VAPoR::ControlExec::ActivateRender	(	int	viz,
		std::string	type,
		int	instance,
		bool	on
	)

static

Activate or Deactivate a renderer

To activate a renderer, a new Renderer instance is created, associate with the RenderParams instance indicated by viz, type, and instance. This renderer instance is inserted in the queue of active renderers for the visualizer. To deactivate a renderer, the associated Renderer instance is removed from the queue of active renderers in the Visualizer, and then deleted.

Parameters

[in]	viz	The visualizer where the renderer is
[in]	type	The type of renderer.
[in]	instance	The instance index to be (de)activated. Must be > 0.
[in]	on	A boolean indicating if the renderer is to be made active (true) or inactive (off)

Returns: status A negative int is returned on failure, indicating that the renderer cannot be activated

static int VAPoR::ControlExec::AddParams	(	int	viz,
		string	type,
		Params *	p
	)

static

Add a new Params instance to the set of instances for a particular visualizer and type.

Parameters

[in]	viz	A valid visualizer handle
[in]	type	The type of the Params instance
[in]	p	The instance to be added.

Return values

zero	if successful.

bool VAPoR::ControlExec::CommandExists ( int offset )

Indicates whether or not there exists a Command at the specified offset from the latest Command which was issued, can be e.g. used to tell whether or not undo or redo is possible. Offset parameter indicates position in Command queue, Offset = 0 for last issued command, offset = -1 for next command to Redo

Parameters

[in] int offset from the end of the queue (last executed command)

Returns: bool is true if there is a command.

static int VAPoR::ControlExec::DrawText	(	int	viz,
		int	x,
		int	y,
		string	font,
		int	size,
		string	text
	)

static

Draw 2D text on the screen

Note: Not yet implemented

This method provides a simple interface for rendering text on the screen. No text will actually be rendered until after Paint() is called. Text rendering will occur after all active renderers associated with viz have completed rendering.

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer()
[in]	x	X coordinate in pixels coordinates of lower left corner of rectangle bounding the text.
[in]	y	Y coordinate in pixels coordinates of lower left corner of rectangle bounding the text.
[in]	font	A string specifying the font name
[in]	size	Font size in points
[in]	text	The text to render

static int VAPoR::ControlExec::EnableCapture	(	string	filename,
		int	viz
	)

static

Capture the next rendered image to a file

Note: Not yet implemented

When this method is called, the next time Paint() is called for the specified visualizer, the rendered image will be written to the specified (.jpg, .tif, ...) file. The UI must call Paint(viz, true) after this method is called. Only one image will be captured; i.e. a subsequent call to Paint() will not capture unless EnableCapture() is called again. If this is called concurrently with a call to Paint(), the image will not be captured until that rendering completes and another Paint() is initiated.

static int VAPoR::ControlExec::FindInstanceIndex	(	int	viz,
		RenderParams *	p
	)

static

Determine the instance index associated with a particular RenderParams instance in a specified visualizer Returns -1 if it is not found

Parameters

[in]	viz	The visualizer index.
[in]	p	The RenderParams whose index is sought

Returns: instance index, or -1 if it is not found.

static AnimationParams* VAPoR::ControlExec::GetActiveAnimationParams ( )

inlinestatic

Obtain the active animation params. This is the AnimationParams instance that is applicable in the current active Visualizer.

Return values

AnimationParams* is the current active AnimationParams instance

Definition at line 300 of file ControlExecutive.h.

static Params* VAPoR::ControlExec::GetActiveParams ( string type )

inlinestatic

Obtain the Params instance that is currently active in the active visualizer If no visualizer is active it returns the default params.

Parameters

[in] type The type of Params

Return values

The	current active Params, or NULL if invalid.

Definition at line 282 of file ControlExecutive.h.

Referenced by VAPoR::EventRouter::GetActiveParams().

static RegionParams* VAPoR::ControlExec::GetActiveRegionParams ( )

inlinestatic

Obtain the active region params. This is the RegionParams instance that is applicable in the current active Visualizer.

Return values

RegionParams* is the current active RegionParams instance

Definition at line 288 of file ControlExecutive.h.

static int VAPoR::ControlExec::GetActiveVizIndex ( )

static

Identify the active visualizer number When using a GUI this is the index of the selected visualizer and is established by calling SetActiveViz()

Returns: index of the current active visualizer

Referenced by VAPoR::VizWinMgr::getActiveVisualizer(), VAPoR::EventRouter::GetActiveVizIndex(), and VAPoR::VizWinMgr::getActiveVizWin().

static ViewpointParams* VAPoR::ControlExec::GetActiveVPParams ( )

inlinestatic

Obtain the active viewpoint params. This is the ViewpointParams instance that is applicable in the current active Visualizer.

Return values

ViewpointParams* is the current active ViewpointParams instance

Definition at line 294 of file ControlExecutive.h.

static AnimationParams* VAPoR::ControlExec::GetAnimationParams ( int winNum )

static

Obtain the AnimationParams that are applicable in a particular Visualizer

Parameters

[in] winNum Visualizer index

Return values

AnimationParams* Params instance that is applicable.

string VAPoR::ControlExec::GetCommandText ( int n )

static Params* VAPoR::ControlExec::GetCurrentParams	(	int	viz,
		string	type
	)

static

Obtain the Params instance that is currently active in the specified visualizer

Parameters

[in]	viz	A valid visualizer handle
[in]	type	The type of Params

Return values

The	current active Params, or NULL if invalid.

static int VAPoR::ControlExec::GetCurrentRenderParamsInstance	(	int	viz,
		string	type
	)

static

Identify the current instance of a RenderParams

Parameters

[in]	viz	A valid visualizer handle
[in]	type	The type of RenderParams

Returns: The instance index that is current in this visualizer

static DataMgrV3_0* VAPoR::ControlExec::GetDataMgr ( )

inlinestatic

Obtain a pointer to the current DataMgr Returns NULL if it does not exist. _dataMgr

Definition at line 411 of file ControlExecutive.h.

static Params* VAPoR::ControlExec::GetDefaultParams ( string type )

static

Method that returns the default Params instance of a particular type. With non-render params this is the global Params instance.

Parameters

[in] type tag associated with the params

Return values

Pointer to specified Params instance

static ControlExec* VAPoR::ControlExec::getInstance ( )

inlinestatic

Obtain the singleton ControlExec object.

Definition at line 41 of file ControlExecutive.h.

static int VAPoR::ControlExec::GetNumBasicParamsClasses ( )

static

Determine how many Basic Params classes are available. These include just the Params that are not associated with tabs.

See also: GetNumTabParamsClasses();

Returns: number of classes

static int VAPoR::ControlExec::GetNumParamsClasses ( )

static

Determine how many different Params classes are available. These include the Params classes associated with tabs in the GUI as well as the Basic Params classes

See also: GetNumTabParamsClasses();

Returns: number of classes

static int VAPoR::ControlExec::GetNumParamsInstances	(	int	viz,
		string	type
	)

static

Determine how many instances of a given renderer type are present in a visualizer. Necessary for setting up a UI.

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer()
[in]	type	The type of the RenderParams or Renderer

Returns: number of instances

static int VAPoR::ControlExec::GetNumTabParamsClasses ( )

static

Determine how many different Params classes are available to be associated with tabs in the GUI. Does not include BasicParams classes

See also: GetNumParamsClasses();

Returns: number of classes

static int VAPoR::ControlExec::GetNumVisualizers ( )

inlinestatic

Determine how many visualizer windows are present

Returns: number of visualizers

Definition at line 314 of file ControlExecutive.h.

static Params* VAPoR::ControlExec::GetParams	(	int	viz,
		string	type,
		int	instance
	)

static

Get a pointer to the existing parameter state information

This method returns a pointer to a Params class object that manages all of the state information for the Params instance identified by (viz,type,instance). The object pointer returned is used to both query parameter information as well as change parameter information.

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer(). If this is -1, then the global or default params is returned.
[in]	type	The type of the Params (e.g. flow, probe) This is the same as the type of Renderer for a RenderParams.
[in]	instance	Instance index, ignored for non-Render params. Use -1 for the current active instance.

Returns: ptr A pointer to the Params object of the specified type that is currently associated with the specified visualizer (and of the specified instance, if this Params is a RenderParams.)

Note: Currently the Params API includes a mechanism for a renderer to register its interest in a changed parameter, and to be notified when that parameter changes. We may also add API to the Params class to register interest in change of any parameter if that proves to be useful.

static RegionParams* VAPoR::ControlExec::GetRegionParams ( int winNum )

static

Obtain the RegionParams that are applicable in a particular Visualizer

Parameters

[in] winNum Visualizer index

Return values

RegionParams* Params instance that is applicable.

static const std::string VAPoR::ControlExec::GetShortName ( string & typetag )

static

Determine the short name associated with a Params type

Parameters

[in] tag of the params type

Returns: short name, e.g. for tab

static ViewpointParams* VAPoR::ControlExec::GetViewpointParams ( int winNum )

static

Obtain the ViewpointParams that are applicable in a particular Visualizer

Parameters

[in] winNum Visualizer index

Return values

ViewpointParams* Params instance that is applicable.

static Visualizer* VAPoR::ControlExec::GetVisualizer ( int viz )

inlinestatic

obtain an existing visualizer

Parameters

[in] viz Handle of desired visualizer

Returns: pointer to specified visualizer

Definition at line 322 of file ControlExecutive.h.

Referenced by VAPoR::VizWinMgr::getActiveVisualizer(), and VAPoR::EventRouter::GetActiveVisualizer().

static void VAPoR::ControlExec::InitializeViz	(	int	viz,
		int	width,
		int	height
	)

static

Perform OpenGL initialization of specified visualizer

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer()
[in]	width	Width of visualizer
[in]	height	Height of visualizer

This method should be called by the UI once before any rendering is performed. The UI should make the OGL context associated with viz current prior to calling this method.

static DataMgrV3_0* VAPoR::ControlExec::LoadData	(	vector< string >	files,
		bool	deflt = `true`
	)

static

Load a data set into the current session

Loads a data set specified by the list of files in files

Parameters

[in]	files	A vector of data file paths. For data sets not containing explicit time information the ordering of time varying data will be determined by the order of the files in `files`.
[in]	deflt	boolean indicating whether data will loaded into the default settings (versus into an existing session).

Returns: datainfo Upon success a constant pointer to a DataInfo structure is returned. The DataInfo structure can be used to query metadata information about the data set. A NULL pointer is returned on failure. Subsequent calls to LoadData() will invalidate previously returned pointers.

Note: The proposed DataMgr API doesn't provide methods to easily query some of the information that will be required by the UI, for example, the coordinate extents of a variable. These methods should either be added to the DataMgr, or the current DataStatus class might be cleaned up. Hence, DataInfo might be an enhanced DataMgr, or a class object designed specifically for returning metadata to the UI.; (AN) It would be much better to incorporate the DataStatus methods into the DataMgr class, rather than keeping them separate.

static int VAPoR::ControlExec::NewVisualizer ( int vizNum = -1 )

static

Create a new visualizer

This method creates a new visualizer. A visualizer is a drawable OpenGL object (e.g. window or pbuffer). The caller is responsible for establishing an OpenGL drawable object and making its context current before calling NewVisualizer().

Parameters

[in] viznum Specifies the proposed handle for the new visualizer. The default viznum is -1, meaning that NewVisualizer will assign an unused value.

Returns: viz Upon success an integer identifier for the visualizer is returned. A negative int is returned on failure

Note: Need to establish what OpenGL state mgt, if any, is performed by UI. For example, who calls swapbuffers?; Since the UI is responsible for setting up the graphics contexts we may need a method that allows the ControlExec to provide hints about what kind of graphics context is needed (e.g. double buffering)

static int VAPoR::ControlExec::Paint	(	int	viz,
		bool	force = `false`
	)

static

Render the contents of a drawable

Tells the control executive to invoke all active renderers associated with the visualizer viz. The control executive may elect to ignore this method if it believes the rendering state to be current, unless force is true.

The UI should make the OGL context associated with viz current prior to calling this method.

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer()
[in]	force	If true all active renderers will rerender their scenes. If false, rendering will only be performed if the params objects associated with any of the active renderers on this visualizer have changed state.

Returns: rc is 0 if actual painting occurred, -1 if not.

Params* VAPoR::ControlExec::Redo ( )

Redo the next session state change Restores the state of the session to what it was before the last change made via Undo,Redo() can be called repeatedly to undo multiple state changes.

State changes do not trigger rendering. It is the UI's responsibility to call Paint() after Redo(), and to make any UI internal changes necessary to reflect the new state. It is also the responsibility of the UI to set any change flags associated with the change in Params state. The returned Params* pointer should be used by the GUI to determine which renderer(s) must be refreshed

Returns: Params* ptr A pointer to the Params object that reflects the change. Pointer is null if there is nothing to Redo

See also: UnDo()

static int VAPoR::ControlExec::RemoveParams	(	int	viz,
		string	type,
		int	instance
	)

static

Delete a RenderParams instance for a particular visualizer, instance index, and Params type The specified instance must previously have been de-activated. There must exist at least one instance or this will fail. All existing Params instances in the same visualizer and with larger instance index will have their instance index reduced by one (so as to avoid gaps in instance numbering).

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer().
[in]	type	The type of the RenderParams (e.g. flow, probe)
[in]	instance	Instance index to be removed. Use -1 for the current active instance.

Returns: int is zero if successful

See also: ActivateRender

static int VAPoR::ControlExec::RemoveVisualizer ( int viz )

static

Delete an existing visualizer

Parameters

[in] viz handle to existing visualizer returned by NewVisualizer

Return values

int	0 if successful;

static void VAPoR::ControlExec::ResizeViz	(	int	viz,
		int	width,
		int	height
	)

static

Notify the control executive that a drawing object has changed size.

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer()
[in]	width	Width of visualizer
[in]	height	Height of visualizer

This method should be called by the UI whenever the drawing object (e.g. window) associated with viz has changed size. The UI should make the OGL context associated with viz current prior to calling this method.

int VAPoR::ControlExec::RestoreSession ( string file )

Restore the session state from a session state file

Note: Not yet implemented

This method sets the session state based on the contents of the session file specified by file. It also has the side effect of deactivating all renderers and unloading any data set previously loaded by LoadData(). If successful, the state of all Params objects may have changed.

Parameters

[in] file Path to the output file

Returns: status A negative int indicates failure. If the method fails the session state remains unchanged (is it possible to guarantee this? )

See also: LoadData(), GetRenderParams(), etc.; SaveSession()

int VAPoR::ControlExec::SaveSession ( string file )

Save the current session state to a file

Note: Not yet implemented

This method saves all current session state information to the file specified by path file. All session state information is stored in Params objects and their derivatives

Parameters

[in] file Path to the output file

Returns: status A negative int indicates failure

See also: RestoreSession()

static int VAPoR::ControlExec::SetActiveVizIndex ( int index )

static

Set the active visualizer GUI uses this method whenever user clicks on a window.

See also: GetActiveVizIndex();

Parameters

[in] index of the current active visualizer

Returns: 0 if successful

static int VAPoR::ControlExec::SetCurrentParamsInstance	(	int	viz,
		string	type,
		int	instance
	)

static

Specify that a particular instance of a Params is current

Parameters

[in]	viz	A valid visualizer handle
[in]	type	The type of RenderParams
[in]	instance	The instance index that will become current.

Returns: zero if successful.

static int VAPoR::ControlExec::SetErrorHandler ( ErrorHandler * handler )

static

Specify an error handler that the ControlExec will use to notify of asynchronous error conditions that arise.

Note: Not yet implemented

The ErrorHandler class will have methods for Setting, clearing error state, which will support A string description and a numerical error code. Only one ErrorHandler can be set. If none is set, no errors will be reported to the UI.

static int VAPoR::ControlExec::SetParams	(	int	viz,
		string	type,
		int	instance,
		Params *	p
	)

static

Specify the Params instance for a particular visualizer, instance index, and Params type This can be used to replace the current Params instance using a new Params pointer. This should not be used to install a Params instance where one did not exist already; Use NewParams for that purpose

Parameters

[in]	viz	A visualizer handle returned by NewVisualizer(). Specify -1 if the Params is global.
[in]	type	The type of the Params (e.g. flow, probe)
[in]	Params*	The pointer to the Params instance being installed. This is the same as the type of Renderer for a RenderParams.
[in]	instance	Instance index, ignored for non-Render params. Use -1 for the current active instance.

Returns: int is zero if successful

static void VAPoR::ControlExec::SetToDefault ( )

static

Set the ControlExec to a default state: Remove all visualizers and Params instances Create default params restart the command queue Delete the DataMgr.

Params* VAPoR::ControlExec::Undo ( )

Undo the last session state change Restores the state of the session to what it was prior to the last change made via a Params object, or prior to the last call to Undo() or Redo(), whichever happened last. I.e. Undo() can be called repeatedly to undo multiple state changes.

State changes do not trigger rendering. It is the UI's responsibility to call Paint() after Undo(), and to make any UI internal changes necessary to reflect the new state. It is also the responsibility of the UI to set any change flags associated with the change in Params state. The returned const Params* pointer should be used by the GUI to determine which renderer(s) must be refreshed

Returns: Params* ptr A pointer to the Params object that reflects the change. Pointer is null if there is nothing to undo.

See also: Redo()

static int VAPoR::ControlExec::ValidateParams ( Params * p )

static

Verify that a Params instance is in a valid state Used to handle synchronous error checking, E.g. checking user input parameters.

Note: Not yet implemented

Parameters

[in] p pointer to Params instance being checked

Returns: status nonzero indicates error

The documentation for this class was generated from the following file:

/Users/clyne/src/vapor-3.0/include/vapor/ControlExecutive.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation