## visu_elements

visu_elements — defines methods to create and acccess to VisuElement.

## Synopsis

    #define             NMAX_TP
    typedef             VisuElement;
    void                visuElementFree                     (VisuElement *ele);
    VisuElement*        visuElementNew_withName             (const char *key);
    int                 visuElementAdd                      (VisuElement *element);
    GList*              visuElementGet_allElements          ();
    VisuElement*        visuElementGet_fromName             (char *name);
    VisuElement*        visuElementRetrieve_fromName        (const gchar *name,
                                                             gboolean *nw);
    int                 visuElementGet_identifierMaterial   (VisuElement *ele);
    gboolean            visuElementGet_sensitiveToPlanes    (VisuElement *element);
    gboolean            visuElementGet_showNodeInfos        (VisuElement *element);

    int                 visuElementSet_allColorValues       (VisuElement *ele,
                                                             float rgb[4],
                                                             float material[5]);
    int                 visuElementSet_allRGBValues         (VisuElement *ele,
                                                             float rgb[4]);
    int                 visuElementSet_RGBValue             (VisuElement *ele,
                                                             int rgb,
                                                             float value);
    int                 visuElementSet_allMaterialValues    (VisuElement *ele,
                                                             float material[5]);
    int                 visuElementSet_materialValue        (VisuElement *ele,
                                                             int material,
                                                             float value);
    int                 visuElementSet_sensitiveToPlanes    (VisuElement *element,
                                                             gboolean status);
    int                 visuElementSet_showNodeInfos        (VisuElement *element,
                                                             gboolean status);

    void                visuElementSet_property             (VisuElement *element,
                                                             char *key,
                                                             gpointer value);
    gpointer            visuElementGet_property             (const VisuElement *element,
                                                             char *key);
    void                visuElementRemove_property          (VisuElement *element,
                                                             char *key);

    gboolean            visuElementGet_rendered             (VisuElement *element);
    int                 visuElementSet_rendered             (VisuElement *element,
                                                             gboolean rendered);

    void                visuElementSet_updateNodesOnMaterialChange
                                                            ();
    gboolean            visuElementGet_updateNodesOnMaterialChange
                                                            ();
    void                visuElementUnset_updateNodesOnMaterialChange
                                                            ();

    void                visuElement_createMaterial          (VisuElement *ele);

    int                 initVisuElements                    ();

## Description

V_Sim is used to rendered at given position several object of the same kind. The VisuElement object is used to control that kind. Typically, it corresponds to chemical element. It can represent the silicon, the iron...

VisuElement are defined by their name and have some characteristic like their color or if they are rendered or not. The color characteristic is defined by an RGBA array and different value for the behavior of the light, as defined in OpenGL : diffusivity, shiningness, emissivity, specular and ambient. These values can be controlled with the following methods : `visuElementSet_allColorValues()`, `visuElementSet_allRGBValues()`, `visuElementSet_RGBValue()`, `visuElementSet_allMaterialValues()` and `visuElementSet_materialValue()`.

Moreover, the user can add new properties to one element using `visuElementSet_property()` and `visuElementGet_property()`. The values stored with these functions are not copied and should be reachable until being remove or until the end of the program.

If the OpenGL representation of one element is not dependent of its position, it is recommended to use the OpenGL list associated to each VisuElement that can be accessed by a call to `visuElementGet_identifierMaterial()`.

## Details

### NMAX_TP

    #define NMAX_TP 500

We suppose that we have at most `NMAX_TP` element. If the actual number of elements must be greater than `NMAX_TP` then one should recompile with a greater value.

### VisuElement

    typedef struct Element_struct VisuElement;

Short name for the Element_struct structure.

### visuElementFree ()

    void                visuElementFree                     (VisuElement *ele);

Free all dynamic memory of `ele` and `ele` itself.

`ele` : | a VisuElement.

### visuElementNew_withName ()

    VisuElement*        visuElementNew_withName             (const char *key);

Allocate a new visuElement with the specified name. Remember that names must be unique since they identify the element.

`key` : | the name of the new element to create.
Returns : | the newly created VisuElement or 0 if something goes wrong in the process (if the name already exist for example).

### visuElementAdd ()

    int                 visuElementAdd                      (VisuElement *element);

Add a VisuElement to the hashtable of the already available elements.

`element` : | the element to add.
Returns : | 0 if the element has been added or if it already exists.

### visuElementGet_allElements ()

    GList*              visuElementGet_allElements          ();

This method returns a list of all the registered VisuElement. The returned list is read-only.

Returns : | the list of all known VisuElement.

### visuElementGet_fromName ()

    VisuElement*        visuElementGet_fromName             (char *name);

This method returns the VisuElement corresponding to the given name.

`name` : | a string.
Returns : | a VisuElement or NULL.

### visuElementRetrieve_fromName ()

    VisuElement*        visuElementRetrieve_fromName        (const gchar *name,
                                                             gboolean *nw);

Try to find a VisuElement already associated to that `name` or create a new one if none has been found. If `nw` is not NULL it is set to FALSE if `name` was found.

`name` : | a string that identify the VisuElement (in UTF8) ;
`nw` : | a location to store a boolean.
Returns : | a VisuElement associated to this `name`.

### visuElementGet_identifierMaterial ()

    int                 visuElementGet_identifierMaterial   (VisuElement *ele);

This method is useful for the rendering method to get the OpenGl identifier of the material of the specified element.

`ele` : | an element.
Returns : | the OpenGL identifier of the specified VisuElement.

### visuElementGet_sensitiveToPlanes ()

    gboolean            visuElementGet_sensitiveToPlanes    (VisuElement *element);

This method is used to retrieve if nodes of the element are sensitive to the masking property of planes, or not.

`element` : | a VisuElement object.
Returns : | TRUE if nodes are masked by planes.

### visuElementGet_showNodeInfos ()

    gboolean            visuElementGet_showNodeInfos        (VisuElement *element);

This method is used to retrieve if nodes of the element are requested to print their informations.

`element` : | a VisuElement object.
Returns : | TRUE if nodes are requested to print some infos.

### visuElementSet_allColorValues ()

    int                 visuElementSet_allColorValues       (VisuElement *ele,
                                                             float rgb[4],
                                                             float material[5]);

This method is used to set all the values that define the color and the lighting of the given element.

`ele` : | the element of which the color must be changed ;
`rgb` : | the new color given by a {red, green, blue} array ;
`material` : | the new values to define the lighting.
Returns : | > 0 if `visuData_createNodes()` should be called and then redraw is need if the value is not null.

### visuElementSet_allRGBValues ()

    int                 visuElementSet_allRGBValues         (VisuElement *ele,
                                                             float rgb[4]);

It saves the values of rgb in the specified VisuElement.

`ele` : | the element of which the color must be changed,
`rgb` : | the new color given by a {red, green, blue} array.
Returns : | > 0 if `visuData_createNodes()` should be called and then redraw is need if the value is not null.

### visuElementSet_RGBValue ()

    int                 visuElementSet_RGBValue             (VisuElement *ele,
                                                             int rgb,
                                                             float value);

It saves the specific value of rgb (0 for red, 1 for green and 2 for bluein the specified VisuElement.

`ele` : | the element of which the color must be changed,
`rgb` : | the component to change, 0 for red, 1 for green and 2 for blue,
`value` : | the value for one of the red, green or blue component.
Returns : | > 0 if `visuData_createNodes()` should be called and then redraw is need if the value is not null.

### visuElementSet_allMaterialValues ()

    int                 visuElementSet_allMaterialValues    (VisuElement *ele,
                                                             float material[5]);

It saves the values of material in the specified VisuElement.

`ele` : | the element of which the color must be changed,
`material` : | the new values to define the lighting.
Returns : | > 0 if `visuData_createNodes()` should be called and then redraw is need if the value is not null.

### visuElementSet_materialValue ()

    int                 visuElementSet_materialValue        (VisuElement *ele,
                                                             int material,
                                                             float value);

It saves the specific value of material (use the enum as the parameter material) in the specified VisuElement.

`ele` : | the element of which the color must be changed,
`material` : | the component to change,
`value` : | the new value of the specified component.
Returns : | > 0 if `visuData_createNodes()` should be called and then redraw is need if the value is not null.

### visuElementSet_sensitiveToPlanes ()

    int                 visuElementSet_sensitiveToPlanes    (VisuElement *element,
                                                             gboolean status);

This method sets the private attribute 'sensitiveToMaskingPlanes' to TRUE or FALSE for the specified visuElement. If TRUE, all the nodes of that VisuElement are not sensitive to the masking property of planes.

`element` : | a VisuElement object ;
`status` : | TRUE or FALSE.
Returns : | 1 if the calling method should call `visuData_createNodes()` for the given VisuElement and then should add `visuObjectRedraw()` to the Gloop.

### visuElementSet_showNodeInfos ()

    int                 visuElementSet_showNodeInfos        (VisuElement *element,
                                                             gboolean status);

This method sets the private attribute 'showNodeInfos' to TRUE or FALSE for the specified visuElement. If TRUE, all the nodes of that VisuElement should print some information near them (currently their position in the input file).

`element` : | a VisuElement object ;
`status` : | TRUE or FALSE.
Returns : | 1 if the calling method should call `visuData_createNodeInfos()` for the given VisuElement and then should add `visuObjectRedraw()` to the Gloop.

### visuElementSet_property ()

    void                visuElementSet_property             (VisuElement *element,
                                                             char *key,
                                                             gpointer value);

This method is used to store some values associated with the given `element`. These values are anything allocated and will be freed (with `free()`) when the `element` is deleted. These values are described by the `key`, and can be retrieved with the #`visuElementGet_property()` method. The `key` is used by the VisuElement and should not be freed. Moreover it is not freed when the node is destroyed.

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

### visuElementGet_property ()

    gpointer            visuElementGet_property             (const VisuElement *element,
                                                             char *key);

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

`element` : | a VisuElement object ;
`key` : | a string.
Returns : | some data associated to the key.

### visuElementRemove_property ()

    void                visuElementRemove_property          (VisuElement *element,
                                                             char *key);

This method remove the data associated with the string `key`. They are freed.

`element` : | a VisuElement object ;
`key` : | a string.

### visuElementGet_rendered ()

    gboolean            visuElementGet_rendered             (VisuElement *element);

This gets the value of the private attribute 'rendered' for the specified VisuElement.

`element` : | a VisuElement object.
Returns : | the value of attribute 'rendered'.

### visuElementSet_rendered ()

    int                 visuElementSet_rendered             (VisuElement *element,
                                                             gboolean rendered);

This method sets the private attribute 'rendered' to TRUE or FALSE for the specified visuElement. If FALSE, all the nodes of that VisuElement are not included in the nodes OpenGL list.

`element` : | a VisuElement object ;
`rendered` : | TRUE or FALSE.
Returns : | 1 if the calling method should call `visuData_createNodes()` for the given VisuElement and then should emit the 'OpenGLAskForReDraw' signal.

### visuElementSet_updateNodesOnMaterialChange ()

    void                visuElementSet_updateNodesOnMaterialChange
                                                            ();

If this method is called, whenever a change occurs to a VisuElement material description (color and light) the corresponding OpenGl list of nodes of the currentVisuData is rebuilt. This is usefull if the nodes can't use the list material because the color is node dependant for example. Use `visuElementUnset_updateNodesOnMaterialChange()` to return to the normal behavior.

### visuElementGet_updateNodesOnMaterialChange ()

    gboolean            visuElementGet_updateNodesOnMaterialChange
                                                            ();

Retrieve if one the VisuElement is sensitive to the material values. See `visuElementSet_updateNodesOnMaterialChange()`.

Returns : | TRUE if `visuData_createNodes()` should be called when the material values are changed.

### visuElementUnset_updateNodesOnMaterialChange ()

    void                visuElementUnset_updateNodesOnMaterialChange
                                                            ();

If this method is called (and no other method has used `visuElementSet_updateNodesOnMaterialChange()`, a changement in the material description only change the list of the material.

### visuElement_createMaterial ()

    void                visuElement_createMaterial          (VisuElement *ele);

Create a list whose number is defined by identifierMaterials + `ele->typeNumber` that stores the definition of light and color for this VisuElement. The previous OpenGL object list with the same identifier is deleted.

`ele` : | a pointer to a valid `VisuElement`.

### initVisuElements ()

    int                 initVisuElements                    ();

This is an initialization method, it should not be used.

Returns : | 1 if everything goes right.