(c)  Copyright 1989 Commodore-Amiga, Inc.   All rights reserved.
The information contained herein is subject to change without notice, and 
is provided "as is" without warranty of any kind, either expressed or implied.  
The entire risk as to the use of this information is assumed by the user.



                     Extended Text Fonts

                       by Andy Finkel


One of the Amiga's strengths is its use of colors.  However, under the
current OS, the use of colors with text is not well supported.  This
will change in a future release of the ROM kernel when the Amiga adopts
the ColorText format for multi-bitplane font definitions designed by
InterActive Softworks.  On the Amiga, the new text structure will be 
called an ExtendedTextFont.

The ExtendedTextFont structure is a logical way to extend the TextFont 
structure to multiple bitplanes, while retaining compatibility with current
software.  The ExtendedTextFont structure allows a program to use up to 
thirty-two colors in a normal working environment.  This structure can be 
used by any programs that need additional colors and shadings for text.
Use of the ExtendedTextFont to add colors can really improve the appearance
of a program.  However, there is a speed penalty for the additional 
bitplanes (if you use more than 2). 

To make a color text font, you can use the Font Editor or Calligrapher 
programs from InterActive Softworks.  These color fonts can then be used
in your applications by calling a special replacement module for the Amiga's
Text() routine provided by InterActive.   This replacement routine will be 
incorporated into the Amiga in a future revision of the ROM set.  For more 
information on the color text routines, contact: InterActive Softworks, 57 
Post St., #811, San Francisco, CA 94104, (415) 956-2660.  They  are also on 
BIX (address: arcade).


The new ExtendedTextFont structure is shown below.  Notice that the first
member in the structure is the old TextFont structure:


     struct ExtendedTextFont =

     {
      struct TextFont ctf_TF; 	/* Text Font Structure     */
 				/* TextFont is in "Amiga Rom Kernal 
                                     Manual, Vol. 2,p. D-41 */

     USHORT ctf_Flags;  	/* ExtendedTextFont preferences and flags */

     UBYTE ctf_Depth;  		/* Number of BitPlanes   */

     UBYTE ctf_FgColor;   	/* Color that is remapped to FgPen   */ 
     
     UBYTE ctf_Low;     	/* Lowest Color in ExtendedTextFont  */
     UBYTE ctf_High;     	/* Highest Color in ExtendedTextFont */

     UBYTE ctf_PlanePick; 	/* PlanePick as described by Images */
     UBYTE ctf_PlaneOnOff; 	/* PlaneOnOff as described by Images */  

     APTR ctf_ColorMap;  	/* Pointer to ColorMap for font */
				/* ColorMap is in "Amiga Rom Kernal 
                                     Manual, Vol. 2, p. D-42 */

     APTR ctf_CharData [8];  	/* Pointers to BitPlane Data  */
    };





The ExtendedTextFont Structure

The struct TextFont ctf_TF contains all the basic information about the 
font.  The tf_CharData pointer in ctf_TF should point to the first plane of 
CharData in the ExtendedTextFont.  By doing this, the system will be able to 
handle the font even if the Text() routines have not been modified to work
with an ExtendedTextFont.

The field, USHORT ctf_Flags, contains flags that tell what kind of an
ExtendedTextFont this is.  Current flags supported are: 

   CTF_COLORFONT  0x0001; /* ExtendedTextFont (Contains Color) */  
   CTF_GREYFONT   0x0002; /* ExtendedTextFont (Contains grey scale) */
   CTF_NORMALFONT 0x8000; /* Normal TextFont (Should not be needed) */

UBYTE ctf_Depth, gives the number of bitplanes in the ExtendedTextFont.  This
should always be greater than one since no ExtendedTextFont should ever 
contain just one bitplane - such a font could be more easily described by the 
old TextFont structure.

The field, UBYTE ctf_FgColor, contains the color that will be dynamically 
remapped during output by changing ctf_FgColor to RastPort->FgPen.  This field
allows an ExtendedTextFont to contain color outlines, shadows, etc. while also
containing a predominant color that can be changed by the user in any given 
program through the standard user palette interface.  If the font does not 
have a predominant color, set ctf_FgColor equal to 0xFF.

For example, given an ExtendedTextFont that has a blue and red outline and a
white center, the person designing the font can set ctf_FgColor equal to white.
Then when the font is used in DPaint, the white will be changed to whatever the
current foreground color is set to. 

The fields, UBYTE ctf_Low and ctf_High, contain the lowest and highest color 
values in the ExtendedTextFont.  For example, a 4 bitplane color font can have
sixteen colors, but the font may use only nine of those colors.  Thus Low=0 
and High=8 .  

The most important use of these colors is for defining the boundaries of a 
grey scale font.  If the font uses less than the total number of colors 
allowed, but needs white as the lowest and black as the highest level of 
grey, then the boundaries would have to be defined in order for the font to 
be rendered correctly.  Defaults for these values should be the lowest and 
the highest values for the given number of bitplanes.  

# of BitPlanes       Default Low         Default High
--------------       -----------         ------------
     1                   0                   1
     2                   0                   3
     3                   0                   7
     4                   0                   15
     5                   0                   31

The members UBYTE ctf_PlanePick and ctf_PlaneOnOff contain information 
for saving space in memory for some types of ExtendedTextFont structures.  
The field UBYTE ctf_PlanePick contains information about where each plane 
of data will be rendered in a given BitMap.  UBYTE ctf_PlaneOnOff contains 
information about planes that are not used to render a plane of font data.  
If ctf_PlaneOnOff contains a 0 bit for a given plane, the plane is cleared. 
If ctf_PlaneOnOff contains a 1 bit for a given plane, the plane is filled.  
Much more information can be found in the Intuition Reference Manual under 
Images and in the ROM Kernal Manual under GELs.

The APTR ctf_ColorMap field contains information about colors used by font.
Size of ColorTable is determined by ctf_ColorMap->Count. The ColorMap 
structure is the same as the structure found in graphics/view.h

The last item in the ExtendedTextFont structure is the array 
APTR ctf_CharData[8] which contains pointers to each of the BitPlanes of 
ColorFont data.  With eight bitplanes, up to 256 colors are supported. 
Since ctf_CharData is the last variable in the structure, the 
ExtendedTextFont can be expanded easily to handle more than eight 
bitplanes of data.   



How to Recognize an ExtendedTextFont

A special bit has been set aside in the TextFont structure in order to 
identify it as ExtendedText.  The bit is 0x40 in the field TextFont->tf_Style.
Thus, in order to recognize ExtendedText, test ( TextFont->tf_Style & 0x40 ) 
for a non-zero result.  The relevant defines are:

#define FSB_COLORFONT 6
#define FSF_COLORFONT (1<<6)




