![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
struct RenderingMethod_struct; typedef RenderingMethod; typedef RenderingFormatLoad; gboolean (*renderingFormatLoadFunc) (VisuData *data, const gchar *filename, FileFormat *format, int nSet, GError **error); enum RenderingErrorFlag; RenderingMethod* renderingMethod_new (char *name, char *printName, char *description, int nbFileType, renderingMethodLoadFunc loadMethod); void renderingMethod_free (RenderingMethod *method); void renderingMethodSet_icon (RenderingMethod *method, char *path); void renderingMethodSet_fileType (RenderingMethod *method, GList *fileTypeList, int fileType, gchar *name); int renderingMethodGet_nbFileType (RenderingMethod *method); GList* renderingMethodGet_fileType (RenderingMethod *method, int fileType); gchar* renderingMethodGet_fileTypeName (RenderingMethod *method, int fileType); float renderingMethodGet_sizeOfElement (RenderingMethod *method, VisuElement *ele); void renderingMethodAdd_fileFormat (RenderingMethod *method, FileFormat *fmt, int fileType); gint renderingMethodCompare_priority (gconstpointer a, gconstpointer b); void registerRenderingMethod (RenderingMethod *method); RenderingMethod* (*RenderingMethodInitFunc) (); gboolean (*renderingMethodLoadFunc) (VisuData *data, FileFormat *format, int nSet, GError **error); int (*createOpenGLElementFunc) (VisuData *visuData, VisuElement *ele); void (*createOpenGLNodeFunc) (VisuData *visuData, VisuNode *node, VisuElement *ele); float (*getExtensOfNodeFunc) (VisuElement *ele); void setOpenGLMethods (RenderingMethod *method, createOpenGLElementFunc createElement, createOpenGLNodeFunc createNode, getExtensOfNodeFunc getSize); void setRenderingMethodInUse (RenderingMethod *method); int setRenderingMethodByName (char *name); RenderingMethod* getRenderingMethodInUse (); GList* renderingMethodGet_AllMethods (); int initRenderingMethods ();
The way visu renders its data is done by modules. They are called rendering methods and they describes how data are drawn on the screen. Many can be defined but only one is used at a time to render the data.
One or more file type are associated with a rendering method. And a rendering method must specify the way to load the data it needs. Taking the example of a spin system representation, there are two kinds of file. The first kind describes the position the spin and the second contains their orientations.
To create a new rendering method, use
renderingMethod_new()
. The name is mandatory and must be
unique. The description is not compulsory. The number of file kinds
is also required. Use renderingMethodSet_fileType()
to associated a
GList of FileFormat. In our example of spin system, the first
kind of file is about positions, and the associated file formats
are *.ascii, *.d3 and *.xyz.
The RenderingMethod_struct has to two pointers on methods
that are important. The first, createOpenGLElementFunc()
is called
when V_Sim needs to create an OpenGL list corresponding to the
VisuElement given as argument. This list then can be used to
render each node and thus accelerating the rendering
operations. The second method is createOpenGLNodeFunc()
and is
called by V_Sim for each node of the system when the main OpenGL
list (the one for the nodes) is created. Thus, in the contrary of
the first method, thios one should not create an OpenGL list but
directly call OpenGL routines to draw the node. This method is also
responsible to put the node at the right position. Use
visuDataGet_nodePosition()
to retrieve the position and translate
the node accordingly.
struct RenderingMethod_struct;
This structure is used to describe a rendering method. Besides names, representing icon... this structure stores pointers to method technically used to draw elements with this method.
typedef struct RenderingMethod_struct RenderingMethod;
Short name to address RenderingMethod_struct objects.
typedef struct RenderingFormatLoad_struct RenderingFormatLoad;
Short way to address RenderingFormatLoad_struct objects.
gboolean (*renderingFormatLoadFunc) (VisuData *data, const gchar *filename, FileFormat *format, int nSet, GError **error);
This is an interface for a generic load method. This method read the file
positionned on filename
and populate or change the arrays in
data
. When enter this method, the data
argument is already
allocated but its arrays may be empty and unallocated (depending on
context). If the load method fails (because the format is wrong or
anything else), the data
argument should not be modified. If some
errors occur, the pointer error
will be instanciated. A
RenderingMethod can have several renderingFormatLoadFunc methods
for each format they support. The nSet
argument is used to load a
specific set of nodes if the input format supports it. If nSet
is
0, then the default set of nodes is loaded.
|
a VisuData object ; |
|
the access to the file to load ; |
|
a FileFormat object (can be NULL) ; |
|
an integer ; |
|
a pointer to store possible errors. |
Returns : |
FALSE if data is unchanged (wrong format), TRUE otherwise (even if
some minor errors have happened).
|
typedef enum { RENDERING_ERROR_METHOD, /* Error from the rendering method. */ RENDERING_ERROR_FILE, /* Error when opening. */ RENDERING_ERROR_FORMAT /* Wrongness in format. */ } RenderingErrorFlag;
Thiese are flags used when reading a file with a rendering method.
RenderingMethod* renderingMethod_new (char *name, char *printName, char *description, int nbFileType, renderingMethodLoadFunc loadMethod);
Method used to create rendering methods. The nbFileType
argument is used to declare
the number of files that the method needs to read to render a set of data.
Use renderingMethodSet_fileType()
method to set some FileFormat for each kind.
|
a string to label the method ; |
|
a string to label the method that can be safely translated ; |
|
a string to describe the method ; |
|
an integer ; |
|
a loadDataFromFileFunc which the load function of the method.
|
Returns : |
the newly created method of a null pointer if something goes wrong. |
void renderingMethod_free (RenderingMethod *method);
Free all the allocated attributes of the specified method.
|
the method to delete. |
void renderingMethodSet_icon (RenderingMethod *method, char *path);
This method is used to set the path to an icon for the specified method. The path is copied, and the given name can be freed freely after a call to this method.
|
a method ; |
|
a path to an image file. |
void renderingMethodSet_fileType (RenderingMethod *method, GList *fileTypeList, int fileType, gchar *name);
Store a list of FileFormat for the kind of file fileType
. The name
argument is copied. but warning, the fileTypeList
GList* is not copied.
|
a method ; |
|
a list of FileFormat ; |
|
an integer used as a key, must >= 0 and < method->nbFilesType ; |
|
a string to shortly describe the kind of file type (not NULL). |
int renderingMethodGet_nbFileType (RenderingMethod *method);
This method is used to get the number of kind of files needed to render a set of data.
|
a method. |
Returns : |
how many kind of files are handled by the given RenderingMethod. |
GList* renderingMethodGet_fileType (RenderingMethod *method, int fileType);
This method is used to get the file formats associated to a kind of input file handled by the rendering method.
|
a method ; |
|
an integer used as a key, must >= 0 and < method->nbFilesType. |
Returns : |
a GList* with the FileFormat. This GList should been considered read-only. |
gchar* renderingMethodGet_fileTypeName (RenderingMethod *method, int fileType);
This method is used to get the name associated to a kind of input file handled by the rendering method.
|
a method ; |
|
an integer used as a key, must >= 0 and < method->nbFilesType. |
Returns : |
a string own by V_Sim. This string should been considered read-only. |
float renderingMethodGet_sizeOfElement (RenderingMethod *method, VisuElement *ele);
This method is used to retrieve the radius of the sphere that contains
the ele
.
|
a method ; |
|
a VisuElement to get the size of. |
Returns : |
the radius of the given element. |
void renderingMethodAdd_fileFormat (RenderingMethod *method, FileFormat *fmt, int fileType);
Add a file format descriptor to the list of already known file formats
of the key fileType
.
|
a method ; |
|
a FileFormat ; |
|
an integer used as a key, must >= 0 and < method->nbFilesType. |
gint renderingMethodCompare_priority (gconstpointer a, gconstpointer b);
Compare the priority field of the structures of the two arguments.
|
a RenderingFormatLoad ; |
|
another RenderingFormatLoad. |
Returns : |
-1 if priority of a is higher (i.e. lower value) than the one of b. |
void registerRenderingMethod (RenderingMethod *method);
A method used by user to registered a new method.
|
a RenderingMethod. |
RenderingMethod* (*RenderingMethodInitFunc) ();
Prototype of the functions used to initialise a new rendering method.
Returns : |
a newly created RenderingMethod. |
gboolean (*renderingMethodLoadFunc) (VisuData *data, FileFormat *format, int nSet, GError **error);
Interface of functions that allow to load data. The filenames are
retrieve from the given VisuData, using the visuDataGet_file()
method. If no format
argument is given, then the format should be
guessed, otherwise, the given format is the one chosen by the
the user. WARNING : this format may not be the right format since
user selected. The nSet
argument is used to load a specific set of
nodes if the input format supports it. If nSet
is 0, then the
default set of nodes is loaded.
|
an already allocated VisuData ; |
|
a pointer on a format (can be NULL if format is to be guessed) ; |
|
an integer ; |
|
a pointer to store a possible error, location must be initialized to (GError*)0. |
Returns : |
TRUE if everything goes right. |
int (*createOpenGLElementFunc) (VisuData *visuData, VisuElement *ele);
Such functions are called whenever a newElement is registered.
|
a VisuData object ; |
|
a VisuElement ; |
Returns : |
an id representing an OpenGL list in which the element has been created. |
void (*createOpenGLNodeFunc) (VisuData *visuData, VisuNode *node, VisuElement *ele);
Such functions are called when the OpenGl list of all the nodes is created.
The ele
parameter is the VisuElement of the given node
and the visuData
one
points to the VisuData object that contains this node.
|
a VisuData object ; |
|
a VisuElement ; |
|
a VisuElement. |
float (*getExtensOfNodeFunc) (VisuElement *ele);
This function is required to inform the OpenGL drawer and to adapt the maximum size of the drawing area.
|
a VisuElement .
|
Returns : |
the geometrical size of the element. |
void setOpenGLMethods (RenderingMethod *method, createOpenGLElementFunc createElement, createOpenGLNodeFunc createNode, getExtensOfNodeFunc getSize);
This method is used to set the callback functions for the specified
rendering method. These callbacks are used by the OpenGl part of the code.
The createElement
parameter is a method called to create an OpenGl list
that draw the symbol corresponding to the element. The createNode
parameter
is called to position and drw the specified node. It should not create a list.
|
a RenderingMethod ; |
|
a createOpenGLElementFunc ;
|
|
a createOpenGLNodeFunc ;
|
|
a getExtensOfNodeFunc .
|
void setRenderingMethodInUse (RenderingMethod *method);
Choose the method used to render the data.
|
a RenderingMethod. |
int setRenderingMethodByName (char *name);
Choose the method used to render the data.
|
the name of a rendering method. |
Returns : |
1 if the method exists and is set, 0 otherwise. |
RenderingMethod* getRenderingMethodInUse ();
Get the current method used to render the data.
Returns : |
the name of the currently used rendering method. |
GList* renderingMethodGet_AllMethods ();
This method gives a GList with pointers to each rendering method. Warning : the returned GList is not a copy, it must not be modified, just read.
Returns : |
A GList containing all the registered rendering methods. |