## visu_nodes visu_nodes — Defines the elementary structure to store informations about an element in a box. |

## Synopsis

                        VisuNode;
                        VisuNodeProperty;
                        VisuNodeArray;
    void                visu_node_newValues                 (VisuNode *node,
                                                             float xyz[3]);
    void                visu_node_copy                      (VisuNode *nodeTo,
                                                             VisuNode *nodeFrom);
    int                 visu_node_setVisibility             (VisuNode *node,
                                                             gboolean visibility);
    gboolean            visu_node_getVisibility             (VisuNode *node);
    VisuNodeArray*      visu_node_array_newNodes            (unsigned int nTypes,
                                                             unsigned int *nNodes);
    void                visu_node_array_removeNodes         (VisuNodeArray *nodeArray,
                                                             int *nodeNumbers);
    gboolean            visu_node_array_removeAllDuplicateNodes
                                                            (VisuNodeArray *nodeArray,
                                                             int **nodeNumbers);
    gint                visu_node_array_getOriginal         (VisuNodeArray *nodeArray,
                                                             guint nodeId);
    gboolean            visu_node_array_setOriginal         (VisuNodeArray *nodeArray,
                                                             guint nodeId);
    void                visu_node_array_freeNodes           (VisuNodeArray *nodeArray);
    void                visu_node_array_allocateNewNodes    (VisuNodeArray *nodeArray,
                                                             unsigned int iEle,
                                                             unsigned int step);
    VisuNode*           visu_node_array_getNewNode          (VisuNodeArray *nodeArray,
                                                             unsigned int iEle);
    gboolean            visu_node_array_switchNumber        (VisuNodeArray *nodeArray,
                                                             guint from,
                                                             guint to);
    VisuNode*           visu_node_array_getCopyNode         (VisuNodeArray *nodeArray,
                                                             VisuNode *node);
    void                visu_node_array_traceProperty       (VisuNodeArray *array,
                                                             const gchar *id);
    VisuNodeProperty*   visu_node_property_newPointer       (VisuNodeArray *nodeArray,
                                                             const char *key,
                                                             GFunc freeFunc,
                                                             GCopyFunc newAndCopyFunc,
                                                             gpointer user_data);
    VisuNodeProperty*   visu_node_property_newInteger       (VisuNodeArray *nodeArray,
                                                             const char *key);
    void                visu_node_array_freeProperty        (VisuNodeArray *nodeArray,
                                                             const char *key);
    VisuNodeProperty*   visu_node_array_getProperty         (VisuNodeArray *nodeArray,
                                                             const char *key);
    #define             visu_node_setpropertyValue          (nodeArray,
                                                             node,
                                                             key,
                                                             value)
    void                visu_node_property_setValue         (VisuNodeProperty *nodeProp,
                                                             VisuNode *node,
                                                             GValue *value);
    #define             visu_node_array_getPropertyValue    (nodeArray,
                                                             node,
                                                             key,
                                                             value)
    GValue*             visu_node_property_getValue         (VisuNodeProperty *nodeProp,
                                                             VisuNode *node,
                                                             GValue *value);

## Description

In V_Sim, elements are drawn in a box. The VisuNode structure is used to represent an instance of an element position somewhere in the box. This element can have several characteristics such as its translation or its visibility.

All nodes are stored in a VisuData object in a two dimensional array. The first dimension is indexed by the VisuElement of the node and the second corresponds to the number of this node for this element. When a node is own by a VisuData, the two integers, that control the indexes in this array, are not negative. See the VisuNode structure for further explanations.

The only basic informations own by the VisuNode structure is basicaly its position. To add further informations (such as orientation for the spin), define a node property using `visu_node_property_newPointer()`.

## Details

### VisuNode

    typedef struct {
      /* coordinates of the node in cartesian coordinates. */
      float xyz[3];

      /* translation */
      float translation[3];

      /* Number of this element in the input file. */
      unsigned int number;
      /* Position in the #VisuData structure. */
      unsigned int posElement, posNode;

      /* A boolean to specify if this node is rendered or not. */
      gboolean rendered;
    } VisuNode;

Structure to store primary data of a node.

float `xyz`[3]; | an array of three floating point values that positions the node in (x, y, z) ;. in. array fixed-size=3.
float `translation`[3]; | an array of three floating point values that translates the node to its drawn position from (x, y, z) ;. in. array fixed-size=3.
unsigned int `number`; | an integer that corresponds to its position in the entry file, it references also the node itself in the array 'fromNumberToVisuNode' of the VisuData that contains the node ;
unsigned int `posElement`; | an integer that is the position of the VisuElement of the node in the array 'fromIntToVisuElement' of the VisuData object that contains the node ;
unsigned int `posNode`; | an integer that is the position of the node itself in the array 'nodes' of the VisuData object that contains the node ;
gboolean `rendered`; | a boolean to store if the node is drwn or not.

### VisuNodeProperty

    typedef struct _VisuNodeProperty VisuNodeProperty;

This structure defines a storage for one property for each node of a given VisuNodeArray. Use `visu_node_property_newPointer()` or `visu_node_property_newInteger()` to create one property.

### VisuNodeArray

    typedef struct {
      /* Number of VisuElements used by these data. */
      unsigned int ntype;
      /* A counter. */
      unsigned int idCounter;
      /* This array gives access to the good VisuNode
         when one has its number. This number is an integer ranging in
         [0;idCounter[. This value is readable in the #VisuNode structure
         as the number attribute. The current allocated size is stored in
         @nodeTableSize. */
      VisuNode   **nodeTable;
      unsigned int nodeTableSize;
      /* The total of allocated VisuNodes. */
      unsigned int nNodes;
      /* The total of stored VisuNodes. */
      unsigned int nbOfAllStoredNodes;

      /* Number of nodes allocated (size of the nodes array) per VisuElement. */
      unsigned int* numberOfNodes;
      /* Number of nodes physically present in the array per VisuElement. */
      unsigned int* numberOfStoredNodes;
      /* Coordinates of all these nodes. */
      VisuNode **nodes;

      /* This is a table to store data, reachable with string keys.
         It should be accessed via visu_node_setproperty()
         and visu_node_array_getProperty(). */
      GHashTable *properties;

      /* A convenient pointer on the original node property. */
      VisuNodeProperty *origProp;
      guint nOrigNodes;
    } VisuNodeArray;

This structure describes a set of nodes of different VisuElement types. It is optimized for quick access, allocation and reallocation.

unsigned int `ntype`; | number of VisuElement used in this object.
unsigned int `idCounter`; | an internal counter used to give an id to new nodes.
VisuNode **`nodeTable`; | give the VisuNode knowing its element number and its own position.
unsigned int `nodeTableSize`; | the size of the previous array.
unsigned int `nNodes`; | the total of allocated VisuNodes.
unsigned int `nbOfAllStoredNodes`; | number of registered VisuNode in this object.
unsigned int *`numberOfNodes`; | give the number of allocated VisuNode for each VisuElement.
unsigned int *`numberOfStoredNodes`; | give the number of stored VisuNode for each VisuElement.
VisuNode **`nodes`; | array that stores all the nodes.
GHashTable *`properties`; | a list of properties (see VisuNodeProperty).
VisuNodeProperty *`origProp`; | a property saying if the nodes are original or not.
guint `nOrigNodes`; | the number of original nodes.

### visu_node_newValues ()

    void                visu_node_newValues                 (VisuNode *node,
                                                             float xyz[3]);

Set the coordinates and set all other values to default.

`node` : | an allocated VisuNode object ;
`xyz` : | the coordinates to set.. in. array fixed-size=3.

### visu_node_copy ()

    void                visu_node_copy                      (VisuNode *nodeTo,
                                                             VisuNode *nodeFrom);

Copy all attributes of the object `nodeFrom` to `nodeTo`.

`nodeTo` : | an allocated VisuNode object ;
`nodeFrom` : | an allocated VisuNode object.

### visu_node_setVisibility ()

    int                 visu_node_setVisibility             (VisuNode *node,
                                                             gboolean visibility);

This method is used to turn on or off the drawing of the specified node.

`node` : | a VisuNode object ;
`visibility` : | a boolean.
Returns : | true if the calling method should recreate the node list with a call to the `visu_data_createAllNodes()` method.

### visu_node_getVisibility ()

    gboolean            visu_node_getVisibility             (VisuNode *node);

This method is used get the status of the drawing state of a node.

`node` : | a VisuNode object.
Returns : | true if the node is rendered, false otherwise.

### visu_node_array_newNodes ()

    VisuNodeArray*      visu_node_array_newNodes            (unsigned int nTypes,
                                                             unsigned int *nNodes);

Create a new VisuNodeArray structure, allocate all necessary values.

`nTypes` : | the size of nNodes.
`nNodes` : | an array giving the number of nodes per element.. in. array length=nTypes.
Returns : | a newly created VisuNodeArray object.. transfer none.

### visu_node_array_removeNodes ()

    void                visu_node_array_removeNodes         (VisuNodeArray *nodeArray,
                                                             int *nodeNumbers);

Remove the given VisuNode from the `nodeArray`. The properties are also updated.

`nodeArray` : | a VisuNodeArray object.
`nodeNumbers` : | an array of integers (negative terminated).. in. array.

### visu_node_array_removeAllDuplicateNodes ()

    gboolean            visu_node_array_removeAllDuplicateNodes
                                                            (VisuNodeArray *nodeArray,
                                                             int **nodeNumbers);

Remove all nodes that are not original in the box. The list of removed nodes ids are stored in `nodeNumbers`. This array is allocated and should be freed with `g_free()`. If no nodes are removed, this array is not allocated.

`nodeArray` : | a VisuNodeArray object.
`nodeNumbers` : | a location to create an arry of int.
Returns : | TRUE if some nodes have been removed (and `nodeNumbers` allocated).

### visu_node_array_getOriginal ()

    gint                visu_node_array_getOriginal         (VisuNodeArray *nodeArray,
                                                             guint nodeId);

Test if the given `nodeId` is an original or a replica for the periodisation.

`nodeArray` : | a VisuNodeArray object.
`nodeId` : | a node id.
Returns : | TRUE for an original node.

### visu_node_array_setOriginal ()

    gboolean            visu_node_array_setOriginal         (VisuNodeArray *nodeArray,
                                                             guint nodeId);

Test if the given `nodeId` is an original or a replica for the periodisation.

`nodeArray` : | a VisuNodeArray object.
`nodeId` : | a node id.
Returns : | TRUE for an original node.

### visu_node_array_freeNodes ()

    void                visu_node_array_freeNodes           (VisuNodeArray *nodeArray);

Free the given object and all associated memory.

`nodeArray` : | a VisuNodeArray object.

### visu_node_array_allocateNewNodes ()

    void                visu_node_array_allocateNewNodes    (VisuNodeArray *nodeArray,
                                                             unsigned int iEle,
                                                             unsigned int step);

When a new node is required, using `visu_node_array_getNewNode()` or `visu_node_array_getCopyNode()` the storing arrays are expand automatically with a fixed increment. If the user wants to control this increment, he should call this routine before the `get()` ones with the appropriated `step` value.

`nodeArray` : | a VisuNodeArray object ;
`iEle` : | the id of a VisuElement to expand the number of allocated nodes ;
`step` : | the number of newly allocated nodes.

### visu_node_array_getNewNode ()

    VisuNode*           visu_node_array_getNewNode          (VisuNodeArray *nodeArray,
                                                             unsigned int iEle);

Return the location of an unstored node for the given VisuElement. The returned node is then added in the list of used nodes.

`nodeArray` : | a VisuNodeArray object ;
`iEle` : | an integer between 0 and `nodeArray->ntypes` - 1.
Returns : | the location of a newly used node.. transfer none.

### visu_node_array_switchNumber ()

    gboolean            visu_node_array_switchNumber        (VisuNodeArray *nodeArray,
                                                             guint from,
                                                             guint to);

Two nodes of `nodeArray` switches their number.

`nodeArray` : | a VisuNodeArray object.
`from` : | a node id.
`to` : | another node id.
Returns : | TRUE if number is switched.

Since 3.6

### visu_node_array_getCopyNode ()

    VisuNode*           visu_node_array_getCopyNode         (VisuNodeArray *nodeArray,
                                                             VisuNode *node);

Return the location of an unstored node that is the deep copy of the given node. The returned node is then added in the list of used nodes.

`nodeArray` : | a VisuNodeArray object ;
`node` : | a node of the given VisuNodeArray.
Returns : | the location of a newly used node.. transfer none.

### visu_node_array_traceProperty ()

    void                visu_node_array_traceProperty       (VisuNodeArray *array,
                                                             const gchar *id);

This is a debug method. It outputs on stderr the values for all nodes of the property `id`.

`array` : | a VisuNodeArray object ;
`id` : | a property name.

### visu_node_property_newPointer ()

    VisuNodeProperty*   visu_node_property_newPointer       (VisuNodeArray *nodeArray,
                                                             const char *key,
                                                             GFunc freeFunc,
                                                             GCopyFunc newAndCopyFunc,
                                                             gpointer user_data);

This method creates and allocates a new area to store nodes associated data that can be retrieve with the `key`. These data are pointers on allocated memory locations. When the property is removed with the visu_node_freePropertry (or the associated VisuNodeArray is free) the area is free and `freeFunc` is called for each token (or `g_free()` if `freeFunc` is NULL).

The method `newAndCopyFunc` is used when the number of nodes is increased, if the const gpointer of the GCopyFunc is not NULL, then we require a copy, if it is NULL, then the routine must create a new token with default values.

`nodeArray` : | a VisuNodeArray object ;
`key` : | a string ;
`freeFunc` : | a method to free each token (can be NULL).. scope call
`newAndCopyFunc` : | a method to create or copy each token.. scope call
`user_data` : | a user defined pointer that will be given to the free and copy routine.. closure
Returns : | the newly created VisuNodeProperty object.. transfer none.

### visu_node_property_newInteger ()

    VisuNodeProperty*   visu_node_property_newInteger       (VisuNodeArray *nodeArray,
                                                             const char *key);

This method creates and allocates a new area to store nodes associated integer values. This is the same than `visu_node_property_newPointer()` but for static integers instead of pointers as data.

`nodeArray` : | a VisuNodeArray object ;
`key` : | a string.
Returns : | the newly created VisuNodeProperty object.. transfer none.

### visu_node_array_freeProperty ()

    void                visu_node_array_freeProperty        (VisuNodeArray *nodeArray,
                                                             const char *key);

This method free the given property and all associated data.

`nodeArray` : | a VisuNodeArray object.
`key` : | the name of the property to be removed.

### visu_node_array_getProperty ()

    VisuNodeProperty*   visu_node_array_getProperty         (VisuNodeArray *nodeArray,
                                                             const char *key);

This method is used to retrieve the node property associated to the given `key`.

`nodeArray` : | a VisuNodeArray object ;
`key` : | a string.
Returns : | a VisuNodeProperty.. transfer none.

### visu_node_setpropertyValue()

    #define             visu_node_setpropertyValue(nodeArray, node, key, value)

This method is used to store some values associated with the given `node` of the given `nodeArray`. These values can be pointers to anything allocated (will be free automatically when the property is deleted) or they can be static values. This depends on the construction of the node property. These values are described by the `key`, and can be retrieved with the `visu_node_array_getPropertyValue()` method.

See `visu_node_property_setValue()` to directly set a value associated to a node.

`nodeArray` : | a VisuNodeArray object ;
`node` : | a VisuNode object ;
`key` : | a string ;
`value` : | A GValue pointer this the value to be stored.

### visu_node_property_setValue ()

    void                visu_node_property_setValue         (VisuNodeProperty *nodeProp,
                                                             VisuNode *node,
                                                             GValue *value);

This method is used to store some values associated with the given `node` of the given `nodeArray`. These values can be pointers to anything allocated (will be free automatically when the property is deleted) or they can be static values. This depends on the construction of the node property. These values can be retrieved with the `visu_node_property_getValue()` method.

See `visu_node_array_getProperty()` to get a property by its name.

`nodeProp` : | a VisuNodeProperty object ;
`node` : | a VisuNode object ;
`value` : | A GValue pointer this the value to be stored.

### visu_node_array_getPropertyValue()

    #define             visu_node_array_getPropertyValue(nodeArray, node, key, value)

This method is used to retrieve some data associated to the specified `node`, stored in the given `data`. These return data should not be freed after used. The read value is stored in the given GValue pointer. This GValue must be of the right type, depending on the creation of the VisuNodeProperty.

`nodeArray` : | a VisuNodeArray object ;
`node` : | a VisuNode object ;
`key` : | a string ;
`value` : | an initialise GValue location.
Returns : | some data associated to the key, stored the given GValue location.

### visu_node_property_getValue ()

    GValue*             visu_node_property_getValue         (VisuNodeProperty *nodeProp,
                                                             VisuNode *node,
                                                             GValue *value);

This method is used to retrieve some data associated to the specified `node`, stored in the given `data`. These return data should not be freed after used. The read value is stored in the given GValue pointer. This GValue must be of the right type, depending on the creation of the VisuNodeProperty.

`nodeProp` : | a VisuNodeArray object ;
`node` : | a VisuNode object ;
`value` : | an initialise GValue location.
Returns : | some data associated to the key, stored the given GValue location.