| V_Sim API - Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Signals | ||||
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);
"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
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:
openGLInteractiveBegin_mark(), is a mode where the mouse can select
a node and this nodes become highlighted.
openGLInteractiveBegin_move(), the mouse is then used to move
picked nodes. Moves are possible in the plane of the screen or
constrained along axis of the bounding box.
openGLInteractiveBegin_observe(), in this mode, the mouse is used
to change the position of camera, its orientation and its zoom
characteristics.
openGLInteractiveBegin_pick(), this mode is the most complex
picking mode. It can select atoms up to two references and measure
distances and angles.
openGLInteractiveBegin_pickAndObserve(), this mode is a simplified
mix of obervation and picking.
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).
typedef struct _VisuInteractiveClass VisuInteractiveClass;
An opaque structure representing the class of VisuInteractive objects.
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.
| no interaction ; | |
| interaction to rotate the view ; | |
| interaction to rotate the view and access limited pick action on the right click ; | |
| interaction to pick and measure ; | |
| interaction to select node ; | |
| interaction to move nodes ; | |
| interaction to mark nodes. |
typedef enum {
interactive_constrained,
interactive_walker
} VisuInteractiveMethod;
Describes the different possible methods for observe moves.
| 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. | |
| the camera is moved following the mouse moves, orienting the view as a walker would do along a sphere. |
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.
| click to void ; | |
| click to select one node ; | |
| click to measure a distance between two nodes ; | |
| click to measure an angle ; | |
| click to highlight a node ; | |
| click to select a first reference ; | |
| click to un-select a first reference ; | |
| click to select a second reference ; | |
| click to un-select a second reference ; | |
| click to measure distances and angles around one node ; | |
| click to select a list of nodes. |
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.
| no error during click ; | |
| click to sleect but nothing selected ; | |
| click to set a reference but reference already exists ; | |
| click to select a first reference but impossible to choose this one ; | |
| the same for second reference. |
void visu_interactive_apply (VisuInteractive *inter,VisuNodeArray *array);
Update all ids of inter to point to actual nodes of array.
|
a VisuInteractive object. |
|
a VisuNodeArray object. [allow-none] |
Since 3.7
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.
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. |
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.
|
an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags. |
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.
|
a VisuInteractive object. |
Returns : |
a location with details on the last event. [transfer none] |
Since 3.7
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.
|
a VisuInteractive object. |
|
a location to store a list of cameras. [out][element-type VisuGlCamera*] |
|
a location to store a list of cameras. [out][element-type VisuGlCamera*] |
Since 3.6
VisuInteractiveId visu_interactive_getType (VisuInteractive *inter);
It returns the kind of interactive session.
|
a VisuInteractive object. |
Returns : |
a VisuInteractiveId value. |
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.
|
a VisuInteractive object ; |
|
a VisuGlView object the interaction happened on. |
|
a simplified event. |
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.
|
a VisuInteractive object. |
|
a VisuData object. |
|
a node id. |
Since 3.7
VisuInteractive * visu_interactive_new (VisuInteractiveId type);
Creates a new interactive session of the given type.
|
a VisuInteractiveId flag. |
Returns : |
a newly created object. [transfer full] |
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.
|
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
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.
|
a VisuInteractive object. |
|
a VisuGlCamera object. |
Since 3.6
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.
|
a VisuInteractive object. |
|
a direction. |
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.
|
a VisuInteractive object. |
|
a list of node ids. [element-type guint32] |
void visu_interactive_setNodeList (VisuInteractive *inter,VisuGlExtNodes *nodes);
Associate a VisuGlExtNodes object for node selection. This is mandatory for move, pick and mark actions.
|
a VisuInteractive object. |
|
a VisuGlExtNodes object. [transfer full][allow-none] |
Since 3.7
void visu_interactive_setReferences (VisuInteractive *inter,VisuInteractive *from);
Copies all node ids used as reference from from to inter.
|
a VisuInteractive object. |
|
another VisuInteractive object. |
gboolean visu_interactive_setType (VisuInteractive *inter,VisuInteractiveId id);
It changes the kind of interactive session.
|
a VisuInteractive object. |
|
a VisuInteractiveId. |
Returns : |
TRUE if indeed changed. |
"menu" signalvoid 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.
|
the object emitting the signal. |
|
the x coordinate. |
|
the y coordinate. |
|
a VisuNode. [type VisuNode*][transfer none][allow-none] |
|
user data set when the signal handler was connected. |
Since 3.7
"move" signalvoid 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.
|
the object emitting the signal. |
|
an array of node ids. |
|
user data set when the signal handler was connected. |
Since 3.6
"node-selection" signalvoid 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.
|
the object emitting the signal. |
|
a flag, see VisuInteractivePick. |
|
the primary node. [type VisuNode*][transfer none] |
|
the secondary node, if any. [type VisuNode*][transfer none] |
|
the tertiary node, if any. [type VisuNode*][transfer none] |
|
user data set when the signal handler was connected. |
Since 3.6
"observe" signalvoid 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).
|
the object emitting the signal. |
|
a boolean. |
|
user data set when the signal handler was connected. |
Since 3.6
"region-selection" signalvoid 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.
|
the object emitting the signal. |
|
an array of node ids. |
|
user data set when the signal handler was connected. |
Since 3.6
"selection-error" signalvoid 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).
|
the object emitting the signal. |
|
an error value. |
|
user data set when the signal handler was connected. |
Since 3.6
"start-move" signalvoid 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.
|
the object emitting the signal. |
|
an array of node ids. |
|
user data set when the signal handler was connected. |
Since 3.6
"stop" signalvoid user_function (VisuInteractive *obj,
gpointer user_data) : No Hooks
This signal is emitted each time a set of nodes are stopped to be moved.
|
the object emitting the signal. |
|
user data set when the signal handler was connected. |
Since 3.6