![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
visu_elementsvisu_elements — defines methods to create and acccess to VisuElement |
#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);
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()
.
#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.
#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.
#define VISU_ELEMENT_EMPTY_LINE 0
Error code for the visuElementGet_fromValueLine method. The given line is empty.
#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').
#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 { /* 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* 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). |
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. |
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. |
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. |
VisuElement* visuElementGet_fromName (char *name);
This method returns the VisuElement corresponding to the given name.
name : |
a string. |
Returns : | a VisuElement or NULL. |
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. |
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.
|
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.
|
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.
|
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.
|
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.
|
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. |
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. |
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. |
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'. |
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.
|
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.
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.
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. |
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 .
|
int initVisuElements ();
This is an initialization method, it should not be used.
Returns : | 1 if everything goes right. |
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. |