## visu_rendering

visu_rendering — Methods to create and add new rendering methods.

## Synopsis

    struct              RenderingMethod_struct;
    typedef             RenderingMethod;
    typedef             RenderingFormatLoad;
    gboolean            (*renderingFormatLoadFunc)          (VisuData *data,
                                                             const gchar *filename,
                                                             FileFormat *format,
                                                             int nSet,
                                                             GError **error);
    enum                RenderingErrorFlag;
    RenderingMethod*    renderingMethod_new                 (char *name,
                                                             char *printName,
                                                             char *description,
                                                             int nbFileType,
                                                             renderingMethodLoadFunc loadMethod);
    void                renderingMethod_free                (RenderingMethod *method);
    void                renderingMethodSet_icon             (RenderingMethod *method,
                                                             char *path);
    void                renderingMethodSet_fileType         (RenderingMethod *method,
                                                             GList *fileTypeList,
                                                             int fileType,
                                                             gchar *name);
    int                 renderingMethodGet_nbFileType       (RenderingMethod *method);
    GList*              renderingMethodGet_fileType         (RenderingMethod *method,
                                                             int fileType);
    gchar*              renderingMethodGet_fileTypeName     (RenderingMethod *method,
                                                             int fileType);
    float               renderingMethodGet_sizeOfElement    (RenderingMethod *method,
                                                             VisuElement *ele);
    void                renderingMethodAdd_fileFormat       (RenderingMethod *method,
                                                             FileFormat *fmt,
                                                             int fileType);
    gint                renderingMethodCompare_priority     (gconstpointer a,
                                                             gconstpointer b);
    void                registerRenderingMethod             (RenderingMethod *method);

    RenderingMethod*    (*RenderingMethodInitFunc)          ();
    gboolean            (*renderingMethodLoadFunc)          (VisuData *data,
                                                             FileFormat *format,
                                                             int nSet,
                                                             GError **error);

    int                 (*createOpenGLElementFunc)          (VisuData *visuData,
                                                             VisuElement *ele);
    void                (*createOpenGLNodeFunc)             (VisuData *visuData,
                                                             VisuNode *node,
                                                             VisuElement *ele);
    float               (*getExtensOfNodeFunc)              (VisuElement *ele);
    void                setOpenGLMethods                    (RenderingMethod *method,
                                                             createOpenGLElementFunc createElement,
                                                             createOpenGLNodeFunc createNode,
                                                             getExtensOfNodeFunc getSize);

    void                setRenderingMethodInUse             (RenderingMethod *method);
    int                 setRenderingMethodByName            (char *name);
    RenderingMethod*    getRenderingMethodInUse             ();
    GList*              renderingMethodGet_AllMethods       ();

    int                 initRenderingMethods                ();

## 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, use `renderingMethod_new()`. 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 FileFormat. 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 RenderingMethod_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 `visuDataGet_nodePosition()` to retrieve the position and translate the node accordingly.

## Details

### struct RenderingMethod_struct

    struct RenderingMethod_struct;

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.

### RenderingMethod

    typedef struct RenderingMethod_struct RenderingMethod;

Short name to address RenderingMethod_struct objects.

### RenderingFormatLoad

    typedef struct RenderingFormatLoad_struct RenderingFormatLoad;

Short way to address RenderingFormatLoad_struct objects.

### renderingFormatLoadFunc ()

    gboolean            (*renderingFormatLoadFunc)          (VisuData *data,
                                                             const gchar *filename,
                                                             FileFormat *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 RenderingMethod can have several renderingFormatLoadFunc 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 FileFormat 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).

### enum RenderingErrorFlag

    typedef enum
      {
        RENDERING_ERROR_METHOD,   /* Error from the rendering method. */
        RENDERING_ERROR_FILE,     /* Error when opening. */
        RENDERING_ERROR_FORMAT    /* Wrongness in format. */
      } 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.

### renderingMethod_new ()

    RenderingMethod*    renderingMethod_new                 (char *name,
                                                             char *printName,
                                                             char *description,
                                                             int nbFileType,
                                                             renderingMethodLoadFunc loadMethod);

Method used to create rendering methods. The `nbFileType` argument is used to declare the number of files that the method needs to read to render a set of data. Use `renderingMethodSet_fileType()` method to set some FileFormat for each kind.

`name` : | a string to label the method ;
`printName` : | a string to label the method that can be safely translated ;
`description` : | a string to describe the method ;
`nbFileType` : | an integer ;
`loadMethod` : | a `loadDataFromFileFunc` which the load function of the method.
Returns : | the newly created method of a null pointer if something goes wrong.

### renderingMethod_free ()

    void                renderingMethod_free                (RenderingMethod *method);

Free all the allocated attributes of the specified method.

`method` : | the method to delete.

### renderingMethodSet_icon ()

    void                renderingMethodSet_icon             (RenderingMethod *method,
                                                             char *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.

### renderingMethodSet_fileType ()

    void                renderingMethodSet_fileType         (RenderingMethod *method,
                                                             GList *fileTypeList,
                                                             int fileType,
                                                             gchar *name);

Store a list of FileFormat for the kind of file `fileType`. The `name` argument is copied. but warning, the `fileTypeList` GList* is not copied.

`method` : | a method ;
`fileTypeList` : | a list of FileFormat ;
`fileType` : | an integer used as a key, must >= 0 and < method->nbFilesType ;
`name` : | a string to shortly describe the kind of file type (not NULL).

### renderingMethodGet_nbFileType ()

    int                 renderingMethodGet_nbFileType       (RenderingMethod *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 RenderingMethod.

### renderingMethodGet_fileType ()

    GList*              renderingMethodGet_fileType         (RenderingMethod *method,
                                                             int fileType);

This method is used to get the file formats 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->nbFilesType.
Returns : | a GList* with the FileFormat. This GList should been considered read-only.

### renderingMethodGet_fileTypeName ()

    gchar*              renderingMethodGet_fileTypeName     (RenderingMethod *method,
                                                             int 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->nbFilesType.
Returns : | a string own by V_Sim. This string should been considered read-only.

### renderingMethodGet_sizeOfElement ()

    float               renderingMethodGet_sizeOfElement    (RenderingMethod *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.

### renderingMethodAdd_fileFormat ()

    void                renderingMethodAdd_fileFormat       (RenderingMethod *method,
                                                             FileFormat *fmt,
                                                             int fileType);

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

`method` : | a method ;
`fmt` : | a FileFormat ;
`fileType` : | an integer used as a key, must >= 0 and < method->nbFilesType.

### renderingMethodCompare_priority ()

    gint                renderingMethodCompare_priority     (gconstpointer a,
                                                             gconstpointer b);

Compare the priority field of the structures of the two arguments.

`a` : | a RenderingFormatLoad ;
`b` : | another RenderingFormatLoad.
Returns : | -1 if priority of a is higher (i.e. lower value) than the one of b.

### registerRenderingMethod ()

    void                registerRenderingMethod             (RenderingMethod *method);

A method used by user to registered a new method.

`method` : | a RenderingMethod.

### RenderingMethodInitFunc ()

    RenderingMethod*    (*RenderingMethodInitFunc)          ();

Prototype of the functions used to initialise a new rendering method.

Returns : | a newly created RenderingMethod.

### renderingMethodLoadFunc ()

    gboolean            (*renderingMethodLoadFunc)          (VisuData *data,
                                                             FileFormat *format,
                                                             int nSet,
                                                             GError **error);

Interface of functions that allow to load data. The filenames are retrieve from the given VisuData, using the `visuDataGet_file()` method. If no `format` argument is given, then the format should be guessed, otherwise, the given format is the one chosen by the the user. WARNING : this format may not be the right format since user selected. 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` : | an already allocated VisuData ;
`format` : | a pointer on a format (can be NULL if format is to be guessed) ;
`nSet` : | an integer ;
`error` : | a pointer to store a possible error, location must be initialized to (GError*)0.
Returns : | TRUE if everything goes right.

### createOpenGLElementFunc ()

    int                 (*createOpenGLElementFunc)          (VisuData *visuData,
                                                             VisuElement *ele);

Such functions are called whenever a newElement is registered.

`visuData` : | a VisuData object ;
`ele` : | a VisuElement ;
Returns : | an id representing an OpenGL list in which the element has been created.

### createOpenGLNodeFunc ()

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

### getExtensOfNodeFunc ()

    float               (*getExtensOfNodeFunc)              (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.

### setOpenGLMethods ()

    void                setOpenGLMethods                    (RenderingMethod *method,
                                                             createOpenGLElementFunc createElement,
                                                             createOpenGLNodeFunc createNode,
                                                             getExtensOfNodeFunc getSize);

This method is used to set the callback functions for the specified rendering method. These callbacks are used by the OpenGl part of the code. The `createElement` parameter is a method called to create an OpenGl list that draw the symbol corresponding to the element. The `createNode` parameter is called to position and drw the specified node. It should not create a list.

`method` : | a RenderingMethod ;
`createElement` : | a `createOpenGLElementFunc` ;
`createNode` : | a `createOpenGLNodeFunc` ;
`getSize` : | a `getExtensOfNodeFunc`.

### setRenderingMethodInUse ()

    void                setRenderingMethodInUse             (RenderingMethod *method);

Choose the method used to render the data.

`method` : | a RenderingMethod.

### setRenderingMethodByName ()

    int                 setRenderingMethodByName            (char *name);

Choose the method used to render the data.

`name` : | the name of a rendering method.
Returns : | 1 if the method exists and is set, 0 otherwise.

### getRenderingMethodInUse ()

    RenderingMethod*    getRenderingMethodInUse             ();

Get the current method used to render the data.

Returns : | the name of the currently used rendering method.

### renderingMethodGet_AllMethods ()

    GList*              renderingMethodGet_AllMethods       ();

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.

### initRenderingMethods ()

    int                 initRenderingMethods                ();

Initialise all the variable of this part. It is called by the main program at startup and should not be used by users.

Returns : | true if everything goes right.