![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
struct VisuRendering; struct VisuRenderingClass; int (*VisuRenderingCreateElementFunc) (VisuElement *ele
,VisuGlView *view
); void (*VisuRenderingCreateNodeFunc) (VisuData *visuData
,VisuNode *node
,VisuElement *ele
,int eleGlId
); enum VisuRenderingErrorFlag; int (*VisuRenderingGetElementGlId) (VisuElement *ele
); float (*VisuRenderingGetNodeExtendFunc) (VisuElement *ele
); gboolean (*VisuRenderingLoadFormatFunc) (VisuData *data
,const gchar *filename
,ToolFileFormat *format
,int nSet
,GCancellable *cancel
,GError **error
); void visu_rendering_addFileFormat (VisuRendering *method
,guint fileType
,ToolFileFormat *fmt
,guint priority
,VisuRenderingLoadFormatFunc loadFunc
); GQuark visu_rendering_class_getErrorQuark (void
); int visu_rendering_createElement (VisuRendering *method
,VisuElement *element
,VisuGlView *view
); void visu_rendering_createNode (VisuRendering *method
,VisuData *data
,VisuNode *node
,VisuElement *ele
,int eleGlId
); GList * visu_rendering_getAllObjects (void
); VisuRendering * visu_rendering_getByName (const gchar *name
); const gchar * visu_rendering_getDescription (VisuRendering *method
); int visu_rendering_getElementGlId (VisuRendering *method
,VisuElement *ele
); GList * visu_rendering_getFileFormat (VisuRendering *method
,guint fileType
); const gchar * visu_rendering_getFileTypeName (VisuRendering *method
,guint fileType
); const gchar * visu_rendering_getIconPath (VisuRendering *method
); guint visu_rendering_getNFileTypes (VisuRendering *method
); const gchar * visu_rendering_getName (VisuRendering *method
,gboolean UTF8
); float visu_rendering_getSizeOfElement (VisuRendering *method
,VisuElement *ele
); gboolean visu_rendering_load (VisuRendering *method
,VisuData *data
,int nSet
,GCancellable *cancel
,GError **error
); void visu_rendering_setFileFormat (VisuRendering *meth
,guint fileType
,VisuRendering *from
); void visu_rendering_setFileTypeLabel (VisuRendering *method
,guint fileType
,const gchar *name
); void visu_rendering_setIcon (VisuRendering *method
,const gchar *path
);
"description" gchar* : Read / Write "label" gchar* : Read / Write "nFiles" guint : Read / Write / Construct Only "name" gchar* : Read / Write / Construct Only
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, subclass
VisuRendering. 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 ToolFileFormat. 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 VisuRendering_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
visu_data_getNodePosition()
to retrieve the position and translate
the node accordingly.
struct VisuRendering;
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.
struct VisuRenderingClass { GObjectClass parent; VisuRenderingCreateElementFunc createElement; VisuRenderingGetElementGlId getElementGlId; VisuRenderingCreateNodeFunc createNode; VisuRenderingGetNodeExtendFunc getNodeExtend; };
The structure for the VisuRenderingClass class.
GObjectClass |
the parent class. |
VisuRenderingCreateElementFunc |
a virtual method to create OpenGL shape for a given VisuElement. |
VisuRenderingGetElementGlId |
a virtual method to get the OpenGL list id used for elements. |
VisuRenderingCreateNodeFunc |
a virtual method to position and draw a specific VisuNode. |
VisuRenderingGetNodeExtendFunc |
a virtual method to get the size of a given VisuElement. |
int (*VisuRenderingCreateElementFunc) (VisuElement *ele
,VisuGlView *view
);
Such functions are called whenever a newElement is registered.
|
a VisuElement object ; |
|
a VisuGlView object. |
Returns : |
an id representing an OpenGL list in which the element has been created. |
void (*VisuRenderingCreateNodeFunc) (VisuData *visuData
,VisuNode *node
,VisuElement *ele
,int eleGlId
);
Such functions are called to draw node
at its right position.
The ele
parameter is the VisuElement of the given node
and the visuData
one
points to the VisuData object that contains this node. eleGlId
additionnal parameter represent an identifier to the OpenGL list
ele
is represented by. One can use this parameter to avoid calling
visu_rendering_getElementGlId()
for each node.
|
a VisuData object ; |
|
a VisuElement ; |
|
a VisuElement ; |
|
an identifier. |
typedef enum { RENDERING_ERROR_METHOD, /* Error from the rendering method. */ RENDERING_ERROR_FILE, /* Error when opening. */ RENDERING_ERROR_FORMAT, /* Wrongness in format. */ RENDERING_ERROR_CANCEL /* Cancellation asked. */ } VisuRenderingErrorFlag;
Thiese are flags used when reading a file with a rendering method.
int (*VisuRenderingGetElementGlId) (VisuElement *ele
);
This function is used to get the OpenGL list identifier for ele
.
|
a VisuElement . |
Returns : |
an id. |
Since 3.7
float (*VisuRenderingGetNodeExtendFunc) (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. |
gboolean (*VisuRenderingLoadFormatFunc) (VisuData *data
,const gchar *filename
,ToolFileFormat *format
,int nSet
,GCancellable *cancel
,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
VisuRendering can have several VisuRenderingLoadFormatFunc 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 ;. [transfer full] |
|
the access to the file to load ; |
|
a ToolFileFormat object (can be NULL) ; |
|
an integer ; |
|
a cancellable. |
|
a pointer to store possible errors. |
Returns : |
FALSE if data is unchanged (wrong format), TRUE otherwise (even if
some minor errors have happened). |
void visu_rendering_addFileFormat (VisuRendering *method
,guint fileType
,ToolFileFormat *fmt
,guint priority
,VisuRenderingLoadFormatFunc loadFunc
);
Add a file format descriptor to the list of already known file formats
of the key fileType
.
|
a method ; |
|
an integer used as a key, must >= 0 and < method->nFiles. |
|
a ToolFileFormat ; |
|
the priority (lower sooner) ; |
|
the loading routine. [scope call] |
GQuark visu_rendering_class_getErrorQuark (void
);
Internal function to handle error.
Returns : |
a GQuark for VisuRendering method errors. |
int visu_rendering_createElement (VisuRendering *method
,VisuElement *element
,VisuGlView *view
);
Use the create element function of method
to render element
for
the given zoom level.
|
a VisuRendering method. |
|
a VisuElement object. |
|
a VisuGlView object. |
Returns : |
the OpenGL list id of this element. |
Since 3.6
void visu_rendering_createNode (VisuRendering *method
,VisuData *data
,VisuNode *node
,VisuElement *ele
,int eleGlId
);
Create node
at the right position calling OpenGL routines.
|
a VisuRendering method. |
|
the VisuData object the node is taken from. |
|
a VisuNode of data . |
|
the VisuElement of node or NULL. [allow-none]
|
|
the OpenGL list id repsresenting ele or -1 to get the
default one. |
Since 3.6
GList * visu_rendering_getAllObjects (void
);
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. [element-type VisuRendering*][transfer none] |
VisuRendering * visu_rendering_getByName (const gchar *name
);
Get the corresponding VisuRendering method to name
.
|
a string. [type filename] |
Returns : |
. [transfer none] |
Since 3.6
const gchar * visu_rendering_getDescription (VisuRendering *method
);
Get its description (in UTF8).
|
a VisuRendering method. |
Returns : |
a string, owned by V_Sim. |
int visu_rendering_getElementGlId (VisuRendering *method
,VisuElement *ele
);
This method is used to get the OpenGL identifier of a list for ele
.
|
a method ; |
|
a VisuElement object. |
Returns : |
a OpenGL list identifier. |
Since 3.7
GList * visu_rendering_getFileFormat (VisuRendering *method
,guint fileType
);
This method is used to get the file formats associated to a kind of input file handled by the rendering method.
|
this VisuRendering object. |
|
the file kind of filee format to get from. |
Returns : |
a GList* with the ToolFileFormat. This GList should been considered read-only. [transfer container][element-type ToolFileFormat*] |
Since 3.6
const gchar * visu_rendering_getFileTypeName (VisuRendering *method
,guint 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->priv->nFiles. |
Returns : |
a string own by V_Sim. This string should been considered read-only. |
const gchar * visu_rendering_getIconPath (VisuRendering *method
);
Get the location where to find the icon of the method.
|
a VisuRendering method. |
Returns : |
a string, owned by V_Sim. |
guint visu_rendering_getNFileTypes (VisuRendering *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 VisuRendering. |
const gchar * visu_rendering_getName (VisuRendering *method
,gboolean UTF8
);
Get its name (in UTF8
or not).
|
a VisuRendering method. |
|
a boolean. |
Returns : |
a string, owned by V_Sim. |
float visu_rendering_getSizeOfElement (VisuRendering *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. |
gboolean visu_rendering_load (VisuRendering *method
,VisuData *data
,int nSet
,GCancellable *cancel
,GError **error
);
Call the load routine of method
. Filenames to read from should
have been set to data
using visu_data_addFile()
. If format
is
NULL, an automatic detection is used, trying all available file
formats.
|
a VisuRendering method. |
|
a new VisuData object to load into. |
|
the set id to read from. |
|
a cancellable. |
|
a location for possible error. |
Returns : |
TRUE on success. |
void visu_rendering_setFileFormat (VisuRendering *meth
,guint fileType
,VisuRendering *from
);
It copies the ToolFileFormat of method from
to meth
for the
given fileType
.
|
a VisuRendering object. |
|
a file kind id. |
|
a VisuRendering object. |
Since 3.6
void visu_rendering_setFileTypeLabel (VisuRendering *method
,guint fileType
,const gchar *name
);
Store a list of ToolFileFormat for the kind of file fileType
. The name
argument is copied. but warning, the fileTypeList
GList* is not copied.
|
a method ; |
|
an integer used as a key, must >= 0 and < method->nFiles ; |
|
a string to shortly describe the kind of file type (not NULL). |
void visu_rendering_setIcon (VisuRendering *method
,const gchar *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. |
"description"
property"description" gchar* : Read / Write
Description of the method.
Default value: ""
"nFiles"
property"nFiles" guint : Read / Write / Construct Only
Required number of input files to read to load a data.
Allowed values: [1,100]
Default value: 1
"name"
property"name" gchar* : Read / Write / Construct Only
Name of the method.
Default value: ""
"elementSizeChanged"
signalvoid user_function (VisuRendering *obj,
gfloat size,
gpointer user_data) : No Recursion
Emitted when the size of a element is changed.
|
the object emitting the signal. |
|
the new size. |
|
user data set when the signal handler was connected. |
Since 3.6
"fileTypeChanged"
signalvoid user_function (VisuRendering *obj,
gpointer user_data) : No Hooks
TODO
|
the object emitting the signal. |
|
user data set when the signal handler was connected. |
Since 3.6