User's Reference - SuperviseState

SuperviseState

Category

Windows

Function

Manages the object and/or camera associated with an image window created using SuperviseWindow.

Syntax

object, camera, where, events = SuperviseState(where,defaultCamera, resetCamera,
                                               object, resetObject, size,
                                               events, mode, args);

Inputs

Name Type Default Description
where string (none) the window for which objects and cameras are to be manipulated
defaultCamera camera (none) initial or default camera
resetCamera flag 0 whether to reset camera to the default
object object (none) initial or default object
resetObject flag 0 whether to reset object to the default
size vector or integer list (none) size
events object (none) mouse or keyboard events from SuperviseWindow
mode integer (none) specifies the mode, or which UserInteractor to enable
args object (none) interactor arguments

Name	Type	Default	Description
`where`	string	(none)	the window for which objects and cameras are to be manipulated
`defaultCamera`	camera	(none)	initial or default camera
`resetCamera`	flag	0	whether to reset camera to the default
`object`	object	(none)	initial or default object
`resetObject`	flag	0	whether to reset object to the default
`size`	vector or integer list	(none)	size
`events`	object	(none)	mouse or keyboard events from SuperviseWindow
`mode`	integer	(none)	specifies the mode, or which UserInteractor to enable
`args`	object	(none)	interactor arguments

Outputs

Name Type Description
object object current object
camera camera current camera
where string input where
events string unhandled events

Name	Type	Description
`object`	object	current object
`camera`	camera	current camera
`where`	string	input where
`events`	string	unhandled events

Functional Details

Briefly, this module allows a user to specify the particular action that should be taken on mouse or keyboard events in a window created using SuperviseWindow. The SuperviseState module is expected to be used together with SuperviseWindow and Display to create and display a window. These modules are used as an alternative to the Image tool. See SuperviseWindow for a more complete discussion of the use of the Supervise modules and the benefits one gets with respect to the simple use of the Image tool.

Actions are specified using user-supplied routines called UserInteractors. A single UserInteractor is the set of actions which take place for any mouse or keyboard event for a given mode. For example, a single mode may define different behaviors for left, middle, and right mouse actions. An arbitrary number of different modes can be defined, providing a limitless number of different user interactions with the image. Note that this implies that different actions (for example zoom and translate) can be implemented either as different modes using the same mouse button, as the same mode with different mouse buttons, or of course, different modes and different buttons.

where
the window for which objects and cameras are to be manipulated. This input should be supplied by the where output of SuperviseWindow.
defaultCamera
is the initial or default camera.
resetCamera
indicates whether to reset camera to the default
object
is the initial or default object
resetObject
indicates whether to reset object to the default
size
is the current size of the image, and should be supplied by the size output of SuperviseWindow
events
mouse or keyboard events. Should be supplied by the events output of SuperviseWindow
mode
specifies the mode, (which UserInteractor to enable). The set of user-defined UserInteractors is created as a table of callbacks. The mode value specifies which entry in that table is to be called.
args
interactor arguments as required by a UserInteractor.

The following are output parameters:

object
current object; should be passed to the object input of Display.
camera
current camera; should be passed to the camera input of Display
where
Window where parameter; should be passed to the where input of Display.
events
are unhandled events, that is any mouse or keyboard events that have been masked off within the routine InitMode, described in UserInteractors.

UserInteractors

UserInteractors consist of the following routines, the contents of which must be provided by the user. You specify the location of your custom interactor object files using the DX_USER_INTERACTOR_FILE environment variable (see "Other Environment Variables" in IBM Visualization Data Explorer User's Guide).

Note: Default user interactors to implement rotation, pan, and zoom functionality are provided by Data Explorer if you do not provide your own custom interactors. Rotation (mode 0) is the same as the standard left-button rotation interaction of the Image tool. Pan (mode 1) operates differently than the Data Explorer pan mode of the Image tool; you simply drag on the object to move it in the desired direction. Zoom (mode 2) operates as follows: drag upward to zoom in; drag downward to zoom out.

void *InitMode(Object args, int width, int height, int *mask)
Given an object containing args (which come in as input to SuperviseState and are up to the interactor builder to specify), and the current width and height of the window, returns a handle that is passed into all the other UserInteractor routines. This routine also sets the value of mask to reflect which events the particular interactor is interested in (for example, only left or right buttons). Once mask is set, only those events which have been specified as interesting to the interactor will cause the interactor to be called. The set of possible masks is:
DXEVENT_LEFT DXEVENT_MIDDLE DXEVENT_RIGHT DXEVENT_KEYPRESS

void EndMode(void *handle)
Frees the space allocated in InitMode.
void SetCamera(void *handle, float *to, float *from, float *up, int projection, float fov, float width)
Passes current camera info from Data Explorer into the interactor. The interactor can extract whatever camera information it is interested in and put into its private handle. Note that if the camera is going to be modified, this handle must retain the entire camera state so that it can be passed back in GetCamera().
void SetRenderable(void *handle, Object object)
Passes the current object into the interactor. If the interactor is going to change the object, it must be retained in handle.
int GetCamera(void *handle, float *to, float *from, float *up, int *projection, float *fov, float *width)
Passes updated camera information from the interactor back to Data Explorer. If the interactor has not updated the camera information, return 0; otherwise set ALL the inputs and return 1.
int GetRenderable(void *handle, Object *obj)
Passes updated object information from the interactor back to Data Explorer. If the interactor has not updated the object, return 0, otherwise set obj to point to the updated object and return 1.
void EventHandler(void *handle, DXEvent *event)
Event handler. Receives the event in *event where a DXEvent is of type:
typedef union { DXAnyEvent any; DXMouseEvent mouse; DXKeyPressEvent keypress; }
and where DXAnyEvent, DXMouseevent, and DXKeyPressEvent are of type:
typedef struct { int event } DXAnyEvent typedef struct { int event; int x; int y; int state; } DXMouseEvent typedef struct { int event; int x; int y; int key; } DXKeyPressEvent
event is one of DXEVENT_LEFT, DXEVENT_MIDDLE, DXEVENT_RIGHT, or DXEVENT_KEYPRESS; x and y are the pixel location of the event; state is one of BUTTON_DOWN, BUTTON_MOTION, or BUTTON_UP; and key is the key that was pressed.

Doing Picking

If you want to do picking in a window created by SuperviseWindow, simply pass the events, object, and camera outputs of SuperviseState to the locations, object, and camera inputs of Pick. Pick will pull out only the locations of button-down events from events and use camera to do the picking.

Example Visual Programs

SIMPLE/Supervise.net
Image_wo_UI.net
IndependentlyArrange.net
InsetImage.net

Also see the demonstrations of custom interactors in /usr/local/dx/samples/supervise.

See Also

SuperviseWindow, Display, Image

[ OpenDX Home at IBM | OpenDX.org ]

`where`	the window for which objects and cameras are to be manipulated. This input should be supplied by the `where` output of SuperviseWindow.
`defaultCamera`	is the initial or default camera.
`resetCamera`	indicates whether to reset camera to the default
`object`	is the initial or default object
`resetObject`	indicates whether to reset object to the default
`size`	is the current size of the image, and should be supplied by the `size` output of SuperviseWindow
`events`	mouse or keyboard events. Should be supplied by the `events` output of SuperviseWindow
`mode`	specifies the mode, (which UserInteractor to enable). The set of user-defined UserInteractors is created as a table of callbacks. The `mode` value specifies which entry in that table is to be called.
`args`	interactor arguments as required by a UserInteractor.

`object`	current object; should be passed to the `object` input of Display.
`camera`	current camera; should be passed to the `camera` input of Display
`where`	Window where parameter; should be passed to the `where` input of Display.
`events`	are unhandled events, that is any mouse or keyboard events that have been masked off within the routine InitMode, described in UserInteractors.

*`void InitMode(Object args, int width, int height, int mask)`*	Given an object containing `args` (which come in as input to SuperviseState and are up to the interactor builder to specify), and the current width and height of the window, returns a handle that is passed into all the other UserInteractor routines. This routine also sets the value of `mask` to reflect which events the particular interactor is interested in (for example, only left or right buttons). Once `mask` is set, only those events which have been specified as interesting to the interactor will cause the interactor to be called. The set of possible masks is: `DXEVENT_LEFT DXEVENT_MIDDLE DXEVENT_RIGHT DXEVENT_KEYPRESS`
*`void EndMode(void handle)`**	Frees the space allocated in InitMode.
*`void SetCamera(void handle, float to, float from, float up, int projection, float fov, float width)`*	Passes current camera info from Data Explorer into the interactor. The interactor can extract whatever camera information it is interested in and put into its private `handle`. Note that if the camera is going to be modified, this handle must retain the entire camera state so that it can be passed back in GetCamera().
*`void SetRenderable(void handle, Object object)`**	Passes the current object into the interactor. If the interactor is going to change the object, it must be retained in `handle`.
*`int GetCamera(void handle, float to, float from, float up, int projection, float fov, float width)`**	Passes updated camera information from the interactor back to Data Explorer. If the interactor has not updated the camera information, return 0; otherwise set ALL the inputs and return 1.
*`int GetRenderable(void handle, Object obj)`*	Passes updated object information from the interactor back to Data Explorer. If the interactor has not updated the object, return 0, otherwise set `obj` to point to the updated object and return 1.
*`void EventHandler(void handle, DXEvent event)`*	Event handler. Receives the event in `*event` where a `DXEvent` is of type: typedef union { DXAnyEvent any; DXMouseEvent mouse; DXKeyPressEvent keypress; } and where `DXAnyEvent`, `DXMouseevent`, and `DXKeyPressEvent` are of type: typedef struct { int event } DXAnyEvent typedef struct { int event; int x; int y; int state; } DXMouseEvent typedef struct { int event; int x; int y; int key; } DXKeyPressEvent `event` is one of `DXEVENT_LEFT`, `DXEVENT_MIDDLE`, `DXEVENT_RIGHT`, or `DXEVENT_KEYPRESS`; `x` and `y` are the pixel location of the event; `state` is one of `BUTTON_DOWN`, `BUTTON_MOTION`, or `BUTTON_UP`; and `key` is the key that was pressed.