## visu_extension

visu_extension — All objects drawn by V_Sim are defined in by a OpenGLExtension object

## Synopsis

    struct      OpenGLExtension_struct;
    typedef     OpenGLExtension;
    void        (*rebuildObjectListFunc)        (VisuData *dataObj);
    #define     OPENGL_EXTENSION_PRIORITY_FIRST
    #define     OPENGL_EXTENSION_PRIORITY_HIGH
    #define     OPENGL_EXTENSION_PRIORITY_NORMAL
    #define     OPENGL_EXTENSION_PRIORITY_LOW
    #define     OPENGL_EXTENSION_PRIORITY_LAST

    OpenGLExtension* OpenGLExtension_new        (char *name,
                                                 char *description,
                                                 int objectListId,
                                                 rebuildObjectListFunc rebuild);
    void        OpenGLExtension_free            (OpenGLExtension *extension);
    GList*      OpenGLExtensionGet_list         ();
    int         OpenGLExtensionGet_active       (OpenGLExtension *extension);
    void        OpenGLExtensionSet_active       (OpenGLExtension *extension,
                                                 int value);
    void        OpenGLExtensionSet_priority     (OpenGLExtension *extension,
                                                 int priority);
    void        OpenGLExtensionSet_saveOpenGLState
                                                (OpenGLExtension *extension,
                                                 gboolean saveState);
    void        OpenGLExtensionSet_sensitiveToRenderingMode
                                                (OpenGLExtension *extension,
                                                 gboolean status);
    gboolean    OpenGLExtensionSet_preferedRenderingMode
                                                (OpenGLExtension *extension,
                                                 gint value);
    void        OpenGLExtensionRegister         (OpenGLExtension *extension);
    void        OpenGLExtensionRemove           (OpenGLExtension *extension);
    void        callAllExtensionsLists          ();
    void        rebuildAllExtensionsLists       (VisuData *dataObj);

    int         initOpenGLExtensions            ();
    void        loadExtensions                  ();

## Description

All objects that are drawn by V_Sim are handled by a OpenGLExtension object. Such an object has an OpenGL list. This list is only COMPILED. When V_Sim receives the 'OpenGLAskForReDraw' or the 'OpenGLForceReDraw' signals, each list of all known OpenGLExtension are excecuted. This excecution can be canceled if the used flag of the OpenGLExtension object is set to FALSE. The order in which the lists are called depends on the priority of the OpenGLExtension object. This priority is set to OPENGL_EXTENSION_PRIORITY_NORMAL as default value, but it can be tune by a call to `OpenGLExtensionSet_priority()`. This priority is an integer, the lower it is, the sooner the list is excecuted.

The method `registerOpenGLExtension()` is used to declare to V_Sim that there is a new OpenGLExtension object available. This allows to create extension when V_Sim is already running. Nevertheless, an extension must be initialized in the initialisation process, it is better to add an initOpenGLExtensionFunc method in the listInitExtensionFunc array declared in extensions/externalOpenGLExtensions.h.

Once again, the OpenGL list corresponding to an OpenGL extension is COMPILE only. Then, OpenGL methods like `glIsenabled()` are totally unusefull because it is called when the list is compiled not when the list is called. If the extension needs to alter some OpenGL state, such as desable GL_LIGHTING, it needs to set a flag for the extension. With this flag, V_Sim will save the OpenGL states and restore it when the list is called. Use `OpenGLExtensionSet_saveOpenGLState()` to set this flag.

## Details

### struct OpenGLExtension_struct

    struct OpenGLExtension_struct {
      /* Some variable to describe this OpenGL extension.
         The attribute name is mandatory since it is
         used to identify the method. */
      char* name;
      char* description;

      /* The id of the possible objects list brings by
         the extension is refered by this int. */
      int objectListId;

      /* Function called to rebuild the object list of the extension. */
      rebuildObjectListFunc rebuild;

      /* A priority for the extension. */
      int priority;

      /* If set, V_Sim save the OpenGL state before the list
         id is called and restore all states after. */
      gboolean saveState;

      /* Fine tune of rendering mode (Wireframe, smooth...).
         The flag isSensitiveToRenderingMode define is the
         extension cares about rendering mode. This flag is FALSE
         by default. When FALSE, the global value for rendering
         mode is used. Otherwise the value is stored in
         preferedRenderingMode. */
      gboolean isSensitiveToRenderingMode;
      gint preferedRenderingMode;

      /* A boolean to know if this extension is actually used
         or not. */
      int used;
    };

This structure allows the user to store data about an OpenGL extension.

char *`name`; | the name of the extension in UTF-8 ;
char *`description`; | a short text in UTF-8 ;
int `objectListId`; | the id of the OpenGL list that represent this extension. This id is called whenever the extension need to be drawn ;
rebuildObjectListFunc `rebuild`; | method called when the OpenGL context has changed and the extension need to be recomputed ;
int `priority`; | control the order of drawing ;
gboolean `saveState`; | if TRUE, all OpenGL parameters are saved and will be restored after the extension has been called ;
gboolean `isSensitiveToRenderingMode`; | if TRUE, the extension can be drawn using a rendering mode different from the other extension (smooth, wireframe...) ;
gint `preferedRenderingMode`; | the specific rendering mode ;
int `used`; | if FALSE, the OpenGL id is skipped when redraw is necessary.

### OpenGLExtension

    typedef struct OpenGLExtension_struct OpenGLExtension;

Common name to refer to a OpenGLExtension_struct.

### rebuildObjectListFunc ()

    void        (*rebuildObjectListFunc)        (VisuData *dataObj);

Prototypes used to recreate OpenGL list of objects for each extension.

`dataObj` : | the VisuData object to be rebuilt.

### OPENGL_EXTENSION_PRIORITY_FIRST

    #define OPENGL_EXTENSION_PRIORITY_FIRST 0

An extension with this priority is drawn first.

### OPENGL_EXTENSION_PRIORITY_HIGH

    #define OPENGL_EXTENSION_PRIORITY_HIGH 20

An extension with this priority is quickly drawn.

### OPENGL_EXTENSION_PRIORITY_NORMAL

    #define OPENGL_EXTENSION_PRIORITY_NORMAL 50

An extension with this priority is drawn after the higher priorities.

### OPENGL_EXTENSION_PRIORITY_LOW

    #define OPENGL_EXTENSION_PRIORITY_LOW 80

An extension with this priority is drawn among last extensions.

### OPENGL_EXTENSION_PRIORITY_LAST

    #define OPENGL_EXTENSION_PRIORITY_LAST 100

An extension with this priority is drawn last.

### OpenGLExtension_new ()

    OpenGLExtension* OpenGLExtension_new        (char *name,
                                                 char *description,
                                                 int objectListId,
                                                 rebuildObjectListFunc rebuild);

Create a new OpenGLExtension with the specified name, description and OpenGL object list. The priority is set by default to OPENGL_EXTENSION_PRIORITY_NORMAL. The flag used to store the OpenGL state is put to FALSE by default (see `OpenGLExtensionSet_saveOpenGLState()` to chance it).

`name` : | name of the extension (must be non null),
`description` : | a brief description of the extension (can be null),
`objectListId` : | an int to identify an list of OpenGL objects (null if this extension as no OpenGL object,
`rebuild` : | handler to a method that is called every time V_Sim needs to create again the OpenGL object list. If NULL, nothing is called.
Returns : | the new OpenGLExtension or null if something wrong happens.

### OpenGLExtension_free ()

    void        OpenGLExtension_free            (OpenGLExtension *extension);

Free all the allocated attributes of the specified method.

`extension` : | the extension to delete.

### OpenGLExtensionGet_list ()

    GList*      OpenGLExtensionGet_list         ();

This method is used to get the list of all registered OpenGLExtension. This list is own by V_Sim and should not be freed.

Returns : | the list of all OpenGLExtension.

### OpenGLExtensionGet_active ()

    int         OpenGLExtensionGet_active       (OpenGLExtension *extension);

Get if the extension is used or not. If not its ObjectList is not rendered.

`extension` : | the extension.
Returns : | 1 if used, 0 otherwise.

### OpenGLExtensionSet_active ()

    void        OpenGLExtensionSet_active       (OpenGLExtension *extension,
                                                 int value);

Set if an extension is actually used or not.

`extension` : | the extension,
`value` : | the new value.

### OpenGLExtensionSet_priority ()

    void        OpenGLExtensionSet_priority     (OpenGLExtension *extension,
                                                 int priority);

Extentions are drawn in an order that depends on their priority. The lower is the number, the sooner the extension is drawn. Flags, such as OPENGL_EXTENSION_PRIORITY_NORMAL or OPENGL_EXTENSION_PRIORITY_LOW, can be used or user defined values are also possible.

`extension` : | a OpenGLExtension object ;
`priority` : | an integer value.

### OpenGLExtensionSet_saveOpenGLState ()

    void        OpenGLExtensionSet_saveOpenGLState
                                                (OpenGLExtension *extension,
                                                 gboolean saveState);

If the extension needs to change some OpenGL state (to disable the fog for example, or the cullface), a flag should be set to enable V_Sim to restore the right values after the extensio have been called. Because the OpenGL list of an extension is just GL_COMPILE the extension can't just save and restore state itself because when the list is called, the state can have been changed.

`extension` : | a OpenGLExtension object ;
`saveState` : | an boolean value.

### OpenGLExtensionSet_sensitiveToRenderingMode ()

    void        OpenGLExtensionSet_sensitiveToRenderingMode
                                                (OpenGLExtension *extension,
                                                 gboolean status);

If `status` is TRUE, when the extension is rendered, OpenGL context is switched to the rendering mode preferd for the extension. Use `OpenGLExtensionSet_preferedRenderingMode()` to choose one.

`extension` : | a OpenGLExtension object ;
`status` : | an boolean value.

### OpenGLExtensionSet_preferedRenderingMode ()

    gboolean    OpenGLExtensionSet_preferedRenderingMode
                                                (OpenGLExtension *extension,
                                                 gint value);

This method is used to specify the rendering mode that the extension should use to be drawn (if the sensitive flag has been set, see `OpenGLExtensionSet_sensitiveToRenderingMode()`). If the `value` is set to -1, the extension follows the global setting for rendering mode.

`extension` : | a OpenGLExtension object ;
`value` : | see RenderingModeId to choose one or -1.
Returns : | TRUE if the "OpenGLAskForReDraw" should be emitted.

### OpenGLExtensionRegister ()

    void        OpenGLExtensionRegister         (OpenGLExtension *extension);

A method used by user to registered a new extension.

`extension` : | an extension.

### OpenGLExtensionRemove ()

    void        OpenGLExtensionRemove           (OpenGLExtension *extension);

This method is used to removed fom the list of registered OpenGLExtension the given one. Removing `extension` does not free it.

`extension` : | an extension.

### callAllExtensionsLists ()

    void        callAllExtensionsLists          ();

For each registered extension that has a valid list (id > 1000), it calls it with glCallList.

### rebuildAllExtensionsLists ()

    void        rebuildAllExtensionsLists       (VisuData *dataObj);

For each registered extension that has a valid rebuild method, it calls it.

`dataObj` : | the VisuData object to be rebuilt.

### initOpenGLExtensions ()

    int         initOpenGLExtensions            ();

Initialise all the variable of this part. It calls all the elements in `listInitExtensionFunc` (that stores the init function of the extensions). If these elements return valid OpenGLExtension, they are registered through a call to `registerOpenGLExtension()`.

Returns : | 1 if everything goes allright during the initialisation.

### loadExtensions ()

    void        loadExtensions                  ();

This method is used when V_Sim is initialized and should not be called elsewhere. For each valid init method found in listInitExtensionFunc, it is called.