Aros/Developer/Docs/Libraries/TTEngine
Introduction
[edit | edit source]- ttf
- bullet
- ttrender
This ttengine (formerly ttrender) system has a lot of limitations which make it unsuitable 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 truetype2.library. Ttengine.library opens TrueType font by itself and renders glyphs directly into any RastPort.
The render engine of the library is based on FreeType2 project (http://www.freetype.org). This version of ttrender.library uses 2.1.3 FreeType build.
The includes used for contrib programs are the ones in:
AROS/bin/linux-i386/gen/include/proto
Expected them to use (assuming its a hosted build your doing..) -:
AROS/bin/linux-i386/AROS/Development/include/proto
#include <proto/ttengine.h>
This is for ttengine.library which is ported to AROS. For more info on the lib. Not in Contrib, because a (linklib) version of freetype isn't built. see https://en.wikibooks.org/wiki/Aros/Developer/Docs/Libraries/FreeType2
The library expands FreeType functionality making usage of TrueType fonts easy and comfortable.
- renders whole strings (not single glyphs) with kerning. - anti-aliasing to any (not necessarily uniform color) background. - user adjustable gamma correction. - optional text transparency. - 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/32-bit Unicode string rendering. - supports ISO-8859 and UTF-8 text encodings. - easy to use, graphics.library like API. - efficient system-wide glyph cache system. - font database system allows flexible font files storage and advanced faces classification.
TTF is just an older standard while OTF is a new standard with, in some cases, extra features. The character outlines in OTFs are created by cubic Bezier paths, whereas TTFs are made of quadratic Beziers.
TTEngine explained step by step
1. How to print a text with TTEngine.
1.1. Open TTEngine.
1.2. Load a font.
1.3. Render to a window.
1.4. RastPort cleanup.
1.5. Close a font.
1.6. Close TTEngine.
2. I want to do some more.
2.1. Changing text colour.
2.2. Changing draw mode.
2.3. Low long my text is?
2.4. Controlling antialias.
2.5. Using many fonts at once.
2.6. Text encodings.
3. Advanced features.
3.1. How to get a pixelmap of a string.
3.2. Text metrics.
3.3. Fitting text into a rectangle.
3.4. Scaling, shearing, rotation.
3.5. Affine transform.
TTEngine is just an AmigaOS shared library so it should be opened the same way every shared library is. You should include TTEngine header file first (I assume you use C or C++ programming language). TTEngine has a few header files for different compilers. Supported compilers are GCC, VBCC, SAS/C, Storm C, Maxon C++ and Dice C. To improve portability and programmer comfort <proto/ttengine.h> file automatically include headers for your compiler. So you can just put
#include <proto/ttengine.h>
into your program includes. Then you should define the library base. Some compilers (GCC for example) do it automatically for you. The library base is named TTEngineBase and is of type struct Library*. There are no user accesible fields in the base, it should be treated as a black-box. If your compiler does not create library bases you can define TTEngine library base as follows:
struct Library *TTEngineBase;
Now you are ready to open TTEngine. As for every shared library you use OpenLibrary() from exec.library. Do not forget to check if TTEngine was opened succesfully. Your code will be similar to this:
TTEngineBase = OpenLibrary("ttengine.library", 5);
if (!TTEngineBase) Printf("Can't open TTEngine!\n");
After this step you are ready to use all the TTEngine functions.
Of course you have to load TrueType font before printing any text. TT_OpenFont() will do this for you. It is a taglist driven function. Tags and taglists are very common to AmigaOS, so you should be familiar with them. You specify font attributes by tags. Font name is probably the most important. There are two possible ways to specify font name. Firstly you can give it directly as a path to font file using TT_FontFile tag. It is especially useful if your application uses some specific font containing for example musical notes, electronics symbols etc. It is however not recommended for general use, because it forces your application user to keep the font in some fixed directory with fixed name. Better way is specify font file by family and style and allow TTEngine to find best matching font in the database. TT_FamilyTable tag specifies a table containing some font family names. Why table instead of just one name? It is possible user has not a font you are requesting. You can provide a number of fallback families, these will be tried in turn. Assume you set following family table:
STRPTR my_table[] = {"Tahoma", "Arial", "sans-serif", "default", NULL};
TTEngine try to load Tahoma font. If it can't be loaded, Arial will be tried. If Arial fails too, TTEngine will try to load a font marked as "default sans-serif" in the database. The last resort is a font marked as "default". Null pointer at the end of table is compulsory as it marks the table end, so you need not specify how many families are in the table. Family however does not specify the font precisely, as it contains fonts of different weight and style. Additional two tags can be used for this. TT_FontWeight as its name says specifies requested weight and its value can be a number from 1 to 1000. This is a way Cascading Style Sheets use. TT_FontWeight_Normal and TT_FontWeight_Bold are the shortcuts for common weights. Fonts have also a number of styles, typically regular style and italic (sometimes called oblique) one. The style can be selected with TT_FontStyle tag and TT_FontStyle_Regular and TT_FontStyle_Italic values. The last important thing is to specify font size. As you can guess TT_FontSize tag does the thing. Just give it the font height in pixels.
All the described tags have reasonable default values (well, except TT_FontFile, but there is no reasonable default for this...). TT_FamilyTable defaults to {"default", NULL}; TT_FontWeight to TT_FontWeight_Normal, TT_FontStyle to TT_FontStyle_Regular and TT_FontSize to 14 pixels. So you can safely call TT_OpenFont() like this:
font = TT_OpenFont(TAG_END);
It will open default font, regular style, normal weight, 14 pixels size. Let's see some more common example. We try to open Georgia font with some fallbacks, bold italic, 48 pixels.
table = {"Georgia", "Times", "serif", "default", NULL};
font = TT_OpenFont(
TT_FamilyTable, (ULONG)table,
TT_FontStyle, TT_FontStyle_Italic,
TT_FontWeight, TT_FontWeight_Bold,
TT_FontSize, 48,
TAG_END);
Here is another example where font is opened from file specified directly. Of course TT_FontStyle and TT_FontWeight make no sense here since style and weight are used to select font file, not to transform font glyphs.
font = TT_OpenFont( TT_FontFile, (ULONG)"PROGDIR:fonts/SpecialSymbols.ttf", TT_FontSize, 37, TAG_END);
Font handle returned by TT_OpenFont is of type APTR and should be treated as a black-box value containing no public fields. Remember to check if the value returned by TT_OpenFont() is not NULL. The function may fail for a few reasons. It may run out of memory, TTEngine may be unable to find matching font in the database, font file may be missing or corrupted.
Now, when you have a font loaded you can try to print some text. The most common case is printing into AmigaOS window. I assume here you know how to open a window and how to handle it. Rendering to other targets such as screen or separate RastPort will be explained later. Most of TTEngine functions use RastPort as their first parameter. As you know window RastPort can be accessed as window->RPort. Our next step will be setting the font for use with window RastPort. It is done by TT_SetFont() call:
TT_SetFont(window->RPort, font); TT_SetFont() returns boolean value of success (TRUE or FALSE). It may fail because it allocates a bit of memory, so for your application reliability you should check returned value.
Now you should specify target window for TTEngine using TT_SetAttrs():
TT_SetAttrs(window->RPort, TT_Window, (ULONG)window, TAG_END);
Where in the window our text will be printed? TTEngine uses RastPort settings whereever possible. Text is always drawn at current RastPort pen position so you should just Move() where you want. Then you can render the text with TT_Text():
Move(window->RPort, 20, 50); TT_Text(window->RPort, "Hello world!", 12);
You have probably noticed TTEngine functions are very similar to graphics.library text functions. This is intentional, for example TT_Text() has the same prototype as Text(), and takes its parameters in the same processor registers. If you have any expirience with graphics.library and text, you will find TTEngine very easy to use.
TTEngine rendering target is always a RastPort. It can be window RastPort, screen RastPort, or a separate one. For every RastPort TTEngine is used with, it creates rendering environment. The environment for a RastPort is created when TT_SetAttrs() or TT_SetFont() is called the first time for this RastPort. All subsequent calls to any TTEngine function taking RastPort as a parameter, trigger a search for an environment of this RastPort (all the environments are linked in a list). Only TT_SetAttrs() and TT_SetFont() are able to create new environment if one does not exist. When you've finished all TTEngine rendering to a RastPort you should dispose the rendering environment for this RastPort. Why? There are two reasons to do this.
Rendering environment takes some memory. If you don't free it, it will stay allocated. Fortunately this memory is allocated within TTEngine internal memory pool. Then the memory will be freed when ttengine.library gets expunged. Memory leak can be dangerous however if your application opens and closes windows many times, for example it is a kind of "start menu". It is quite possible Intuition will create new window RastPort at the same address as just closed one. If the system is generally idling (all running applications are waiting for user input) you have great chance it will happen this way. Then TTEngine use old environment instead of creating (and initializing to default state) a new one. It can lead to weird results.
Rendering environment can't be disposed automatically. Even if I try to patch the system to track RastPort life. There is no function to create or dispose a RastPort, it can be as well created "by hand". That is why TTEngine provides a function for disposing rendering environment called TT_DoneRastPort(). You should call it after the last text rendering operation to the RastPort, but before the RastPort gets disposed. If you are working with window, call TT_DoneRastPort() just before CloseWindow().
TT_DoneRastPort(window->RPort); CloseWindow(window);
When you do not need a font anymore, you should close it (note that you can use one font in many RastPorts at once, there is no need to open a font separately for every RastPort). Use TT_CloseFont(), it is very simple:
TT_CloseFont(font);
TTEngine should be closed after use, as every shared library does. CloseLibrary() from exec will do this for you. Do not forget to close all opened fonts before.
CloseLibrary(TTEngineBase);
There are two ways to change text foreground and background colours with TTEngine. The first method is more general and is based on RastPort and its pens. Every RastPort has two pens. APen is the foreground pen and is used for many operations like drawing pixels, lines, rectangles, flood fill etc. BPen is the background pen used for example in JAM2 mode of text output. TTEngine uses RastPort pens as default rendering colours. Using RastPort pens is very simple if you want to output text using system pens. For example let's print some text (without background) using pen 1 (in typical Workbench palette it is black):
SetDrMd(window->RPort, JAM1); SetAPen(window->RPort, 1); TT_Text(window->RPort, "[maybe] black text", 18); Color example 1
In the code above, assumed font is already opened and set for the RastPort. Things get a bit complicated when you want specific RGB colour, not just a system pen. You have to remember TTEngine can work in environment with very few pens available, so your request for red colour can end up in white on traditional, 4 colours Workbench screen. On custom screen you can just set all the palette to the colours you want, and use them, setting pens with SetAPen(). On public screen you can try to obtain best matched pen as shared, or obtain any pen as exclusive and change its colour to the desired one. The second approach can fail if there are no free pens on the screen.
/* obtain pen as shared */
LONG red_pen;
red_pen = ObtainBestPen(window->WScreen->ViewPort.ColorMap,
0xFFFFFFFF, 0x00000000, 0x00000000, TAG_END);
SetAPen(window->RPort, red_pen);
TT_Text(window->RPort, "more or less red text", 21);
/* ... */
TT_DoneRastPort(window->RastPort);
ReleasePen(window->WScreen->ViewPort.ColorMap, red_pen);
CloseWindow(window); Color example 2
/* obtain pen as exclusive */
LONG red_pen;
red_pen = ObtainPen(window->WScreen->ViewPort.ColorMap, -1,
0xFFFFFFFF, 0x00000000, 0x00000000, PEN_EXCLUSIVE);
if (red_pen != -1)
{
SetAPen(window->RPort, red_pen);
TT_Text(window->RPort, "exactly red text", 16);
}
else PutStr("No free pens.\n");
/* ... */
TT_DoneRastPort(window->RastPort);
ReleasePen(window->WScreen->ViewPort.ColorMap, red_pen);
CloseWindow(window); Color example 3
As you can see, it is not very comfortable, however it will work on every screen from two colours to 32 bit. But on the other hand you can be reported that there are no free pens while working on 24-bit screen, which is a bit imprecise... That is why TTEngine allows for another way of specifing text colours via TT_SetAttrs() using TT_Foreground and TT_Background tags. Note however this alternative way works only for RGB RastPorts, it means 15 or more bits depth. For palette based RastPorts these tags are ignored. Tags take 32-bit colour value defined as 0RGB, most significant byte has to be zero, next three bytes contain red, green and blue components of the colour. Here is an example:
TT_SetAttrs(window->RastPort, TT_Foreground, 0x0060FF80, TT_Background, 0x00000000, TAG_END); SetDrMd(window->RastPort, JAM2); TT_Text(window->RastPort, "neon green on black back", 24); Color example 4 You may want to return TTEngine text colour control back to RastPort and its pens. It can be done with special values for background and foreground tags as shown below: TT_SetAttrs(window->RastPort, TT_Foreground, TT_Foreground_UseRastPort, TT_Background, TT_Background_UseRastPort, TAG_END);
TTEngine supports and uses all RastPort drawing modes and its combinations. These are:
JAM1 - glyphs are laid on existing background. This is the default. Glyphs colour is controlled by RastPort APen or TT_Foreground tag.
JAM2 - glyphs are rendered with background colour rectangle. Background colour is defined by RastPort BPen or TT_Background tag.
INVERSVID - foreground and background are reversed. INVERSVID can be combined with JAM1 or JAM2.
COMPLEMENT - pixels are not rendered in background or foreground color, but negated. When a text is rendered again at the same position it disappears, double negation is equal to no
operation. COMPLEMENT can be combined with JAM1 or JAM2 as well as with INVERSVID. On RGB RastPorts negation is replaced by XOR operation between the background and pixel. Double XOR with the same value is equal to no operation too.
Here are examples of JAM1 and JAM2 modes also combined with INVERSVID. The window backgound is a gray checkerboard. Foreground colour is yellow, background colour is dark blue.
JAM1 This is an example of JAM1 draw mode. Yellow glyphs are smoothly laid on the checkerboard. JAM2 This is JAM2. Glyphs are rendered over a rectangle of RastPort background colour. JAM1 combined with INVERSVID. Foreground and transparent background are reversed. JAM2 combined with INVERSVID. Background and foreground are reversed. RastPort draw modes are set by SetDrMd() function as usual. TTEngine has however another interesting draw mode not supported by graphics.library. This is transparency. Transparency as well as smoothing works for RGB RastPorts only. For palette based RastPorts transparency setting is ignored. As transparency is TTEngine specific, TT_SetAttrs() should be used to control it with TT_Transparency tag. It takes an unsigned byte value (0 - 255, higher bytes are truncated). Zero means no transparency, glyphs are fully opaque (0 is the default setting). Higher values mean more transparency, with transparency of 255 text is almost invisible (well, you probably need 24-bit screen to see something with TT_Transparency set to 255). Of course transparency can be freely combined with RastPort draw modes. If JAM2 is selected, transparency is applied to both foreground and background colours. Look at examples below.
JAM1 JAM2 Transparency JAM1, transparency 51 (20%) JAM2, transparency 51 (20%) 20% (51, 0x33) JAM1, transparency 128 (50%) JAM2, transparency 128 (50%) 50% (128, 0x80) JAM1, transparency 205 (80%) JAM2, transparency 205 (80%) 80% (205, 0xCD) A little example code below shows how one can set JAM2 mode with INVERSVID and 25% transparency:
SetDrMd(window->RastPort, JAM2 | INVERSVID); TT_SetAttrs(window->RastPort, TT_Transparency, 0x40, TAG_END);
You may want to know the length of a text in pixels. It can be useful if doing any text layout, aligning to the right, centering or justifying. TT_TextLength() can be used for obtaining pixel length of a string. It is used the same as graphics.library TextLength(). Returned value is horizontal RastPort pen advance in pixels. Note that for some fonts (especially italic) some pixels may render before text start point and some after text end point. For in-depth discussion of text metrics see 3.2. Text metrics. TT_TextLength() however is precise enough for typical applications. Here is an example of use:
LONG length; length = TT_TextLength(window->RastPort, "Tell me how long is it.", 25);
If you want to calculate text pixel length before you open your window, you can use screen RastPort for calculation. Do not forget to call TT_DoneRastPort() after calculations. The example below shows how can you measure the text before you open a window on Workbench screen:
struct Screen *wb; LONG textlen; wb = LockPubScreen(NULL); TT_SetFont(&wb->RastPort, font); textlen = TT_TextLength(&wb->RastPort, "Some text", 9); TT_DoneRastPort(&wb->RastPort); UnlockPubScreen(NULL, wb);
You do not need to hold the screen lock until a window is opened on it because text length does not depend on RastPort properties (of course you should use the same font for length calculation and rendering...).
Antialias is one of TTEngine key features. Note it works on RGB RastPorts only. TTEngine antialias is much better compared to bare FreeType ports because it is brightness based, not just an average between background and foreground. Actual background pixel colour (or background colour in JAM2) and foreground colour are decomposed to a brightness and a hue. Both the components are averaged separately, then translated back to RGB domain. Sometimes however it may be preferrable to switch the smoothing off. TT_Antialias tag of TT_SetAttrs() function can be used for this. The tag has three possible values described below:
TT_Antialias_Off - switches smoothing off regardless of font size.
TT_Antialias_On - switches smoothing on regardles of font size.
TT_Antialias_Auto - antialias depends on font size.
There are two threshold sizes, let's name it Min and Max (Min is usually lower than Max). If the font size is between Min and Max (including them), smoothing is switched off. If the font size is lower than Min, or higher than Max, smoothing is switched on. Min and Max can be adjusted by user in the font database. If a font is opened via TT_FontFile (which bypasses the database) Min is set to 10, Max is set to 18. This behaviour bases on the fact that small sizes are more readable without smoothing. Sizes below 9 (about) are unreadable anyway and smoothing them gives better "overall look". Sizes above about 18 looks better smoothed. User can adjust threshold values separately for every font face, she can also turn smoothing on or off for all sizes of given face. Do not override TT_Antialias_Auto without a reason. It is also default value.
Times New Roman 8
Times New Roman 8 pixels not smoothed Times New Roman 13
Times New Roman 13 pixels not smoothed Times New Roman 18
Times New Roman 18 pixels not smoothed Times New Roman 8 smoothed
Times New Roman 8 pixels smoothed Times New Roman 13 smoothed
Times New Roman 13 pixels smoothed Times New Roman 18 smoothed
Times New Roman 18 pixels smoothed
Comparison of different sizes of Times New Roman antialiased or not.
Examples
[edit | edit source]References
[edit | edit source]ttengine.library/background
ttengine.library/font_database
ttengine.library/TT_AllocRequest
ttengine.library/TT_CloseFont
ttengine.library/TT_DoneRastPort
ttengine.library/TT_FreeFamilyList
ttengine.library/TT_FreePixmap
ttengine.library/TT_FreeRequest
ttengine.library/TT_GetAttrsA
ttengine.library/TT_GetPixmapA
ttengine.library/TT_ObtainFamilyListA
ttengine.library/TT_OpenFontA
ttengine.library/TT_RequestA
ttengine.library/TT_SetAttrsA
ttengine.library/TT_SetFont
ttengine.library/TT_Text
ttengine.library/TT_TextExtent
ttengine.library/TT_TextFit
ttengine.library/TT_TextLength
ttengine.library/background ttengine.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 ttengine.library uses 2.1.3
FreeType build.
REQUIREMENTS
- OS 3.0+.
- 68020 or better processor.
- for antialiased output graphics board with at least 15-bit screenmode
and RTG system: CyberGraphX 3.x+ or Picasso96 2.x+.
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 almost identical to graphics.library
font 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 ttengine.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.
ttengine.library/font_database ttengine.library/font_database
GENERAL INFORMATION
'ttengine.database' is a plain text file (placed in 'ENV:' directory)
containing informations about TrueType fonts available in the system.
The database is generated and edited with TTManager usually, some tweaks
can be done by hand however. 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.
ttengine.library/TT_AllocRequest ttengine.library/TT_AllocRequest
NAME
TT_AllocRequest -- Allocates resources for TTEngine font requester.
(V6)
SYNOPSIS
requester = TT_AllocRequest ()
APTR TT_AllocRequest (VOID);
FUNCTION
Allocates resources used by TTEngine font requester. A taglist
returned by further TT_RequestA() is allocated here amongst other
resources. This call must be followed by TT_FreeRequest() call when
the taglist returned by TT_RequestA() is no longer needed.
INPUTS
none
RESULT
requester - pointer to TTEngine internal structure containing all the
allocated resources. Private data inside - do not touch please.
Returned value should be only used as a parameter to TT_RequestA()
and TT_FreeRequest() calls. Function can return NULL if resource
allocation fails.
EXAMPLE
see TT_RequestA().
NOTES
BUGS
SEE ALSO
TT_RequestA(), TT_FreeRequest()
ttengine.library/TT_CloseFont ttengine.library/TT_CloseFont
NAME
TT_CloseFont -- Closes TrueType font. (V4)
SYNOPSIS
TT_CloseFont (font)
A0
VOID TT_CloseFont (APTR);
FUNCTION
Closes font opened by TT_OpenFontA()
INPUTS
font - the result of TT_OpenFontA(). Can be NULL, no action is taken
in the case.
RESULT
none
NOTES
BUGS
SEE ALSO
TT_OpenFontA()
ttengine.library/TT_DoneRastPort ttengine.library/TT_DoneRastPort
NAME
TT_DoneRastPort -- Releases TTEngine resources associated to a
RastPort. (V5)
SYNOPSIS
TT_DoneRastPort (rastport)
A1
VOID TT_DoneRastPort (struct RastPort*);
FUNCTION
Frees internal TTEngine resources associated with a RastPort.
TTEngine creates rendering environment for every RastPort at first
call of TT_SetFont() or TT_SetAttrs() for this RastPort. You should
free this environment before disposing RastPort (typically before
closing a window or screen). Leaving rendering environment not freed
has two drawbacks. Firstly it causes memory leak, this memory is
recovered however when ttengine.library is expunged. Secondly it is
possible that a new RastPort will be created at the same address as
disposed one. Then TTEngine will not create new rendering context but
use old instead, which can lead to some unexpected behaviour.
INPUTS
rastport - pointer to RastPort. Rendering environment for this
RastPort will be disposed. Can be NULL, in the case function does
nothing.
RESULT
none
EXAMPLE
font = TT_OpenFont( /* tags */ );
window = OpenWindowTags(NULL, /* tags */);
TT_SetFont(rport, font); /* environment is created here */
TT_SetAttrs(rport, TT_Window, window, /* ... */);
/* you can call TT_SetAttrs() and TT_SetFont() as many times */
/* as you want */
TT_DoneRastPort(rport); /* environment is disposed */
CloseWindow(window); /* RastPort is disposed */
NOTES
BUGS
SEE ALSO
TT_SetAttrsA(), TT_SetFont()
ttengine.library/TT_FreeFamilyList ttengine.library/TT_FreeFamilyList
NAME
TT_FreeFamilyList -- Frees family list allocated with
TT_ObtainFamilyListA(). (V7)
SYNOPSIS
TT_FreeFamilyList (list)
A0
VOID TT_FreeFamilyList (STRPTR*);
FUNCTION
Frees family table obtained by TT_ObtainFamilyListA(). You should
call this function when family table is no more needed.
INPUTS
list - pointer to family table, it is the result of
TT_ObtainFamilyTable() call. It can be NULL, the function just does
nothing in the case.
RESULT
none
EXAMPLE
See TT_ObtainFamilyListA().
NOTES
BUGS
SEE ALSO
TT_ObtainFamilyListA()
ttengine.library/TT_FreePixmap ttengine.library/TT_FreePixmap
NAME
TT_FreePixmap -- Releases grayscale pixmap. (V5)
SYNOPSIS
TT_FreePixmap (pixmap)
A0
VOID TT_FreePixmap (struct TT_Pixmap*);
FUNCTION
Frees pixmap data and structure allocated by TT_GetPixmap().
INPUTS
pixmap - pointer to TT_Pixmap structure. May be NULL, function does
nothing in the case.
RESULT
none
NOTES
BUGS
SEE ALSO
TT_GetPixmapA()
ttengine.library/TT_FreeRequest ttengine.library/TT_FreeRequest
NAME
TT_FreeRequest -- Frees resources allocated for TTEngine font
request. (V6)
SYNOPSIS
TT_FreeRequest (request)
A0
VOID TT_FreeRequest (APTR);
FUNCTION
Frees internal TTEngine resources allocated for a font request.
Taglist returned by TT_AllocRequestA() is also freed by this call,
so after it the taglist is no longer valid and must not be used or
referenced.
INPUTS
requester - pointer returned by previous call to TT_AllocRequest().
NULL is a valid value here, no action will be performed in the
case.
RESULT
none
EXAMPLE
See TT_RequestA().
NOTES
BUGS
SEE ALSO
TT_AllocRequest(), TT_RequestA()
ttengine.library/TT_GetAttrsA ttengine.library/TT_GetAttrsA
NAME
TT_GetAttrsA -- Gets current font and render engine attributes (V4).
SYNOPSIS
count = TT_GetAttrsA (rastport, taglist)
A1 A0
ULONG TT_GetAttrsA (struct RastPort*, struct TagItem*);
count = TT_GetAttrs (rastport, Tag1, ...)
ULONG TT_GetAttrs (struct RastPort*, Tag, ...);
FUNCTION
Gets current font or render engine attributes for given RastPort. The
value of every attribute is written to an ULONG pointed by ti_Data
field of the TagItem. Here is a list of attributes:
TT_Antialias - Current state of an antialias switch (on, off or
auto).
TT_FontAscender - 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.
TT_FontDescender - 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).
TT_FontName - full font name as found in the font file. Pointer to a
NULL-terminated string is written. This string is localized if the
font file contains names in different languages. Language
precedence is loaded from "Preferred languages" table of
locale.library.
TT_FamilyName - font family name as found in the font file. Pointer
to a NULL-terminated string is written. This string is localized if
the font file contains names in different languages. Language
precedence is loaded from "Preferred languages" table of
locale.library.
TT_SubfamilyName - font subfamily name (typically describing font
variant like "italic" or "bold") as found in the font file. Pointer
to a NULL-terminated string is written. This string is localized if
the font file contains names in different languages. Language
precedence is loaded from "Preferred languages" table of
locale.library.
TT_Transparency - returns actual transparency setting.
TT_FontRealAscender - returns the height of capital letters in pixels.
Precisely it is the distance between the baseline and top of capital
letter.
TT_FontAccentedAscender - returns the height of capital accented
letters in pixels including accents (grave, acute, caron etc.).
Precisely it is the distance between the baseline and top of
accent.
TT_FontRealDescender - returns a distance between the baseline and
lowest pixels of letters like g, j, p, q, y.
TT_FontMaxTop - returns a distance between the baseline and the
topmost element of the whole font face.
TT_FontMaxBottom - returns a distance between the baseline and the
lowest element of the whole font face.
TT_FontDesignHeight - returns a distance between two baselines of
text as stored in the font file. This is the line spacing font is
designed for. Design height is usually greater than font size.
TT_FontBaseline (V6.7) - the same as TT_FontAccentedAscender.
TT_FontHeight (V6.7) - equal to TT_FontAccentedAscender +
TT_FontRealDescender.
TT_FontWidth (V6.7) - cursor horizontal advance for one character in
pixels. For monospaced fonts only, proportional ones return zero.
TT_FontFixedWidth (V6.7) - returns true if the loaded font is
monospaced.
NOTE: TT_FontAscender and TT_FontDescender are guarranted to fulfill
following formula: ascender - descender = font height.
INPUTS
rastport - attributes associated with this RastPort will be returned.
taglist - the list of attributes.
RESULT
counter - the count of recognized tags.
NOTES
Data returned are valid only until TT_CloseFont() call.
BUGS
SEE ALSO
TT_OpenFontA(), TT_SetAttrsA()
ttengine.library/TT_GetPixmapA ttengine.library/TT_GetPixmapA
NAME
TT_GetPixmapA -- Renders string to 8-bit grayscale pixel map. (V5)
SYNOPSIS
pixmap = TT_GetPixmapA (font, string, count, taglist)
A1 A2 D0 A0
struct TT_Pixmap *TT_GetPixmapA (APTR, APTR, ULONG, struct TagItem*);
pixmap = TT_GetPixmap (font, string, count, Tag1, ...)
ULONG TT_GetPixmap (APTR, APTR, ULONG, Tag, ...);
FUNCTION
Renders a string to 8-bit grayscale pixel map. Function may be useful
if the string image is additionally manipulated before rendering into
RastPort (e.g. in image processing software). Pixel map is a
continuous memory area where one byte represents one gray pixel (0 is
black, 255 is white). The first byte is the upper left pixmap corner.
Pixels are placed left-to-right in rows, rows are placed
top-to-bottom. There is no row padding, it means pixmap modulo is
always the same as pixmap width and pixmap data size is equal to width
* height. The function accepts following tags:
TT_Antialias - (BOOL) - controls antialiasing (on, off or
automatic):
TT_Antialias_Off - turns antialias off
TT_Antialias_On - turns antialias on
TT_Antialias_Auto (default) - antialias state depends on font
size. Typically sizes of 9 or less pixels are antialiased, sizes
from 10 to 19 pixels are not antialiased, sizes of 20 of more
pixels are antialiased. These settings can be changed in the font
database separately for every font face.
TT_Encoding - selects font encoding table to be used:
TT_Encoding_Default - loads encoding table from "ENV:ttfcodepage"
file, compatible with ttf.library. If no such file is found,
ISO-8859-1 encoding (Amiga default) is used.
TT_Encoding_ISO8859_x - where 'x' can be one of 1, 2, 3, 4, 5, 6,
7, 8, 9, 10, 11, 13, 14, 15, 16. One of 8-bit encodings defined
in ISO-8859 normative.
TT_Encoding_UTF16_BE - 16-bit Unicode, big endian (68k/PPC style).
Endian mark (0xFFFE) is ignored.
TT_Encoding_UTF32_BE - 32-bit Unicode, big endian (68k/PPC style).
Endian mark (0x0000FFFE) is ignored.
TT_Encoding_UTF16_LE - 16-bit Unicode, little endian (x86 style).
Endian mark (0xFFFE) is ignored.
TT_Encoding_UTF32_LE - 32-bit Unicode, little endian (x86 style).
Endian mark (0xFFFE0000) is ignored.
TT_Encoding_UTF16 - 16-bit Unicode, with endian determined by
endian mark. If no endian mark encountered big endian is assumed.
TT_Encoding_UTF32 - 32-bit Unicode, with endian determined by
endian mark. If no endian mark encountered big endian is assumed.
TT_Encoding_UTF8 - 8-bit Unicode encapsulation (RFC 2279).
TT_CustomEncoding - select custom 8-bit encoding table. Tag data
should point to 256 UWORDs, every containing one 16-bit big endian
Unicode character code. 8-bit character is used as an index of the
table. This tag overrides TT_Encoding regardless of its position in
the taglist if both are specified in the same taglist.
TT_ScaleX - a floating point (IEEE single precision) horizontal scale
factor. Its absolute value will be limited to <0.01, 100> range. It
may be negative (it means horizontal mirror around starting pen
position, string will be rendered to the left).
TT_ScaleY - a floating point (IEEE single precision) vertical scale
factor. Its absolute value will be limited to <0.01, 100> range. It
may be negative (it means vertical mirror around the baseline,
string will be rendered mostly under the baseline).
INPUTS
font - font pointer obtained with TT_OpenFont().
string - pointer to string to be rendered to a pixmap.
count - length of the string in characters (only equal to bytes in
pure 8-bit encodings).
taglist - list of rendering attributes.
RESULT
pixmap - structure describing a pixmap defined as follows:
struct TT_Pixmap
{
ULONG ttp_Size;
ULONG ttp_Width;
ULONG ttp_Height;
UBYTE *ttp_Data;
};
ttp_Size is the size of the structure (not the pixmap) containing
useful informations including ttp_Size itself. For V5 pixmaps the size
is 16 bytes. ttp_Width is pixmap width (and modulo) in bytes.
ttp_Height is a number of pixmap rows. ttp_Data points to actual
pixmap data.
Function returns NULL if pixmap allocation fails.
NOTES
TT_Pixmap structure is READ ONLY.
BUGS
SEE ALSO
TT_FreePixmap(), TT_OpenFontA(), TT_SetAtrrsA()
ttengine.library/TT_ObtainFamilyListA ttengine.library/TT_ObtainFamilyListA
NAME
TT_ObtainFamilyListA -- Obtains a list of available font families.
(V7)
SYNOPSIS
list = TT_ObtainFamilyListA (taglist)
A0
STRPTR* TT_ObtainFamilyListA (struct TagItem*);
FUNCTION
Creates a NULL-terminated table of pointers to strings. Every pointer
points to a NULL-terminated string being a name of font family. Such
a table can be directly passed to MUI cycle or list class. Family
table is filtered according to passed tasks. The table is a local
copy so can be modified by calling application (but you must not
increase the size!).
INPUTS
taglist - a list of filter tags. Currently defined tags are:
TTRQ_FixedWidthOnly - if TRUE only monospaced families are listed.
Defaults to FALSE.
NULL taglist is valid input and is treated as empty taglist.
RESULT
list - pointer to a NULL-terminated table of pointers to names. The
function can return NULL if memory allocation fails or there is no
families in the database.
EXAMPLE
Following example prints out all avaliable families to the standard
output:
STRPTR *families;
if (families = TT_ObtainFamilyListA(NULL))
{
STRPTR *p = families;
while (*p) Printf("%s\n", *p++);
TT_FreeFamilyList(families);
}
NOTES
BUGS
SEE ALSO
TT_FreeFamilyList()
ttengine.library/TT_OpenFontA ttengine.library/TT_OpenFontA
NAME
TT_OpenFontA -- Opens TrueType font. (V4)
SYNOPSIS
font = TT_OpenFontA (taglist)
A0
APTR TT_OpenFontA (struct TagItem*);
font = TT_OpenFont (Tag1, ...)
APTR TT_OpenFont (Tag, ...);
FUNCTION
Opens a TrueType font preparing it to use with any RastPort. Font may
be specified directly as a path to "*.ttf" file, or indirectly via
set of attributes, database search will be performed for this set and
best matching font will be opened. It is graphics.library OpenFont()
counterpart but taglist is used instead TextAttr structure.
INPUTS
taglist - a list of tags containing requested font attributes.
Following tags are recognized:
TT_FontFile - this tag is a pointer to string containing a full
path to TrueType font file to be opened. This tag allows for
overriding database search and match. That means
TT_FamilyTable, TT_FontStyle and TT_FontWeight are ignored if
TT_FontFile is specified. Useful for opening application
specific fonts, containing for example musical notes or some
other kind of symbols. This tag has no default value.
TT_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};
TT_FontSize - font size in pixels defined as the distance between
baselines of two following text lines. The default value for
this tag is 14 pixels.
TT_FontStyle - there are three styles defined:
TT_FontStyle_Regular (default),
TT_FontStyle_Italic,
TT_FontWeight - defined with Cascading Style Sheets manner as a
number from 0 (the lightest face) to 999 (the heaviest face).
You can use TT_FontWeight_Normal (equal to 400) and
TT_FontWeight_Bold (equal to 700) shortcuts.
TT_FontWeight_Normal is the default value.
TT_FixedWidth - function checks if the opened font is
monospaced (fixed width). If it isn't, font is closed and
TT_OpenFont() returns NULL. Default value for this tag is
FALSE. (V6.7)
RESULT
success - font pointer (for use with TT_SetFont() and TT_CloseFont())
if the font has been opened successfully, NULL
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_SetFont(), TT_CloseFont(), font_database
ttengine.library/TT_RequestA ttengine.library/TT_RequestA
NAME
TT_RequestA -- Opens and handles TTEngine font requester window. (V6)
SYNOPSIS
attrlist = TT_RequestA (requester, taglist)
A0 A1
struct TagItem* TT_RequestA (APTR, struct TagItem*);
attrlist = TT_Request (requester, Tag1, ...)
struct TagItem* TT_Request (APTR, Tag, ...);
FUNCTION
INPUTS
requester - pointer to requester resources returned by
TT_AllocRequest(). Can be NULL, in the case no action is performed
and function returns NULL.
taglist - defines requester properties and gadgets. If NULL, empty
taglist is assumed (empty taglist is valid, all tags are optional).
Following tags are recognized:
TTRQ_Window (struct Window*) - Parent window of requester. If no
TTRQ_Screen tag is specified, the window structure is used to
determine on which screen to open the requesting window.
TTRQ_PubScreenName (STRPTR) - Name of a public screen to open on.
This overrides the screen used by TTRQ_Window.
TTRQ_Screen (struct Screen*) - Screen on which to open the
requester. This overrides the screen used by TTRQ_Window or by
TTRQ_PubScreenName.
TTRQ_TitleText (STRPTR) - Title to use for the requesting window.
English default is "Select TrueType font".
TTRQ_PositiveText (STRPTR) - Label of the positive gadget in the
requester. English default is "OK".
TTRQ_NegativeText (STRPTR) - Label of the negative gadget in the
requester. English default is "Cancel".
TTRQ_InitialLeftEdge (WORD) - Suggested left edge of requesting
window. Default is to center the window on the screen.
TTRQ_InitialTopEdge (WORD) - Suggested top edge of requesting
window. Default is to center the window on the screen.
TTRQ_InitialWidth (WORD) - Suggested width of requesting window.
Default is 200 or 25% of screen width whichever is greater.
TTRQ_InitialHeight (WORD) - Suggested height of requesting window.
Default is 200 or 50% of screen height whichever is greater.
TTRQ_DoSizes (BOOL) - Controls font size listview and string. If
FALSE, size listview is not displayed. Defaults to TRUE to be
consistent with ASL font requester.
TTRQ_DoStyle (BOOL) - Controls font style (regular / italic) cycle
gadget. Defaults to FALSE (no style cycle gadget).
TTRQ_DoWeight (BOOL) - Controls font weight cycle gadgets. TTEngine
distincts 9 font weights enumerated as 100, 200, ... 900
according to Cascading Style Sheets specification. Of course not
every font has all the 9 weights, cycle gadget always show only
available ones. Defaults to FALSE (no weight cycle gadget).
TTRQ_Activate (BOOL) - Specifies if requester window is to be
activated after opening. Defaults to TRUE.
TTRQ_FixedWidthOnly (BOOL) - Requester displays only monospaced
fonts. Defaults to FALSE.
RESULT
attrlist - a list of font attributes. You should pass it to
TT_OpenFontA() and then to TT_SetAttrsA() to have a font open
exactly matching user choice. Taglist is valid until you call
TT_FreeRequest().
EXAMPLE
APTR font, request;
struct RastPort *rp; /* initialized elsewhere */
request = TT_AllocRequest();
attrlist = TT_Request(request, TAG_END);
if (attrlist)
{
if (font = TT_OpenFontA(attrlist))
{
TT_SetAttrsA(rp, attrlist));
if (TT_SetFont(rp, font))
{
/* use the font */
}
TT_DoneRastPort(rp);
}
TT_CloseFont(font);
}
TT_FreeRequest(request);
NOTES
BUGS
SEE ALSO
TT_SetAttrsA(), TT_SetFont(), TT_OpenFontA(), TT_SetAttrsA().
ttengine.library/TT_SetAttrsA ttengine.library/TT_SetAttrsA
NAME
TT_SetAttrsA -- Sets rendering engine and font attributes. (V4)
SYNOPSIS
count = TT_SetAttrsA (rastport, taglist)
A1 A0
ULONG TT_SetAttrsA (struct RastPort*, struct TagItem*);
count = TT_SetAttrs (rastport, Tag1, ...)
ULONG TT_SetAttrs (struct RastPort*, Tag, ...);
FUNCTION
Sets render engine settings for given RastPort. Every following
TrutType render and metrics calls for this RastPort will use these
settings. Here is a list of attributes:
TT_ColorMap - (struct ColorMap*) - ColorMap used to convert pen
number to RGB color value.
TT_Screen - (struct Screen*) - useful shortcut for TT_ColorMap,
automatically sets screen ColorMap.
TT_Window - (struct Window*) - useful shortcut for TT_ColorMap,
automatically sets window ColorMap.
TT_Antialias - (BOOL) - controls antialiasing (on, off or
automatic):
TT_Antialias_Off - turns antialias off
TT_Antialias_On - turns antialias on
TT_Antialias_Auto (default) - antialias state depends on font
size. Typically sizes of 9 or less pixels are antialiased, sizes
from 10 to 19 pixels are not antialiased, sizes of 20 of more
pixels are antialiased. These settings can be changed in the font
database separately for every font face.
TT_Encoding - selects font encoding table to be used:
TT_Encoding_Default - loads encoding table from "ENV:ttfcodepage"
file, compatible with ttf.library. If no such file is found,
ISO-8859-1 encoding (Amiga default) is used.
TT_Encoding_ISO8859_x - where 'x' can be one of 1, 2, 3, 4, 5, 6,
7, 8, 9, 10, 11, 13, 14, 15, 16. One of 8-bit encodings defined
in ISO-8859 normative.
TT_Encoding_UTF16_BE - 16-bit Unicode, big endian (68k/PPC style).
Endian mark (0xFEFF) is ignored.
TT_Encoding_UTF32_BE - 32-bit Unicode, big endian (68k/PPC style).
Endian mark (0x0000FEFF) is ignored.
TT_Encoding_UTF16_LE - 16-bit Unicode, little endian (x86 style).
Endian mark (0xFFFE) is ignored.
TT_Encoding_UTF32_LE - 32-bit Unicode, little endian (x86 style).
Endian mark (0xFFFE0000) is ignored.
TT_Encoding_UTF16 - 16-bit Unicode, with endian determined by
endian mark. If no endian mark encountered big endian is assumed.
TT_Encoding_UTF32 - 32-bit Unicode, with endian determined by
endian mark. If no endian mark encountered big endian is assumed.
TT_Encoding_UTF8 - 8-bit Unicode encapsulation (RFC 2279).
TT_CustomEncoding - select custom 8-bit encoding table. Tag data
should point to 256 UWORDs, every containing one 16-bit big endian
Unicode character code. 8-bit character is used as an index of the
table. This tag overrides TT_Encoding regardless of its position in
the taglist if both are specified in the same taglist.
TT_Transparency - Allows for rendering transparent text (the
background shines through the text). 0 value means no transparency
(this is the default), 255 is maximum transparency.
TT_ScaleX - a floating point (IEEE single precision) horizontal scale
factor. Its absolute value will be limited to <0.01, 100> range. It
may be negative (it means horizontal mirror around starting pen
position, string will be rendered to the left).
TT_ScaleY - a floating point (IEEE single precision) vertical scale
factor. Its absolute value will be limited to <0.01, 100> range. It
may be negative (it means vertical mirror around the baseline,
string will be rendered mostly under the baseline).
TT_SoftStyle - controls software generated font modifications. Any of
software styles can be combined (OR-ing the values).
TT_SoftStyle_None - clears all software styles.
TT_SoftStyle_Underlined - boolean tag controlling text underline.
TT_SoftStyle_DblUnderlined - boolean tag controlling text double
underline. Combining it with TT_Underlined gives one thick line.
TT_SoftStyle_Overstriked - boolean tag controlling text overstriked
line.
TT_SoftStyle_DblOverstriked - boolean tag controlling text
overstriked double line. Combining it with TT_Overstriked gives
one thick line.
TT_Foreground - allows for using direct RGB value of foreground color
instead of RastPort 'A' pen. On LUT screens this tag will be
ignored. Special value TT_Foreground_UseRastPort returns foreground
color control back to the RastPort and its 'A' pen.
TT_Background - allows for using direct RGB value of background color
(used in JAM2 drawmode only) instead of RastPort 'B' pen. On LUT
screens this tag will be ignored. Special value
TT_Background_UseRastPort returns background color control back to
the RastPort and its 'B' pen.
TT_Gamma - adjustable gamma correction used for antialiasing. After
RGB alphablending gamma correction is applied to resulting pixel
colour according to x' = x ^ 1/gamma, where x is a RGB component.
TT_Gamma is 'gamma' exponent multiplied by 1000 to avoid messing
with floating point numbers. Default TT_Gamma is 2500 (2.5) which
is typical for CRT display. Default gamma exponent can be set by
user in 'ttengine.database' file.
TT_DiskFontMetrics - changes TTEngine rendering to be diskfont-like.
In this mode JAM2 filled area extends vertically between
TT_FontAccentedAscender and TT_FontRealDescender and as such is
equal to TT_FontHeight. Also if the left bearing of the first
glyph or the right bearing of the last glyph is negative, JAM2
fill area is extended to the left or right accordingly. Note
however, glyphs higher than TT_FontAccentedAscender or extending
below TT_FontRealDescender will be clipped. This mode is useful
especially for text-oriented applications using JAM2 draw mode.
Defaults to FALSE.
INPUTS
rastport - attributes will be set for this RastPort.
taglist - the list of attributes.
RESULT
counter - the count of recognized tags.
NOTES
BUGS
SEE ALSO
TT_OpenFontA(), TT_Text(), TT_GetAttrs()
ttengine.library/TT_SetFont ttengine.library/TT_SetFont
NAME
TT_SetFont -- Sets TrueType font for a RastPort. (V4)
SYNOPSIS
TT_SetFont (rastport, font)
A1 A0
BOOL TT_SetFont (struct RastPort*, APTR);
FUNCTION
Sets a font previously opened with TT_OpenFontA() for use with given
RastPort. All further calls of text rendering or metrics function for
this RastPort will use font set.
INPUTS
rastport - The font will be set for this RastPort.
font - Pointer returned by TT_OpenFontA(). May be NULL, function
returns immediately in the case.
RESULT
TRUE if success, false otherwise.
EXAMPLE
/* use two fonts to render in one RastPort */
APTR times, arial;
times = TT_OpenFont(
TT_FamilyTable, (ULONG){"Times", "serif", "default", NULL},
TT_FontSize, 26,
TAG_END);
arial = TT_OpenFont(
TT_FamilyTable, (ULONG){"Arial", "sans-serif", "default", NULL},
TT_FontSize, 22,
TT_FontWeight, TT_FontWeight_Bold,
TAG_END);
if (times && arial)
{
SetAPen(win->RPort, 1);
SetDrMd(win->RPort, JAM1);
Move(win->RPort, 100, 100);
TT_SetAttrs(win->RPort, TT_Window, win, TAG_END);
if (TT_SetFont(win->RPort, times))
TT_Text(win->RPort, "Times 26 points", 15);
if (TT_SetFont(win->RPort, arial))
TT_Text(win->RPort, "Arial 22 points", 15);
}
if (arial) TT_CloseFont(arial);
if (times) TT_CloseFont(times);
NOTES
Function can fail returning FALSE if:
1. RastPort pointer is NULL.
2. Font pointer is NULL.
3. Font pointer is not found on opened fonts list (it means the pointer
was not obtained as a result of TT_OpenFontA() call).
4. Memory allocation during environment creation fails.
BUGS
SEE ALSO
TT_OpenFontA(), TT_SetAttrsA(), TT_CloseFont()
ttengine.library/TT_Text ttengine.library/TT_Text
NAME
TT_Text -- Renders string into RastPort. (V4)
SYNOPSIS
TT_Text (rastport, string, count)
A1 A0 D0
VOID TT_Text (struct RastPort*, APTR, ULONG);
FUNCTION
Renders the string using current ttengine.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
current (set by TT_SetAttrs()) encoding table.
INPUTS
rastport - Target RastPort for rendering.
string - String to render to (need not to be NULL terminated).
count - How many characters to render (note that NULL code will
be rendered as well).
RESULT
none
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_SetAttrs(win->RPort, TT_Window, win, TAG_END);
TT_Text(win->RPort, "some text", 9);
NOTES
BUGS
SEE ALSO
TT_OpenFontA(), TT_SetAttrsA()
ttengine.library/TT_TextExtent ttengine.library/TT_TextExtent
NAME
TT_TextExtent -- Determine raster extent of text data. (V4)
SYNOPSIS
TT_TextExtent (rastport, text, count, extent)
A1 A0 D0:16 A2
VOID TT_TextExtent (struct RastPort*, APTR, WORD,
struct TextExtent*);
FUNCTION
Computes dimensions and coordinates of smallest rectangle containing
on the whole given text rendered with current settings. TextExtent
structure fields have following meaning:
te_Width - Horizontal advance of RastPort pen position. The same as
TT_TextLength() call result.
te_Height - Just current font height.
te_Extent.MinX - The horizontal distance from text start point to the
leftmost pixel rendered. May be negative, it means that some
pixels will be plotted before the start point.
te_Extent.MaxX - The horizontal distance from text start point to the
rightmost pixel rendered.
te_Extent.MinY - The vertical distance from text start point to the
topmost pixel rendered. Always negative, do not neccesarily equal
to -TTFA_Ascender.
te_Extent.MaxY - The vertical distance from text start point to the
lowermost pixel rendered. Typically positive if anything is to be
drawn below the baseline.
INPUTS
rastport - this rastport settings (font, size, style etc.) will be
used for calculations.
text - a string (not neccesarily NULL-terminated) to compute the
rectangle for.
count - length of the string in characters.
extent - pointer to TextExtent structure - it will be filled with
data.
RESULT
No retrurn value. TextExtent structure is filled with data.
NOTES
This function is almost identical to graphics.library/TextExtent().
It even receives parameters in the same registers.
Do not assume neither horizontal extents sum up to te_Width, nor
vertical ones sum up to font height.
BUGS
SEE ALSO
TT_OpenFontA(), graphics.library/TextExtent()
ttengine.library/TT_TextFit ttengine.library/TT_TextFit
NAME
TT_TextFit -- Count characters that will fit in a given extent. (V4)
SYNOPSIS
characters = TT_TextFit (rastport, string, count, extent,
A1 A0 D0:16 A2
constr_extent, direction, width, height)
A3 D1 D2 D3
ULONG TT_TextFit (struct RastPort*, APTR, UWORD, struct TextExtent*,
struct TextExtent*, WORD, UWORD, UWORD);
FUNCTION
Computes how many characters of given NULL-terminated string rendered
with current settings will fit into given extent. Also calculates an
extent for this fitting part of the string. Function can fit from the
beginning of the string to the right, or from the end of the string
to the left. If 'constr_extent' is non NULL, string is fitted only
against it, constraining 'width' and 'height' are ignored.
INPUTS
rastport - calculations will be performed using this rastport
settings (font, size, styles etc.).
string - A string (not neccesarily NULL-terminated) to fit.
count - string lenght in characters.
extent - Pointer to TextExtent structure - it will be filled with
dimensions of fitted part of the string. May be filled with all
zeros if no fit is possible at all (e.g. height is to small).
constr_extent - Pointer to already filled TextExtent structure. Part
of the string will fit into this extent. It is not modified by
function. May be NULL, 'width' and 'height' will be used as
constraints.
direction - When equal to 1 string will be fitted starting from it's
beginning to the rigth. When equal to -1, string will be fitted
starting from it's end to the left.
width - If 'constr_extent' is NULL, the string width will be compared
with this parameter. Ignored otherwise.
height - If 'constr_extent' is NULL, the string height will be
compared with this parameter. Ignored otherwise.
RESULT
characters - the length of fitting string part. May be zero if no fit
found.
NOTES
This function is almost identical to graphics.library/TextFit().
It even receives parameters in the same registers.
Do not assume neither horizontal extents sum up to te_Width, nor
vertical ones sum up to font height (in returned extent).
BUGS
SEE ALSO
TT_OpenFontA(), graphics.library/TextFit()
ttengine.library/TT_TextLength ttengine.library/TT_TextLength
NAME
TT_TextLength -- Gets string length in pixels (V4).
SYNOPSIS
length = TT_TextLength(rastport, string, count)
A1 A0 D0
ULONG TT_TextLength (struct RastPort*, APTR, ULONG);
FUNCTION
Calculates the pixel width of given string written with current font.
Takes kerning into account. String will be mapped to Unicode using
current encoding.
INPUTS
rastport - render engine and font settings for this RastPort will be
used for calculations.
string - the length of this string will be calculated.
count - the string lenght in characters.
RESULT
length - the length of the string in pixels.
NOTES
BUGS
SEE ALSO
TT_Text(), TT_OpenFontA()