VisuRendering

VisuRendering — Methods to create and add new rendering methods.

Synopsis

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);

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"                             : No Recursion
  "fileTypeChanged"                                : 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

struct VisuRendering

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

struct VisuRenderingClass {
  GObjectClass parent;

  VisuRenderingCreateElementFunc createElement;
  VisuRenderingGetElementGlId    getElementGlId;
  VisuRenderingCreateNodeFunc    createNode;
  VisuRenderingGetNodeExtendFunc getNodeExtend;
};

The structure for the VisuRenderingClass class.

GObjectClass parent;

the parent class.

VisuRenderingCreateElementFunc createElement;

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

VisuRenderingGetElementGlId getElementGlId;

a virtual method to get the OpenGL list id used for elements.

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.

VisuRenderingCreateElementFunc ()

int                 (*VisuRenderingCreateElementFunc)   (VisuElement *ele,
                                                         VisuGlView *view);

Such functions are called whenever a newElement is registered.

ele :

a VisuElement object ;

view :

a VisuGlView object.

Returns :

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

VisuRenderingCreateNodeFunc ()

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.

visuData :

a VisuData object ;

node :

a VisuElement ;

ele :

a VisuElement ;

eleGlId :

an identifier.

enum VisuRenderingErrorFlag

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.

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.

VisuRenderingGetElementGlId ()

int                 (*VisuRenderingGetElementGlId)      (VisuElement *ele);

This function is used to get the OpenGL list identifier for ele.

ele :

a VisuElement.

Returns :

an id.

Since 3.7


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.

VisuRenderingLoadFormatFunc ()

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.

data :

a VisuData object ;. [transfer full]

filename :

the access to the file to load ;

format :

a ToolFileFormat object (can be NULL) ;

nSet :

an integer ;

cancel :

a cancellable.

error :

a pointer to store possible errors.

Returns :

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

visu_rendering_addFileFormat ()

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.

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. [scope call]

visu_rendering_class_getErrorQuark ()

GQuark              visu_rendering_class_getErrorQuark  (void);

Internal function to handle error.

Returns :

a GQuark for VisuRendering method errors.

visu_rendering_createElement ()

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.

method :

a VisuRendering method.

element :

a VisuElement object.

view :

a VisuGlView object.

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,
                                                         int eleGlId);

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 or NULL. [allow-none]

eleGlId :

the OpenGL list id repsresenting ele or -1 to get the default one.

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. [element-type VisuRendering*][transfer none]

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


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_getElementGlId ()

int                 visu_rendering_getElementGlId       (VisuRendering *method,
                                                         VisuElement *ele);

This method is used to get the OpenGL identifier of a list for ele.

method :

a method ;

ele :

a VisuElement object.

Returns :

a OpenGL list identifier.

Since 3.7


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_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_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_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_load ()

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.

method :

a VisuRendering method.

data :

a new VisuData object to load into.

nSet :

the set id to read from.

cancel :

a cancellable.

error :

a location for possible error.

Returns :

TRUE on success.

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_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_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.

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)      : 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)      : No Hooks

TODO

obj :

the object emitting the signal.

user_data :

user data set when the signal handler was connected.

Since 3.6