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

## Synopsis

    struct              OpenGLExtension_struct;
    typedef             OpenGLExtension;
    OpenGLExtension*    (*OpenGLExtensionInitFunc)          ();
    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                 (const gchar *name,
                                                             const gchar *nameI18n,
                                                             const gchar *description,
                                                             int objectListId,
                                                             rebuildObjectListFunc rebuild);
    void                OpenGLExtension_free                (OpenGLExtension *extension);
    OpenGLExtension*    OpenGLExtensionGet_fromName         (const gchar *name);
    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,
                                                             RenderingModeId value);
    void                OpenGLExtensionRegister             (OpenGLExtension *extension);
    void                OpenGLExtensionRemove               (OpenGLExtension *extension);
    void                OpenGLExtensionCall_list            (const char *name,
                                                             gboolean lastOnly);
    void                OpenGLExtensionRebuild_list         (VisuData *dataObj,
                                                             const char *name);
    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;

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

### OpenGLExtension

    typedef struct OpenGLExtension_struct OpenGLExtension;

Common name to refer to a OpenGLExtension_struct.

### OpenGLExtensionInitFunc ()

    OpenGLExtension*    (*OpenGLExtensionInitFunc)          ();

Prototype of the functions used to initialise a new drawing capability.

Returns : | a newly allocated drawing extension.

### 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                 (const gchar *name,
                                                             const gchar *nameI18n,
                                                             const gchar *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, in ASCII, used as id in the config files,
`nameI18n` : | name in UTF8 that can be translated and shown to user,
`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_fromName ()

    OpenGLExtension*    OpenGLExtensionGet_fromName         (const gchar *name);

Look for the extension with this name.

`name` : | a string.
Returns : | the extension or NULL if none.

### 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,
                                                             RenderingModeId 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 followGeneralSetting, the extension follows the global setting for rendering mode.

`extension` : | a OpenGLExtension object ;
`value` : | see RenderingModeId to choose one.
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.

### OpenGLExtensionCall_list ()

    void                OpenGLExtensionCall_list            (const char *name,
                                                             gboolean lastOnly);

Select the OpenGLExtension matching the given `name` and call it. To draw all of them, use `callAllExtensionsLists()` instead.

`name` : | the name of the list to be called.

### OpenGLExtensionRebuild_list ()

    void                OpenGLExtensionRebuild_list         (VisuData *dataObj,
                                                             const char *name);

Select the OpenGLExtension matching the given `name` and rebuild it. This routine does not sort the extension on their priority and should be used only to draw some selected extensions. To draw all of them, use `rebuildAllExtensionsLists()` instead.

`dataObj` : | the VisuData object to be rebuilt ;
`name` : | the name of the list to be rebuilt.

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