[fog] Document that fogging only works with opaque or unmultipled colors

The fixed function fogging provided by OpenGL only works with unmultiplied
colors (or if the color has an alpha of 1.0) so since we now premultiply
textures and colors by default a note to this affect has been added to
clutter_stage_set_fog and cogl_set_fog.

test-depth.c no longer uses clutter_stage_set_fog for this reason.

In the future when we can depend on fragment shaders we should also be
able to support fogging of premultiplied primitives.

clutter/clutter-stage.c

@@ -1668,6 +1668,16 @@ clutter_stage_set_use_fog (ClutterStage *stage,
  *   }
  * ]|
  *
+ * Note: The fogging functions only work correctly when the visible actors use
+ *       unmultiplied alpha colors. By default Cogl will premultiply textures
+ *       and cogl_set_source_color will premultiply colors, so unless you
+ *       explicitly load your textures requesting an unmultiplied
+ *       internal_format and use cogl_material_set_color you can only use
+ *       fogging with fully opaque actors.
+ *
+ *       We can look to improve this in the future when we can depend on
+ *       fragment shaders.
+ *
  * Since: 0.6
  */
 void

clutter/cogl/cogl.h.in

@@ -386,13 +386,22 @@ gboolean        cogl_get_backface_culling_enabled (void);
  * @z_near: Position along z-axis where no fogging should be applied
  * @z_far: Position along z-axes where full fogging should be applied
  *
- * Enables fogging. Fogging causes vertices that are further away from
+ * Enables fogging. Fogging causes vertices that are further away from the eye
- * the eye to be rendered with a different color. The color is determined
+ * to be rendered with a different color. The color is determined according to
- * according to the chosen fog mode; at it's simplest the color is
+ * the chosen fog mode; at it's simplest the color is linearly interpolated so
- * linearly interpolated so that vertices at @z_near are drawn fully
+ * that vertices at @z_near are drawn fully with their original color and
- * with their original color and vertices at @z_far are drawn fully
+ * vertices at @z_far are drawn fully with @fog_color. Fogging will remain
- * with @fog_color. Fogging will remain enabled until you call
+ * enabled until you call cogl_disable_fog().
- * cogl_disable_fog().
+ *
+ * Note: The fogging functions only work correctly when primitives use
+ *       unmultiplied alpha colors. By default Cogl will premultiply textures
+ *       and cogl_set_source_color will premultiply colors, so unless you
+ *       explicitly load your textures requesting an unmultiplied
+ *       internal_format and use cogl_material_set_color you can only use
+ *       fogging with fully opaque primitives.
+ *
+ *       We can look to improve this in the future when we can depend on
+ *       fragment shaders.
  */
 void            cogl_set_fog                  (const CoglColor *fog_color,
                                                CoglFogMode      mode,

tests/interactive/test-depth.c

@@ -119,15 +119,12 @@ test_depth_main (int argc, char *argv[])
   ClutterActor     *group, *hand, *label, *rect, *janus, *box;
   ClutterColor      stage_color = { 0xcc, 0xcc, 0xcc, 0xff };
   ClutterColor      rect_color  = { 0, 0, 0, 0x88 };
-  ClutterFog        stage_fog   = { 10.0, -50.0 };
   GError           *error;
 
   clutter_init (&argc, &argv);
 
   stage = clutter_stage_get_default ();
   clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);
-  clutter_stage_set_fog (CLUTTER_STAGE (stage), &stage_fog);
-  clutter_stage_set_use_fog (CLUTTER_STAGE (stage), TRUE);
 
   g_signal_connect (stage,
                     "button-press-event", G_CALLBACK (clutter_main_quit),