![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
visu_pairsvisu_pairs — V_Sim can draw link between nodes. This part defines a pair object and interface to draw pairs. |
#define PAIRS_MIN #define PAIRS_MAX void (*foreachPairsFunc) (VisuElement *ele1, VisuElement *ele2, VisuPairData *data, gpointer userData); typedef VisuPair; struct VisuPair_struct; typedef VisuPairData; typedef VisuPairDistribution; void (*initEndOpenGlPairsFunc) (); void (*startEndPairsFunc) (VisuElement *ele1, VisuElement *ele2, VisuPairData *data); void (*pairDefinitionFunc) (VisuElement *ele1, VisuElement *ele2, VisuPairData *data, OpenGLView *view, double x1, double y1, double z1, double x2, double y2, double z2, float d2, float alpha); struct PairsExtension_struct; typedef PairsExtension; PairsExtension* (*PairsExtensionInitFunc) (void); PairsExtension* visuPairExtensionNew (const char *name, const char *printName, const char *description, gboolean sensitive, initEndOpenGlPairsFunc init, initEndOpenGlPairsFunc stop, startEndPairsFunc start, startEndPairsFunc end, pairDefinitionFunc draw); void visuPairExtensionFree (PairsExtension *extension); void visuPairExtensionAdd (PairsExtension *extension); GList* visuPairExtensionGet_allMethods (); PairsExtension* visuPairExtensionGet_current (); gboolean visuPairExtensionSet (PairsExtension *extension); gboolean visuPairBuild (VisuData *dataObj); void visuPairForeach (foreachPairsFunc whatToDo, gpointer userData); gboolean visuPairGet_status (); float visuPairGet_distance (VisuPairData *data, int minOrMax); VisuPairDistribution* visuPairGet_distanceDistribution (VisuPair *pair, VisuData *dataObj, float step, float max); gboolean visuPairGet_drawn (VisuPairData *data); VisuPairData* visuPairGet_link (VisuElement *ele1, VisuElement *ele2, float minMax[2]); VisuPairData* visuPairGet_linkFromId (VisuElement *ele1, VisuElement *ele2, guint pos); GList* visuPairGet_links (VisuElement *ele1, VisuElement *ele2); gpointer visuPairGet_linkProperty (VisuPairData *data, const gchar *key); VisuPair* visuPairGet_pair (VisuElement *ele1, VisuElement *ele2); gboolean visuPairGet_printLength (VisuPairData *data); gpointer visuPairGet_property (VisuPair *pair, const gchar *key); gboolean visuPairRead_linkFromTokens (gchar **tokens, int *index, VisuPairData **data, int position, GError **error); gboolean visuPairRemove_link (VisuElement *ele1, VisuElement *ele2, VisuPairData *data); gboolean visuPairSet_status (gboolean onOff); void visuPairSet_outOfDate (); gboolean visuPairSet_color (VisuPairData *data, Color *destColor); gboolean visuPairSet_distance (VisuPairData *data, float val, int minOrMax); gboolean visuPairSet_drawn (VisuPairData *data, gboolean drawn); gboolean visuPairSet_printLength (VisuPairData *data, gboolean status); void visuPairSet_property (VisuPair *pair, const gchar *key, gpointer value, GDestroyNotify freeFunc); void visuPairSet_linkProperty (VisuPairData *data, const gchar *key, gpointer value); int initPairsModule ();
The visu_pairs.c defines only general methods to draw
pairs. It introduces a new object called PairsData. This stores
some characteristics on links between two VisuElement. The main
characteristic is that pairs are drawn only if the length between
two nodes is in a specific range. Use setPairsDistance()
and
getPairsDistance()
to tune this range.
This file does not draw any pairs. But it gives some
interface to create rendering capabilities. To create a new pair
rendering module, called PairsExtension, use
pairsExtension_new()
. Basically, a PairsExtension is characterized
by it drawing method. But it can have other methods that are called
in different cases. See initEndOpenGlPairsFunc()
and
startEndPairsFunc()
prototypes to have more informations.
#define PAIRS_MIN 0
Flag used to define the minimum length to draw pair. This is useful with
the getPairsDistance()
and the getPairsDistance()
methods.
#define PAIRS_MAX 1
Flag used to define the maximum length to draw pair. This is useful with
the getPairsDistance()
and the getPairsDistance()
methods.
void (*foreachPairsFunc) (VisuElement *ele1, VisuElement *ele2, VisuPairData *data, gpointer userData);
Prototype of functions called with the foreach method apply to each pairs.
|
a VisuElement object ; |
|
a VisuElement object ; |
|
a VisuPairData object ; |
|
some user defined data. |
struct VisuPair_struct;
An opaque structure to store informations about links between two elements.
typedef struct pairsData_struct VisuPairData;
A common way to name pairsData_struct objects.
typedef struct VisuPairDistribution_struct VisuPairDistribution;
A convenient name for VisuPairDistribution_struct objects.
void (*initEndOpenGlPairsFunc) ();
Prototype of functions called at the beginning and the end of opengl pairs drawing. Such methods are useful to change some OpenGL variables such as lighting or blending...
void (*startEndPairsFunc) (VisuElement *ele1, VisuElement *ele2, VisuPairData *data);
Prototype of functions called at the beginning and
the end of drawing of each pairs types. ele1
and ele2
arguments are the two elements between the pair defined by data
is drawn.
This is useful to set some OpenGL definition specific to each pair, such
as the color for example.
|
a VisuElement object ; |
|
a VisuElement object ; |
|
a VisuPairData object. |
void (*pairDefinitionFunc) (VisuElement *ele1, VisuElement *ele2, VisuPairData *data, OpenGLView *view, double x1, double y1, double z1, double x2, double y2, double z2, float d2, float alpha);
Prototype of function to draw a pair. Such function are called each time a pair
is drawn between the two points (x1
, y1
, z1
) and (x2
, y2
, z2
). The d2
argument
is the square distance between the two points. The alpha
argument
is a proposed alpha colour from the main program, its value is in [0;1].
|
a VisuElement object ; |
|
a VisuElement object ; |
|
a VisuPairData object ; |
|
a OpenGLView object, giving some constants describing the OpenGL scene ; |
|
a floating point value ; |
|
a floating point value ; |
|
a floating point value ; |
|
a floating point value ; |
|
a floating point value ; |
|
a floating point value ; |
|
a floating point value ; |
|
a floating point value. |
struct PairsExtension_struct;
Structure to store pairs extensions. All fields are private and should not be accessed directly. This structure will not be public in near future, do not use it.
typedef struct PairsExtension_struct PairsExtension;
Common naming for PairsExtension_struct objects.
PairsExtension* (*PairsExtensionInitFunc) (void);
Prototype of the functions used to initialise a new pair models.
Returns : |
a newly allocated pair model. |
PairsExtension* visuPairExtensionNew (const char *name, const char *printName, const char *description, gboolean sensitive, initEndOpenGlPairsFunc init, initEndOpenGlPairsFunc stop, startEndPairsFunc start, startEndPairsFunc end, pairDefinitionFunc draw);
This creates a new pairs extension. Such an extension describes how to draw
links (called pairs) between elements. The sensitive
argument is to inform if
pairs must be redrawn when the OpenGL engine sends the OpenGLFacetteChanged signal.
|
name of the extension (must be non null) ; |
|
a string to label the method that can be safely translated ; |
|
a brief description of the extension (can be null) ; |
|
a boolean 0 or 1 ; |
|
a initEndOpenGlPairsFunc() method or NULL ;
|
|
a initEndOpenGlPairsFunc() method or NULL ;
|
|
a startEndPairsFunc() method or NULL ;
|
|
a startEndPairsFunc() method or NULL ;
|
|
a pairDefinitionFunc() method (not NULL).
|
Returns : |
the new PairsExtension or null if something wrong happens. |
void visuPairExtensionFree (PairsExtension *extension);
Free all the allocated attributes of the specified method.
|
the extension to delete. |
void visuPairExtensionAdd (PairsExtension *extension);
A method used by user to registered a new extension.
|
an extension. |
GList* visuPairExtensionGet_allMethods ();
Useful to know all PairsExtension.
Returns : |
a list of all the known PairsExtension. This list should be considered read-only. |
PairsExtension* visuPairExtensionGet_current ();
If some process need to know the current PairsExtension. Such extension has
been set with setPairsMethod()
.
Returns : |
the current PairsExtension, NULL if none has been set. |
gboolean visuPairExtensionSet (PairsExtension *extension);
Choose the method used to draw pairs. If necessary, visuPairBuild()
are called.
|
a PairsExtension object. |
Returns : |
TRUE if the OpenGLAskForReDraw signal show be emitted or not. |
gboolean visuPairBuild (VisuData *dataObj);
This methods recreates the OpenGL list of the OpenGLExtension associated
to the pairs.
Thus it is the heart of the pairs drawing. When called, if a
valid PairsExtension has been set with setPairsMethod()
, it takes all the
nodes and compute all the distances between two different nodes. If this distance
is compatible with the distance of drawn pairs for the two elements it calls
the pairDefinitionFunc()
for these two nodes. WARNING! this method is very expensive
in computing cost.
|
the VisuData object to create pairs for. |
Returns : |
TRUE if the OpenGLAskForReDraw signal show be emitted or not. |
void visuPairForeach (foreachPairsFunc whatToDo, gpointer userData);
The way PairsData are stored in V_Sim is private and could changed between version. This method is used to apply some method each pairs.
|
a foreachPairsFunc() method ;
|
|
some user defined data. |
gboolean visuPairGet_status ();
Get the status of pairs, drawn or not.
Returns : |
TRUE if pairs are drawn. |
float visuPairGet_distance (VisuPairData *data, int minOrMax);
A pair between ele1
and ele2
is drawn only if its length is between
a minimum and a maximum value. This method can get these values.
VisuPairDistribution* visuPairGet_distanceDistribution (VisuPair *pair, VisuData *dataObj, float step, float max);
This will compute the distnace distribution of nodes for the given
pair
.
|
a VisuPair ; |
|
a VisuData ; |
|
a float for the distance mesh (negative value to use built-in default) ; |
|
a float for the maximum scanning value (negative value to use built-in default). |
Returns : |
a structure defining the distance distribution. This structure is private and should not be freed. |
gboolean visuPairGet_drawn (VisuPairData *data);
A pair can or cannot be drawn, use this method to retrieve its state.
|
a PairsData object ; |
Returns : |
TRUE if pairs can be drawn. |
VisuPairData* visuPairGet_link (VisuElement *ele1, VisuElement *ele2, float minMax[2]);
A link between two elements is characterized by its boundary distances.
|
a VisuElement object ; |
|
a VisuElement object ; |
|
the two min and max distances. |
Returns : |
the VisuPairData object associated to the given two elements and distances. If none exists it is created. The returned value should not be freed. |
VisuPairData* visuPairGet_linkFromId (VisuElement *ele1, VisuElement *ele2, guint pos);
A link can also be retrieved by its position.
|
a VisuElement object ; |
|
a VisuElement object ; |
|
the position in the list of links. |
Returns : |
the VisuPairData object associated to the given two elements and distances. If none exists NULL is returned. |
GList* visuPairGet_links (VisuElement *ele1, VisuElement *ele2);
There can be one or several links between elements, retrieve them with this routine.
|
a VisuElement object ; |
|
a VisuElement object. |
Returns : |
a list of VisuPairData. The list is owned by V_Sim and should not be freed. |
gpointer visuPairGet_linkProperty (VisuPairData *data, const gchar *key);
Each pair can store some informations that can be retrieve by a string key.
This method is used to retrieve a stored value associated to the key key
.
|
a PairsData object ; |
|
a static string. |
Returns : |
a found value, or NULL if nothing is associated to the key .
If something is returned it should not be freed.
|
VisuPair* visuPairGet_pair (VisuElement *ele1, VisuElement *ele2);
The object VisuPair is used to characterized links between two elements.
|
a VisuElement object ; |
|
a VisuElement object. |
Returns : |
the VisuPair object associated to the given two elements. If none exists it is created. The returned value should not be freed. |
gboolean visuPairGet_printLength (VisuPairData *data);
Get the print length parameter of a pair. This parameter is used to tell if length should be drawn near pairs of this kind.
|
a PairsData object. |
Returns : |
TRUE if length are printed. |
gpointer visuPairGet_property (VisuPair *pair, const gchar *key);
Retrieve the property associated to the key
or NULL if none exist.
|
a VisuPair object ; |
|
a string. |
Returns : |
the associated data. |
gboolean visuPairRead_linkFromTokens (gchar **tokens, int *index, VisuPairData **data, int position, GError **error);
This routine is used to read the resource file. Given tokens
, it
associate a link object by reading the two elements and the two
distances that characterised this link.
|
array of tokens resulting from a call to g_strsplit() with " " as separator ;
|
|
IN, the position of the beginning in tokens ; OUT, one token
after the last read ;
|
|
a pointer to return an allocated link object ; |
|
the number of the line of the config
file which the line argument is taken from ;
|
|
a location to store a possible reading error. |
Returns : |
TRUE if succeed. |
gboolean visuPairRemove_link (VisuElement *ele1, VisuElement *ele2, VisuPairData *data);
Delete the given link.
|
a VisuElement object ; |
|
a VisuElement object ; |
|
a link object. |
Returns : |
TRUE if the link exists and has been successfully removed. |
gboolean visuPairSet_status (gboolean onOff);
Turn on or off the pairs.
|
a boolean 0 or 1. |
Returns : |
TRUE if visuPairBuild() should be called and then the 'OpenGLAskForReDraw'
signal be emitted.
|
void visuPairSet_outOfDate ();
Use this method to change the internal flag that pairs should be rebuilt. It is useful when an extension of pairs has one of its parameters that has changed.
gboolean visuPairSet_color (VisuPairData *data, Color *destColor);
Set the color of the given pair.
|
a PairsData object ; |
|
a Color object. |
Returns : |
TRUE if visuPairBuild() should be called or not.
|
gboolean visuPairSet_distance (VisuPairData *data, float val, int minOrMax);
Set the minimum or the maximum length for the given pair.
|
a floating point value ; |
|
a PairsData object ; |
|
PAIRS_MAX or PAIRS_MIN. |
Returns : |
TRUE if visuPairBuild() should be called or not.
|
gboolean visuPairSet_drawn (VisuPairData *data, gboolean drawn);
A pair can or cannot be drawn, use this method to tune it.
|
a PairsData object ; |
|
a boolean. |
Returns : |
TRUE if visuPairBuild() should be called.
|
gboolean visuPairSet_printLength (VisuPairData *data, gboolean status);
Set the attribute that controls if the length of pairs are drawn near pairs.
|
a PairsData object ; |
|
TRUE to print length near pairs. |
Returns : |
TRUE if visuPairBuild() should be called or not.
|
void visuPairSet_property (VisuPair *pair, const gchar *key, gpointer value, GDestroyNotify freeFunc);
Each element/element can have associated data.
|
a Pairs object ; |
|
a static string ; |
|
a pointer to some allocated data ; |
|
a destroying method (can be NULL). |
void visuPairSet_linkProperty (VisuPairData *data, const gchar *key, gpointer value);
Each pair can store some informations that can be retrieve by a string key.
This method is used to registered a new value associated to the key key
.
|
a PairsData object ; |
|
a static string ; |
|
a pointer to some allocated data. |
int initPairsModule ();
Initialise all the variable of this part. It calls all
the elements in listInitPairsFunc
(that stores the
init function of the pairs extensions). If these elements return
valid PairsExtension, they are registered through a call
to registerPairsExtension()
.
This method is called by the main program at the initialisation stage and
should not be called in others circonstempses.
Returns : |
1 if everything goes allright during the initialisation. |