OpenDX - Documentation
Full Contents QuickStart Guide User's Guide User's Reference
Previous Page Next Page Table of Contents Partial Table of Contents Index Search

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

Outputs
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


Full Contents QuickStart Guide User's Guide User's Reference

[ OpenDX Home at IBM | OpenDX.org ]