## visu_pairs

visu_pairs — V_Sim can draw link between nodes. This part defines a pair object and interface to draw pairs.

## Synopsis

    #define     PAIRS_MIN
    #define     PAIRS_MAX
    #define     PAIRS_COLOR_R
    #define     PAIRS_COLOR_G
    #define     PAIRS_COLOR_B
    void        (*foreachPairsFunc)             (PairsData *data,
                                                 gpointer userData);
    struct      pairsData_struct;
    typedef     PairsData;
    int         setPairsOnOff                   (int onOff);
    int         setPairsAll                     (PairsData *data,
                                                 float rgb[3],
                                                 float minMax[2]);
    int         setPairsDistance                (float val,
                                                 PairsData *data,
                                                 int minOrMax);
    int         setPairsDrawn                   (PairsData *data,
                                                 gboolean drawn);
    int         setPairsColor                   (PairsData *data,
                                                 Color *color);
    void        setPairsProperty                (PairsData *data,
                                                 const gchar *key,
                                                 gpointer value);
    int         getPairsOnOff                   ();
    float       getPairsDistance                (VisuElement *ele1,
                                                 VisuElement *ele2,
                                                 int minOrMax);
    PairsData*  getPairsData                    (VisuElement *ele1,
                                                 VisuElement *ele2);
    gboolean    getPairsDrawn                   (PairsData *data);
    gpointer    getPairsProperty                (PairsData *data,
                                                 const gchar *key);
    void        foreachPairsData                (foreachPairsFunc whatToDo,
                                                 gpointer userData);
    int         createPairs                     (VisuData *dataObj);

    void        (*initEndOpenGlPairsFunc)       ();
    void        (*startEndPairsFunc)            (VisuElement *ele1,
                                                 VisuElement *ele2,
                                                 PairsData *data);
    void        (*pairDefinitionFunc)           (VisuElement *ele1,
                                                 VisuElement *ele2,
                                                 PairsData *data,
                                                 OpenGLView *view,
                                                 double x1,
                                                 double y1,
                                                 double z1,
                                                 double x2,
                                                 double y2,
                                                 double z2,
                                                 float d2);
    struct      PairsExtension_struct;
    typedef     PairsExtension;
    PairsExtension* pairsExtension_new          (char *name,
                                                 char *printName,
                                                 char *description,
                                                 int sensitive,
                                                 initEndOpenGlPairsFunc init,
                                                 initEndOpenGlPairsFunc stop,
                                                 startEndPairsFunc start,
                                                 startEndPairsFunc end,
                                                 pairDefinitionFunc draw);
    void        PairsExtension_free             (PairsExtension *extension);
    void        registerPairsExtension          (PairsExtension *extension);
    int         setPairsMethod                  (PairsExtension *extension);
    void        setPairsAreOutOfDate            ();
    PairsExtension* getCurrentPairsMethods      ();
    int         isValidPairsExtension           (PairsExtension *pairsModel);
    GList*      getAllPairsMethods              ();
    char*       getNameOfPairsMethod            (PairsExtension *extension);

    int         initPairsModule                 ();

## Description

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.

## Details

### PAIRS_MIN

    #define PAIRS_MIN 0

Flag used to define the minimum length to draw pair. This is useful with the `getPairsDistance()` and the `getPairsDistance()` methods.

### PAIRS_MAX

    #define PAIRS_MAX 1

Flag used to define the maximum length to draw pair. This is useful with the `getPairsDistance()` and the `getPairsDistance()` methods.

### PAIRS_COLOR_R

    #define PAIRS_COLOR_R 0

Flag used to define the red color of a pair. This is useful to access the rgba array of the Color object return by `setPairsColor()`.

### PAIRS_COLOR_G

    #define PAIRS_COLOR_G 1

Flag used to define the green color of a pair. This is useful to access the rgba array of the Color object return by `setPairsColor()`.

### PAIRS_COLOR_B

    #define PAIRS_COLOR_B 2

Flag used to define the blue color of a pair. This is useful to access the rgba array of the Color object return by `setPairsColor()`.

### foreachPairsFunc ()

    void        (*foreachPairsFunc)             (PairsData *data,
                                                 gpointer userData);

Prototype of functions called with the foreach method apply to each pairs.

`data` : | a PairsData object ;
`userData` : | some user defined data.

### struct pairsData_struct

    struct pairsData_struct {
      char *name1, *name2;
      float minMax[2];
      GHashTable *properties;
      gboolean drawn;
    };

This structure is used to describe a pair between two elements. These elements are described by their name. A pair is drawn only its length is between the minimum and the maximum value stored in the minMax array.

char *`name1`; | the name of the first VisuElement ;
char *`name2`; | the name of the second VisuElement ;
float `minMax`[2]; | storage for the length bounds for drawn pairs ;
GHashTable *`properties`; | a storage for userData ;
gboolean `drawn`; | a boolean to say if the pair is drawn or not.

### PairsData

    typedef struct pairsData_struct PairsData;

A common way to name pairsData_struct objects.

### setPairsOnOff ()

    int         setPairsOnOff                   (int onOff);

Turn on or off the pairs.

`onOff` : | a boolean 0 or 1.
Returns : | 1 if `createPairs()` should be called and then the 'OpenGLAskForReDraw' signal be emitted.

### setPairsAll ()

    int         setPairsAll                     (PairsData *data,
                                                 float rgb[3],
                                                 float minMax[2]);

This method sets length and color informations for the given pairs.

`data` : | a PairsData object ;
`rgb` : | an array of three floating point values ;
`minMax` : | an array of two floating point values.
Returns : | 1 if `createPairs()` should be called and then the 'OpenGLAskForReDraw' signal be emitted.

### setPairsDistance ()

    int         setPairsDistance                (float val,
                                                 PairsData *data,
                                                 int minOrMax);

Set the minimum or the maximum length for the given pair.

`val` : | a floating point value ;
`data` : | a PairsData object ;
`minOrMax` : | PAIRS_MAX or PAIRS_MIN.
Returns : | 1 if `createPairs()` should be called or not.

### setPairsDrawn ()

    int         setPairsDrawn                   (PairsData *data,
                                                 gboolean drawn);

A pair can or cannot be drawn, use this method to tune it.

`data` : | a PairsData object ;
`drawn` : | a boolean.
Returns : | 1 if `createPairs()` should be called.

### setPairsColor ()

    int         setPairsColor                   (PairsData *data,
                                                 Color *color);

Set the color of the given pair.

`data` : | a PairsData object ;
`color` : | a Color object..
Returns : | 1 if `createPairs()` should be called or not.

### setPairsProperty ()

    void        setPairsProperty                (PairsData *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`.

`data` : | a PairsData object ;
`key` : | a static string ;
`value` : | a pointer to some allocated data.

### getPairsOnOff ()

    int         getPairsOnOff                   ();

Get the status of pairs, drawn or not.

Returns : | 1 if pairs are drawn.

### getPairsDistance ()

    float       getPairsDistance                (VisuElement *ele1,
                                                 VisuElement *ele2,
                                                 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.

`ele1` : | a VisuElement object ;
`ele2` : | a VisuElement object ;
`minOrMax` : | PAIRS_MIN or PAIRS_MAX.
Returns : | the minimum or the maximum value for the pair between `ele1` and `ele2`.

### getPairsData ()

    PairsData*  getPairsData                    (VisuElement *ele1,
                                                 VisuElement *ele2);

The object PairsData is used to characterized the link between two elements.

`ele1` : | a VisuElement object ;
`ele2` : | a VisuElement object.
Returns : | the PairsData object associated to the given two elements. If none exists it is created. The returned value should not be freed.

### getPairsDrawn ()

    gboolean    getPairsDrawn                   (PairsData *data);

A pair can or cannot be drawn, use this method to retrieve its state.

`data` : | a PairsData object ;
Returns : | TRUE if pairs can be drawn.

### getPairsProperty ()

    gpointer    getPairsProperty                (PairsData *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`.

`data` : | a PairsData object ;
`key` : | 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.

### foreachPairsData ()

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

`whatToDo` : | a `foreachPairsFunc()` method ;
`userData` : | some user defined data.

### createPairs ()

    int         createPairs                     (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.

`dataObj` : | the VisuData object to create pairs for.
Returns : | 1 if the OpenGLAskForReDraw signal show be emitted or not.

### initEndOpenGlPairsFunc ()

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

### startEndPairsFunc ()

    void        (*startEndPairsFunc)            (VisuElement *ele1,
                                                 VisuElement *ele2,
                                                 PairsData *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.

`ele1` : | a VisuElement object ;
`ele2` : | a VisuElement object ;
`data` : | a PairsData object.

### pairDefinitionFunc ()

    void        (*pairDefinitionFunc)           (VisuElement *ele1,
                                                 VisuElement *ele2,
                                                 PairsData *data,
                                                 OpenGLView *view,
                                                 double x1,
                                                 double y1,
                                                 double z1,
                                                 double x2,
                                                 double y2,
                                                 double z2,
                                                 float d2);

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.

`ele1` : | a VisuElement object ;
`ele2` : | a VisuElement object ;
`data` : | a PairsData object ;
`view` : | a OpenGLView object, giving some constants describing the OpenGL scene ;
`x1` : | a floating point value ;
`y1` : | a floating point value ;
`z1` : | a floating point value ;
`x2` : | a floating point value ;
`y2` : | a floating point value ;
`z2` : | a floating point value ;
`d2` : | a floating point value.

### struct PairsExtension_struct

    struct PairsExtension_struct {
      /* Some variable to describe this OpenGL extension.
         The attribute name is mandatory since it is
         used to identify the method. */
      char* name;
      char* printName;
      char* description;

      int sensitiveToFacette;

      initEndOpenGlPairsFunc initOpenGl;
      initEndOpenGlPairsFunc stopOpenGl;
      startEndPairsFunc beginDrawingPairs;
      startEndPairsFunc endDrawingPairs;
      pairDefinitionFunc drawPairs;
    };

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.

char *`name`; | an internal name ;
char *`printName`; | the UTF-8 name, used for the GUI ;
char *`description`; | an UTF-8 short description of the pairs method.
int `sensitiveToFacette`; | if TRUE, the OpenGL list of the pairs is recompute each time the number of facette changes ;
initEndOpenGlPairsFunc `initOpenGl`; | method called sometime ;
initEndOpenGlPairsFunc `stopOpenGl`; | method called sometime ;
startEndPairsFunc `beginDrawingPairs`; | method called a startup of drawing pairs ;
startEndPairsFunc `endDrawingPairs`; | method called a ending of drawing pairs ;
pairDefinitionFunc `drawPairs`; | the drawing method for each pair.

### PairsExtension

    typedef struct PairsExtension_struct PairsExtension;

Common naming for PairsExtension_struct objects.

### pairsExtension_new ()

    PairsExtension* pairsExtension_new          (char *name,
                                                 char *printName,
                                                 char *description,
                                                 int 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` : | name of the extension (must be non null) ;
`printName` : | a string to label the method that can be safely translated ;
`description` : | a brief description of the extension (can be null) ;
`sensitive` : | a boolean 0 or 1 ;
`init` : | a `initEndOpenGlPairsFunc()` method or NULL ;
`stop` : | a `initEndOpenGlPairsFunc()` method or NULL ;
`start` : | a `startEndPairsFunc()` method or NULL ;
`end` : | a `startEndPairsFunc()` method or NULL ;
`draw` : | a `pairDefinitionFunc()` method (not NULL).
Returns : | the new PairsExtension or null if something wrong happens.

### PairsExtension_free ()

    void        PairsExtension_free             (PairsExtension *extension);

Free all the allocated attributes of the specified method.

`extension` : | the extension to delete.

### registerPairsExtension ()

    void        registerPairsExtension          (PairsExtension *extension);

A method used by user to registered a new extension.

`extension` : | an extension.

### setPairsMethod ()

    int         setPairsMethod                  (PairsExtension *extension);

Choose the method used to draw pairs. If necessary, `createPairs()` are called.

`extension` : | a PairsExtension object.
Returns : | 1 if the OpenGLAskForReDraw signal show be emitted or not.

### setPairsAreOutOfDate ()

    void        setPairsAreOutOfDate            ();

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.

### getCurrentPairsMethods ()

    PairsExtension* getCurrentPairsMethods      ();

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.

### isValidPairsExtension ()

    int         isValidPairsExtension           (PairsExtension *pairsModel);

Test if the given PairsExtension has been already registered by V_Sim.

`pairsModel` : | a PairsExtension object.
Returns : | 1 if the given extension is already stored.

### getAllPairsMethods ()

    GList*      getAllPairsMethods              ();

Useful to know all PairsExtension.

Returns : | a list of all the known PairsExtension. This list should be considered read-only.

### getNameOfPairsMethod ()

    char*       getNameOfPairsMethod            (PairsExtension *extension);

All PairsExtension has a name.

`extension` : | a PairsExtension object.
Returns : | a string that is associated to the given PairsExtension. This string should not be freed.

### initPairsModule ()

    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.