## VisuData

VisuData — Give methods to store and manage data from input file(s).

## Synopsis

    #include <visu_nodes.h>

                        VisuData;
    #define             EXT_VISU_DATA_ID

    void                (*setColorFunc)                     (VisuData *visuData,
                                                             float rgba[4],
                                                             VisuElement *ele,
                                                             VisuNode *node);
    VisuData*           visuDataNew                         ();
    VisuData*           visuDataNew_withOpenGLView          (OpenGLView *view);
    VisuNodeArray*      visuDataGet_nodeArray               (VisuData *data);
    void                visuDataAdd_nodeFromElement         (VisuData *data,
                                                             VisuElement *ele,
                                                             float xyz[3]);
    void                visuDataAdd_nodeFromIndex           (VisuData *data,
                                                             unsigned int position,
                                                             float xyz[3]);
    VisuNode*           visuDataGet_nodeFromNumber          (VisuData *data,
                                                             unsigned int number);
    int                 visuDataGet_objectList              (VisuData *data);
    int                 visuDataSet_population              (VisuData *data,
                                                             unsigned int nbOfTypes,
                                                             unsigned int *nbOfNodesPerVisuElement,
                                                             VisuElement **visuElementUsed);
    void                visuDataFree_population             (VisuData *data);
    GenericRenderingWindow visuDataGet_renderingWindow      (VisuData *data);
    void                visuDataRemove_nodes                (VisuData *data,
                                                             int *nodeNumbers);
    gboolean            visuData_replicate                  (VisuData *data,
                                                             float extension[3],
                                                             gboolean *rebuild);
    gboolean            visuData_restore                    (VisuData *data);

    void                visuDataIter_new                    (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_start                  (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_startNumber            (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_startVisible           (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_restartNode            (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_next                   (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_nextNodeNumber         (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_nextElement            (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_nextNode               (VisuData *data,
                                                             VisuDataIter *iter);
    void                visuDataIter_nextVisible            (VisuData *data,
                                                             VisuDataIter *iter);

    void                visuDataConvert_boxCoordinatestoXYZ (VisuData *data,
                                                             float xyz[3],
                                                             float boxCoord[3]);
    void                visuDataConvert_XYZtoBoxCoordinates (VisuData *data,
                                                             float boxCoord[3],
                                                             float xyz[3]);
    float               visuDataGet_boxGeometry             (VisuData *data,
                                                             int vector);
    void                visuDataSet_boxGeometry             (VisuData *data,
                                                             float geometry[6],
                                                             gboolean periodic);
    gboolean            visuDataGet_periodic                (VisuData *data);
    void                visuDataGet_extension               (VisuData *dataObj,
                                                             float extension[3]);
    gboolean            visuDataGet_translationStatus       (VisuData *data);
    float*              visuDataGet_XYZtranslation          (VisuData *data);
    int                 visuDataSet_XYZtranslation          (VisuData *data,
                                                             float xyz[3]);
    void                visuDataGet_boxMatrix               (VisuData *data,
                                                             float matrix[3][3]);

    gboolean            visuData_constrainedElementInTheBox (VisuData *data,
                                                             VisuElement *element);
    gboolean            visuData_constrainedInTheBox        (VisuData *data);
    gboolean            visuData_constrainedFree            (VisuData *data);
    void                visuDataGet_nodePosition            (VisuData *data,
                                                             VisuNode *node,
                                                             float coord[3]);

    gboolean            visuData_compareElements            (VisuData *data1,
                                                             VisuData *data2);
    void                visuDataSet_changeElementFlag       (VisuData *data,
                                                             gboolean changeElement);
    gboolean            visuDataGet_changeElementFlag       (VisuData *data);
    guint               visuDataAdd_timeout                 (VisuData *data,
                                                             guint time,
                                                             GSourceFunc func,
                                                             gpointer user_data);
    gboolean            visuDataRemove_timeout              (VisuData *data,
                                                             guint timeoutId);

    int                 visuDataGet_nSet                    (VisuData *data);
    int                 visuDataGet_setId                   (VisuData *data);
    void                visuDataSet_nSet                    (VisuData *data,
                                                             int nSet);
    void                visuDataSet_setId                   (VisuData *data,
                                                             int iSet);
    void                visuDataAdd_file                    (VisuData *data,
                                                             gchar *file,
                                                             int kind,
                                                             FileFormat *format);
    gchar*              visuDataGet_file                    (VisuData *data,
                                                             int kind,
                                                             FileFormat **format);
    void                visuDataRemove_allFiles             (VisuData *data);
    void                visuDataSet_fileCommentary          (VisuData *data,
                                                             gchar *commentary,
                                                             gint iSet);
    gchar*              visuDataGet_fileCommentary          (VisuData *data,
                                                             gint iSet);

    void                visuDataSet_ColorFunc               (VisuData *data,
                                                             setColorFunc func);
    GList*              visuDataGet_allObjects              ();
    void                visuData_createNode                 (VisuData *data,
                                                             VisuNode *node);
    void                visuData_createNodeInfos            (VisuData *data);
    void                visuData_createNodes                (VisuData *data,
                                                             VisuElement *ele);
    void                visuData_createAllNodes             (VisuData *data);
    void                visuData_createAllElements          (VisuData *data);

    void                visuDataEmit_askForShowHideNodes    (VisuData *data,
                                                             gboolean *redraw);
    void                visuDataEmit_elementRenderedChange  (VisuData *data,
                                                             VisuElement *element);
    void                visuDataEmit_facettesChanged        (VisuData *data);
    void                visuDataEmit_nodePositionChanged    (VisuData *data);
    void                visuDataEmit_nodeRenderedChange     (VisuData *data);
    void                visuDataEmit_observeMovement        (VisuData *data,
                                                             gboolean start);

    OpenGLView*         visuDataGet_openGLView              (VisuData *data);
    int                 visuDataSet_angleOfView             (VisuData *data,
                                                             float valueTheta,
                                                             float valuePhi,
                                                             float valueOmega,
                                                             int mask);
    int                 visuDataSet_perspectiveOfView       (VisuData *data,
                                                             float value);
    int                 visuDataSet_positionOfView          (VisuData *data,
                                                             float valueX,
                                                             float valueY,
                                                             int mask);
    void                visuDataSet_renderingWindow         (VisuData *data,
                                                             GenericRenderingWindow window);
    int                 visuDataSet_sizeOfView              (VisuData *data,
                                                             guint width,
                                                             guint height);
    int                 visuDataSet_zoomOfView              (VisuData *data,
                                                             float value);

    #define             visuDataSet_property                (data, key, value)
    #define             visuDataSet_propertyWithDestroyFunc (data, key, value, freeFunc)
    #define             visuDataGet_property                (data, key)

## Object Hierarchy

      GObject
       +----VisuData

## Signals

      "BoxSizeChanged"                                 : Run Last / No Recursion / No Hooks
      "ElementRenderedChanged"                         : Run Last / No Recursion / No Hooks
      "NodeAskForShowHide"                             : Run Last / No Recursion / No Hooks
      "NodePopulationDecrease"                         : Run Last / No Recursion / No Hooks
      "NodePopulationIncrease"                         : Run Last / No Recursion / No Hooks
      "NodePositionChanged"                            : Run Last / No Recursion / No Hooks
      "NodeRenderedChanged"                            : Run Last / No Recursion / No Hooks
      "OpenGLFacetteChanged"                           : Run Last / No Recursion / No Hooks
      "OpenGLGross"                                    : Run Last / No Recursion / No Hooks
      "OpenGLNearFar"                                  : Run Last / No Recursion / No Hooks
      "OpenGLObserveMovement"                          : Run Last / No Recursion / No Hooks
      "OpenGLPersp"                                    : Run Last / No Recursion / No Hooks
      "OpenGLThetaPhiOmega"                            : Run Last / No Recursion / No Hooks
      "OpenGLWidthHeight"                              : Run Last / No Recursion / No Hooks
      "OpenGLXsYs"                                     : Run Last / No Recursion / No Hooks
      "objectFreed"                                    : Run Last / No Recursion / No Hooks

## Description

The main goal of V_Sim is to draw lists of elements. For example, when used to render atoms, a box that contains 24 silicon atoms and 46 germanium atoms is a box with two elements (silicon and germanium) where the silicon element has 24 nodes and the germanium element has 46 nodes. This module gives then methods to create nodes (see VisuElement to create and managed elements).

A node is characterised by its position in the space and its orientation. When rendered, a specific translation can be applied. It has also one number that is its position in the read input file and one boolean to control if it is rendered on screen. One can associate whatever properties using `visuDataSet_nodeProperty()`. These properties can be retrieved with `visuDataGet_nodeProperty()`. But before using these methods, the needed space must be allocated using `visuDataAdd_nodeProperty()`. The stored properties must be pointers on something.

All nodes are stored in a structure called VisuData. V_Sim uses one VisuData per input file(s). A pointer `currentVisuData` points to the current rendered VisuData. This structure contains a list of pointers on all the VisuElement used in this file. It also contains the list of all VisuNodes of this file (or these files).

## Details

### VisuData

    typedef struct _VisuData VisuData;

This structure describes a VisuData object.

### EXT_VISU_DATA_ID

    #define EXT_VISU_DATA_ID "AllElements"

The id used to identify this extension, see `OpenGLExtensionRebuild_list()` for instance.

### setColorFunc ()

    void                (*setColorFunc)                     (VisuData *visuData,
                                                             float rgba[4],
                                                             VisuElement *ele,
                                                             VisuNode *node);

This prototype is used to specify an optional method to associate a color with external values to each node.

`visuData` : | a pointer to the calling object ;
`rgba` : | an 4 allocated float area to store the return values.
`ele` : | a VisuElement ;
`node` : | a VisuNode ;

### visuDataNew ()

    VisuData*           visuDataNew                         ();

This creates an empty VisuData object.

Returns : | a newly created VisuData object (its ref count is set to 1).

### visuDataNew_withOpenGLView ()

    VisuData*           visuDataNew_withOpenGLView          (OpenGLView *view);

This creates an empty VisuData object with values for its veiw taken from the given `view` argument (the argument is indeed copied).

`view` : | an OpenGLView object.
Returns : | a newly created VisuData object (its ref count is set to 1).

### visuDataGet_nodeArray ()

    VisuNodeArray*      visuDataGet_nodeArray               (VisuData *data);

This method retrieve the VisuNodeArray associated to the given `data`.

`data` : | a VisuData object.
Returns : | the associated VisuNodeArray.

### visuDataAdd_nodeFromElement ()

    void                visuDataAdd_nodeFromElement         (VisuData *data,
                                                             VisuElement *ele,
                                                             float xyz[3]);

This method adds a new VisuNode to the specified VisuData.

`data` : | the VisuData where to add the new VisuNode ;
`ele` : | the VisuElement kind of the new VisuNode ;
`xyz` : | its coordinates.

### visuDataAdd_nodeFromIndex ()

    void                visuDataAdd_nodeFromIndex           (VisuData *data,
                                                             unsigned int position,
                                                             float xyz[3]);

This method adds a new VisuNode to the specified VisuData. Position must be chosen between 0 and (ntype - 1) and corresponds to the position of the array of VisuNodes of a VisuElement.

`data` : | the VisuData where to add the new VisuNode ;
`position` : | a integer corresponding to the position of a VisuElement in the array **nodes in the structure;
`xyz` : | its coordinates.

### visuDataGet_nodeFromNumber ()

    VisuNode*           visuDataGet_nodeFromNumber          (VisuData *data,
                                                             unsigned int number);

This methods retrieves the VisuNode identified by the integer `number`. The number must be strictly positive. No eror is raised if no node corresponds to the given number.

`data` : | a `VisuData` structure which stores the nodes.
`number` : | an integer.
Returns : | the found VisuNode or NULL if none corresponds to number.

### visuDataGet_objectList ()

    int                 visuDataGet_objectList              (VisuData *data);

All the drawned nodes are stored in an OpenGL list. The identifier of this list can be access with the present method.

`data` : | a valid VisuObject ;
Returns : | an integer that identifies the OpenGL list of all drawn nodes.

### visuDataSet_population ()

    int                 visuDataSet_population              (VisuData *data,
                                                             unsigned int nbOfTypes,
                                                             unsigned int *nbOfNodesPerVisuElement,
                                                             VisuElement **visuElementUsed);

This method allocates the storing part of the given VisuData structure and store all the VisuNodes.

`data` : | a VisuData object ;
`nbOfTypes` : | number of VisuElement ;
`nbOfNodesPerVisuElement` : | number of VisuNode per VisuElement ;
`visuElementUsed` : | pointers to VisuElement in the same order that `nbOfNodesPerVisuElement`.
Returns : | 1 if everything goes right.

### visuDataFree_population ()

    void                visuDataFree_population             (VisuData *data);

This method frees only the allocated memory that deals with the nodes (i.e. everything except the data of the files, the properties and the setColor method.

`data` : | a VisuData to be freed.

### visuDataGet_renderingWindow ()

    GenericRenderingWindow visuDataGet_renderingWindow      (VisuData *data);

The VisuData objects can be rendered into a window. They are attached to one using `visuRenderingWindowSet_visuData()` method. The actual method is then used to retrieve the window the argument `data` is attached to.

`data` : | a VisuData object.
Returns : | the window the `data` argument is attached to, or NULL if the object has not yet been attached or if the rendering is done off-screen.

### visuDataRemove_nodes ()

    void                visuDataRemove_nodes                (VisuData *data,
                                                             int *nodeNumbers);

Delete some nodes using this method. The nodes are identified by their number and have not to be of the same element. This routine raises the "NodePopulationDecrease" signal. The `nodeNumbers` argument must be terminated with a negative value.

`data` : | a VisuData object ;
`nodeNumbers` : | an allocated int array with number identifying nodes.

### visuData_replicate ()

    gboolean            visuData_replicate                  (VisuData *data,
                                                             float extension[3],
                                                             gboolean *rebuild);

This routine will create (or remove) nodes to expand the initial box to the required size. An extension of 0 means no extension, i.e. the initial box. The extension is done symmetrically in each direction toward negative and positive direction.

If the `rebuild` argument is TRUE, the nodes should be rebuilt (with `visuData_createAllNodes()`).

To remove added nodes, see `visuData_restore()`.

`data` : | a VisuData object ;
`extension` : | three floating point values ;
`rebuild` : | a location to store a flag.
Returns : | TRUE if the redraw should be done.

### visuData_restore ()

    gboolean            visuData_restore                    (VisuData *data);

Remove all nodes that have been added by a `visuData_replicate()` call.

`data` : | a VisuData object.
Returns : | TRUE if some nodes has been indeed removed.

### visuDataIter_new ()

    void                visuDataIter_new                    (VisuData *data,
                                                             VisuDataIter *iter);

Set values to a VisuDataIter object to iterate over nodes. Its contain is initialised with the data size (number of elements, number of nodes per element...).

`data` : | a VisuData object ;
`iter` : | an alocated iterator.

### visuDataIter_start ()

    void                visuDataIter_start                  (VisuData *data,
                                                             VisuDataIter *iter);

Initialise the node and element internal pointers for a run over the nodes.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_startNumber ()

    void                visuDataIter_startNumber            (VisuData *data,
                                                             VisuDataIter *iter);

Initialise the node and element internal pointers for a run following the node oder.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_startVisible ()

    void                visuDataIter_startVisible           (VisuData *data,
                                                             VisuDataIter *iter);

Initialise the node and element internal pointers for a run over the visible nodes (see visuDataIter_nextVisible).

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_restartNode ()

    void                visuDataIter_restartNode            (VisuData *data,
                                                             VisuDataIter *iter);

The element internal pointer must be associated. Then, it returns the node pointer to the first node for this element.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_next ()

    void                visuDataIter_next                   (VisuData *data,
                                                             VisuDataIter *iter);

Modify node and element internal pointers to the next node, or NULL if none remains.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_nextNodeNumber ()

    void                visuDataIter_nextNodeNumber         (VisuData *data,
                                                             VisuDataIter *iter);

Modify node internal pointer to the next node, increasing the id of the current node. The element internal pointer is also updated accordingly. If no more nodes exist after the given one, node and element internal pointers are set to NULL.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_nextElement ()

    void                visuDataIter_nextElement            (VisuData *data,
                                                             VisuDataIter *iter);

Modify element internal pointer to the next element and set node to the first one, or NULL if none remains.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_nextNode ()

    void                visuDataIter_nextNode               (VisuData *data,
                                                             VisuDataIter *iter);

Modify node internal pointer to the next node, or NULL if none remains. Contrary to `visuDataIter_next()` it does not go to the next element if one exists.

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataIter_nextVisible ()

    void                visuDataIter_nextVisible            (VisuData *data,
                                                             VisuDataIter *iter);

Go to the next rendered node (changing element if required).

`data` : | a VisuData object ;
`iter` : | a VisuDataIter object.

### visuDataConvert_boxCoordinatestoXYZ ()

    void                visuDataConvert_boxCoordinatestoXYZ (VisuData *data,
                                                             float xyz[3],
                                                             float boxCoord[3]);

Use this method to transform box coordinates into cartesian.

`data` : | a VisuData object ;
`xyz` : | an array of floating point values to store the result ;
`boxCoord` : | an array of floating point values that describes the box coordinates.

### visuDataConvert_XYZtoBoxCoordinates ()

    void                visuDataConvert_XYZtoBoxCoordinates (VisuData *data,
                                                             float boxCoord[3],
                                                             float xyz[3]);

Use this method to transform cartesian coordinates to the box coordinates.

`data` : | a VisuData object ;
`boxCoord` : | an array of floating point values to store the result ;
`xyz` : | an array of floating point values describing coordinates in cartesian.

### visuDataGet_boxGeometry ()

    float               visuDataGet_boxGeometry             (VisuData *data,
                                                             int vector);

Retrieve the value of a vector defining the bounding box. The vector is chosen with an int, see the visuData_boxVector enum for more details.

`data` : | a VisuData object ;
`vector` : | an int corresponding to a vector of the box.
Returns : | the value of the required vector (always a positive value), a negative value if something goes wrong.

### visuDataSet_boxGeometry ()

    void                visuDataSet_boxGeometry             (VisuData *data,
                                                             float geometry[6],
                                                             gboolean periodic);

This methods set the size of the box that defines the viewport. If the `periodic` argument is TRUE, the box is also the limit of a periodic system.

`data` : | a VisuData object ;
`geometry` : | a 6 floating point array ;
`periodic` : | a boolean.

### visuDataGet_periodic ()

    gboolean            visuDataGet_periodic                (VisuData *data);

The bounding box can be just useful to set the OpenGl viewport, or it can define a limit for periodic conditions.

`data` : | a VisuData object.
Returns : | if the box is a periodic limit or not.

### visuDataGet_extension ()

    void                visuDataGet_extension               (VisuData *dataObj,
                                                             float extension[3]);

Using `visuData_replicate()`, it is possible to duplicate the primitive box in each directions. Use this method to know the current extension. Returned values are positive floating point values. An extension of 0. means that only the primitive box exists, while a value of one means a duplication of one box in each direction of the coordinate.

`dataObj` : | a VisuData object ;
`extension` : | an allocated array to store the values.

### visuDataGet_translationStatus ()

    gboolean            visuDataGet_translationStatus       (VisuData *data);

When a translation is applied (even with a [0,0,0] vector), the nodes are shifted to be in the box. This routine returns the translation status of all nodes. If one of them is translated, then return value is TRUE.

`data` : | a VisuData object.
Returns : | if one of the nodes is shifted.

### visuDataGet_XYZtranslation ()

    float*              visuDataGet_XYZtranslation          (VisuData *data);

The nodes are rendered at thier coordinates plus a translation. This method allows to retrieve that translation.

`data` : | a VisuData object.
Returns : | a newly allocated array of 3 floats. It should be freed with a call to `free()` after use.

### visuDataSet_XYZtranslation ()

    int                 visuDataSet_XYZtranslation          (VisuData *data,
                                                             float xyz[3]);

This set the translations of the specified VisuData whatever previous values. The translation is done in the orthonormal referential, not the referential of the box.

`data` : | a VisuData object ;
`xyz` : | an array of floating point values.
Returns : | if returns 1, `visuData_createAllNodes()` should be called and the 'NodePositionChanged' should be emitted.

### visuDataGet_boxMatrix ()

    void                visuDataGet_boxMatrix               (VisuData *data,
                                                             float matrix[3][3]);

This method is used when the box matrix is required. This matrix can transform a vector given in box coordinates into a cartesian vector. If a simple vector multication is required, then the use of `visuDataConvert_boxCoordinatestoXYZ()` should be prefered.

`data` : | a VisuData object ;
`matrix` : | an area to store the matrix.

### visuData_constrainedElementInTheBox ()

    gboolean            visuData_constrainedElementInTheBox (VisuData *data,
                                                             VisuElement *element);

Check all the nodes of the specified `element` and change their coordinates if they are out of the bounding box. The position of each node is the result of the sum of their own position and of the box translation.

`data` : | a VisuData object ;
`element` : | a VisuElement object.
Returns : | TRUE if `visuData_createAllNodes()` should be called and the 'NodePositionChanged' should be emitted.

### visuData_constrainedInTheBox ()

    gboolean            visuData_constrainedInTheBox        (VisuData *data);

It does the same things that `visuData_constrainedElementInTheBox()` but for all the VisuElement of the given `data`. I.e. it checks all the nodes and changes their coordinates if they are out of the bounding box. The position of each node is the result of the sum of their own position and of the box translation.

`data` : | a VisuData object.
Returns : | TRUE if `visuData_createAllNodes()` should be called and the 'NodePositionChanged' should be emitted.

### visuData_constrainedFree ()

    gboolean            visuData_constrainedFree            (VisuData *data);

Return all the nodes to their original position, except for the global translation.

`data` : | a VisuData object.
Returns : | TRUE if `visuData_createAllNodes()` should be called and the 'NodePositionChanged' should be emitted.

### visuDataGet_nodePosition ()

    void                visuDataGet_nodePosition            (VisuData *data,
                                                             VisuNode *node,
                                                             float coord[3]);

Position of nodes are subject to various translations and different transformations. Their coordinates should not be access directly through node.[xyz]. This method is used to retrieve the given node position.

`data` : | a VisuData object ;
`node` : | a VisuNode object ;
`coord` : | an array of 3 floating point values to store the position.

### visuData_compareElements ()

    gboolean            visuData_compareElements            (VisuData *data1,
                                                             VisuData *data2);

This method is used to compare the composition of the given two VisuData objects. The test is only done on VisuElement lists.

`data1` : | a VisuData object ;
`data2` : | an other VisuData object.
Returns : | TRUE if the two objects contains exactly the same VisuElemet objects (not one more or one less or one different), FALSE otherwise.

### visuDataSet_changeElementFlag ()

    void                visuDataSet_changeElementFlag       (VisuData *data,
                                                             gboolean changeElement);

This method is mainly used by internal gears to set a flag. This flag control if the `data` object has the same VisuElement objects than the previously rendered one.

`data` : | a VisuData object ;
`changeElement` : | a boolean.

### visuDataGet_changeElementFlag ()

    gboolean            visuDataGet_changeElementFlag       (VisuData *data);

V_Sim can use a flag set on `data` object to know if `data` has exactly the same VisuElement list than the previously rendered one.

`data` : | a VisuData object.
Returns : | TRUE if the previously rendered VisuData object has had the same VisuElement list than the given one, FALSE otherwise.

### visuDataAdd_timeout ()

    guint               visuDataAdd_timeout                 (VisuData *data,
                                                             guint time,
                                                             GSourceFunc func,
                                                             gpointer user_data);

This method is used to add the `func` method to be called regularly at the period `time`. This methos calls in fact `g_timeout_add()` with the given arguments. But the source id is stored internaly and the timeout function is removed automatically when the object `data` is destroyed. It is convienient to add a method working on the VisuData object that is called periodically during the life of te object.

`data` : | a valid VisuData object ;
`time` : | the period of call in milliseconds ;
`func` : | the callback function to be called ;
`user_data` : | a pointer to some user defined informations.
Returns : | the source id if the calling method need to work with it. To remove the callback, don't use `g_source_remove()` but `visuDataRemove_timeout()` to inform the VisuData object that this source has been removed and not to remove it when the object will be destroyed.

### visuDataRemove_timeout ()

    gboolean            visuDataRemove_timeout              (VisuData *data,
                                                             guint timeoutId);

This method is used to remove a timeout that has been associated to the given `data` (see `visuDataAdd_timeout()`).

`data` : | a valid VisuData object ;
`timeoutId` : | a source id.
Returns : | TRUE if the source has been found and removed.

### visuDataGet_nSet ()

    int                 visuDataGet_nSet                    (VisuData *data);

Retrieve the number of available sets of nodes for this VisuData, see `visuDataSet_nSet()`.

`data` : | a VisuData object.
Returns : | the number of set of nodes (1 is default).

### visuDataGet_setId ()

    int                 visuDataGet_setId                   (VisuData *data);

Retrieve the id of the current set of data (ordered as in C, beginning at 0).

`data` : | a VisuData object.
Returns : | the id of the set of nodes currently loaded, -1 if none.

### visuDataSet_nSet ()

    void                visuDataSet_nSet                    (VisuData *data,
                                                             int nSet);

Change the number of available sets of nodes for this VisuData. This has a side effect to delete all previously saved file commentaries (see `visuDataSet_fileCommentary()`).

`data` : | a VisuData object ;
`nSet` : | an integer.

### visuDataSet_setId ()

    void                visuDataSet_setId                   (VisuData *data,
                                                             int iSet);

Change the current id of the set of data (ordered as in C, beginning at 0).

`data` : | a VisuData object ;
`iSet` : | an integer.

### visuDataAdd_file ()

    void                visuDataAdd_file                    (VisuData *data,
                                                             gchar *file,
                                                             int kind,
                                                             FileFormat *format);

This method is used to add files of type `kind` to the `data`. The `file` attribute is copied. The `format` argument can be null.

`data` : | a VisuData object ;
`file` : | a string that points to a file ;
`kind` : | an integer to qualify the file to add ;
`format` : | a file format.

### visuDataGet_file ()

    gchar*              visuDataGet_file                    (VisuData *data,
                                                             int kind,
                                                             FileFormat **format);

This prototype is used to retrieve stored files identify by their `kind`.

`data` : | a VisuData object.
`kind` : | an integer to qualify the required file ;
`format` : | a location for a file format (can be NULL).
Returns : | the name of a file (it should not be deleted).

### visuDataRemove_allFiles ()

    void                visuDataRemove_allFiles             (VisuData *data);

This method is used to empty the list of known file from the given `data`.

`data` : | a VisuData object.

### visuDataSet_fileCommentary ()

    void                visuDataSet_fileCommentary          (VisuData *data,
                                                             gchar *commentary,
                                                             gint iSet);

This method is used to store a description of the given `data`. This string is copied and `commentary` can be freed. Before using this method, the number of possible node sets must have been defined using `visuDataSet_nSet()`, if not, only iSet == 0 is allowed.

`data` : | a VisuData object ;
`commentary` : | the message to be stored (null terminated) ;
`iSet` : | an integer.

### visuDataGet_fileCommentary ()

    gchar*              visuDataGet_fileCommentary          (VisuData *data,
                                                             gint iSet);

Get the commentary associated to the given `data`, for the given node set.

`data` : | a VisuData object ;
`iSet` : | an integer (>= 0).
Returns : | a string description (possibly empty). This string is own by V_Sim and should not be freed.

### visuDataSet_ColorFunc ()

    void                visuDataSet_ColorFunc               (VisuData *data,
                                                             setColorFunc func);

This is a little trick to colorized the nodes. It should not be used since it will probably be different in future release.

`data` : | a VisuData object ;
`func` : | a method that colorize the nodes.

### visuDataGet_allObjects ()

    GList*              visuDataGet_allObjects              ();

This methods is used to retrieve all VisuObject currently allocated in V_Sim. It is usefull to apply some changes on all objects (resources for example).

Returns : | a list of V_Sim own VisuData objects.

### visuData_createNode ()

    void                visuData_createNode                 (VisuData *data,
                                                             VisuNode *node);

This method call the createNode method of the current rendering method for the given node. It also calls the list of the material associated to the given node.

`data` : | a VisuData object ;
`node` : | a VisuNode object.

### visuData_createNodeInfos ()

    void                visuData_createNodeInfos            (VisuData *data);

This create is list with labels positions on nodes with some informations. These informations are taken from the DataNode stored in the property "dataNode". If this property is 1, then the number of nodes are printed, if the value is 2, the name of the element is used, instead the value is a pointer to a DataNode object and its method is used to get the label.

`data` : | a VisuData object.

### visuData_createNodes ()

    void                visuData_createNodes                (VisuData *data,
                                                             VisuElement *ele);

This create the glObjectList registered at (`identifierAllNodes` + the position of the `ele` in the `data` object + 1) that contains all the nodes of the given VisuElement.

`data` : | a VisuData object ;
`ele` : | a VisuElement object.

### visuData_createAllNodes ()

    void                visuData_createAllNodes             (VisuData *data);

This create the glObjectList registered at `identifierAllNodes` that contains all the nodes. This glObjectList is made of all nodes of all element that has a flag `rendered` at true translated to their own positions.

This method doesn't ask for redraw and signal `OpenGLAskForReDraw` should be emitted manually.

`data` : | a VisuData object.

### visuData_createAllElements ()

    void                visuData_createAllElements          (VisuData *data);

This method will call the `createOpenGLElementFunc()` method of the current RenderingMethod on all the nodes of the given VisuData.

`data` : | a VisuData object.

### visuDataEmit_askForShowHideNodes ()

    void                visuDataEmit_askForShowHideNodes    (VisuData *data,
                                                             gboolean *redraw);

This methods is used to emit the 'NodeAskForShowHide' signal. This signal asks all modules that may hide nodes to recompute their hiding scheme and put in `redraw` if they have changed something. Since all listeners write in `redraw`, they should modify it with an union. `redraw` is initialised at FALSE before the signal is emitted.

`data` : | a valid VisuData object ;
`redraw` : | a pointer to a location to store if redraw is needed after all listeners have modified the nodes of the given `data`.

### visuDataEmit_elementRenderedChange ()

    void                visuDataEmit_elementRenderedChange  (VisuData *data,
                                                             VisuElement *element);

This method is used to emit the 'ElementRenderedChanged' signal. This signal asks all modules that are dependent of the given `element` visibility to recompute their OpenGL lists.

`data` : | a valid VisuData object ;
`element` : | a valid VisuElement object.

### visuDataEmit_facettesChanged ()

    void                visuDataEmit_facettesChanged        (VisuData *data);

Emit the 'OpenGLFacetteChanged' signal.

`data` : | a valid VisuData object.

### visuDataEmit_nodePositionChanged ()

    void                visuDataEmit_nodePositionChanged    (VisuData *data);

This method is used to emit the 'NodePositionChanged' signal. This signal asks all modules that are dependent of the nodes' positions to recompute their OpenGL lists.

`data` : | a valid VisuData object.

### visuDataEmit_nodeRenderedChange ()

    void                visuDataEmit_nodeRenderedChange     (VisuData *data);

This method is used to emit the 'NodeRenderedChanged' signal. This signal asks all modules that are dependent of the nodes' visibility to recompute their OpenGL lists. This signal is usualy emitted after a call to `visuDataEmit_askForShowHideNodes()`.

`data` : | a valid VisuData object.

### visuDataEmit_observeMovement ()

    void                visuDataEmit_observeMovement        (VisuData *data,
                                                             gboolean start);

This method is used to emit the 'OpenGLObserveMovement' signal. This signal signify that an observe movement has been initiated or has just finished.

`data` : | a valid VisuData object ;
`start` : | TRUE to signify a starting movement, FALSE for an ending one.

### visuDataGet_openGLView ()

    OpenGLView*         visuDataGet_openGLView              (VisuData *data);

Once the object `data` has been initialised, an OpenGLView object is automattically attached and this method can be used to retrieve it.

`data` : | a VisuData object.
Returns : | the OpenGLView attached to the given `data`.

### visuDataSet_angleOfView ()

    int                 visuDataSet_angleOfView             (VisuData *data,
                                                             float valueTheta,
                                                             float valuePhi,
                                                             float valueOmega,
                                                             int mask);

This method is used to change the camera orientation for the given `data`. If necessary, this method will emit the 'OpenGLThetaPhiOmega' signal.

`data` : | a VisuData object ;
`valueTheta` : | a floatinf point value in degrees ;
`valuePhi` : | a floating point value in degrees ;
`valueOmega` : | a floating point value in degrees ;
`mask` : | to specified what values will be changed.
Returns : | 1 if the 'OpenGLAskForReDraw' signal should be emitted.

### visuDataSet_perspectiveOfView ()

    int                 visuDataSet_perspectiveOfView       (VisuData *data,
                                                             float value);

This method is used to change the camera perspective for the given `data`. If necessary, this method will emit the 'OpenGLPersp' signal and the 'OpenGLFacetteChanged' signal.

`data` : | a VisuData object ;
`value` : | a positive floating point value (> 1.1).
Returns : | 1 if the 'OpenGLAskForReDraw' signal should be emitted.

### visuDataSet_positionOfView ()

    int                 visuDataSet_positionOfView          (VisuData *data,
                                                             float valueX,
                                                             float valueY,
                                                             int mask);

This method is used to change the camera position for the given `data`. If necessary, this method will emit the 'OpenGLXsYs' signal.

`data` : | a VisuData object ;
`valueX` : | a floatinf point value in the bounding box scale (1 is the size of the bounding box) ;
`valueY` : | a floating point value in bounding box scale ;
`mask` : | to specified what values will be changed.
Returns : | 1 if the 'OpenGLAskForReDraw' signal should be emitted.

### visuDataSet_renderingWindow ()

    void                visuDataSet_renderingWindow         (VisuData *data,
                                                             GenericRenderingWindow window);

This method is used to tell the `data` object which window is used to render it. Normally, one has not to use this method, using `visuRenderingWindowSet_visuData()` calls it already.

`data` : | a VisuData object ;
`window` : | a pointer to a rendering window (can be NULL).

### visuDataSet_sizeOfView ()

    int                 visuDataSet_sizeOfView              (VisuData *data,
                                                             guint width,
                                                             guint height);

It changes the size of the OpenGl area and reccompute the OpenGL viewport. Warning : it doesn't change the size of the window.

`data` : | a valid VisuData object ;
`width` : | the new horizontal size ;
`height` : | the new vertical size.
Returns : | 1 if the 'OpenGLAskForReDraw' signal should be emitted.

### visuDataSet_zoomOfView ()

    int                 visuDataSet_zoomOfView              (VisuData *data,
                                                             float value);

This method is used to change the camera zoom for the given `data`. If necessary, this method will emit the 'OpenGLGross' signal and the 'OpenGLFacetteChanged' signal.

`data` : | a VisuData object ;
`value` : | a positive floating point value.
Returns : | 1 if the 'OpenGLAskForReDraw' signal should be emitted.

### visuDataSet_property()

    #define             visuDataSet_property(data, key, value)

### Warning

`visuDataSet_property` is deprecated and should not be used in newly-written code. use directly `g_object_set_data()` instead.

This method is used to store some values associated with the given `data`. These values are anything but will not be freed when the property is changed or removed. These values are described by the `key`, and can be retrieved with the `visuDataGet_property()` method.

`data` : | a VisuData object ;
`key` : | a string ;
`value` : | an allocated area to store data.

### visuDataSet_propertyWithDestroyFunc()

    #define             visuDataSet_propertyWithDestroyFunc(data, key, value, freeFunc)

### Warning

`visuDataSet_propertyWithDestroyFunc` is deprecated and should not be used in newly-written code. use directly `g_object_set_data_full()` instead.

Same method as `visuDataSet_property()` but giving a free method when the data is removed (like `g_free()`).

`data` : | a VisuData object ;
`key` : | a string ;
`value` : | an allocated area to store data ;
`freeFunc` : | a method to free each token.

### visuDataGet_property()

    #define             visuDataGet_property(data, key)

### Warning

`visuDataGet_property` is deprecated and should not be used in newly-written code. use directly `g_object_get_data()` instead.

This method is used to retrieve some data associated to the specified `data`. These return data should not be freed after used.

`data` : | a VisuData object ;
`key` : | a string.

## Signal Details

### The `"BoxSizeChanged"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the box size is changed (because of box duplication for instance).

`dataObj` : | the object which received the signal ;
`user_data` : | user data set when the signal handler was connected.

Since 3.4

### The `"ElementRenderedChanged"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  element,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when one of the rendered VisuElement is made visible or hidden.

`dataObj` : | the object which received the signal ;
`element` : | the VisuElement which has changed.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"NodeAskForShowHide"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  redraw,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when external modules should recompute their masking effect on nodes. Location pointed by `redraw` must be set to TRUE if the visibility of at least one node is changed.

`dataObj` : | the object which received the signal ;
`redraw` : | a location on a boolean.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"NodePopulationDecrease"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  ids,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the number of nodes has changed, decreasing. `ids` contains all removed ids and is -1 terminated. When emitted, nodes have already been removed, so no external routines should keep pointers on these nodes.

`dataObj` : | the object which received the signal ;
`ids` : | an array of VisuNode ids.
`user_data` : | user data set when the signal handler was connected.

Since 3.4

### The `"NodePopulationIncrease"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  ids,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the number of nodes has changed, increasing. `ids` contains all new ids and is -1 terminated.

`dataObj` : | the object which received the signal ;
`ids` : | an array of VisuNode ids.
`user_data` : | user data set when the signal handler was connected.

Since 3.4

### The `"NodePositionChanged"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when one or more nodes have moved, because of translations or because the user has moved them manually.

`dataObj` : | the object which received the signal ;
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"NodeRenderedChanged"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when one or more nodes have changed of visibility. Some may have appeared, some may have disappeared.

`dataObj` : | the object which received the signal ;
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLFacetteChanged"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when precision of the drawn object has been changed.

`dataObj` : | the object which received the signal ;
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLGross"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  view,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the camera zoom factor has been changed.

`dataObj` : | the object which received the signal ;
`view` : | the new OpenGLView.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLNearFar"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  view,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the viewing field has been changed.

`dataObj` : | the object which received the signal ;
`view` : | the new OpenGLView.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLObserveMovement"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gboolean  start,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the user begins or ends an observe movement on the VisuData.

`dataObj` : | the object which received the signal ;
`start` : | a boolean.
`user_data` : | user data set when the signal handler was connected.

Since 3.3

### The `"OpenGLPersp"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  view,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the camera perspective factor has been changed.

`dataObj` : | the object which received the signal ;
`view` : | the new OpenGLView.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLThetaPhiOmega"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  view,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the camera angles have been changed.

`dataObj` : | the object which received the signal ;
`view` : | the new OpenGLView.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLWidthHeight"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  view,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the viewing frame has been changed.

`dataObj` : | the object which received the signal ;
`view` : | the new OpenGLView.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"OpenGLXsYs"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  view,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the camera position has been changed.

`dataObj` : | the object which received the signal ;
`view` : | the new OpenGLView.
`user_data` : | user data set when the signal handler was connected.

Since 3.2

### The `"objectFreed"` signal

    void                user_function                      (VisuData *dataObj,
                                                            gpointer  user_data)      : Run Last / No Recursion / No Hooks

Gets emitted when the object is been destroyed. All external objects having a reference on this VisuData should clean it.

`dataObj` : | the object which received the signal ;
`user_data` : | user data set when the signal handler was connected.

Since 3.3