## 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