[AD] Colourfont documentation change proposal

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

Attached proposed documentation.

Evert

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.315
diff -u -r1.315 allegro._tx
--- docs/src/allegro._tx	1 Apr 2005 08:50:54 -0000	1.315
+++ docs/src/allegro._tx	7 Apr 2005 15:59:26 -0000
@@ -6842,21 +6842,37 @@
 @xref grab_font_from_bitmap
 @shortdesc Grabs a font from a bitmap file.
    Tries to grab a font from a bitmap. The bitmap can be in any format that
-   load_bitmap understands but it must have a color depth of 8 bits.
+   load_bitmap understands.
 
    The size of each character is determined by the layout of the image, which
    should be a rectangular grid containing all the ASCII characters from
-   space (32) up to the tilde (126). Use color 0 for the transparent
+   space (32) up to the tilde (126). The way the characters are separated
+   depends on the colourdepth of the image file:
+<ul><li>
+paletted (8 bit) image file<br>
+   Use colour 0 for the transparent portions of the characters and fill the 
+   spaces between each letter with color 255.  
+<li>
+High (15/16 bit) and true (24/32 bit) colour image file<br>
+   Use bright pink (maximum red and blue, zero green) for the transparent
    portions of the characters and fill the spaces between each letter with
-   color 255.
+   bright yellow (maximum red and green, zero blue).
+</ul>
    
-   Note that in each horizontal row the color-0 bounding boxes around the
-   characters should align and have the same height.
+   Note that in each horizontal row the bounding boxes around the characters 
+   should align and have the same height.
    
    Probably the easiest way to get to grips with how this works is to load up 
    the `demo.dat' file and export the TITLE_FONT into a PCX file. Have a look
    at the resulting picture in your paint program: that is the format a font
    should be in.
+
+   Take care with high and true colour fonts: Allegro will convert these to the
+   current colourdepth when you load the font. If you try to use a font on
+   a bitmap with a different colourdepth Allegro will do colourconversions on
+   the fly, which will be rather slow. For optimal performance you should
+   set the colourdepth to the colourdepth you want to use before loading any
+   fonts.
 @retval
    Returns a pointer to the font or NULL on error. Remember that you are
    responsible for destroying the font when you are finished with it to
@@ -6953,6 +6969,8 @@
    and a color font is in use, it will be drawn using the colors from the
    original font bitmap (the one you imported into the grabber program),
    which allows multicolored text output.
+   For high and true color fonts, the foreground color is ignored and always
+   treated as -1.
 
 @\void @textout_centre_ex(BITMAP *bmp, const FONT *f, const char *s,
 @@                       int x, y, color, bg);