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);
void        callAllExtensionsLists          ();
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 {
  /* Some variable to describe this OpenGL extension.
     The attribute name is mandatory since it is
     used to identify the method. */
  gchar *name, *nameI18n;
  gchar *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;
  RenderingModeId 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.

gchar *name; name of the extension, in ASCII, used as id in the config files ;
gchar *nameI18n; name in UTF8 that can be translated and shown to user ;
gchar *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...) ;
RenderingModeId 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.


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);

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.

callAllExtensionsLists ()

void        callAllExtensionsLists          ();

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


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.