## fogAndBGColor

fogAndBGColor — Handle the background colour and the fog.

## Synopsis

    VisuExtension*      initExtFogAndBG                     ();
    #define             VISU_GLEXT_FOG_AND_BG_ID
    int                 visu_glExt_fog_setValues            (float rgba[4],
                                                             int mask);
    gboolean            visu_glExt_fog_setOn                (gboolean value);
    gboolean            visu_glExt_fog_setUseSpecificColor  (gboolean value);
    #define             VISU_GLEXT_FOG_MASK_START
    #define             VISU_GLEXT_FOG_MASK_END
    gboolean            visu_glExt_fog_setStartEndValues    (float startEnd[2],
                                                             int mask);
    void                visu_glExt_fog_getValues            (float rgba[4]);
    gboolean            visu_glExt_fog_getOn                ();
    gboolean            visu_glExt_fog_getUseSpecificColor  ();
    float               visu_glExt_fog_getStart             ();
    float               visu_glExt_fog_getEnd               ();
    int                 visu_glExt_bg_setValues             (float rgba[3],
                                                             int mask);
    void                visu_glExt_bg_getValues             (float rgba[4]);
    void                visu_glExt_fog_create               (VisuData *data);
    void                visu_glExt_fog_create_color         ();
    void                visu_glExt_bg_setImage              (const guchar *imageData,
                                                             guint width,
                                                             guint height,
                                                             gboolean alpha,
                                                             const gchar *title,
                                                             gboolean fit);

## Description

This module is used to support a background colour and to tune the fog. This last one can be turn on or off and its colour can be either a user defined one or the one of the background. The fog is a linear blending into the fog colour. It starts at a given z position (in the camera basis set) and ends at a lower z.

## Details

### initExtFogAndBG ()

    VisuExtension*      initExtFogAndBG                     ();

It initialises all variables of the OpenGL extension. It creates all resources and parameters introduced by this extension. This method should be added in the `listInitExtensionFunc` to be called automatically by the `initVisuExtensions()` at V_Sim startup.

Returns : | a pointer to the VisuExtension it created or NULL otherwise.

### VISU_GLEXT_FOG_AND_BG_ID

    #define VISU_GLEXT_FOG_AND_BG_ID "FogAndColor"

The id used to identify this extension, see `visuExtensions_rebuildList()` for instance.

### visu_glExt_fog_setValues ()

    int                 visu_glExt_fog_setValues            (float rgba[4],
                                                             int mask);

Method used to change the value of the parameter fog_specific_color. This color is actually used only if fog_color_is_specific is set to 1, use `setFogColorSpecific()` to do that.

`rgba` : | a three floats array with values (0 <= values <= 1) for the red, the green and the blue color. Only values specified by the mask are really relevant.
`mask` : | use TOOL_COLOR_MASK_R, TOOL_COLOR_MASK_G, TOOL_COLOR_MASK_B, TOOL_COLOR_MASK_RGBA or a combinaison to indicate what values in the rgb array must be taken into account.
Returns : | 0 if redrawing is not necessary. 1 if the rendering window must be redrawn.

### visu_glExt_fog_setOn ()

    gboolean            visu_glExt_fog_setOn                (gboolean value);

Method used to change the value of the parameter fog_is_on.

`value` : | TRUE if fog must be rendered, FALSE otherwise.
Returns : | FALSE if redrawing is not necessary. TRUE if the rendering window must be redrawn.

### visu_glExt_fog_setUseSpecificColor ()

    gboolean            visu_glExt_fog_setUseSpecificColor  (gboolean value);

Method used to change the value of the parameter fog_color_is_specific.

`value` : | TRUE if fog is rendered with its own color specified by `setFogRGBValues()` or FALSE if the fog uses the background color.
Returns : | TRUE if `visu_glExt_fog_create()` should be called. In all cases, 'OpenGLAskForReDraw' signal should then be emitted.

### VISU_GLEXT_FOG_MASK_START

    #define VISU_GLEXT_FOG_MASK_START (1 << 0)

Value used by the second parameter of `setFogStartEndValues()` to specified the value that must be changed. This actually changes the fog_start value.

### VISU_GLEXT_FOG_MASK_END

    #define VISU_GLEXT_FOG_MASK_END (1 << 1)

Value used by the second parameter of `setFogStartEndValues()` to specified the value that must be changed. This actually changes the fog_end value.

### visu_glExt_fog_setStartEndValues ()

    gboolean            visu_glExt_fog_setStartEndValues    (float startEnd[2],
                                                             int mask);

Method used to change the value of the parameters fog_start and fog_end.

`startEnd` : | a two floats array with values (0 <= values <= 1) for the beging and the ending of the fog position. Only values specified by the mask are really relevant.
`mask` : | use VISU_GLEXT_FOG_MASK_START, VISU_GLEXT_FOG_MASK_END to indicate what values in the startEnd array must be taken into account.
Returns : | TRUE if `visu_glExt_fog_create()` should be called and then 'OpenGLAskForReDraw' signal be emitted.

### visu_glExt_fog_getValues ()

    void                visu_glExt_fog_getValues            (float rgba[4]);

Read the RGBA value of the specific fog colour (in [0;1]).

`rgba` : | a storage for four values.

### visu_glExt_fog_getOn ()

    gboolean            visu_glExt_fog_getOn                ();

Read if fog is used or not.

Returns : | TRUE if the fog is rendered, FALSE otherwise.

### visu_glExt_fog_getUseSpecificColor ()

    gboolean            visu_glExt_fog_getUseSpecificColor  ();

Read if fog uses a specific colour or not.

Returns : | TRUE if the fog uses its own color or FALSE if it uses the color of the background.

### visu_glExt_fog_getStart ()

    float               visu_glExt_fog_getStart             ();

Read the starting value of the fog (in [0;1]).

Returns : | the position where the fog starts.

### visu_glExt_fog_getEnd ()

    float               visu_glExt_fog_getEnd               ();

Read the ending value of the fog (in [0;1]).

Returns : | the position where the fog ends.

### visu_glExt_bg_setValues ()

    int                 visu_glExt_bg_setValues             (float rgba[3],
                                                             int mask);

Method used to change the value of the parameter background_color.

`rgba` : | a three floats array with values (0 <= values <= 1) for the red, the green and the blue color. Only values specified by the mask are really relevant.
`mask` : | use TOOL_COLOR_MASK_R, TOOL_COLOR_MASK_G, TOOL_COLOR_MASK_B, TOOL_COLOR_MASK_RGBA or a combinaison to indicate what values in the rgb array must be taken into account.
Returns : | 0 if redrawing is not necessary. 1 if the rendering window must be redrawn.

### visu_glExt_bg_getValues ()

    void                visu_glExt_bg_getValues             (float rgba[4]);

Read the RGBA value of the specific background colour (in [0;1]).

`rgba` : | a storage for four values.

### visu_glExt_fog_create ()

    void                visu_glExt_fog_create               (VisuData *data);

Call the OpenGL routine to enable and initialise the fog.

`data` : | the VisuData object the fog apply to.

### visu_glExt_fog_create_color ()

    void                visu_glExt_fog_create_color         ();

Call the OpenGL routines that change the colour of the fog.

### visu_glExt_bg_setImage ()

    void                visu_glExt_bg_setImage              (const guchar *imageData,
                                                             guint width,
                                                             guint height,
                                                             gboolean alpha,
                                                             const gchar *title,
                                                             gboolean fit);

Draw the `imageData` on the background. The image is scaled to the viewport dimensions, keeping the width/height ratio, if `fit` is set to TRUE. If `title` is not NULL, the title is also printed on the background. The image data are copied and can be free after this call.

`imageData` : | raw image data in RGB or RGBA format ;
`width` : | the width ;
`height` : | the height ;
`alpha` : | TRUE if the image is RGBA ;
`title` : | an optional title (can be NULL).
`fit` : | a boolean (default is TRUE).