VisuRendering

VisuRendering — Methods to create and add new rendering methods.

Synopsis

#define             VISU_ERROR_RENDERING
GQuark              visuRenderingClassGet_quark         (void);
enum                RenderingErrorFlag;
#define             VISU_RENDERING_TYPE
#define             VISU_RENDERING                      (obj)
#define             VISU_RENDERING_CLASS                (klass)
#define             IS_VISU_RENDERING_TYPE              (obj)
#define             IS_VISU_RENDERING_CLASS             (klass)
#define             VISU_RENDERING_GET_CLASS            (obj)
gboolean            (*VisuRenderingLoadFormatFunc)      (VisuData *data,
                                                         const gchar *filename,
                                                         ToolFileFormat *format,
                                                         int nSet,
                                                         GError **error);
int                 (*VisuRenderingCreateElementFunc)   (VisuElement *ele,
                                                         VisuOpenGLCamera *camera,
                                                         guint winSize);
void                (*VisuRenderingCreateNodeFunc)      (VisuData *visuData,
                                                         VisuNode *node,
                                                         VisuElement *ele);
float               (*VisuRenderingGetNodeExtendFunc)   (VisuElement *ele);
                    VisuRenderingPriv;
                    VisuRendering;
                    VisuRenderingClass;
GType               visu_rendering_get_type             (void);
void                visu_rendering_addFileFormat        (VisuRendering *method,
                                                         guint fileType,
                                                         ToolFileFormat *fmt,
                                                         guint priority,
                                                         VisuRenderingLoadFormatFunc loadFunc,
                                                         GDestroyNotify notify);
void                visu_rendering_setFileTypeLabel     (VisuRendering *method,
                                                         guint fileType,
                                                         const gchar *name);
void                visu_rendering_setFileFormat        (VisuRendering *meth,
                                                         guint fileType,
                                                         VisuRendering *from);
void                visu_rendering_setIcon              (VisuRendering *method,
                                                         const gchar *path);
gboolean            visu_rendering_load                 (VisuRendering *method,
                                                         VisuData *data,
                                                         ToolFileFormat *format,
                                                         int nSet,
                                                         GError **error);
const gchar*        visu_rendering_getName              (VisuRendering *method,
                                                         gboolean UTF8);
const gchar*        visu_rendering_getDescription       (VisuRendering *method);
guint               visu_rendering_getNFileTypes        (VisuRendering *method);
GList*              visu_rendering_getFileFormat        (VisuRendering *method,
                                                         guint fileType);
const gchar*        visu_rendering_getFileTypeName      (VisuRendering *method,
                                                         guint fileType);
const gchar*        visu_rendering_getIconPath          (VisuRendering *method);
float               visu_rendering_getSizeOfElement     (VisuRendering *method,
                                                         VisuElement *ele);
int                 visu_rendering_createElement        (VisuRendering *method,
                                                         VisuElement *element,
                                                         VisuOpenGLCamera *camera,
                                                         guint winSize);
void                visu_rendering_createNode           (VisuRendering *method,
                                                         VisuData *data,
                                                         VisuNode *node,
                                                         VisuElement *ele);
GList*              visu_rendering_getAllObjects        (void);
VisuRendering*      visu_rendering_getByName            (const gchar *name);

Object Hierarchy

  GObject
   +----VisuRendering
         +----VisuRenderingAtomic
         +----VisuRenderingSpin

Properties

  "description"              gchar*                : Read / Write
  "label"                    gchar*                : Read / Write
  "nFiles"                   guint                 : Read / Write / Construct Only
  "name"                     gchar*                : Read / Write / Construct Only

Signals

  "elementSizeChanged"                             : Run Last / No Recursion
  "fileTypeChanged"                                : Run Last / No Recursion / No Hooks

Description

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.

Details

VISU_ERROR_RENDERING

#define VISU_ERROR_RENDERING visuRenderingClassGet_quark()

visuRenderingClassGet_quark ()

GQuark              visuRenderingClassGet_quark         (void);

Internal function to handle error.

Returns :

a GQuark for VisuRendering method errors.

enum RenderingErrorFlag

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. */
  } RenderingErrorFlag;

Thiese are flags used when reading a file with a rendering method.

RENDERING_ERROR_METHOD

Error from the rendering method.

RENDERING_ERROR_FILE

Error when opening.

RENDERING_ERROR_FORMAT

Wrongness in format.

RENDERING_ERROR_CANCEL

the rendering operation has been cancelled.

VISU_RENDERING_TYPE

#define VISU_RENDERING_TYPE	     (visu_rendering_get_type ())

return the type of VisuRendering.


VISU_RENDERING()

#define VISU_RENDERING(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, VISU_RENDERING_TYPE, VisuRendering))

Cast the given obj into VisuRendering type.

obj :

a GObject to cast.

VISU_RENDERING_CLASS()

#define VISU_RENDERING_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, VISU_RENDERING_TYPE, VisuRenderingClass))

Cast the given klass into VisuRenderingClass.

klass :

a GObjectClass to cast.

IS_VISU_RENDERING_TYPE()

#define IS_VISU_RENDERING_TYPE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, VISU_RENDERING_TYPE))

Test if the given ogj is of the type of VisuRendering object.

obj :

a GObject to test.

IS_VISU_RENDERING_CLASS()

#define IS_VISU_RENDERING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, VISU_RENDERING_TYPE))

Test if the given klass is of the type of VisuRenderingClass class.

klass :

a GObjectClass to test.

VISU_RENDERING_GET_CLASS()

#define VISU_RENDERING_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, VISU_RENDERING_TYPE, VisuRenderingClass))

It returns the class of the given obj.

obj :

a GObject to get the class of.

VisuRenderingLoadFormatFunc ()

gboolean            (*VisuRenderingLoadFormatFunc)      (VisuData *data,
                                                         const gchar *filename,
                                                         ToolFileFormat *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 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.

data :

a VisuData object ;

filename :

the access to the file to load ;

format :

a ToolFileFormat object (can be NULL) ;

nSet :

an integer ;

error :

a pointer to store possible errors.

Returns :

FALSE if data is unchanged (wrong format), TRUE otherwise (even if some minor errors have happened).

VisuRenderingCreateElementFunc ()

int                 (*VisuRenderingCreateElementFunc)   (VisuElement *ele,
                                                         VisuOpenGLCamera *camera,
                                                         guint winSize);

Such functions are called whenever a newElement is registered.

ele :

a VisuElement object ;

camera :

a VisuOpenGLCamera object ;

winSize :

the minimum size of the rendering area.

Returns :

an id representing an OpenGL list in which the element has been created.

VisuRenderingCreateNodeFunc ()

void                (*VisuRenderingCreateNodeFunc)      (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.

visuData :

a VisuData object ;

node :

a VisuElement ;

ele :

a VisuElement.

VisuRenderingGetNodeExtendFunc ()

float               (*VisuRenderingGetNodeExtendFunc)   (VisuElement *ele);

This function is required to inform the OpenGL drawer and to adapt the maximum size of the drawing area.

ele :

a VisuElement.

Returns :

the geometrical size of the element.

VisuRenderingPriv

typedef struct _VisuRenderingPriv VisuRenderingPriv;

An opaque structure.

Since 3.6


VisuRendering

typedef struct _VisuRendering 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.


VisuRenderingClass

typedef struct {
  GObjectClass parent;

  VisuRenderingCreateElementFunc createElement;
  VisuRenderingCreateNodeFunc    createNode;
  VisuRenderingGetNodeExtendFunc getNodeExtend;
} VisuRenderingClass;

The structure for the VisuRenderingClass class.

GObjectClass parent;

the parent class.

VisuRenderingCreateElementFunc createElement;

a virtual method to create OpenGL shape for a given VisuElement.

VisuRenderingCreateNodeFunc createNode;

a virtual method to position and draw a specific VisuNode.

VisuRenderingGetNodeExtendFunc getNodeExtend;

a virtual method to get the size of a given VisuElement.

visu_rendering_get_type ()

GType               visu_rendering_get_type             (void);

This method returns the type of VisuRendering, use VISU_RENDERING_TYPE instead.

Returns :

the type of VisuRendering.

visu_rendering_addFileFormat ()

void                visu_rendering_addFileFormat        (VisuRendering *method,
                                                         guint fileType,
                                                         ToolFileFormat *fmt,
                                                         guint priority,
                                                         VisuRenderingLoadFormatFunc loadFunc,
                                                         GDestroyNotify notify);

Add a file format descriptor to the list of already known file formats of the key fileType.

method :

a method ;

fileType :

an integer used as a key, must >= 0 and < method->nFiles.

fmt :

a ToolFileFormat ;

priority :

the priority (lower sooner) ;

loadFunc :

the loading routine ;

notify :

not used.

visu_rendering_setFileTypeLabel ()

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.

method :

a method ;

fileType :

an integer used as a key, must >= 0 and < method->nFiles ;

name :

a string to shortly describe the kind of file type (not NULL).

visu_rendering_setFileFormat ()

void                visu_rendering_setFileFormat        (VisuRendering *meth,
                                                         guint fileType,
                                                         VisuRendering *from);

It copies the ToolFileFormat of method from to meth for the given fileType.

meth :

a VisuRendering object.

fileType :

a file kind id.

from :

a VisuRendering object.

Since 3.6


visu_rendering_setIcon ()

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.

method :

a method ;

path :

a path to an image file.

visu_rendering_load ()

gboolean            visu_rendering_load                 (VisuRendering *method,
                                                         VisuData *data,
                                                         ToolFileFormat *format,
                                                         int nSet,
                                                         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.

method :

a VisuRendering method.

data :

a new VisuData object to load into.

format :

a ToolFileFormat to read input files from (can be NULL).

nSet :

the set id to read from.

error :

a location for possible error.

Returns :

TRUE on success.

visu_rendering_getName ()

const gchar*        visu_rendering_getName              (VisuRendering *method,
                                                         gboolean UTF8);

Get its name (in UTF8 or not).

method :

a VisuRendering method.

UTF8 :

a boolean.

Returns :

a string, owned by V_Sim.

visu_rendering_getDescription ()

const gchar*        visu_rendering_getDescription       (VisuRendering *method);

Get its description (in UTF8).

method :

a VisuRendering method.

Returns :

a string, owned by V_Sim.

visu_rendering_getNFileTypes ()

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.

method :

a method.

Returns :

how many kind of files are handled by the given VisuRendering.

visu_rendering_getFileFormat ()

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.

method :

this VisuRendering object.

fileType :

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


visu_rendering_getFileTypeName ()

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.

method :

a method ;

fileType :

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.

visu_rendering_getIconPath ()

const gchar*        visu_rendering_getIconPath          (VisuRendering *method);

Get the location where to find the icon of the method.

method :

a VisuRendering method.

Returns :

a string, owned by V_Sim.

visu_rendering_getSizeOfElement ()

float               visu_rendering_getSizeOfElement     (VisuRendering *method,
                                                         VisuElement *ele);

This method is used to retrieve the radius of the sphere that contains the ele.

method :

a method ;

ele :

a VisuElement to get the size of.

Returns :

the radius of the given element.

visu_rendering_createElement ()

int                 visu_rendering_createElement        (VisuRendering *method,
                                                         VisuElement *element,
                                                         VisuOpenGLCamera *camera,
                                                         guint winSize);

Use the create element function of method to render element for the given zoom level.

method :

a VisuRendering method.

element :

a VisuElement object.

camera :

a VisuOpenGLCamera object.

winSize :

the window size.

Returns :

the OpenGL list id of this element.

Since 3.6


visu_rendering_createNode ()

void                visu_rendering_createNode           (VisuRendering *method,
                                                         VisuData *data,
                                                         VisuNode *node,
                                                         VisuElement *ele);

Create node at the right position calling OpenGL routines.

method :

a VisuRendering method.

data :

the VisuData object the node is taken from.

node :

a VisuNode of data.

ele :

the VisuElement of node.

Since 3.6


visu_rendering_getAllObjects ()

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.

visu_rendering_getByName ()

VisuRendering*      visu_rendering_getByName            (const gchar *name);

Get the corresponding VisuRendering method to name.

name :

a string.. type filename

Returns :

. transfer none.

Since 3.6

Property Details

The "description" property

  "description"              gchar*                : Read / Write

Description of the method.

Default value: ""


The "label" property

  "label"                    gchar*                : Read / Write

Label of the method.

Default value: ""


The "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


The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

Name of the method.

Default value: ""

Signal Details

The "elementSizeChanged" signal

void                user_function                      (VisuRendering *obj,
                                                        gfloat         size,
                                                        gpointer       user_data)      : Run Last / No Recursion

Emitted when the size of a element is changed.

obj :

the object emitting the signal.

size :

the new size.

user_data :

user data set when the signal handler was connected.

Since 3.6


The "fileTypeChanged" signal

void                user_function                      (VisuRendering *obj,
                                                        gpointer       user_data)      : Run Last / No Recursion / No Hooks

TODO

obj :

the object emitting the signal.

user_data :

user data set when the signal handler was connected.

Since 3.6