[AD] Bug #675062

[Eric Botcazou <ebotcazou@xxxxxxxxxx>]

It seems that the docs are a bit unclear about the limitations of 
stretch_blit() and stretch_sprite() with regard to those of blit() and 
draw_sprite(). The proposed patch is attached.

-- 
Eric Botcazou

--- /home/eric/cvs/allegro/docs/src/allegro._tx	Mon Jan 27 13:46:50 2003
+++ allegro/docs/src/allegro._tx	Mon Jan 27 20:45:13 2003
@@ -3866,12 +3866,26 @@
    destination bitmaps to be of different color depths, so it can be used to 
    convert images from one pixel format to another.
 
+@\void @stretch_blit(BITMAP *source, BITMAP *dest,
+@\                  int source_x, source_y, source_width, source_height,
+@@                  int dest_x, dest_y, dest_width, dest_height);
+@xref blit, masked_stretch_blit, stretch_sprite
+   Like blit(), except it can scale images (so the source and destination 
+   rectangles don't need to be the same size) and requires the source and 
+   destination bitmaps to be of the same color depth. This routine doesn't 
+   do as much safety checking as the regular blit(): in particular you must 
+   take care not to copy from areas outside the source bitmap, and you 
+   cannot blit between overlapping regions, ie. you must use different 
+   bitmaps for the source and the destination. Moreover, the source must 
+   be a memory bitmap or sub-bitmap.
+
 @\void @masked_blit(BITMAP *source, BITMAP *dest, int source_x, int source_y,
 @@                 int dest_x, int dest_y, int width, int height);
 @xref blit, masked_stretch_blit, draw_sprite, bitmap_mask_color
    Like blit(), but skips transparent pixels, which are marked by a zero in 
    256 color modes or bright pink for truecolor data (maximum red and blue, 
-   zero green). The source and destination regions must not overlap.
+   zero green), and requires the source and destination bitmaps to be of 
+   the same color depth. The source and destination regions must not overlap.
 
    If the GFX_HW_VRAM_BLIT_MASKED bit in the gfx_capabilities flag is set, 
    the current driver supports hardware accelerated masked blits from one 
@@ -3880,29 +3894,18 @@
    sprites in an offscreen portion of the video memory.
 
    Warning: if the hardware acceleration flag is not set, masked_blit() will 
-   not work correctly when used with a video memory source image, and the 
-   input graphic must always be a memory bitmap!
-
-@domain.hid @stretch_blit(BITMAP *source, BITMAP *dest,
-@\                  int source_x, source_y, source_width, source_height,
-@@                  int dest_x, dest_y, dest_width, dest_height);
-@domain.hid blit, masked_stretch_blit, stretch_sprite
-   Like blit(), except it can scale images so the source and destination 
-   rectangles don't need to be the same size. This routine doesn't do as 
-   much safety checking as the regular blit: in particular you must take 
-   care not to copy from areas outside the source bitmap, and you cannot 
-   blit between overlapping regions, ie. you must use different bitmaps for 
-   the source and the destination. Also, the source must be a memory bitmap 
-   or sub-bitmap, not the hardware screen.
+   not work correctly when used with a source image in system or video 
+   memory so the latter must be a memory bitmap.
 
 @\void @masked_stretch_blit(BITMAP *source, BITMAP *dest,
 @\                         int source_x, source_y, source_w, source_h,
 @@                         int dest_x, dest_y, dest_w, dest_h);
 @xref blit, masked_blit, stretch_blit, stretch_sprite
-   Like stretch_blit(), but skips transparent pixels, which are marked by a 
-   zero in 256 color modes or bright pink for truecolor data (maximum red 
-   and blue, zero green). The source and destination regions must not 
-   overlap.
+   Like masked_blit(), except it can scale images (so the source and 
+   destination rectangles don't need to be the same size). This routine 
+   doesn't do as much safety checking as the regular masked_blit(): in 
+   particular you must take care not to copy from areas outside the source 
+   bitmap. Moreover, the source must be a memory bitmap or sub-bitmap.
 
 @@void @draw_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y);
 @xref draw_sprite_v_flip, draw_trans_sprite, draw_lit_sprite
@@ -3925,14 +3928,21 @@
    memory.
 
    Warning: if the hardware acceleration flag is not set, draw_sprite() will 
-   not work correctly when used with a video memory source image, and the 
-   input graphic must always be a memory bitmap!
+   not work correctly when used with a sprite image in system or video 
+   memory so the latter must be a memory bitmap.
 
    Although generally not supporting graphics of mixed color depths, as a 
    special case this function can be used to draw 256 color source images 
    onto truecolor destination bitmaps, so you can use palette effects on 
    specific sprites within a truecolor program.
 
+@@void @stretch_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y, int w, int h);
+@xref draw_sprite, stretch_blit, bitmap_mask_color
+   Like draw_sprite(), except it can stretch the sprite image to the 
+   specified width and height and requires the sprite image and destination 
+   bitmap to be of the same color depth. Moreover, the sprite image must 
+   be a memory bitmap.
+
 @@void @draw_sprite_v_flip(BITMAP *bmp, BITMAP *sprite, int x, int y);
 @@void @draw_sprite_h_flip(BITMAP *bmp, BITMAP *sprite, int x, int y);
 @@void @draw_sprite_vh_flip(BITMAP *bmp, BITMAP *sprite, int x, int y);
@@ -4053,14 +4063,6 @@
    given by (cx, cy) to (x, y) in the bitmap, then rotates and scales around
    this point.
 
-@domain.hid @stretch_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y, int w, int h);
-@domain.hid draw_sprite, stretch_blit, bitmap_mask_color
-   Draws the sprite image onto the bitmap at the specified position, 
-   stretching it to the specified width and height. The difference between 
-   stretch_sprite() and stretch_blit() is that stretch_sprite() masks out 
-   transparent pixels, which are marked by a zero in 256 color modes or 
-   bright pink for truecolor data (maximum red and blue, zero green).
-
 
 
 @heading