## fogAndBGColor

fogAndBGColor — Handle the background colour and the fog.

## Synopsis

    #define             EXT_FOG_AND_BG_ID
    OpenGLExtension*    extFogAndBGInit                     ();
    #define             MASK_FOG_START
    #define             MASK_FOG_END
    void                fogCreate                           (VisuData *data);
    void                fogCreate_color                     ();
    float               fogGet_end                          ();
    gboolean            fogGet_isOn                         ();
    float               fogGet_start                        ();
    gboolean            fogGet_useSpecificColor             ();
    gboolean            fogSet_isOn                         (gboolean value);
    gboolean            fogSet_startEndValues               (float startEnd[2],
                                                             int mask);
    gboolean            fogSet_useSpecificColor             (gboolean value);
    void                fogGet_value                        (float rgba[4]);
    int                 fogSet_values                       (float rgba[4],
                                                             int mask);
    void                bgGet_value                         (float rgba[4]);
    int                 bgSet_values                        (float rgba[3],
                                                             int mask);
    void                bgSet_image                         (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

### EXT_FOG_AND_BG_ID

    #define EXT_FOG_AND_BG_ID "FogAndColor"

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

### extFogAndBGInit ()

    OpenGLExtension*    extFogAndBGInit                     ();

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 `initOpenGLExtensions()` at V_Sim startup.

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

### MASK_FOG_START

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

### MASK_FOG_END

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

### fogCreate ()

    void                fogCreate                           (VisuData *data);

Call the OpenGL routine to enable and initialise the fog.

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

### fogCreate_color ()

    void                fogCreate_color                     ();

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

### fogGet_end ()

    float               fogGet_end                          ();

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

Returns : | the position where the fog ends.

### fogGet_isOn ()

    gboolean            fogGet_isOn                         ();

Read if fog is used or not.

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

### fogGet_start ()

    float               fogGet_start                        ();

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

Returns : | the position where the fog starts.

### fogGet_useSpecificColor ()

    gboolean            fogGet_useSpecificColor             ();

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.

### fogSet_isOn ()

    gboolean            fogSet_isOn                         (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.

### fogSet_startEndValues ()

    gboolean            fogSet_startEndValues               (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 MASK_FOG_START, MASK_FOG_END to indicate what values in the startEnd array must be taken into account.
Returns : | TRUE if `fogCreate()` should be called and then 'OpenGLAskForReDraw' signal be emitted.

### fogSet_useSpecificColor ()

    gboolean            fogSet_useSpecificColor             (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 `fogCreate()` should be called. In all cases, 'OpenGLAskForReDraw' signal should then be emitted.

### fogGet_value ()

    void                fogGet_value                        (float rgba[4]);

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

`rgba` : | a storage for four values.

### fogSet_values ()

    int                 fogSet_values                       (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 MASK_RGB_R, MASK_RGB_G, MASK_RGB_B, MASK_RGB_ALL 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.

### bgGet_value ()

    void                bgGet_value                         (float rgba[4]);

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

`rgba` : | a storage for four values.

### bgSet_values ()

    int                 bgSet_values                        (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 MASK_RGB_R, MASK_RGB_G, MASK_RGB_B, MASK_RGB_ALL 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.

### bgSet_image ()

    void                bgSet_image                         (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).