stage: Deprecate :use-fog and :fog

The depth cueing through GL fog has been broken for a long while, now.

The fog-related API in Clutter is ridiculously limited, and harks back
to simpler times; the ClutterFog structure is not enough to express all
the GL fog machinery, and required application code to connect to the
Stage's paint implementation and drop into Cogl directly.

Additionally, the fixed pipeline fog machinery in GL simply does not
work with premultiplied alpha, unless you use a shader - and in that
case it would only work for textures. Let's deprecate it, and just
don't do anything if somebody has the brilliant idea of setting the
:use-fog property to TRUE.

3 files changed, 113 insertions, 98 deletions

diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c
index a292b922a..47539b055 100644
--- a/clutter/clutter-stage.c
+++ b/clutter/clutter-stage.c
@@ -48,9 +48,13 @@
 #include "config.h"
 #endif
 
+#include <math.h>
 #include <cairo.h>
 
+#define CLUTTER_DISABLE_DEPRECATION_WARNINGS
+
 #include "clutter-stage.h"
+#include "deprecated/clutter-stage.h"
 
 #include "clutter-actor-private.h"
 #include "clutter-backend-private.h"
@@ -76,13 +80,6 @@
 
 #include "cogl/cogl.h"
 
-#include <math.h>
-
-#ifdef USE_GDKPIXBUF
-#include <gdk-pixbuf/gdk-pixbuf.h>
-#endif
-
-
 G_DEFINE_TYPE (ClutterStage, clutter_stage, CLUTTER_TYPE_GROUP);
 
 #define CLUTTER_STAGE_GET_PRIVATE(obj) \
@@ -646,7 +643,8 @@ clutter_stage_paint (ClutterActor *self)
 
   CLUTTER_TIMER_STOP (_clutter_uprof_context, stage_clear_timer);
 
-  if (priv->use_fog)
+#if 0
+  if (G_UNLIKELY (priv->use_fog))
     {
       /* we only expose the linear progression of the fog in
        * the ClutterStage API, and that ignores the fog density.
@@ -660,6 +658,7 @@ clutter_stage_paint (ClutterActor *self)
     }
   else
     cogl_disable_fog ();
+#endif
 
   /* this will take care of painting every child */
   CLUTTER_ACTOR_CLASS (clutter_stage_parent_class)->paint (self);
@@ -1791,15 +1790,13 @@ clutter_stage_class_init (ClutterStageClass *klass)
    *
    * Whether the stage should be rendered in an offscreen buffer.
    *
-   * <warning><para>Not every backend supports redirecting the
-   * stage to an offscreen buffer. This property might not work
-   * and it might be deprecated at any later date.</para></warning>
+   * Deprecated: 1.10: This property does not do anything.
    */
   pspec = g_param_spec_boolean ("offscreen",
                                 P_("Offscreen"),
                                 P_("Whether the main stage should be rendered offscreen"),
                                 FALSE,
-                                CLUTTER_PARAM_READWRITE);
+                                CLUTTER_PARAM_READWRITE | G_PARAM_DEPRECATED);
   g_object_class_install_property (gobject_class,
                                    PROP_OFFSCREEN,
                                    pspec);
@@ -1882,12 +1879,14 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * actors farther from the viewpoint.
    *
    * Since: 0.6
+   *
+   * Deprecated: 1.10: This property does not do anything.
    */
   pspec = g_param_spec_boolean ("use-fog",
                                 P_("Use Fog"),
                                 P_("Whether to enable depth cueing"),
                                 FALSE,
-                                CLUTTER_PARAM_READWRITE);
+                                CLUTTER_PARAM_READWRITE | G_PARAM_DEPRECATED);
   g_object_class_install_property (gobject_class, PROP_USE_FOG, pspec);
 
   /**
@@ -1897,12 +1896,14 @@ clutter_stage_class_init (ClutterStageClass *klass)
    * is set to %TRUE
    *
    * Since: 1.0
+   *
+   * Deprecated: 1.10: This property does not do anything.
    */
   pspec = g_param_spec_boxed ("fog",
                               P_("Fog"),
                               P_("Settings for the depth cueing"),
                               CLUTTER_TYPE_FOG,
-                              CLUTTER_PARAM_READWRITE);
+                              CLUTTER_PARAM_READWRITE | G_PARAM_DEPRECATED);
   g_object_class_install_property (gobject_class, PROP_FOG, pspec);
 
   /**
@@ -2162,7 +2163,7 @@ clutter_stage_init (ClutterStage *self)
                                       geom.height);
 
 
-  /* depth cueing */
+  /* FIXME - remove for 2.0 */
   priv->fog.z_near = 1.0;
   priv->fog.z_far  = 2.0;
 
@@ -3019,6 +3020,8 @@ clutter_stage_get_key_focus (ClutterStage *stage)
  * Return value: %TRUE if the depth cueing effect is enabled
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.10: This function will always return %FALSE
  */
 gboolean
 clutter_stage_get_use_fog (ClutterStage *stage)
@@ -3043,11 +3046,14 @@ clutter_stage_get_use_fog (ClutterStage *stage)
  * clutter_stage_set_fog() function.
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.10: Calling this function produces no visible effect
  */
 void
 clutter_stage_set_use_fog (ClutterStage *stage,
                            gboolean      fog)
 {
+#if 0
   ClutterStagePrivate *priv;
 
   g_return_if_fail (CLUTTER_IS_STAGE (stage));
@@ -3065,6 +3071,7 @@ clutter_stage_set_use_fog (ClutterStage *stage,
 
       g_object_notify (G_OBJECT (stage), "use-fog");
     }
+#endif
 }
 
 /**
@@ -3122,11 +3129,14 @@ clutter_stage_set_use_fog (ClutterStage *stage,
  * depend on fragment shaders.</note>
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.10: Fog settings are ignored.
  */
 void
 clutter_stage_set_fog (ClutterStage *stage,
                        ClutterFog   *fog)
 {
+#if 0
   ClutterStagePrivate *priv;
 
   g_return_if_fail (CLUTTER_IS_STAGE (stage));
@@ -3138,6 +3148,7 @@ clutter_stage_set_fog (ClutterStage *stage,
 
   if (priv->use_fog)
     clutter_actor_queue_redraw (CLUTTER_ACTOR (stage));
+#endif
 }
 
 /**
@@ -3148,6 +3159,9 @@ clutter_stage_set_fog (ClutterStage *stage,
  * Retrieves the current depth cueing settings from the stage.
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.10: This function will always return the default
+ *   values of #ClutterFog
  */
 void
 clutter_stage_get_fog (ClutterStage *stage,
diff --git a/clutter/clutter-stage.h b/clutter/clutter-stage.h
index 20a87d360..36bb7fc55 100644
--- a/clutter/clutter-stage.h
+++ b/clutter/clutter-stage.h
@@ -142,89 +142,76 @@ struct _ClutterFog
   gfloat z_far;
 };
 
-GType         clutter_perspective_get_type    (void) G_GNUC_CONST;
-GType         clutter_fog_get_type            (void) G_GNUC_CONST;
-GType         clutter_stage_get_type          (void) G_GNUC_CONST;
-
-ClutterActor *clutter_stage_new               (void);
-
-void          clutter_stage_set_color         (ClutterStage       *stage,
-                                               const ClutterColor *color);
-void          clutter_stage_get_color         (ClutterStage       *stage,
-                                               ClutterColor       *color);
-void          clutter_stage_set_perspective   (ClutterStage       *stage,
-			                       ClutterPerspective *perspective);
-void          clutter_stage_get_perspective   (ClutterStage       *stage,
-			                       ClutterPerspective *perspective);
-void          clutter_stage_set_fullscreen    (ClutterStage       *stage,
-                                               gboolean            fullscreen);
-gboolean      clutter_stage_get_fullscreen    (ClutterStage       *stage);
-void          clutter_stage_show_cursor       (ClutterStage       *stage);
-void          clutter_stage_hide_cursor       (ClutterStage       *stage);
-
-ClutterActor *clutter_stage_get_actor_at_pos  (ClutterStage       *stage,
-                                               ClutterPickMode     pick_mode,
-                                               gint                x,
-                                               gint                y);
-guchar *      clutter_stage_read_pixels       (ClutterStage       *stage,
-                                               gint                x,
-                                               gint                y,
-                                               gint                width,
-                                               gint                height);
-gboolean      clutter_stage_event             (ClutterStage       *stage,
-                                               ClutterEvent       *event);
-
-void                  clutter_stage_set_title          (ClutterStage *stage,
-                                                        const gchar  *title);
-const gchar *         clutter_stage_get_title          (ClutterStage *stage);
-void                  clutter_stage_set_user_resizable (ClutterStage *stage,
-						        gboolean      resizable);
-gboolean              clutter_stage_get_user_resizable (ClutterStage *stage);
-void                  clutter_stage_set_use_fog        (ClutterStage *stage,
-                                                        gboolean      fog);
-gboolean              clutter_stage_get_use_fog        (ClutterStage *stage);
-void                  clutter_stage_set_fog            (ClutterStage *stage,
-                                                        ClutterFog   *fog);
-void                  clutter_stage_get_fog            (ClutterStage *stage,
-                                                        ClutterFog   *fog);
-
-void                  clutter_stage_set_key_focus      (ClutterStage *stage,
-                                                        ClutterActor *actor);
-ClutterActor *        clutter_stage_get_key_focus      (ClutterStage *stage);
-void                  clutter_stage_ensure_current     (ClutterStage *stage);
-void                  clutter_stage_ensure_viewport    (ClutterStage *stage);
-void                  clutter_stage_ensure_redraw      (ClutterStage *stage);
-
-void     clutter_stage_set_throttle_motion_events (ClutterStage *stage,
-                                                   gboolean      throttle);
-gboolean clutter_stage_get_throttle_motion_events (ClutterStage *stage);
-
-void                  clutter_stage_set_use_alpha      (ClutterStage *stage,
-                                                        gboolean      use_alpha);
-gboolean              clutter_stage_get_use_alpha      (ClutterStage *stage);
-
-void                  clutter_stage_set_minimum_size (ClutterStage *stage,
-                                                      guint         width,
-                                                      guint         height);
-void                  clutter_stage_get_minimum_size (ClutterStage *stage,
-                                                      guint        *width,
-                                                      guint        *height);
-
-void                  clutter_stage_set_no_clear_hint (ClutterStage *stage,
-                                                       gboolean      no_clear);
-gboolean              clutter_stage_get_no_clear_hint (ClutterStage *stage);
-
-void                  clutter_stage_set_accept_focus  (ClutterStage *stage,
-                                                       gboolean      accept_focus);
-gboolean              clutter_stage_get_accept_focus  (ClutterStage *stage);
-
-
-void                  clutter_stage_get_redraw_clip_bounds    (ClutterStage    *stage,
-                                                               cairo_rectangle_int_t *clip);
-
-void                  clutter_stage_set_motion_events_enabled (ClutterStage *stage,
-                                                               gboolean      enabled);
-gboolean              clutter_stage_get_motion_events_enabled (ClutterStage *stage);
+GType clutter_perspective_get_type (void) G_GNUC_CONST;
+GType clutter_fog_get_type (void) G_GNUC_CONST;
+GType clutter_stage_get_type (void) G_GNUC_CONST;
+
+ClutterActor *  clutter_stage_new                               (void);
+
+void            clutter_stage_set_color                         (ClutterStage          *stage,
+                                                                 const ClutterColor    *color);
+void            clutter_stage_get_color                         (ClutterStage          *stage,
+                                                                 ClutterColor          *color);
+void            clutter_stage_set_perspective                   (ClutterStage          *stage,
+			                                         ClutterPerspective    *perspective);
+void            clutter_stage_get_perspective                   (ClutterStage          *stage,
+			                                         ClutterPerspective    *perspective);
+void            clutter_stage_set_fullscreen                    (ClutterStage          *stage,
+                                                                 gboolean               fullscreen);
+gboolean        clutter_stage_get_fullscreen                    (ClutterStage          *stage);
+void            clutter_stage_show_cursor                       (ClutterStage          *stage);
+void            clutter_stage_hide_cursor                       (ClutterStage          *stage);
+void            clutter_stage_set_title                         (ClutterStage          *stage,
+                                                                 const gchar           *title);
+const gchar *   clutter_stage_get_title                         (ClutterStage          *stage);
+void            clutter_stage_set_user_resizable                (ClutterStage          *stage,
+						                 gboolean               resizable);
+gboolean        clutter_stage_get_user_resizable                (ClutterStage          *stage);
+
+void            clutter_stage_set_minimum_size                  (ClutterStage          *stage,
+                                                                 guint                  width,
+                                                                 guint                  height);
+void            clutter_stage_get_minimum_size                  (ClutterStage          *stage,
+                                                                 guint                 *width,
+                                                                 guint                 *height);
+void            clutter_stage_set_no_clear_hint                 (ClutterStage          *stage,
+                                                                 gboolean               no_clear);
+gboolean        clutter_stage_get_no_clear_hint                 (ClutterStage          *stage);
+void            clutter_stage_set_use_alpha                     (ClutterStage          *stage,
+                                                                 gboolean               use_alpha);
+gboolean        clutter_stage_get_use_alpha                     (ClutterStage          *stage);
+
+void            clutter_stage_set_key_focus                     (ClutterStage          *stage,
+                                                                 ClutterActor          *actor);
+ClutterActor *  clutter_stage_get_key_focus                     (ClutterStage          *stage);
+void            clutter_stage_set_throttle_motion_events        (ClutterStage          *stage,
+                                                                 gboolean               throttle);
+gboolean        clutter_stage_get_throttle_motion_events        (ClutterStage          *stage);
+void            clutter_stage_set_motion_events_enabled         (ClutterStage          *stage,
+                                                                 gboolean               enabled);
+gboolean        clutter_stage_get_motion_events_enabled         (ClutterStage          *stage);
+void            clutter_stage_set_accept_focus                  (ClutterStage          *stage,
+                                                                 gboolean               accept_focus);
+gboolean        clutter_stage_get_accept_focus                  (ClutterStage          *stage);
+gboolean        clutter_stage_event                             (ClutterStage          *stage,
+                                                                 ClutterEvent          *event);
+
+ClutterActor *  clutter_stage_get_actor_at_pos                  (ClutterStage          *stage,
+                                                                 ClutterPickMode        pick_mode,
+                                                                 gint                   x,
+                                                                 gint                   y);
+guchar *        clutter_stage_read_pixels                       (ClutterStage          *stage,
+                                                                 gint                   x,
+                                                                 gint                   y,
+                                                                 gint                   width,
+                                                                 gint                   height);
+
+void            clutter_stage_get_redraw_clip_bounds            (ClutterStage          *stage,
+                                                                 cairo_rectangle_int_t *clip);
+
+void            clutter_stage_ensure_current                    (ClutterStage          *stage);
+void            clutter_stage_ensure_viewport                   (ClutterStage          *stage);
+void            clutter_stage_ensure_redraw                     (ClutterStage          *stage);
 
 G_END_DECLS
 
diff --git a/clutter/deprecated/clutter-stage.h b/clutter/deprecated/clutter-stage.h
index 3cc6db1b4..d8d66c6c0 100644
--- a/clutter/deprecated/clutter-stage.h
+++ b/clutter/deprecated/clutter-stage.h
@@ -49,6 +49,20 @@ gboolean        clutter_stage_is_default        (ClutterStage *stage);
 CLUTTER_DEPRECATED_FOR(clutter_actor_queue_redraw)
 void            clutter_stage_queue_redraw      (ClutterStage *stage);
 
+CLUTTER_DEPRECATED
+void            clutter_stage_set_use_fog       (ClutterStage *stage,
+                                                 gboolean      fog);
+
+CLUTTER_DEPRECATED
+gboolean        clutter_stage_get_use_fog       (ClutterStage *stage);
+
+CLUTTER_DEPRECATED
+void            clutter_stage_set_fog           (ClutterStage *stage,
+                                                 ClutterFog   *fog);
+
+CLUTTER_DEPRECATED
+void            clutter_stage_get_fog           (ClutterStage *stage,
+                                                 ClutterFog   *fog);
 G_END_DECLS
 
 #endif /* __CLUTTER_STAGE_DEPRECATED_H__ */