brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[cogl-clip] deprecate parts and cleanup the API

Browse Source 
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.
This commit is contained in:
Robert Bragg 2009-11-04 19:31:43 +00:00
parent 6cd49fdd40
commit 272e227109
5 changed files with 144 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README
View File

@ -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
-------------------------------

32
clutter/cogl/cogl/cogl-clip-stack.c
View File

@ -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,8 +485,8 @@ try_pushing_rect_as_window_rect (float x_1,
return TRUE;
}
static void
_cogl_clip_push_rectangle (float x_1,
void
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);

92
clutter/cogl/cogl/cogl.h.in
View File

@ -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:

9
doc/reference/cogl/cogl-sections.txt
View File

@ -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>

14
tests/interactive/test-cogl-primitives.c
View File

@ -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);