TABLE OF CONTENTS

ttrender.library/background
ttrender.library/TT_GetFontAttrsTagList
ttrender.library/TT_PutStr
ttrender.library/TT_PutStrTagList
ttrender.library/TT_PutUStr
ttrender.library/TT_PutUStrTagList
ttrender.library/TT_SetFont
ttrender.library/TT_SetModesTagList
ttrender.library/TT_StrWidth
ttrender.library/TT_UStrWidth
ttrender.library/background                       ttrender.library/background


   PURPOSE

   The library is fast, AmigaOS friendly TrueType render engine. It has
   nothing to do with Amiga outline font system. This system has a lot of
   limitations which make it useless for high speed and quality text output.
   If someone wants an integration of TrueType with AmigaOS bullet.library
   like outline font system, should consider using ttf.library. This library
   opens TrueType font by itself and renders high quality glyphs directly
   into any RastPort.

   FREETYPE2 BASED

   The render engine of the library is based on FreeType2 project
   (http://www.freetype.org). This version of ttrender.library uses 2.0.9
   FreeType build.

   REQUIREMENTS

   The library requires at least CyberGraphX 3.x or Picasso96 2.x system. It
   is possible that non-antialiased output will be possible on AGA machines
   in the future.

   FEATURES

   The library expands FreeType functionality making usage of TrueType fonts
   easy and comfortable. Below you can find key features:

   - renders whole strings (not single glyphs) with kerning.
   - antialiasing to any (not neccesarily uniform color) background.
   - system compatible output to any (including planar) RastPort.
   - supports JAM1. JAM2, INVERSVID, COMPLEMENT RastPort modes.
   - supports 8-bit to Unicode mapping with "ENV:ttfcodepage" table
     compatible with ttf.library.
   - allows for direct 16-bit Unicode string rendering.
   - easy to use, taglist based API.
   - efficient system-wide glyph cache system.

   CACHE SYSTEM

   The library uses my own (not that experimental FreeType one) cache system
   speeding up strings rendering alot. The cache is system-wide, it means it
   is common to every application using ttrender.library. Only used glyphs of
   given font face are cached. If the library encounters cache miss, missing
   glyph is loaded and rasterized on the fly. Cache system is totally
   transparent to the library user, so there are no cache functions in the
   library API. Cache uses one single Exec memory pool avoiding memory
   fragmentation.

   FONT DIRECTORIES

   The library searches for a font in three directories:
   1. Process current directory.
   2. "PROGDIR:" of the calling application.
   3. "FONTS:_TrueType_Outlines" as a common location for TrueType fonts.

ttrender.library/TT_GetFontAttrsTagListtrender.library/TT_GetFontAttrsTagList

   NAME
       TT_GetFontAttrsTagList -- Gets current font attributes (V2).

   SYNOPSIS
       count = TT_GetFontAttrsTagList (taglist)
                                       A0

       ULONG TT_GetFontAttrsTagList (struct TagItem*);

       count = TT_GetFontAttrsTags (Tag1, ...)

       ULONG TT_GetFontAttrsTags (Tag, ...);

   FUNCTION
       Gets current (set by last SetFont() call) font attributes (global
       metrics mainly). The value of every attribute is written to an ULONG
       pointed by ti_Data field of the TagItem. Here is a list of attributes:

       TTFA_Ascender - This is a distance (in pixels) between the baseline
         and top elements of the font (typically these elements are accents
         of capital letters). NOTE: many shareware TT fonts have wrong ascen-
         der value.

       TTFA_Descender - This is a distance (in pixels) between the baseline
         and bottom elements of the font (typically in letters 'p', 'q', 'g'
         etc.). NOTE: many shareware TT fonts have wrong descender value.
         Descender value is typically negative (as bottom elements usually
         are placed below the baseline).

       NOTE: TTFA_Ascender and TTFA_Descender are guarranted to fulfill
       following formula: ascender - descender = font height.

   INPUTS
       taglist - the list of attributes.

   RESULT
       counter - the count of recognized tags.

   NOTES

   BUGS

   SEE ALSO
       TT_SetFont()

ttrender.library/TT_PutStr                         ttrender.library/TT_PutStr

   NAME
       TT_PutStr -- Renders string into RastPort.

   SYNOPSIS
       success = TT_PutStr (string)
                            A0

       BOOL TT_PutStr (UBYTE*);

   FUNCTION
       Renders the string using current ttrender.library settings, and
       current RastPort settings (pen, drawmode). String is rendered at
       current RastPort (x, y) position, where 'y' means position of font
       baseline. String is converted to Unicode according to
       "ENV:ttfcodepage" mapping table. If there is no mapping table,
       ISO-8859-1 mapping is used which is equal to ECMA Latin1 Amiga
       standard.

   INPUTS
       string - NULL-terminated string to render to.

   RESULT
       TRUE if the string has been rendered.

   EXAMPLE
       /* write a text with pen 1 and transp. background at (100, 100) */
       /* rendering is done to a system window                         */

       SetAPen(win->RPort, 1);
       SetDrMd(win->RPort, JAM1);
       Move(win->RPort, 100, 100);
       TT_SetModesTags(TTA_Window, win);
       TT_PutStr("some text");

   NOTES

   BUGS

   SEE ALSO
       TT_PutStrTagList(), TT_SetModesTagList(), TT_PutUStr()

ttrender.library/TT_PutStrTagList           ttrender.library/TT_PutStrTagList

   NAME
       TT_PutStrTagList -- Renders string into RastPort with local settings.

   SYNOPSIS
       success = TT_PutStrTagList (string, taglist)
                                   A0      A1

       BOOL TT_PutStrTagList (UBYTE*, struct TagItem*);

       success = TT_PutStrTags (string, Tag1, ...)

       BOOL TT_PutStrTags (UBYTE*, Tag, ...);

   FUNCTION
       Renders the string allowing temporary override of current
       ttrender.library settings, and current RastPort settings. Attributes
       given in the taglist have local precedence over global
       ttrender.library settings set by TT_SetModesTagList() call. Check
       TT_SetModesTagList() docs for a list of tags.

   INPUTS
       string - NULL-terminated string to render to.

       taglist - local attributes valid only in this function call.

   RESULT
       TRUE if the string has been rendered.

   EXAMPLE

       /* Turn antialias mode on globally */

       TT_SetModesTags(TTA_Antialias, TRUE);

       TT_PutStr("some text");           /* this text will be antialiased */
       TT_PutStrTags("another text",
         TTA_Antialias, FALSE,           /* this text won't (locally      */
         TAG_END);                       /* switched off)                 */
       TT_PutStr("third text");          /* this text will be antialiased */

   NOTES

   BUGS

   SEE ALSO
       TT_PutStr(), TT_SetModesTagList()

ttrender.library/TT_PutUStr                       ttrender.library/TT_PutUStr

   NAME
       TT_PutUStr -- Renders Unicode string into RastPort.

   SYNOPSIS
       success = TT_PutUStr (string)
                             A0

       BOOL TT_PutUStr (UWORD*);

   FUNCTION
       Renders the string using current ttrender.library (RastPort, ColorMap,
       render mode), and RastPort settings (pen, drawmode). String is
       rendered at current RastPort (x, y) position, where 'y' means position
       of font baseline. String is an 16-bit Unicode one and should be
       terminated with 16-bit zero.

   INPUTS
       string - 16-bit Unicode NULL-terminated string to render to.

   RESULT
       TRUE if the string has been rendered.

   BUGS

   SEE ALSO
       TT_PutUStrTagList(), TT_SetModesTagList(), TT_PutStr()

ttrender.library/TT_PutUStrTagList         ttrender.library/TT_PutUStrTagList

   NAME
       TT_PutUStrTagList -- Renders 16-bit Unicode string into RastPort with
                           local settings.

   SYNOPSIS
       success = TT_PutUStrTagList (string, taglist)
                                   A0      A1

       BOOL TT_PutUStrTagList (UWORD*, struct TagItem*);

       success = TT_PutUStrTags (string, Tag1, ...)

       BOOL TT_PutUStrTags (UWORD*, Tag, ...);

   FUNCTION
       Renders the 16-bit Unicode string allowing temporary override of
       current ttrender.library settings, and current RastPort settings.
       Attributes given in the taglist have local precedence over global
       ttrender.library settings set by TT_SetModesTagList() call. Check
       TT_SetModesTagList() docs for a list of tags.

   INPUTS
       string - NULL-terminated 16-bit Unicode string to render to.

       taglist - local attributes valid only in this function call.

   RESULT
       TRUE if the string has been rendered.

   NOTES

   BUGS

   SEE ALSO
       TT_PutUStr(), TT_SetModesTagList()

ttrender.library/TT_SetFont                       ttrender.library/TT_SetFont

   NAME
       TT_SetFont -- Opens TrueType font with given name and size.

   SYNOPSIS
       success = TT_SetFont (name, size)
                             A0    D0:16

       BOOL TT_SetFont (STRPTR, UWORD);

   FUNCTION
       Opens TrueType font file and sets current font size in pixels. Every
       following call to TT_PutStr[Tags/TagList]() or
       TT_PutUStr[Tags/TagList]() will use this font and size.

   INPUTS
       name - pointer to a NULL terminated string containing font name.
              ".ttf" suffix will be added automatically. Search order is
              defined as follows:
              1. current directory
                  "<name>.ttf"
              2. PROGDIR:
                  "PROGDIR:<name>.ttf"
              3. "FONTS:_TrueType_Outlines" (by analogy to _Bullet_Outlines)
                  "FONTS:_TrueType_Outlines/<name>.ttf"
       size - screen size of the font in pixels (to be exact - it is the
              distance between baselines of two following lines of text
              expressed in pixels).

   RESULT
       success - TRUE if the font has been opened successfully, FALSE
                 otherwise. This function can fail for three reasons:
                 1. File not found or malformed.
                 2. Zero font size.
                 3. No memory for requested (too big?) size.

   NOTES

   BUGS

   SEE ALSO
       TT_PutStr(), TT_PutUStr()

ttrender.library/TT_SetModesTagList       ttrender.library/TT_SetModesTagList

   NAME
       TT_SetModesTagList -- Sets global rendering settings.

   SYNOPSIS
       count = TT_SetModesTagList (taglist)
                                   A0

       ULONG TT_SetModesTagList (struct TagItem*);

       count = TT_SetModesTags (Tag1, ...)

       ULONG TT_SetModesTags (Tag, ...);

   FUNCTION
       Sets global (per library opening) render engine settings. Every
       following TT_PutStr() / TT_PutUStr() call will use these settings.
       They can by overriden temporarily however, with TT_PutStrTagList() /
       TT_PutUStrTagList() calls. Here is a list of attributes:

       TTA_RastPort - (struct RastPort*) - Destination RastPort for
         rendering. The library will adhere to this RastPort settings like
         draw mode, pens, current pen position.

       TTA_ColorMap - (struct ColorMap*) - ColorMap used to convert pen
         number to RGB color value.

       TTA_Screen - (struct Screen*) - useful shortcut for TTA_RastPort and
         TTA_ColorMap, automatically sets screen ColorMap and screen
         RastPort.

       TTA_Window - (struct Window*) - useful shortcut for TTA_RastPort and
         TTA_ColorMap, automatically sets window ColorMap and window
         RastPort.

       TTA_Antialias - (BOOL) - controls antialiasing (on or off).

   INPUTS
       taglist - the list of global attributes.

   RESULT
       counter - the count of recognized tags.

   NOTES
       TTA_RastPort and TTA_ColorMap attributes have precedence over
       TTA_Screen and TTA_Window ones. It can be useful if one wants to use
       window/screen ColorMap but separate RastPort. An example:

       TT_SetModesTags(TTA_Window, win, TTA_RastPort, my_rport, TAG_END);

       It will set window colormap and 'my_rport' as targets. Note that the
       precedence is based on tag values, not on tags order. So ordering of
       the tags is meaningless for the function.

   BUGS

   SEE ALSO
       TT_PutStr(), TT_SetModesTagList()

ttrender.library/TT_StrWidth                     ttrender.library/TT_StrWidth

   NAME
       TT_StrWidth -- Gets string width in pixels (V2).

   SYNOPSIS
       width = TT_StrWidth(string)
                           A0

       ULONG TT_StrWidth (UBYTE*);

   FUNCTION
       Calculates the pixel width of given string written with current font.
       Takes kerning into account. String will be mapped to Unicode using
       "ENV:ttfcodepage" table (see TT_PutStr() docs).

   INPUTS
       string - the width of this string will be calculated.

   RESULT
       width - the width of the string in pixels.

   NOTES

   BUGS

   SEE ALSO
       TT_PutStr(), TT_SetFont()

ttrender.library/TT_UStrWidth                   ttrender.library/TT_UStrWidth

   NAME
       TT_UStrWidth -- Gets Unicode 16-bit string width in pixels (V2).

   SYNOPSIS
       width = TT_UStrWidth(string)
                            A0

       ULONG TT_UStrWidth (UWORD*);

   FUNCTION
       Calculates the pixel width of given 16-bit Unicode string written
       with current font. Takes kerning into account.

   INPUTS
       string - the width of this 16-bit Unicode string will be calculated.

   RESULT
       width - the width of the string in pixels.

   NOTES

   BUGS

   SEE ALSO
       TT_PutUStr(), TT_SetFont()