interactive

interactive — Gives tools to interact with the rendered area.

Synopsis

                    VisuInteractive;
                    VisuInteractiveClass;
enum                VisuInteractiveId;
enum                VisuInteractiveMethod;
enum                VisuInteractivePick;
enum                VisuInteractivePickError;
void                visu_interactive_apply              (VisuInteractive *inter,
                                                         VisuNodeArray *array);
void                visu_interactive_class_getNodes2DCoordinates
                                                        (VisuData *dataObj,
                                                         guint *nodeIds,
                                                         guint nNodes,
                                                         float *coordinates2D,
                                                         guint *size);
VisuInteractiveMethod visu_interactive_class_getPreferedObserveMethod
                                                        ();
void                visu_interactive_class_setPreferedObserveMethod
                                                        (VisuInteractiveMethod method);
ToolSimplifiedEvents * visu_interactive_getEvent        (VisuInteractive *inter);
void                visu_interactive_getSavedCameras    (VisuInteractive *inter,
                                                         GList **cameras,
                                                         GList **head);
VisuInteractiveId   visu_interactive_getType            (VisuInteractive *inter);
void                visu_interactive_handleEvent        (VisuInteractive *inter,
                                                         VisuGlView *view,
                                                         ToolSimplifiedEvents *ev);
void                visu_interactive_highlight          (VisuInteractive *inter,
                                                         VisuData *dataObj,
                                                         guint nodeId);
VisuInteractive *   visu_interactive_new                (VisuInteractiveId type);
VisuGlCamera *      visu_interactive_popSavedCamera     (VisuInteractive *inter);
void                visu_interactive_pushSavedCamera    (VisuInteractive *inter,
                                                         VisuGlCamera *camera);
void                visu_interactive_setMovingAxe       (VisuInteractive *inter,
                                                         float axe[3]);
void                visu_interactive_setMovingNodes     (VisuInteractive *inter,
                                                         GList *nodeIds);
void                visu_interactive_setNodeList        (VisuInteractive *inter,
                                                         VisuGlExtNodes *nodes);
void                visu_interactive_setReferences      (VisuInteractive *inter,
                                                         VisuInteractive *from);
gboolean            visu_interactive_setType            (VisuInteractive *inter,
                                                         VisuInteractiveId id);

Object Hierarchy

  GObject
   +----VisuInteractive

Signals

  "menu"                                           : No Recursion
  "move"                                           : No Hooks
  "node-selection"                                 : No Recursion
  "observe"                                        : No Recursion
  "region-selection"                               : No Hooks
  "selection-error"                                : No Hooks
  "start-move"                                     : No Hooks
  "stop"                                           : No Hooks

Description

When one wants some interactions on the rendering area (either from the mouse or from the keyboard), one should initialise it using openGLInteractiveInit_session(). Then, during the interactive session, several modes have been implemented:

The observe mode has two different moving algorithms that can be changed using openGLInteractiveSet_preferedObserveMethod(). The first, called 'constrained' (cf. OPENGL_OBSERVE_CONSTRAINED) corresponds to movements along parallels and meridians. When the mouse is moved along x axis, the camera raotates along a parallel. When the camera is moved along y axis, the camera rotate along a meridian. The top is always pointing to the north pole (in fact, omega is always forced to 0 in this mode). This mode has a 'strange' behavior when the observer is near a pole: moving mouse along x axis make the box rotates on itself. It is normal, because movements on x axis is equivalent to movements on parallel and near the poles, parallel are small circle around the z axis. This can be unnatural in some occasion and the other mode, called 'walker' (see OPENGL_OBSERVE_WALKER) can be used instead of the 'constrained' mode. In the former, the moving is done has if the observer was a walking ant on a sphere : moving the mouse along y axis makes the ant go on or forward ; and x axis movements makes the ant goes on its left or on it right. This is a more natural way to move the box but it has the inconvient that it is hard to return in a given position (omega has never the right value).

Details

VisuInteractive

typedef struct _VisuInteractive VisuInteractive;

All fields are private.


VisuInteractiveClass

typedef struct _VisuInteractiveClass VisuInteractiveClass;

An opaque structure representing the class of VisuInteractive objects.


enum VisuInteractiveId

typedef enum {
    interactive_none,
    interactive_observe,
    interactive_measureAndObserve,
    interactive_measure,
    interactive_pick,
    interactive_move,
    interactive_mark
} VisuInteractiveId;

These are the possible mouse interaction that are implemented.

interactive_none

no interaction ;

interactive_observe

interaction to rotate the view ;

interactive_measureAndObserve

interaction to rotate the view and access limited pick action on the right click ;

interactive_measure

interaction to pick and measure ;

interactive_pick

interaction to select node ;

interactive_move

interaction to move nodes ;

interactive_mark

interaction to mark nodes.

enum VisuInteractiveMethod

typedef enum {
    interactive_constrained,
    interactive_walker
} VisuInteractiveMethod;

Describes the different possible methods for observe moves.

interactive_constrained

the camera is moved keeping the north pole up. The north pole is defined by the Z axis et periodic boundary conditions and by normal to surface in surface conditions.

interactive_walker

the camera is moved following the mouse moves, orienting the view as a walker would do along a sphere.

enum VisuInteractivePick

typedef enum {
    PICK_NONE,
    PICK_SELECTED,
    PICK_DISTANCE,
    PICK_ANGLE,
    PICK_HIGHLIGHT,
    PICK_REFERENCE_1,
    PICK_UNREFERENCE_1,
    PICK_REFERENCE_2,
    PICK_UNREFERENCE_2,
    PICK_INFORMATION,
    PICK_REGION
} VisuInteractivePick;

Possible significations of a click.

PICK_NONE

click to void ;

PICK_SELECTED

click to select one node ;

PICK_DISTANCE

click to measure a distance between two nodes ;

PICK_ANGLE

click to measure an angle ;

PICK_HIGHLIGHT

click to highlight a node ;

PICK_REFERENCE_1

click to select a first reference ;

PICK_UNREFERENCE_1

click to un-select a first reference ;

PICK_REFERENCE_2

click to select a second reference ;

PICK_UNREFERENCE_2

click to un-select a second reference ;

PICK_INFORMATION

click to measure distances and angles around one node ;

PICK_REGION

click to select a list of nodes.

enum VisuInteractivePickError

typedef enum {
    PICK_ERROR_NONE,
    PICK_ERROR_NO_SELECTION,
    PICK_ERROR_SAME_REF,
    PICK_ERROR_REF1,
    PICK_ERROR_REF2
} VisuInteractivePickError;

Possible errors to occur when pick or measure.

PICK_ERROR_NONE

no error during click ;

PICK_ERROR_NO_SELECTION

click to sleect but nothing selected ;

PICK_ERROR_SAME_REF

click to set a reference but reference already exists ;

PICK_ERROR_REF1

click to select a first reference but impossible to choose this one ;

PICK_ERROR_REF2

the same for second reference.

visu_interactive_apply ()

void                visu_interactive_apply              (VisuInteractive *inter,
                                                         VisuNodeArray *array);

Update all ids of inter to point to actual nodes of array.

inter :

a VisuInteractive object.

array :

a VisuNodeArray object. [allow-none]

Since 3.7


visu_interactive_class_getNodes2DCoordinates ()

void                visu_interactive_class_getNodes2DCoordinates
                                                        (VisuData *dataObj,
                                                         guint *nodeIds,
                                                         guint nNodes,
                                                         float *coordinates2D,
                                                         guint *size);

From nodes ids, compute and store in coordinates2D their 2D coordinates.

dataObj :

a VisuData object ;

nodeIds :

an array of VisuNode ids ;

nNodes :

the number of nodes in the array ;

coordinates2D :

an array of nodes 2D coordinates ;

size :

the size of the coordinates array.

visu_interactive_class_getPreferedObserveMethod ()

VisuInteractiveMethod visu_interactive_class_getPreferedObserveMethod
                                                        ();

There are two methods to move the camera in a pick and observe sesion. These two methods are described in the commentary of the keys OPENGL_OBSERVE_CONSTRAINED an dOPENGL_OBSERVE_WALKER.

Returns :

an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags.

visu_interactive_class_setPreferedObserveMethod ()

void                visu_interactive_class_setPreferedObserveMethod
                                                        (VisuInteractiveMethod method);

There are two methods to move the camera in a pick and observe sesion. These two methods are described in the commentary of the keys OPENGL_OBSERVE_CONSTRAINED an dOPENGL_OBSERVE_WALKER.

method :

an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags.

visu_interactive_getEvent ()

ToolSimplifiedEvents * visu_interactive_getEvent        (VisuInteractive *inter);

This routine can be called in callbacks of inter to get some details about the event that raise signals like VisuInteractive::node-selection.

inter :

a VisuInteractive object.

Returns :

a location with details on the last event. [transfer none]

Since 3.7


visu_interactive_getSavedCameras ()

void                visu_interactive_getSavedCameras    (VisuInteractive *inter,
                                                         GList **cameras,
                                                         GList **head);

inter object stores camera settings as a ring. One can access the set of saved cameras thanks to cameras or to the current position in the ring thanks to head. cameras or head are not copied and are owned by V_Sim. They should be considered read-only.

inter :

a VisuInteractive object.

cameras :

a location to store a list of cameras. [out][element-type VisuGlCamera*]

head :

a location to store a list of cameras. [out][element-type VisuGlCamera*]

Since 3.6


visu_interactive_getType ()

VisuInteractiveId   visu_interactive_getType            (VisuInteractive *inter);

It returns the kind of interactive session.

inter :

a VisuInteractive object.

Returns :

a VisuInteractiveId value.

visu_interactive_handleEvent ()

void                visu_interactive_handleEvent        (VisuInteractive *inter,
                                                         VisuGlView *view,
                                                         ToolSimplifiedEvents *ev);

This routine should be called by the rendering window when some event is raised on the rendering surface.

inter :

a VisuInteractive object ;

view :

a VisuGlView object the interaction happened on.

ev :

a simplified event.

visu_interactive_highlight ()

void                visu_interactive_highlight          (VisuInteractive *inter,
                                                         VisuData *dataObj,
                                                         guint nodeId);

This routine simulates an highlight action on nodeId from dataObj. This triggers the signal "node-selection", or "selection-error" if nodeId is invalid.

inter :

a VisuInteractive object.

dataObj :

a VisuData object.

nodeId :

a node id.

Since 3.7


visu_interactive_new ()

VisuInteractive *   visu_interactive_new                (VisuInteractiveId type);

Creates a new interactive session of the given type.

type :

a VisuInteractiveId flag.

Returns :

a newly created object. [transfer full]

visu_interactive_popSavedCamera ()

VisuGlCamera *      visu_interactive_popSavedCamera     (VisuInteractive *inter);

inter object stores camera settings as a ring. This routine goes to the next camera in the ring and returns the current one. The popped camera is not actually removed from the ring.

inter :

a VisuInteractive object.

Returns :

a pointer to the previously current VisuGlCamera. It is owned by V_Sim and should not be touched.

Since 3.6


visu_interactive_pushSavedCamera ()

void                visu_interactive_pushSavedCamera    (VisuInteractive *inter,
                                                         VisuGlCamera *camera);

inter object stores camera settings as a ring. The given camera is copied in the ring if its values not already exist. The current camera is set to this new one.

inter :

a VisuInteractive object.

camera :

a VisuGlCamera object.

Since 3.6


visu_interactive_setMovingAxe ()

void                visu_interactive_setMovingAxe       (VisuInteractive *inter,
                                                         float axe[3]);

Defines the axe that can be used to move along if inter is a move action session.

inter :

a VisuInteractive object.

axe :

a direction.

visu_interactive_setMovingNodes ()

void                visu_interactive_setMovingNodes     (VisuInteractive *inter,
                                                         GList *nodeIds);

Defines the nodes that should be moved if inter is a move action session. The list is actually copied.

inter :

a VisuInteractive object.

nodeIds :

a list of node ids. [element-type guint32]

visu_interactive_setNodeList ()

void                visu_interactive_setNodeList        (VisuInteractive *inter,
                                                         VisuGlExtNodes *nodes);

Associate a VisuGlExtNodes object for node selection. This is mandatory for move, pick and mark actions.

inter :

a VisuInteractive object.

nodes :

a VisuGlExtNodes object. [transfer full][allow-none]

Since 3.7


visu_interactive_setReferences ()

void                visu_interactive_setReferences      (VisuInteractive *inter,
                                                         VisuInteractive *from);

Copies all node ids used as reference from from to inter.

inter :

a VisuInteractive object.

from :

another VisuInteractive object.

visu_interactive_setType ()

gboolean            visu_interactive_setType            (VisuInteractive *inter,
                                                         VisuInteractiveId id);

It changes the kind of interactive session.

inter :

a VisuInteractive object.

id :

a VisuInteractiveId.

Returns :

TRUE if indeed changed.

Signal Details

The "menu" signal

void                user_function                      (VisuInteractive *obj,
                                                        gint             x,
                                                        gint             y,
                                                        VisuNode        *node,
                                                        gpointer         user_data)      : No Recursion

This signal is emitted each time a menu key stroke is done.

obj :

the object emitting the signal.

x :

the x coordinate.

y :

the y coordinate.

node :

a VisuNode. [type VisuNode*][transfer none][allow-none]

user_data :

user data set when the signal handler was connected.

Since 3.7


The "move" signal

void                user_function                      (VisuInteractive *obj,
                                                        gpointer         nodes,
                                                        gpointer         user_data)      : No Hooks

This signal is emitted each time a set of nodes are moved. The corresponding nodes are stored in nodes.

obj :

the object emitting the signal.

nodes :

an array of node ids.

user_data :

user data set when the signal handler was connected.

Since 3.6


The "node-selection" signal

void                user_function                      (VisuInteractive *obj,
                                                        guint            kind,
                                                        VisuNode        *node1,
                                                        VisuNode        *node2,
                                                        VisuNode        *node3,
                                                        gpointer         user_data)      : No Recursion

This signal is emitted each time a single node selection succeed, providing the kind in kind (see VisuInteractivePick). The corresponding nodes are stored in node1, node2 and node3.

obj :

the object emitting the signal.

kind :

a flag, see VisuInteractivePick.

node1 :

the primary node. [type VisuNode*][transfer none]

node2 :

the secondary node, if any. [type VisuNode*][transfer none]

node3 :

the tertiary node, if any. [type VisuNode*][transfer none]

user_data :

user data set when the signal handler was connected.

Since 3.6


The "observe" signal

void                user_function                      (VisuInteractive *obj,
                                                        gboolean         bool,
                                                        gpointer         user_data)      : No Recursion

This signal is emitted each time an observe session is start (bool is TRUE) or finished (bool is FALSE).

obj :

the object emitting the signal.

bool :

a boolean.

user_data :

user data set when the signal handler was connected.

Since 3.6


The "region-selection" signal

void                user_function                      (VisuInteractive *obj,
                                                        gpointer         nodes,
                                                        gpointer         user_data)      : No Hooks

This signal is emitted each time a region selection succeed. The corresponding nodes are stored in nodes.

obj :

the object emitting the signal.

nodes :

an array of node ids.

user_data :

user data set when the signal handler was connected.

Since 3.6


The "selection-error" signal

void                user_function                      (VisuInteractive *obj,
                                                        guint            err,
                                                        gpointer         user_data)      : No Hooks

This signal is emitted each time a selection fails, providing the error in err (see VisuInteractivePickError).

obj :

the object emitting the signal.

err :

an error value.

user_data :

user data set when the signal handler was connected.

Since 3.6


The "start-move" signal

void                user_function                      (VisuInteractive *obj,
                                                        gpointer         nodes,
                                                        gpointer         user_data)      : No Hooks

This signal is emitted each time a set of nodes are clicked to be moved. The corresponding nodes are stored in nodes.

obj :

the object emitting the signal.

nodes :

an array of node ids.

user_data :

user data set when the signal handler was connected.

Since 3.6


The "stop" signal

void                user_function                      (VisuInteractive *obj,
                                                        gpointer         user_data)      : No Hooks

This signal is emitted each time a set of nodes are stopped to be moved.

obj :

the object emitting the signal.

user_data :

user data set when the signal handler was connected.

Since 3.6