visu_elements

visu_elements — defines methods to create and acccess to VisuElement.

Synopsis




#define     NMAX_TP
typedef     VisuElement;
VisuElement* visuElementNew_withName        (const char *key);
int         visuElementAdd                  (VisuElement *element);
GList*      visuElementGet_allElements      ();
VisuElement* visuElementGet_fromName        (char *name);
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.


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.

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.