## visu_elements

visu_elements — defines methods to create and acccess to VisuElement.

## Synopsis

    #define             VISU_ELEMENT_MAX_NUMBER
    #define             VISU_ELEMENT_TYPE
    #define             VISU_ELEMENT                        (obj)
    #define             VISU_ELEMENT_CLASS                  (klass)
    #define             IS_VISU_ELEMENT_TYPE                (obj)
    #define             IS_VISU_ELEMENT_CLASS               (klass)
    #define             VISU_ELEMENT_GET_CLASS              (obj)
                        VisuElementClass;
                        VisuElement;
    GType               visu_element_get_type               (void);
    const GList *       visu_element_getAllElements         (void);
    VisuElement *       visu_element_retrieveFromName       (const gchar *name,
                                                             gboolean *nw);
    VisuElement *       visu_element_lookup                 (const gchar *name);
    VisuElement *       visu_element_new                    (const char *key);
    gint                visu_element_setAllColorValues      (VisuElement *ele,
                                                             float rgb[4],
                                                             float material[5]);
    gint                visu_element_setAllRGBValues        (VisuElement *ele,
                                                             float rgb[4]);
    gint                visu_element_setRGBValue            (VisuElement *ele,
                                                             int rgb,
                                                             float value);
    gint                visu_element_setAllMaterialValues   (VisuElement *ele,
                                                             float material[5]);
    gint                visu_element_setMaterialValue       (VisuElement *ele,
                                                             int material,
                                                             float value);
    gboolean            visu_element_setRendered            (VisuElement *element,
                                                             gboolean rendered);
    gboolean            visu_element_setSensitiveToPlanes   (VisuElement *element,
                                                             gboolean status);
    void                visu_element_createMaterial         (VisuElement *ele);
    int                 visu_element_getIdentifierMaterial  (VisuElement *ele);
    gboolean            visu_element_getRendered            (VisuElement *element);
    gboolean            visu_element_getSensitiveToPlanes   (VisuElement *element);
    void                visu_element_setUpdateNodesOnMaterialChange
                                                            (void);
    void                visu_element_unsetUpdateNodesOnMaterialChange
                                                            (void);
    gboolean            visu_element_getUpdateNodesOnMaterialChange
                                                            (void);

## Object Hierarchy

      GObject
       +----VisuElement

## Signals

      "ElementMaterialChanged"                         : Run Last / No Recursion
      "ElementNew"                                     : Run Last / No Recursion
      "ElementPlaneChanged"                            : Run Last / No Recursion
      "ElementRenderedChanged"                         : Run Last / No Recursion

## 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 : `visu_element_setAllColorValues()`, `visu_element_setAllRGBValues()`, `visu_element_setRGBValue()`, `visu_element_setAllMaterialValues()` and `visu_element_setMaterialValue()`.

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 `visu_element_getIdentifierMaterial()`.

## Details

### VISU_ELEMENT_MAX_NUMBER

    #define VISU_ELEMENT_MAX_NUMBER 500

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

### VISU_ELEMENT_TYPE

    #define VISU_ELEMENT_TYPE	     (visu_element_get_type ())

return the type of VisuElement.

### VISU_ELEMENT()

    #define VISU_ELEMENT(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, VISU_ELEMENT_TYPE, VisuElement))

Cast the given `obj` into VisuElement type.

`obj` : | a GObject to cast.

### VISU_ELEMENT_CLASS()

    #define VISU_ELEMENT_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, VISU_ELEMENT_TYPE, VisuElementClass))

Cast the given `klass` into VisuElementClass.

`klass` : | a GObjectClass to cast.

### IS_VISU_ELEMENT_TYPE()

    #define IS_VISU_ELEMENT_TYPE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, VISU_ELEMENT_TYPE))

Test if the given `ogj` is of the type of VisuElement object.

`obj` : | a GObject to test.

### IS_VISU_ELEMENT_CLASS()

    #define IS_VISU_ELEMENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, VISU_ELEMENT_TYPE))

Test if the given `klass` is of the type of VisuElementClass class.

`klass` : | a GObjectClass to test.

### VISU_ELEMENT_GET_CLASS()

    #define VISU_ELEMENT_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, VISU_ELEMENT_TYPE, VisuElementClass))

It returns the class of the given `obj`.

`obj` : | a GObject to get the class of.

### VisuElementClass

    typedef struct _VisuElementClass VisuElementClass;

An opaque structure representing the class of VisuElement objects.

### VisuElement

    typedef struct _VisuElement VisuElement;

Structure to store the description of an element.

### visu_element_get_type ()

    GType               visu_element_get_type               (void);

This method returns the type of VisuElement, use VISU_ELEMENT_TYPE instead.

Returns : | the type of VisuElement.

### visu_element_getAllElements ()

    const GList *       visu_element_getAllElements         (void);

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

Returns : | the list of all known VisuElement.. element-type VisuElement. transfer none VisuElement.

### visu_element_retrieveFromName ()

    VisuElement *       visu_element_retrieveFromName       (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.. out caller-allocates.
Returns : | a VisuElement associated to this `name`.. transfer none.

### visu_element_lookup ()

    VisuElement *       visu_element_lookup                 (const gchar *name);

Lookup for element `name` in the base. Do not create it if not found. To do this, use `visu_element_retrieveFromName()`.

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

Since 3.6

### visu_element_new ()

    VisuElement *       visu_element_new                    (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).. transfer none.

### visu_element_setAllColorValues ()

    gint                visu_element_setAllColorValues      (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 ;. in. array fixed-size=4.
`material` : | the new values to define the lighting.. in. array fixed-size=5.
Returns : | > 0 if `visu_data_createNodes()` should be called and then redraw is need if the value is not null.

### visu_element_setAllRGBValues ()

    gint                visu_element_setAllRGBValues        (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.. in. array fixed-size=4.
Returns : | > 0 if `visu_data_createNodes()` should be called and then redraw is need if the value is not null.

### visu_element_setRGBValue ()

    gint                visu_element_setRGBValue            (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 `visu_data_createNodes()` should be called and then redraw is need if the value is not null.

### visu_element_setAllMaterialValues ()

    gint                visu_element_setAllMaterialValues   (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.. in. array fixed-size=5.
Returns : | > 0 if `visu_data_createNodes()` should be called and then redraw is need if the value is not null.

### visu_element_setMaterialValue ()

    gint                visu_element_setMaterialValue       (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 `visu_data_createNodes()` should be called and then redraw is need if the value is not null.

### visu_element_setRendered ()

    gboolean            visu_element_setRendered            (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 `visu_data_createNodes()` for the given VisuElement and then should emit the 'OpenGLAskForReDraw' signal.

### visu_element_setSensitiveToPlanes ()

    gboolean            visu_element_setSensitiveToPlanes   (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 `visu_data_createNodes()` for the given VisuElement and then should add `visu_object_redraw()` to the Gloop.

### visu_element_createMaterial ()

    void                visu_element_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`.

### visu_element_getIdentifierMaterial ()

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

### visu_element_getRendered ()

    gboolean            visu_element_getRendered            (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'.

### visu_element_getSensitiveToPlanes ()

    gboolean            visu_element_getSensitiveToPlanes   (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.

### visu_element_setUpdateNodesOnMaterialChange ()

    void                visu_element_setUpdateNodesOnMaterialChange
                                                            (void);

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 `visu_element_unsetUpdateNodesOnMaterialChange()` to return to the normal behavior.

### visu_element_unsetUpdateNodesOnMaterialChange ()

    void                visu_element_unsetUpdateNodesOnMaterialChange
                                                            (void);

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

### visu_element_getUpdateNodesOnMaterialChange ()

    gboolean            visu_element_getUpdateNodesOnMaterialChange
                                                            (void);

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

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

## Signal Details

### The `"ElementMaterialChanged"` signal

    void                user_function                      (VisuElement *element,
                                                            gpointer     user_data)      : Run Last / No Recursion

Gets emitted when the material or color properties of a VisuElement are modified.

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

Since 3.6

### The `"ElementNew"` signal

    void                user_function                      (VisuElement *element,
                                                            gpointer     user_data)      : Run Last / No Recursion

A new element is available.

`element` : | the object emitting the signal.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"ElementPlaneChanged"` signal

    void                user_function                      (VisuElement *element,
                                                            gpointer     user_data)      : Run Last / No Recursion

Gets emitted when the property of masking by plane is modified.

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

Since 3.6

### The `"ElementRenderedChanged"` signal

    void                user_function                      (VisuElement *element,
                                                            gpointer     user_data)      : Run Last / No Recursion

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

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

Since 3.6