[cogl-clip] deprecate parts and cleanup the API

cogl_clip_push() which accepts a rectangle in model space shouldn't have
been defined to take x,y,width,height arguments because this isn't consistant
with other Cogl API dealing with model space rectangles.  If you are using a
coordinate system with the origin at the center and the y+ extending up,
then x,y,width,height isn't as natural as (x0,y0)(x1,y1). This API has
now been replace with cogl_clip_push_rectangle()

(As a general note: the Cogl API should only use the x,y,width,height style
when the appropriate coordinate space is defined by Cogl to have a top left
origin.  E.g.  window coordinates, or potentially texture coordinates)

cogl_clip_push_window_rect() shouldn't have been defined to take float
arguments since we only clip with integral pixel precision. We also
shouldn't have abbreviated "rectangle". This API has been replaced with
cogl_clip_push_window_rectangle()

cogl_clip_ensure() wasn't documented at all in Clutter 1.0 and probably
no one even knew it existed. This API isn't useful, and so it's now
deprecated. If no one complains we may remove the API altogether for
Clutter 1.2.

cogl_clip_stack_save() and cogl_clip_stack_restore() were originally added
to allow us to save/restore the clip when switching to/from offscreen
rendering.  Now that offscreen draw buffers are defined to own their clip
state and the state will be automatically saved and restored this API is now
redundant and so deprecated.

README

@@ -218,6 +218,19 @@ Cogl API changes for Clutter 1.2
 * cogl_viewport is now deprecated in favour of cogl_set_viewport which
   accepts a viewport offset.
 
+* cogl_clip_push() is now deprecated and new code should use
+  cogl_clip_push_rectangle() instead. The old API wasn't consistent with other
+  Cogl APIs that specify model space rectangles using (x0,y0)(x1,y1) pairs.
+
+* cogl_clip_push_window_rect() is now deprecated and new code should use
+  cogl_clip_push_window_rectangle(). The old API shouldn't have been defined
+  to take floats and the abbreviation wasn't consistent with other Cogl API.
+
+* cogl_clip_stack_save() and cogl_clip_stack_restore() are deprecated, as
+  the functionality is redundant now that offscreen draw buffers own their
+  clip state and switching to/from offscreen rendering will automatically
+  save and restore the clip state.
+
 Release Notes for Clutter 1.0
 -------------------------------
 

clutter/cogl/cogl/cogl-clip-stack.c

@@ -334,18 +334,11 @@ disable_clip_planes (void)
   GE( glDisable (GL_CLIP_PLANE0) );
 }
 
-/* FIXME: deprecate and replace with:
- * void
- * cogl_clip_push_window_rectangle (int x_offset,
- *                                  int y_offset,
- *                                  int width,
- *                                  int height);
- */
 void
-cogl_clip_push_window_rect (float x_offset,
+cogl_clip_push_window_rectangle (int x_offset,
-	                    float y_offset,
+	                         int y_offset,
-	                    float width,
+	                         int width,
-	                    float height)
+	                         int height)
 {
   CoglHandle draw_buffer;
   CoglClipStackState *clip_state;
@@ -395,6 +388,16 @@ cogl_clip_push_window_rect (float x_offset,
   clip_state->stack_dirty = TRUE;
 }
 
+/* XXX: This is deprecated API */
+void
+cogl_clip_push_window_rect (float x_offset,
+	                    float y_offset,
+	                    float width,
+	                    float height)
+{
+  cogl_clip_push_window_rectangle (x_offset, y_offset, width, height);
+}
+
 /* Scale from OpenGL normalized device coordinates (ranging from -1 to 1)
  * to Cogl window/draw-buffer coordinates (ranging from 0 to buffer-size) with
  * (0,0) being top left. */
@@ -482,8 +485,8 @@ try_pushing_rect_as_window_rect (float x_1,
   return TRUE;
 }
 
-static void
+void
-_cogl_clip_push_rectangle (float x_1,
+cogl_clip_push_rectangle (float x_1,
                           float y_1,
                           float x_2,
                           float y_2)
@@ -526,13 +529,14 @@ _cogl_clip_push_rectangle (float x_1,
   clip_state->stack_dirty = TRUE;
 }
 
+/* XXX: Deprecated API */
 void
 cogl_clip_push (float x_offset,
 	        float y_offset,
 	        float width,
 	        float height)
 {
-  _cogl_clip_push_rectangle (x_offset,
+  cogl_clip_push_rectangle (x_offset,
                             y_offset,
                             x_offset + width,
                             y_offset + height);

clutter/cogl/cogl/cogl.h.in

@@ -571,6 +571,8 @@ void            cogl_set_source_texture       (CoglHandle texture_handle);
  * intersected with the previous region.
  */
 
+#ifndef COGL_DISABLE_DEPRECATED
+
 /**
  * cogl_clip_push_window_rect:
  * @x_offset: left edge of the clip rectangle in window coordinates
@@ -586,11 +588,42 @@ void            cogl_set_source_texture       (CoglHandle texture_handle);
  *
  * The rectangle is intersected with the current clip region. To undo
  * the effect of this function, call cogl_clip_pop().
+ *
+ * Deprecated: It was a mistake to take float arguments and to abreviate
+ *             "rectangle", so please use cogl_clip_push_window_rectangle
+ *             instead.
  */
 void            cogl_clip_push_window_rect    (float x_offset,
                                                float y_offset,
                                                float width,
-                                               float height);
+                                               float height) G_GNUC_DEPRECATED;
+
+#endif
+
+/**
+ * cogl_clip_push_window_rectangle:
+ * @x_offset: left edge of the clip rectangle in window coordinates
+ * @y_offset: top edge of the clip rectangle in window coordinates
+ * @width: width of the clip rectangle
+ * @height: height of the clip rectangle
+ *
+ * Specifies a rectangular clipping area for all subsequent drawing
+ * operations. Any drawing commands that extend outside the rectangle
+ * will be clipped so that only the portion inside the rectangle will
+ * be displayed. The rectangle dimensions are not transformed by the
+ * current model-view matrix.
+ *
+ * The rectangle is intersected with the current clip region. To undo
+ * the effect of this function, call cogl_clip_pop().
+ *
+ * Since: 1.2
+ */
+void            cogl_clip_push_window_rectangle (int x_offset,
+                                                 int y_offset,
+                                                 int width,
+                                                 int height);
+
+#ifndef COGL_DISABLE_DEPRECATED
 
 /**
  * cogl_clip_push:
@@ -607,11 +640,42 @@ void            cogl_clip_push_window_rect    (float x_offset,
  *
  * The rectangle is intersected with the current clip region. To undo
  * the effect of this function, call cogl_clip_pop().
+ *
+ * Deprecated: The x, y, width, height arguments are inconsistent with other
+ *             APIs that specify rectangles in model space, and when used
+ *             with a coordinate space that puts the origin at the center
+ *             and y+ extending up, it's awkward to use. Please use
+ *             cogl_clip_push_rectangle instead.
  */
 void            cogl_clip_push                (float        x_offset,
                                                float        y_offset,
                                                float        width,
-                                               float        height);
+                                               float        height) G_GNUC_DEPRECATED;
+
+#endif
+
+/**
+ * cogl_clip_push_rectangle:
+ * @x0: x coordinate for top left corner of the clip rectangle
+ * @y0: y coordinate for top left corner of the clip rectangle
+ * @x1: x coordinate for bottom right corner of the clip rectangle
+ * @y1: y coordinate for bottom right corner of the clip rectangle
+ *
+ * Specifies a rectangular clipping area for all subsequent drawing
+ * operations. Any drawing commands that extend outside the rectangle
+ * will be clipped so that only the portion inside the rectangle will
+ * be displayed. The rectangle dimensions are transformed by the
+ * current model-view matrix.
+ *
+ * The rectangle is intersected with the current clip region. To undo
+ * the effect of this function, call cogl_clip_pop().
+ *
+ * Since: 1.2
+ */
+void            cogl_clip_push_rectangle      (float        x0,
+                                               float        y0,
+                                               float        x1,
+                                               float        y1);
 
 /**
  * cogl_clip_push_from_path:
@@ -645,6 +709,8 @@ void            cogl_clip_push_from_path_preserve (void);
  */
 void            cogl_clip_pop               (void);
 
+#ifndef COGL_DISABLE_DEPRECATED
+
 /**
  * cogl_clip_ensure:
  *
@@ -653,9 +719,11 @@ void            cogl_clip_pop               (void);
  * maybe be neccessary to call if you are using raw GL calls with
  * clipping.
  *
+ * Deprecated: It was a mistake that this was ever made public
+ *
  * Since: 1.0
  */
-void            cogl_clip_ensure              (void);
+void            cogl_clip_ensure              (void) G_GNUC_DEPRECATED;
 
 /**
  * cogl_clip_stack_save:
@@ -666,9 +734,15 @@ void            cogl_clip_ensure              (void);
  * must be matched by a call to cogl_clip_pop() before calling
  * cogl_clip_stack_restore().
  *
+ * Deprecated: This was originally added to allow us to save the clip
+ *             stack when switching to an offscreen draw buffer, but
+ *             it's not necessary anymore given that draw buffers now
+ *             own separate clip stacks which will be automatically
+ *             switched between when a new buffer is set.
+ *
  * Since: 0.8.2
  */
-void            cogl_clip_stack_save          (void);
+void            cogl_clip_stack_save          (void) G_GNUC_DEPRECATED;
 
 /**
  * cogl_clip_stack_restore:
@@ -676,9 +750,17 @@ void            cogl_clip_stack_save          (void);
  * Restore the state of the clipping stack that was previously saved
  * by cogl_clip_stack_save().
  *
+ * Deprecated: This was originally added to allow us to restore the clip
+ *             stack when switching back from an offscreen draw buffer, but
+ *             it's not necessary anymore given that draw buffers now own
+ *             separate clip stacks which will be automatically switched
+ *             between when a new buffer is set.
+ *
  * Since: 0.8.2
  */
-void            cogl_clip_stack_restore       (void);
+void            cogl_clip_stack_restore       (void) G_GNUC_DEPRECATED;
+
+#endif
 
 /**
  * cogl_set_draw_buffer:

doc/reference/cogl/cogl-sections.txt

@@ -120,14 +120,17 @@ cogl_debug_flags
 <FILE>cogl-clipping</FILE>
 <TITLE>Clipping</TITLE>
 CoglClipStackState
-cogl_clip_push
+cogl_clip_push_rectangle
+cogl_clip_push_window_rectangle
 cogl_clip_push_from_path
 cogl_clip_push_from_path_preserve
-cogl_clip_push_window_rect
 cogl_clip_pop
+<SUBSECTION>
+cogl_clip_push
+cogl_clip_push_window_rect
+cogl_clip_ensure
 cogl_clip_stack_save
 cogl_clip_stack_restore
-cogl_clip_ensure
 </SECTION>
 
 <SECTION>

tests/interactive/test-cogl-primitives.c

@@ -6,6 +6,7 @@
 #include <cogl/cogl.h>
 
 typedef void (*PaintFunc) (void);
+CoglHandle hand;
 
 static void
 test_paint_line ()
@@ -94,6 +95,7 @@ paint_cb (ClutterActor *self, ClutterTimeline *tl)
 
   cogl_translate (150, 0, 0);
   cogl_set_source_color4ub (200, 0, 0, 255);
+  //cogl_set_source_texture (hand);
   cogl_path_fill ();
 
   cogl_pop_matrix();
@@ -105,9 +107,21 @@ test_cogl_primitives_main (int argc, char *argv[])
   ClutterActor *stage;
   ClutterActor *coglbox;
   ClutterTimeline *tl;
+  GError *error = NULL;
 
   clutter_init(&argc, &argv);
 
+  hand =cogl_texture_new_from_file ("redhand.png",
+                              COGL_TEXTURE_NONE,
+                              COGL_PIXEL_FORMAT_ANY,
+                              &error);
+  if (error)
+    {
+      g_critical ("Failed to load redhand.png: %s", error->message);
+      g_error_free (error);
+      return 1;
+    }
+
   tl = clutter_timeline_new (G_N_ELEMENTS (paint_func) * 1000);
   clutter_timeline_set_loop (tl, TRUE);
   clutter_timeline_start (tl);