diff --git a/cogl/cogl-clip-stack.c b/cogl/cogl-clip-stack.c
index 9ffaa8576..822fd93b7 100644
--- a/cogl/cogl-clip-stack.c
+++ b/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,
- float y_offset,
- float width,
- float height)
+cogl_clip_push_window_rectangle (int x_offset,
+ int y_offset,
+ int width,
+ 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,11 +485,11 @@ try_pushing_rect_as_window_rect (float x_1,
return TRUE;
}
-static void
-_cogl_clip_push_rectangle (float x_1,
- float y_1,
- float x_2,
- float y_2)
+void
+cogl_clip_push_rectangle (float x_1,
+ float y_1,
+ float x_2,
+ float y_2)
{
CoglHandle draw_buffer;
CoglClipStackState *clip_state;
@@ -526,16 +529,17 @@ _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,
- y_offset,
- x_offset + width,
- y_offset + height);
+ cogl_clip_push_rectangle (x_offset,
+ y_offset,
+ x_offset + width,
+ y_offset + height);
}
void
diff --git a/cogl/cogl.h.in b/cogl/cogl.h.in
index 03ab052d9..854686e71 100644
--- a/cogl/cogl.h.in
+++ b/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:
diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt
index a1efa0667..699481712 100644
--- a/doc/reference/cogl/cogl-sections.txt
+++ b/doc/reference/cogl/cogl-sections.txt
@@ -120,14 +120,17 @@ cogl_debug_flags
cogl-clipping
Clipping
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
+
+cogl_clip_push
+cogl_clip_push_window_rect
+cogl_clip_ensure
cogl_clip_stack_save
cogl_clip_stack_restore
-cogl_clip_ensure