## visu_rendering

visu_rendering — Methods to create and add new rendering methods.

## Synopsis

    struct      RenderingMethod_struct;
    typedef     RenderingMethod;
    struct      RenderingFormatLoad_struct;
    typedef     RenderingFormatLoad;
    gboolean    (*renderingFormatLoadFunc)      (VisuData *data,
                                                 const gchar *filename,
                                                 FileFormat *format,
                                                 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);

    gboolean    (*renderingMethodLoadFunc)      (VisuData *data,
                                                 FileFormat *format,
                                                 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 {
      /* Some variable to describe this rendering method.
         The attribute name is mandatory since it is
         used to identify the method. */
      char* name;
      char* printName;
      char* description;
      /* A path to a small 16x16 image to represent the method.
         If null, no image is used. */
      char* icon;

      /* Dealing with file type. */
      /* Number of files required to render one set of data. */
      int nbFilesType;
      /* Types of files described by this rendering method. */
      GList **fileType;
      /* Label associated to this each kind of file. */
      gchar **fileTypeLabel;

      /* Pointer to the file functions. */
      renderingMethodLoadFunc loadMethod;

      /* Pointers to useful openGL methods. */
      createOpenGLElementFunc createElement;
      createOpenGLNodeFunc createNode;
      getExtensOfNodeFunc getExtensForElement;
    };

char *`name`; | a string describing the method (not NULL) ;
char *`printName`; | a string describing the method (not NULL) that can be safely translated ;
char *`description`; | a string to give a longer description to the method (can be NULL) ;
char *`icon`; | a path to a small 16x16 image to represent the method, if null, no image is used ;
int `nbFilesType`; | the number of files required to render one set of data, for example 2 for one file with positions and one file with orientations to represent a vector field ;
GList **`fileType`; | an array of GList* that contains FileFormat ;
gchar **`fileTypeLabel`; | an array of string that describes each kind of file ;
renderingMethodLoadFunc `loadMethod`; | a pointer to a method used to read input data ;
createOpenGLElementFunc `createElement`; | a pointer to a method used to create OpenGL lists for VisuElement ;
createOpenGLNodeFunc `createNode`; | a pointer to a method used to draw a given node ;
getExtensOfNodeFunc `getExtensForElement`; | not used.

### RenderingMethod

    typedef struct RenderingMethod_struct RenderingMethod;

Short name to address RenderingMethod_struct objects.

### struct RenderingFormatLoad_struct

    struct RenderingFormatLoad_struct {
      gchar* name;

      FileFormat *fmt;
      renderingFormatLoadFunc load;

      int priority;
    };

The priority argument is used when a file is tested to be opened. The smaller, the earlier the load method is tested.

gchar *`name`; | a descriptive name ;
FileFormat *`fmt`; | file formats associated to this load method ;
renderingFormatLoadFunc `load`; | the load method ;
int `priority`; | an int.

### RenderingFormatLoad

    typedef struct RenderingFormatLoad_struct RenderingFormatLoad;

Short way to address RenderingFormatLoad_struct objects.

### renderingFormatLoadFunc ()

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

`data` : | a VisuData object ;
`filename` : | the access to the file to load ;
`format` : | a FileFormat object (can be NULL) ;
`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.

### renderingMethodLoadFunc ()

    gboolean    (*renderingMethodLoadFunc)      (VisuData *data,
                                                 FileFormat *format,
                                                 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.

`data` : | an already allocated VisuData ;
`format` : | a pointer on a format (can be NULL if format is to be guessed) ;
`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.