TABLE OF CONTENTS ttrender.library/background ttrender.library/font_database ttrender.library/TT_GetFontAttrsTagList ttrender.library/TT_OpenFontTagList 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. ttrender.library/font_database ttrender.library/font_database GENERAL INFORMATION 'ttrender.database' is a plain text file (placed in 'ENV:' directory) containing informations about TrueType fonts available in the system. There is no tool (yet) to automatically generate it, the database have to be written by hand. Every line contains one keyword followed by parameter value. Name and value can be separated by space(s) or equality sign, exactly the same as shell command parameters (to say more - database is parsed by the same ReadArgs() system call as shell command parameters are). Parameter values containing spaces should be quoted. Here are some examples: FAMILY Tahoma FAMILY=Times FAMILY = "Times New Roman" FAMILY "Weird Font" KEYWORDS FAMILY - defines the name used for font opening. All variants of the font (italic, bold, black, heavy, light, demi etc.) will have the same family name. Family names (and aliases described below) are case insensitive. ALIAS - defines another name for the same family. It generally has three purposes: 1. Similar names for the same font, like "Times", "TimesNewRoman" and "Times New Roman". 2. One replacement font for some very similar ones, for example "Helvetica" and "Switzerland" can be aliased to "Arial". 3. Generic names like "default", "serif", "sans-serif", "monospaced". An application can request generic name without specific family name, or generic font can be used as a fallback if given name can't be found in the database. For example you can alias "monospaced" to "Courier", and an application (be it CSS compatible HTML viewer) can request 'LucidaConsole, monospaced'. If there is no LucidaConsole font in the system, Courier will be used. The same way you can alias any font to any other, for example Times to Arial, this makes not much sense however. 'default' font can be used as a last resort. FILE - defines single TrueType font file and its attributes, which are: FILE itself - defines a path to the font file. Font files can be placed anywhere in the filesystem(s). There is no default value for the attribute, it must be given explicitly. WEIGHT - defines font weight in Cascading Style Sheets manner, where 0 means the lightest and 999 means the heaviest weight. 400 is typical value for normal weight, 700 for bold. Default value is 400 (normal). STYLE - "regular" or "italic" for italic and oblique faces. Default value is "regular". SMOOTHSMALL - controls antialiasing of small sizes. Any sizes smaller or equal to SMOOTHSMALL will be antialiased. Note: can be overriden by application. Default value is 9. SMOOTHBIG - controls antialiasing of big sizes. Any sizes bigger or equal to SMOOTHBIG will be antialiased. Note: can be overriden by application. Default value is 18. Every FILE is automatically added to the nearest FAMILY defined above in the database file. Every ALIAS or FILE placed before the first FAMILY is rejected quietly. COMMENTS You can place any full-line comments in the file starting a line with hash or semicolon. End-line comments are not supported. 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_OpenFontTagList ttrender.library/TT_OpenFontTagList NAME TT_OpenFontTagList -- Opens TrueType font using font database. (V3) SYNOPSIS success = TT_OpenFontTagList (taglist) A0 BOOL TT_OpenFontTagList (struct TagItem*); success = TT_OpenFontTags (Tag1, ...) BOOL TT_OpenFontTags (Tag, ...); FUNCTION Finds and sets TrueType font from the font database best matching attributes given. Every following call of TT_PutStr[Tags/TagList]() or TT_PutUStr[Tags/TagList]() will use this font and size. INPUTS taglist - a list of tags containing requested font attributes. Following tags are recognized: TTFA_FamilyTable - NULL-terminated table of pointers to font family names from the most desired to the last resort fallback. It is intended for easy implementing things like HTML 'FONT FACE' attribute. You can use real family names here, as well as generic names: 'serif', 'sans-serif', 'monospaced', 'cursive', 'fantasy', and 'default', especially useful as a fallbacks. Family names are case insensitive. The default value for the tag is {"default", NULL}; TTFA_Size - font size in pixels defined as the distance between baselines of two following text lines. The default value for this tag is 14 pixels. TTFA_Style - there are two styles defined: TTFA_Style_Regular (default), TTFA_Style_Italic. TTFA_Weight - defined with Cascading Style Sheets manner as a number from 0 (the lightest face) to 999 (the heaviest face). You can use TTFA_Weight_Normal (equal to 400) and TTFA_Weight_Bold (equal to 700) shortcuts. TTFA_Weight_Normal is the default value. RESULT success - TRUE if the font has been opened successfully, FALSE otherwise. This function can fail for four reasons: 1. There is no matching face in the database (NOTE: even 'default' can fail if not defined in the database!) 2. File not found or malformed. 3. Zero font size. 4. No memory for requested (too big?) size. NOTES BUGS SEE ALSO TT_PutStr(), TT_PutUStr(), font_database 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 ".ttf" 2. PROGDIR: "PROGDIR:.ttf" 3. "FONTS:_TrueType_Outlines" (by analogy to _Bullet_Outlines) "FONTS:_TrueType_Outlines/.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 This function is considered obsolete starting from release 3 of the library, because it by-passes font database. Use TT_OpenFontTagList() instead. BUGS SEE ALSO TT_PutStr(), TT_PutUStr(), TT_OpenFontTagList() 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()