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

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

[ OpenDX Home at IBM | OpenDX.org ]