From 272e227109387c9287081e9dad467290e4e93faf Mon Sep 17 00:00:00 2001 From: Robert Bragg Date: Wed, 4 Nov 2009 19:31:43 +0000 Subject: [PATCH] [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 | 13 ++++ clutter/cogl/cogl/cogl-clip-stack.c | 44 ++++++------ clutter/cogl/cogl/cogl.h.in | 92 ++++++++++++++++++++++-- doc/reference/cogl/cogl-sections.txt | 9 ++- tests/interactive/test-cogl-primitives.c | 14 ++++ 5 files changed, 144 insertions(+), 28 deletions(-) diff --git a/README b/README index 464ebe9ee..8516f2e86 100644 --- a/README +++ b/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 ------------------------------- diff --git a/clutter/cogl/cogl/cogl-clip-stack.c b/clutter/cogl/cogl/cogl-clip-stack.c index 9ffaa8576..822fd93b7 100644 --- a/clutter/cogl/cogl/cogl-clip-stack.c +++ b/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, - 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/clutter/cogl/cogl/cogl.h.in b/clutter/cogl/cogl/cogl.h.in index 03ab052d9..854686e71 100644 --- a/clutter/cogl/cogl/cogl.h.in +++ b/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: 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
diff --git a/tests/interactive/test-cogl-primitives.c b/tests/interactive/test-cogl-primitives.c index fb5adb378..103407784 100644 --- a/tests/interactive/test-cogl-primitives.c +++ b/tests/interactive/test-cogl-primitives.c @@ -6,6 +6,7 @@ #include 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);