Re: [AD] draw_lit_sprite doc update

[Eric Botcazou <ebotcazou@xxxxxxxxxx>]

> This thread:
> http://www.allegro.cc/forums/view_thread.php?_id=228670&request=1040599642&;
>
> Prompted this patch. I have never used the draw_lit_sprite routine, so I
> don't know how accurate this patch is.

diff -u -r1.116 allegro._tx
--- docs/src/allegro._tx	21 Dec 2002 10:10:49 -0000	1.116
+++ docs/src/allegro._tx	22 Dec 2002 23:19:02 -0000
@@ -3933,11 +3933,14 @@
 @@void @draw_lit_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y, int 
color);
 @xref draw_sprite, draw_trans_sprite, draw_gouraud_sprite
 @xref draw_lit_rle_sprite, color_map, set_trans_blender, bitmap_mask_color
-   Tints the sprite image to the specified color or light level, using the 
-   global color_map table, and draws the resulting image to the destination 
-   bitmap. This must only be used after you have set up the color mapping 
-   table (for 256 color modes) or blender functions (for truecolor modes).
-
+   Draws the source sprite on the destination bitmap by tinting it to the
+   specified color or light level. This must only be used after you have set
+   up the color mapping table (for 256 color modes) or blender functions
+   (for truecolor modes). The color parameter may be used for alpha-only
+   blending (such as the trans blender), in which case it must be a value in
+   the range [0-255].
+   
+  
 @\void @draw_gouraud_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y,
 @@                         int c1, int c2, int c3, int c4);
 @xref draw_sprite, draw_lit_sprite, color_map, set_trans_blender


I think that the name of the 'color' parameter is really misleading, since in 
most cases (and always in truecolor modes) it represents a light level:
- in 8-bit mode, it represents the first index of the color_map color mapping 
table (hence presumably its name), which is a light level if the table was 
built by create_light_table(). Of course, if the table was built by 
create_trans_table() or create_color_table(), it may represent anything.
- in truecolor mode, quoting the header of set_blender_mode() is src/gfx.c:
"In translucent drawing modes, the two colors are taken from the source
and destination images and the alpha is specified by this function. In
lit modes, the alpha is specified when you call the drawing routine, and
the interpolation is between the source color and the RGB values you pass
to this function."
And of course, in any case, its value must be in the range [0-255].

So I propose the attached patch instead.

-- 
Eric Botcazou

--- /home/eric/cvs/allegro/docs/src/allegro._tx	Fri Jan 10 13:31:04 2003
+++ allegro/docs/src/allegro._tx	Fri Jan 10 17:26:58 2003
@@ -3933,19 +3933,25 @@
 @@void @draw_lit_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y, int color);
 @xref draw_sprite, draw_trans_sprite, draw_gouraud_sprite
 @xref draw_lit_rle_sprite, color_map, set_trans_blender, bitmap_mask_color
-   Tints the sprite image to the specified color or light level, using the 
-   global color_map table, and draws the resulting image to the destination 
-   bitmap. This must only be used after you have set up the color mapping 
-   table (for 256 color modes) or blender functions (for truecolor modes).
+   In 256 color modes, use the global color_map table to tint the sprite
+   image to the specified color or to light it to the level specified by
+   'color', depending on the function which was used to build the table
+   (create_trans_table or create_light_table), and draws the resulting image
+   to the destination bitmap. In truecolor modes, use the blender functions
+   to light the sprite image using the alpha level specified by 'color' (the
+   alpha level which was passed to the blender functions is ignored) and
+   draws the resulting image to the destination bitmap. The 'color' parameter
+   must be in the range [0-255] whatever its actual meaning is. This must
+   only be used after you have set up the color mapping table (for 256 color
+   modes) or blender functions (for truecolor modes).
 
 @\void @draw_gouraud_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y,
 @@                         int c1, int c2, int c3, int c4);
 @xref draw_sprite, draw_lit_sprite, color_map, set_trans_blender
 @xref bitmap_mask_color
-   Tints the sprite to the specified color or light level, interpolating the 
-   four corner colors across the surface of the image. This must only be 
-   used after you have set up the color mapping table (for 256 color modes) 
-   or blender functions (for truecolor modes).
+   More sophisticated version of draw_lit_sprite(): the 'color' parameter is
+   not constant across the sprite image anymore but interpolated between the
+   four specified corner colors, which have the same actual meaning as it.
 
 @\void @draw_character_ex(BITMAP *bmp, BITMAP *sprite, int x, int y,
 @@                       color, bg);