interactive

interactive — Gives tools to interact with the rendered area.

Synopsis

enum                VisuInteractiveMethod;
enum                VisuInteractiveId;
enum                VisuInteractivePick;
enum                VisuInteractivePickError;
#define             VISU_INTERACTIVE_TYPE
#define             VISU_INTERACTIVE                    (obj)
#define             VISU_INTERACTIVE_CLASS              (klass)
#define             IS_VISU_INTERACTIVE                 (obj)
#define             IS_VISU_INTERACTIVE_CLASS           (klass)
#define             VISU_INTERACTIVE_GET_CLASS          (obj)
                    VisuInteractive;
                    VisuInteractiveClass;
GType               visuInteractive_get_type            (void);
void                visuInteractiveClassSet_preferedObserveMethod
                                                        (VisuInteractiveMethod method);
VisuInteractiveMethod  visuInteractiveClassGet_preferedObserveMethod
                                                        ();
VisuInteractive*    visuInteractiveNew                  (VisuInteractiveId type);
VisuInteractiveId   visuInteractiveGet_type             (VisuInteractive *inter);
void                visuInteractiveHandle_event         (VisuInteractive *inter,
                                                         VisuData *dataObj,
                                                         SimplifiedEvents *ev);
void                visuInteractiveSet_movingNodes      (VisuInteractive *inter,
                                                         GList *nodeIds);
void                visuInteractiveSet_movingAxe        (VisuInteractive *inter,
                                                         float axe[3]);
VisuOpenGLCamera*   visuInteractivePop_savedCamera      (VisuInteractive *inter);
void                visuInteractivePush_savedCamera     (VisuInteractive *inter,
                                                         VisuOpenGLCamera *camera);
void                visuInteractiveGet_savedCameras     (VisuInteractive *inter,
                                                         GList **cameras,
                                                         GList **head);
void                visuInteractiveSet_references       (VisuInteractive *inter,
                                                         VisuInteractive *from);
void                getNodes2DCoordinates               (VisuData *dataObj,
                                                         unsigned int *nodeIds,
                                                         unsigned int nNodes,
                                                         float *coordinates2D,
                                                         unsigned int *size);

Object Hierarchy

  GObject
   +----VisuInteractive

Signals

  "move"                                           : Run Last / No Recursion / No Hooks
  "node-selection"                                 : Run Last / No Recursion
  "observe"                                        : Run Last / No Recursion
  "region-selection"                               : Run Last / No Recursion / No Hooks
  "selection-error"                                : Run Last / No Recursion / No Hooks
  "start-move"                                     : Run Last / No Recursion / No Hooks
  "stop"                                           : Run Last / No Recursion / 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

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 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 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_TYPE

#define VISU_INTERACTIVE_TYPE	     (visuInteractive_get_type ())

return the type of VisuInteractive.


VISU_INTERACTIVE()

#define VISU_INTERACTIVE(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, VISU_INTERACTIVE_TYPE, VisuInteractive))

Cast the given obj into VisuInteractive type.

obj :

a GObject to cast.

VISU_INTERACTIVE_CLASS()

#define VISU_INTERACTIVE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, VISU_INTERACTIVE_TYPE, VisuInteractiveClass))

Cast the given klass into VisuInteractiveClass.

klass :

a GObjectClass to cast.

IS_VISU_INTERACTIVE()

#define IS_VISU_INTERACTIVE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, VISU_INTERACTIVE_TYPE))

Test if the given ogj is of the type of VisuInteractive object.

obj :

a GObject to test.

IS_VISU_INTERACTIVE_CLASS()

#define IS_VISU_INTERACTIVE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, VISU_INTERACTIVE_TYPE))

Test if the given klass is of the type of VisuInteractiveClass class.

klass :

a GObjectClass to test.

VISU_INTERACTIVE_GET_CLASS()

#define VISU_INTERACTIVE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, VISU_INTERACTIVE_TYPE, VisuInteractiveClass))

It returns the class of the given obj.

obj :

a GObject to get the class of.

VisuInteractive

typedef struct _VisuInteractive VisuInteractive;

All fields are private.


VisuInteractiveClass

typedef struct _VisuInteractiveClass VisuInteractiveClass;

An opaque structure representing the class of VisuInteractive objects.


visuInteractive_get_type ()

GType               visuInteractive_get_type            (void);

This method returns the type of VisuInteractive, use VISU_INTERACTIVE_TYPE instead.

Returns :

the type of VisuInteractive.

visuInteractiveClassSet_preferedObserveMethod ()

void                visuInteractiveClassSet_preferedObserveMethod
                                                        (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.

visuInteractiveClassGet_preferedObserveMethod ()

VisuInteractiveMethod  visuInteractiveClassGet_preferedObserveMethod
                                                        ();

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.

visuInteractiveNew ()

VisuInteractive*    visuInteractiveNew                  (VisuInteractiveId type);

Creates a new interactive session of the given type.

type :

a VisuInteractiveId flag.

Returns :

a newly created object.

visuInteractiveGet_type ()

VisuInteractiveId   visuInteractiveGet_type             (VisuInteractive *inter);

It returns the kind of interactive session.

inter :

a VisuInteractive object.

Returns :

a VisuInteractiveId value.

visuInteractiveHandle_event ()

void                visuInteractiveHandle_event         (VisuInteractive *inter,
                                                         VisuData *dataObj,
                                                         SimplifiedEvents *ev);

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

inter :

a VisuInteractive object ;

dataObj :

the VisuData object to interact with ;

ev :

a simplified event.

visuInteractiveSet_movingNodes ()

void                visuInteractiveSet_movingNodes      (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.

visuInteractiveSet_movingAxe ()

void                visuInteractiveSet_movingAxe        (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.

visuInteractivePop_savedCamera ()

VisuOpenGLCamera*   visuInteractivePop_savedCamera      (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 VisuOpenGLCamera. It is owned by V_Sim and should not be touched.

Since 3.6


visuInteractivePush_savedCamera ()

void                visuInteractivePush_savedCamera     (VisuInteractive *inter,
                                                         VisuOpenGLCamera *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 VisuOpenGLCamera object.

Since 3.6


visuInteractiveGet_savedCameras ()

void                visuInteractiveGet_savedCameras     (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.

head :

a location to store a list of cameras.

Since 3.6


visuInteractiveSet_references ()

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

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

inter :

a VisuInteractive object.

from :

another VisuInteractive object.

getNodes2DCoordinates ()

void                getNodes2DCoordinates               (VisuData *dataObj,
                                                         unsigned int *nodeIds,
                                                         unsigned int nNodes,
                                                         float *coordinates2D,
                                                         unsigned int *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.

Signal Details

The "move" signal

void                user_function                      (VisuInteractive *obj,
                                                        gpointer         nodes,
                                                        gpointer         user_data)      : Run Last / No Recursion / 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,
                                                        gpointer         nodes,
                                                        gpointer         user_data)      : Run Last / 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 nodes.

obj :

the object emitting the signal.

kind :

a flag.

nodes :

an array of three node ids.

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)      : Run Last / 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)      : Run Last / No Recursion / 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)      : Run Last / No Recursion / 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)      : Run Last / No Recursion / 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)      : Run Last / No Recursion / 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