## visu_elements

visu_elements — defines methods to create and acccess to VisuElement

## Synopsis

    #define     NMAX_TP
    #define     VISU_ELEMENT_MAX_REACHED
    #define     VISU_ELEMENT_EMPTY_LINE
    #define     VISU_ELEMENT_BAD_NAME
    #define     VISU_ELEMENT_CREATE_ERROR
    struct      Element_struct;
    typedef     VisuElement;
    VisuElement* visuElementNewWithName         (char *key);
    int         visuElementAdd                  (VisuElement *element);
    GList*      visuElementGet_allElements      ();
    VisuElement* visuElementGet_fromValueLine   (char **line,
                                                 int sizeMax,
                                                 int *errorFlag);
    VisuElement* visuElementGet_fromName        (char *name);
    int         visuElementGet_identifierMaterial
                                                (const VisuElement *ele);

    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);

    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
                                                ();
    void        visuElementUnset_updateNodesOnMaterialChange
                                                ();

    void        visuElementPrint_errorFromValueLine
                                                (GString *dest,
                                                 int line,
                                                 int flag);
    void        visuElement_createMaterial      (VisuElement *ele);

    int         initVisuElements                ();
    VisuElement* visuElementRead_fromLine       (char **line,
                                                 int sizeMax,
                                                 int position,
                                                 GError **error);

    void        debug_AllVisuElements           ();
    void        debug_VisuElement               (gpointer key,
                                                 gpointer value,
                                                 gpointer data);

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

### VISU_ELEMENT_MAX_REACHED

    #define VISU_ELEMENT_MAX_REACHED 2

Error code for the visuElementGet_fromValueLine method. The maximum number of element has been reached (NMAX_TP) and the element one the line can't be added.

### VISU_ELEMENT_EMPTY_LINE

    #define VISU_ELEMENT_EMPTY_LINE 0

Error code for the visuElementGet_fromValueLine method. The given line is empty.

### VISU_ELEMENT_BAD_NAME

    #define VISU_ELEMENT_BAD_NAME   1

Error code for the visuElementGet_fromValueLine method. The given name contains a carriage return or a nnull caracter ('\0').

### VISU_ELEMENT_CREATE_ERROR

    #define VISU_ELEMENT_CREATE_ERROR 3

Error code for the visuElementGet_fromValueLine method. The element read is new but can't be created (mostly for bad allocation).

### struct Element_struct

    struct Element_struct {
      /* Name of the key used in the hashtable to find
         this element. The int variable is the number
         of this type. */
      char* name;
      /* An integer unique for each VisuElement, it is
         used as a name for the opengl material associated
         with it. */
      int typeNumber;

      /* OpenGl part */
      /* main color of the element  in [r, g, b, a] format*/
      float rgb[4];
      /* lighting effects for material in [amb, dif, shi, spe, emi] format. */
      float material[5];
      /* the identifier that stores the glObjectList that draw this VisuElement. */
      int openGLIdentifier;

      /* A flag that is TRUE when the OpenGL list of the material is up to date. */
      gboolean materialIsUpToDate;
      /* A flag to store if all nodes of this element are rendered or not.
         Its default value is TRUE. */
      gboolean rendered;

      /* This hashtable is usefull to store some data associated with the VisuData.
         It should be accessed with the visuDataSet_property()
         and the visuDataGet_property methods. */
      GHashTable *properties;
    };

Structure to store the description of an element.

char *`name`; | Name of the key used in the hashtable to find this element. The int variable is the number of this type.
int `typeNumber`; | An integer unique for each VisuElement, it is used as a name for the opengl material associated with it.
float `rgb`[4]; | main color of the element in [r, g, b, a] format.
float `material`[5]; | lighting effects for material in [amb, dif, shi, spe, emi] format.
int `openGLIdentifier`; | the identifier that stores the glObjectList that draw this VisuElement.
gboolean `materialIsUpToDate`; | A flag that is TRUE when the OpenGL list of the material is up to date.
gboolean `rendered`; | A flag to store if all nodes of this element are rendered or not. Its default value is TRUE.
GHashTable *`properties`; | This hashtable is usefull to store some data associated with the VisuElement. It should be accessed with the `visuElementSet_property()` and the visuElementGet_property methods.

### VisuElement

    typedef struct Element_struct VisuElement;

Short name for the Element_struct structure.

### visuElementNewWithName ()

    VisuElement* visuElementNewWithName         (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_fromValueLine ()

    VisuElement* visuElementGet_fromValueLine   (char **line,
                                                 int sizeMax,
                                                 int *errorFlag);

This method is a unified way to retrieve the element at the beginning of line of value. It is really useful when reading lines of resource file. Note that the position of pointer line is modified to point to the character immediatly after the last found character of an element name. At most sizeMax character are read from line. DEPRECATED, use `visuElementRead_fromLine()` instead.

`line` : | the line to scan.
`sizeMax` : | number of characters read, at most.
`errorFlag` : | a pointer to an integer to store a identifier of error if the function return a NULL pointer (otherwise, errorFlag is not set).
Returns : | the VisuElement structure corresponding to the name read or NULL if the element is unknown or its name unreadable.

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

### visuElementGet_identifierMaterial ()

    int         visuElementGet_identifierMaterial
                                                (const 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.

### 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_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 set 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.

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

### visuElementPrint_errorFromValueLine ()

    void        visuElementPrint_errorFromValueLine
                                                (GString *dest,
                                                 int line,
                                                 int flag);

This function print an error message corresponding to the `flag` to the string buffer desgned by `dest`.

`dest` : | an already allocated string buffer to append the message.
`line` : | the number of the line read.
`flag` : | the identifier of the error.

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

### visuElementRead_fromLine ()

    VisuElement* visuElementRead_fromLine       (char **line,
                                                 int sizeMax,
                                                 int position,
                                                 GError **error);

This routine is the same that `visuElementGet_fromValueLine()` but uses GError instead.

`line` : | the line to scan ;
`sizeMax` : | number of characters read, at most ;
`position` : | the number of the line in the input file ;
`error` : | a pointer to a GError*.
Returns : | the VisuElement structure corresponding to the name read or NULL if the element is unknown or its name unreadable.

### debug_AllVisuElements ()

    void        debug_AllVisuElements           ();

### debug_VisuElement ()

    void        debug_VisuElement               (gpointer key,
                                                 gpointer value,
                                                 gpointer data);

`key` : |
`value` : |
`data` : |