[AD] get_clip()

[Eric Botcazou <ebotcazou@xxxxxxxxxx>]

[Follow-up to Elias' patch]

The attached patch is a reworked version of a long pending patch from Vincent. 
It adds the get_clip() function that retrieves the clipping rectangle of a 
bitmap. I agree with Vincent that the function is needed because of the +1 
tweak on the right and bottom clipping values.

-- 
Eric Botcazou

--- /home/eric/cvs/allegro/src/graphics.c	Fri Nov  1 12:45:57 2002
+++ allegro/src/graphics.c	Sat Nov  2 22:24:06 2002
@@ -1423,6 +1423,26 @@
 
 
 
+/* get_clip:
+ *  Returns the clipping rectangle of the bitmap. The function follows the
+ *  semantics of set_clip() in that it returns zero for x1, y1, x2 and y2
+ *  when clipping is turned off.
+ */
+void get_clip(BITMAP *bitmap, int *x1, int *y1, int *x2, int *y2)
+{
+   if (!bitmap->clip) {
+      *x1 = *y1 = *x2 = *y2 = 0;
+      return;
+   }
+
+   *x1 = bitmap->cl;
+   *y1 = bitmap->ct;
+   *x2 = bitmap->cr-1;
+   *y2 = bitmap->cb-1;
+}
+
+
+
 /* scroll_screen:
  *  Attempts to scroll the hardware screen, returning 0 on success. 
  *  Check the VIRTUAL_W and VIRTUAL_H values to see how far the screen
--- /home/eric/cvs/allegro/include/allegro/gfx.h	Thu Oct 31 13:53:47 2002
+++ allegro/include/allegro/gfx.h	Sat Nov  2 22:24:06 2002
@@ -360,6 +360,7 @@
 AL_FUNC(BITMAP *, create_system_bitmap, (int width, int height));
 AL_FUNC(void, destroy_bitmap, (BITMAP *bitmap));
 AL_FUNC(void, set_clip, (BITMAP *bitmap, int x1, int y1, int x2, int y2));
+AL_FUNC(void, get_clip, (BITMAP *bitmap, int *x1, int *y1, int *x2, int *y2));
 AL_FUNC(void, clear_bitmap, (BITMAP *bitmap));
 AL_FUNC(void, vsync, (void));
 
--- /home/eric/cvs/allegro/docs/src/allegro._tx	Thu Oct 31 11:56:23 2002
+++ allegro/docs/src/allegro._tx	Sat Nov  2 22:27:06 2002
@@ -339,7 +339,7 @@
    math routines" for the full explanation.
    
 @@typedef struct @BITMAP
-@domain.hid create_bitmap, set_clip, bitmap_color_depth, RLE_SPRITE
+@xref create_bitmap, set_clip, get_clip, bitmap_color_depth, RLE_SPRITE
 @xref COMPILED_SPRITE, Direct access to video memory
 <codeblock>
    int w, h;               - size of the bitmap in pixels
@@ -358,12 +358,12 @@
    The clipping rectangle is inclusive on the left and top (0 allows drawing
    to position 0) but exclusive on the right and bottom (10 allows drawing
    to position 9, but not to 10). Note this is not the same format as you
-   pass to set_clip(), which takes inclusive coordinates for all four
-   corners. All the values of this structure should be regarded as read-only,
-   with the exception of the line field, whose access is described in depth
-   in the "Direct access to video memory" section of the manual. If you want
-   to modify the clipping region, please refrain from changing this
-   structure, use set_clip() instead.
+   pass to set_clip() and retrieve from get_clip(), which takes inclusive
+   coordinates for all four corners. All the values of this structure should
+   be regarded as read-only, with the exception of the line field, whose
+   access is described in depth in the "Direct access to video memory"
+   section of the manual. If you want to modify the clipping region, please
+   refrain from changing this structure, use set_clip() instead.
 
 @@typedef struct @RLE_SPRITE
 @xref get_rle_sprite, BITMAP, COMPILED_SPRITE, RLE sprites
@@ -3153,6 +3153,7 @@
    Shortcut version of release_bitmap(screen);
 
 @@void @set_clip(BITMAP *bitmap, int x1, int y1, int x2, int y2);
+@xref get_clip
    Each bitmap has an associated clipping rectangle, which is the area of 
    the image that it is ok to draw on. Nothing will be drawn to positions 
    outside this space. Pass the two opposite corners of the clipping 
@@ -3163,9 +3164,10 @@
    difference, although every little helps) but will result in your program 
    dying a horrible death if you try to draw beyond the edges of the bitmap.
 
-   There's no get_clip like function. To obtain the clipping rectangle of an
-   existing bitmap, check the appropiate fields of the BITMAP structure
-   holding it.
+@@void @get_clip(BITMAP *bitmap, int *x1, int *y1, int *x2, int *y2);
+@xref set_clip
+   Returns the clipping rectangle of the bitmap. If clipping has been turned
+   off, returns zero for x1, y1, x2, and y2.