![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
struct VisuData; struct VisuDataClass; gboolean (*VisuDataColorFunc) (VisuData *visuData
,float rgba[4]
,VisuElement *ele
,VisuNode *node
); float (*VisuDataScalingFunc) (VisuData *visuData
,VisuNode *node
); void visu_data_addFile (VisuData *data
,const gchar *file
,int kind
,ToolFileFormat *format
); VisuNode * visu_data_addNodeFromElement (VisuData *data
,VisuElement *ele
,float xyz[3]
,gboolean reduced
,gboolean emitSignal
); VisuNode * visu_data_addNodeFromElementName (VisuData *data
,const gchar *name
,float xyz[3]
,gboolean reduced
,gboolean emitSignal
); VisuNode * visu_data_addNodeFromIndex (VisuData *data
,guint position
,float xyz[3]
,gboolean reduced
,gboolean emitSignal
); guint visu_data_addTimeout (VisuData *data
,guint time
,GSourceFunc func
,gpointer user_data
); GList * visu_data_class_getAllObjects (void
); gboolean visu_data_constrainedElementInTheBox (VisuData *data
,VisuElement *element
); gboolean visu_data_constrainedFree (VisuData *data
); gboolean visu_data_constrainedInTheBox (VisuData *data
); gboolean visu_data_forceXYZtranslation (VisuData *data
,float xyz[3]
); void visu_data_freePopulation (VisuData *data
); gfloat visu_data_getAllNodeExtens (VisuData *dataObj
,VisuBox *box
); gboolean visu_data_getChangeElementFlag (VisuData *data
); VisuNodeInfo * visu_data_getDistanceList (VisuData *data
,guint nodeId
,float *minVal
); const gchar * visu_data_getFile (VisuData *data
,int kind
,ToolFileFormat **format
); gchar * visu_data_getFileCommentary (VisuData *data
,gint iSet
); gchar * visu_data_getFilesAsLabel (const VisuData *data
); int visu_data_getISubset (VisuData *data
); int visu_data_getNSubset (VisuData *data
); gboolean visu_data_getNodeBoxFromCoord (VisuData *data
,float xcart[3]
,int nodeBox[3]
); gboolean visu_data_getNodeBoxFromNumber (VisuData *data
,guint nodeId
,int nodeBox[3]
); void visu_data_getNodeCoordinates (VisuData *data
,VisuNode *node
,float *x
,float *y
,float *z
); void visu_data_getNodePosition (VisuData *data
,VisuNode *node
,float coord[3]
); float visu_data_getNodeScalingFactor (VisuData *data
,VisuNode *node
); void visu_data_getNodeUserPosition (VisuData *data
,VisuNode *node
,float coord[3]
); gboolean visu_data_getTranslationStatus (VisuData *data
); gboolean visu_data_getUserColor (VisuData *data
,VisuElement *ele
,VisuNode *node
,float rgba[4]
); float * visu_data_getXYZtranslation (VisuData *data
); gboolean visu_data_hasUserColorFunc (VisuData *data
); VisuData * visu_data_new (void
); VisuData * visu_data_new_withFiles (const gchar **files
); void visu_data_removeAllFiles (VisuData *data
); gboolean visu_data_removeTimeout (VisuData *data
,guint timeoutId
); gboolean visu_data_reorder (VisuData *data
,VisuData *dataRef
); gboolean visu_data_replicate (VisuData *data
,float extension[3]
); gboolean visu_data_restore (VisuData *data
); void visu_data_setChangeElementFlag (VisuData *data
,gboolean changeElement
); void visu_data_setColorFunc (VisuData *data
,VisuDataColorFunc func
); void visu_data_setFileCommentary (VisuData *data
,gchar *commentary
,gint iSet
); void visu_data_setISubset (VisuData *data
,int iSet
); void visu_data_setNSubset (VisuData *data
,int nSet
); gboolean visu_data_setNewBasis (VisuData *data
,float matA[3][3]
,float O[3]
); gboolean visu_data_setNewBasisFromNodes (VisuData *data
,guint nO
,guint nA
,guint nB
,guint nC
); void visu_data_setNodeScalingFunc (VisuData *data
,VisuDataScalingFunc scaling
); VisuBox * visu_data_setTightBox (VisuData *data
); gboolean visu_data_setXYZtranslation (VisuData *data
,float xyz[3]
);
The main goal of V_Sim is to draw lists of elements. For example, when used to render atoms, a box that contains 24 silicon atoms and 46 germanium atoms is a box with two elements (silicon and germanium) where the silicon element has 24 nodes and the germanium element has 46 nodes. This module gives then methods to create nodes (see VisuElement to create and managed elements).
All nodes are stored in a structure called VisuNodes and VisuNodes is encapsulated in a VisuData for all not-node related information. V_Sim uses one VisuData per input file(s). This structure contains a list of pointers on all the VisuElement used in this file.
To iterate on nodes, one should use the provided iterators
(see VisuNodeArrayIter) methods, like visu_node_array_iter_next()
.
struct VisuDataClass { VisuNodeArrayClass parent; };
A short way to identify _VisuDataClass structure.
VisuNodeArrayClass |
the parent class. |
gboolean (*VisuDataColorFunc) (VisuData *visuData
,float rgba[4]
,VisuElement *ele
,VisuNode *node
);
This prototype is used to specify an optional method to associate a color with external values to each node.
|
a pointer to the calling object ; |
|
a VisuElement ; |
|
a VisuNode ; |
|
an 4 allocated float area to store the return values. [in][array fixed-size=4] |
Returns : |
TRUE if the node should take colour read in rgba . |
float (*VisuDataScalingFunc) (VisuData *visuData
,VisuNode *node
);
Interface for routine that need to rescale node
before drawing
them.
|
a pointer to the calling object ; |
|
a VisuNode ; |
Returns : |
the scaling factor. |
void visu_data_addFile (VisuData *data
,const gchar *file
,int kind
,ToolFileFormat *format
);
This method is used to add files
of type kind
to the data
. The file
attribute is copied. The format
argument can be null.
|
a VisuData object ; |
|
a string that points to a file ; |
|
an integer to qualify the file to add ; |
|
a file format. [allow-none] |
VisuNode * visu_data_addNodeFromElement (VisuData *data
,VisuElement *ele
,float xyz[3]
,gboolean reduced
,gboolean emitSignal
);
This method adds a new VisuNode to the specified VisuData. If
emitSignal
is TRUE, then PopulationIncrease signal is
triggered.
|
the VisuData where to add the new VisuNode ; |
|
the VisuElement kind of the new VisuNode ; |
|
its coordinates ;. [in][array fixed-size=3] |
|
coordinates are in reduced coordinates ; |
|
a boolean. |
Returns : |
a pointer to the newly created node. [transfer none] |
VisuNode * visu_data_addNodeFromElementName (VisuData *data
,const gchar *name
,float xyz[3]
,gboolean reduced
,gboolean emitSignal
);
This method adds a new VisuNode to the specified VisuData. If
emitSignal
is TRUE, then PopulationIncrease signal is
triggered.
|
the VisuData where to add the new VisuNode ; |
|
the name of the element ; |
|
its coordinates ;. [in][array fixed-size=3] |
|
coordinates are in reduced coordinates ; |
|
a boolean. |
Returns : |
a pointer to the newly created node. [transfer none] |
Since 3.6
VisuNode * visu_data_addNodeFromIndex (VisuData *data
,guint position
,float xyz[3]
,gboolean reduced
,gboolean emitSignal
);
This method adds a new VisuNode to the specified VisuData. Position must be
chosen between 0 and (ntype - 1) and corresponds to the position of the array
of VisuNodes of a VisuElement. If emitSignal
is TRUE, then
PopulationIncrease signal is triggered.
|
the VisuData where to add the new VisuNode ; |
|
a integer corresponding to the position of a VisuElement in the array **nodes in the structure; |
|
its coordinates ;. [in][array fixed-size=3] |
|
coordinates are in reduced coordinates ; |
|
a boolean. |
Returns : |
a pointer to the newly created node. [transfer none] |
guint visu_data_addTimeout (VisuData *data
,guint time
,GSourceFunc func
,gpointer user_data
);
This method is used to add the func
method to be called regularly at the period
time
. This methos calls in fact g_timeout_add()
with the given arguments. But
the source id is stored internaly and the timeout function is removed automatically
when the object data
is destroyed. It is convienient to add a method working
on the VisuData object that is called periodically during the life of te object.
|
a valid VisuData object ; |
|
the period of call in milliseconds ; |
|
the callback function to be called ;. [scope call] |
|
a pointer to some user defined informations. [closure] |
Returns : |
the source id if the calling method need to work with it. To remove
the callback, don't use g_source_remove() but visu_data_removeTimeout()
to inform the VisuData object that this source has been removed and
not to remove it when the object will be destroyed. |
GList * visu_data_class_getAllObjects (void
);
This methods is used to retrieve all VisuObject currently allocated in V_Sim. It is usefull to apply some changes on all objects (resources for example).
Returns : |
a list of V_Sim own VisuData objects. [transfer none][element-type VisuData*] |
gboolean visu_data_constrainedElementInTheBox (VisuData *data
,VisuElement *element
);
Check all the nodes of the specified element
and change their coordinates if they are out
of the bounding box. The position of each node is the result of the
sum of their own position and of the box translation.
|
a VisuData object ; |
|
a VisuElement object. |
Returns : |
if returns TRUE, the VisuNodeArray::PositionChanged signal should be emitted. |
gboolean visu_data_constrainedFree (VisuData *data
);
Return all the nodes to their original position, except for the global translation.
|
a VisuData object. |
Returns : |
if returns TRUE, the VisuNodeArray::PositionChanged signal should be emitted. |
gboolean visu_data_constrainedInTheBox (VisuData *data
);
It does the same things that visu_data_constrainedElementInTheBox()
but for all
the VisuElement of the given data
. I.e. it checks all the nodes and changes
their coordinates if they are out of the bounding box.
The position of each node is the result of the
sum of their own position and of the box translation.
|
a VisuData object. |
Returns : |
if returns TRUE, the VisuNodeArray::PositionChanged signal should be emitted. |
gboolean visu_data_forceXYZtranslation (VisuData *data
,float xyz[3]
);
Apply the given box translation without paying attention to the box
boundary conditions. See visu_data_setXYZtranslation()
for a method
respecting the periodicity.
|
a VisuData object. |
|
three floats in cartesian representation. [in][array fixed-size=3] |
Returns : |
if returns TRUE, the VisuNodeArray::PositionChanged signal should be emitted. |
Since 3.7
void visu_data_freePopulation (VisuData *data
);
This method frees only the allocated memory that deals with the nodes (i.e. everything except the data of the files, the properties and the setColor method.
|
a VisuData to be freed. |
gfloat visu_data_getAllNodeExtens (VisuData *dataObj
,VisuBox *box
);
Calculate the longest distance between the surface of box
(without
extension) and all the nodes. If box
is NULL, then the internal
box of dataObj
is used.
|
a VisuData object. |
|
a VisuBox object. [allow-none] |
Returns : |
the longest distance between the surface of box (without
extension) and all the nodes. |
Since 3.7
gboolean visu_data_getChangeElementFlag (VisuData *data
);
V_Sim can use a flag set on data
object to know if data
has exactly the same
VisuElement list than the previously rendered one.
|
a VisuData object. |
Returns : |
TRUE if the previously rendered VisuData object has had the same VisuElement list than the given one, FALSE otherwise. |
VisuNodeInfo * visu_data_getDistanceList (VisuData *data
,guint nodeId
,float *minVal
);
This routine creates an array of VisuNodeInfo, storing for each
node its node id and its distance to nodeId
. The periodicity is
NOT taken into account. The array is not distance sorted, but if
minVal
is provided, it will contain the minimal distance between
nodeId
and the other nodes.
|
a VisuData object ; |
|
a node id. |
|
a location for a float. |
Returns : |
an array of VisuNodeInfo of size the number of nodes. It
is terminated by nodeId value itself. |
Since 3.5
const gchar * visu_data_getFile (VisuData *data
,int kind
,ToolFileFormat **format
);
This prototype is used to retrieve stored
files identify by their kind
.
|
a VisuData object. |
|
an integer to qualify the required file ; |
|
a location for a file format (can be NULL). |
Returns : |
the name of a file (it should not be deleted). |
gchar * visu_data_getFileCommentary (VisuData *data
,gint iSet
);
Get the commentary associated to the given data
, for the given
node set.
|
a VisuData object ; |
|
an integer (>= 0). |
Returns : |
a string description (possibly empty). This string is own by V_Sim and should not be freed. |
gchar * visu_data_getFilesAsLabel (const VisuData *data
);
Creates a label using the list of files used to defined this data
separated by dashes.
|
a VisuData object. |
Returns : |
a newly created string with the filenames. If no filename
were used to defined data , the function returns NULL. |
Since 3.6
int visu_data_getISubset (VisuData *data
);
Retrieve the id of the current set of data (ordered as in C, beginning at 0).
|
a VisuData object. |
Returns : |
the id of the set of nodes currently loaded, -1 if none. |
int visu_data_getNSubset (VisuData *data
);
Retrieve the number of available sets of nodes for this VisuData,
see visu_data_setNSubset()
.
|
a VisuData object. |
Returns : |
the number of set of nodes (1 is default). |
gboolean visu_data_getNodeBoxFromCoord (VisuData *data
,float xcart[3]
,int nodeBox[3]
);
This method retrieves the value of the box associated to the coordinates of the node (with respect to the unit cell).
|
a VisuData object. |
|
the coordinates of a node. [in][array fixed-size=3] |
|
the array to store the box of the node. [in][array fixed-size=3] |
Returns : |
TRUE if everything went well, FALSE otherwise. The box is stored in the nodeBox array. |
gboolean visu_data_getNodeBoxFromNumber (VisuData *data
,guint nodeId
,int nodeBox[3]
);
This method retrieves the value of the box associated to a node (with respect to the unit cell).
|
a VisuData object. |
|
the index of the node considered. |
|
the array to store the box of the node. [in][array fixed-size=3] |
Returns : |
TRUE if everything went well, FALSE otherwise. The box is stored in the nodeBox array. |
void visu_data_getNodeCoordinates (VisuData *data
,VisuNode *node
,float *x
,float *y
,float *z
);
Wrapper for the function visu_data_getNodePosition()
in case of call
from python.
|
a VisuData object ; |
|
a VisuNode object ; |
|
the x coordinate. [out caller-allocates] |
|
the y coordinate. [out caller-allocates] |
|
the z coordinate. [out caller-allocates] |
Since 3.6
void visu_data_getNodePosition (VisuData *data
,VisuNode *node
,float coord[3]
);
Position of nodes are subject to various translations and different transformations. Their coordinates should not be access directly through node.[xyz]. This method is used to retrieve the given node position.
float visu_data_getNodeScalingFactor (VisuData *data
,VisuNode *node
);
One can modify the size of a given node using a routine set by
visu_data_setNodeScalingFunc()
. By default the scaling is 1.
|
a VisuData object. |
|
a VisuNode object. |
Returns : |
the scaling factor to be applied to node node . |
Since 3.5
void visu_data_getNodeUserPosition (VisuData *data
,VisuNode *node
,float coord[3]
);
This routine is equivalent to visu_data_getNodePosition()
except
that it's not applying internal box translation for non periodic
directions.
|
a VisuData object ; |
|
a VisuNode object ; |
|
an array of 3 floating point values to store the position. [array fixed-size=3][out caller-allocates] |
Since 3.7
gboolean visu_data_getTranslationStatus (VisuData *data
);
When a translation is applied (even with a [0,0,0] vector), the nodes are shifted to be in the box. This routine returns the translation status of all nodes. If one of them is translated, then return value is TRUE.
|
a VisuData object. |
Returns : |
if one of the nodes is shifted. |
gboolean visu_data_getUserColor (VisuData *data
,VisuElement *ele
,VisuNode *node
,float rgba[4]
);
If a user defined color has been set (see
visu_data_setColorFunc()
), then call this method to obtain a color
for the given node.
|
a VisuData object ; |
|
a VisuElement object ; |
|
a VisuNode object ; |
|
a location to store the color. [array fixed-size=4] |
Returns : |
TRUE if a user color has been defined. |
Since 3.6
float * visu_data_getXYZtranslation (VisuData *data
);
The nodes are rendered at thier coordinates plus a translation. This method allows to retrieve that translation.
|
a VisuData object. |
Returns : |
a newly allocated
array of 3 floats. It should be freed with a call to free() after
use. [array fixed-size=3][transfer full]
|
gboolean visu_data_hasUserColorFunc (VisuData *data
);
Test the existence of a user defined colourisation function.
|
a VisuData object. |
Returns : |
TRUE if a user color function has been defined with
visu_data_setColorFunc() . |
Since 3.6
VisuData * visu_data_new (void
);
This creates an empty VisuData object.
Returns : |
a newly created VisuData object (its ref count is set to 1). |
VisuData * visu_data_new_withFiles (const gchar **files
);
This creates an empty VisuData object with filename set to be ready to be loaded.
|
a list of names. [element-type filename][array zero-terminated=1] |
Returns : |
a newly created VisuData object (its ref count is set to 1). |
Since 3.7
void visu_data_removeAllFiles (VisuData *data
);
This method is used to empty the list of
known file from the given data
.
|
a VisuData object. |
gboolean visu_data_removeTimeout (VisuData *data
,guint timeoutId
);
This method is used to remove a timeout that has been associated to the given
data
(see visu_data_addTimeout()
).
|
a valid VisuData object ; |
|
a source id. |
Returns : |
TRUE if the source has been found and removed. |
gboolean visu_data_reorder (VisuData *data
,VisuData *dataRef
);
This routine modifies the node ordering of data
using the order in
dataRef
. The association is done by nearest neigbours conditions.
|
a VisuData object, to reorder. |
|
a VisuData object, to take the order from. |
Returns : |
TRUE is the reordering is successfull (i.e. all nodes of
data correspond to one of dataRef ). |
Since 3.6
gboolean visu_data_replicate (VisuData *data
,float extension[3]
);
This routine will create (or remove) nodes to expand the initial box to the required size. An extension of 0 means no extension, i.e. the initial box. The extension is done symmetrically in each direction toward negative and positive direction.
To remove added nodes, see visu_data_restore()
.
|
a VisuData object ; |
|
three floating point values ;. [in][array fixed-size=3] |
Returns : |
TRUE if the redraw should be done. |
gboolean visu_data_restore (VisuData *data
);
Remove all nodes that have been added by a visu_data_replicate()
call.
|
a VisuData object. |
Returns : |
TRUE if some nodes has been indeed removed. |
void visu_data_setChangeElementFlag (VisuData *data
,gboolean changeElement
);
This method is mainly used by internal gears to set a flag. This flag control
if the data
object has the same VisuElement objects than the previously rendered one.
|
a VisuData object ; |
|
a boolean. |
void visu_data_setColorFunc (VisuData *data
,VisuDataColorFunc func
);
This is a little trick to colorized the nodes. It should not be used since it will probably be different in future release.
|
a VisuData object ; |
|
a method that colorize the nodes. [scope call] |
void visu_data_setFileCommentary (VisuData *data
,gchar *commentary
,gint iSet
);
This method is used to store a description of the given data
. This
string is copied and commentary
can be freed. Before using this
method, the number of possible node sets must have been defined
using visu_data_setNSubset()
, if not, only iSet == 0 is allowed.
|
a VisuData object ; |
|
the message to be stored (null terminated) ; |
|
an integer. |
void visu_data_setISubset (VisuData *data
,int iSet
);
Change the current id of the set of data (ordered as in C, beginning at 0).
|
a VisuData object ; |
|
an integer. |
void visu_data_setNSubset (VisuData *data
,int nSet
);
Change the number of available sets of nodes for this
VisuData. This has a side effect to delete all previously saved
file commentaries (see visu_data_setFileCommentary()
).
|
a VisuData object ; |
|
an integer. |
gboolean visu_data_setNewBasis (VisuData *data
,float matA[3][3]
,float O[3]
);
Change the basis set of data
according to the new definition given
by matA
and O
. Nodes outside the new box are killed. See also
visu_data_setNewBasisFromNodes()
for a convenient function using
nodes as basis set definition.
|
a VisuData object. |
|
a basis set definition. |
|
the origin cartesian coordinates. |
Returns : |
TRUE if the new basis set is valid. |
Since 3.6
gboolean visu_data_setNewBasisFromNodes (VisuData *data
,guint nO
,guint nA
,guint nB
,guint nC
);
Change the basis set by providing the new basis set from a list of
nodes. See also visu_data_setNewBasis()
. Nodes outside the new box
are killed.
|
a VisuData object. |
|
the index of node as origin. |
|
the index of node on X axis. |
|
the index of node as Y axis. |
|
the index of node as Z axis. |
Returns : |
TRUE if the new basis set is valid. |
Since 3.6
void visu_data_setNodeScalingFunc (VisuData *data
,VisuDataScalingFunc scaling
);
Change the scaling routine when nodes are drawn.
|
a VisuData object ; |
|
a scaling routine. [scope call] |
Since 3.5
VisuBox * visu_data_setTightBox (VisuData *data
);
Calculate the box geometry to have a tight box in directions that
are not periodic. If some directions are still periodic, the box
size in these directions should be setup first with
visu_box_setGeometry()
.
gboolean visu_data_setXYZtranslation (VisuData *data
,float xyz[3]
);
This set the translations of the specified VisuData whatever previous values. The translation is done in the orthonormal referential, not the referential of the box.
|
a VisuData object ; |
|
an array of floating point values. [in][array fixed-size=3] |
Returns : |
if returns TRUE, the VisuNodeArray::PositionChanged signal should be emitted. |
"totalEnergy"
property"totalEnergy" gdouble : Read / Write / Construct
Total energy of the system (eV).
Allowed values: [-G_MAXFLOAT,G_MAXFLOAT]
Default value: 3.40282e+38
"FilesChanged"
signalvoid user_function (VisuData *dataObj,
guint arg1,
gpointer user_data) : No Hooks
Gets emitted when one file of dataObj
is set.
|
the object which received the signal ; |
|
user data set when the signal handler was connected. |
Since 3.7
"TranslationsChanged"
signalvoid user_function (VisuData *dataObj,
gpointer user_data) : No Hooks
Gets emitted when translations are changed. At that point, node coordinates are all different, but to update on node positions, it's better to listen to VisuNodeArray::PositionChanged.
|
the object which received the signal ; |
|
user data set when the signal handler was connected. |
Since 3.7
"objectFreed"
signalvoid user_function (VisuData *dataObj,
gpointer user_data) : No Hooks
Gets emitted when the object is been destroyed. All external objects having a reference on this VisuData should clean it.
|
the object which received the signal ; |
|
user data set when the signal handler was connected. |
Since 3.3