1%---------------------------------------------------------------------------- 2% ----- File: ut1lib.tex 3% ----- Author: Rainer Menzner (Rainer.Menzner@web.de) 4% ----- Date: 2005-05-18 5% ----- Description: This file is part of the t1lib-documentation. 6% ----- Copyright: t1lib is copyrighted (c) Rainer Menzner, 1996-2005. 7% As of version 0.5, t1lib is distributed under the 8% GNU General Public Library License. The 9% conditions can be found in the files LICENSE and 10% LGPL, which should reside in the top level 11% directory of the distribution. Please note that 12% there are parts of t1lib that are subject to 13% other licenses: 14% The parseAFM-package is copyrighted by Adobe Systems 15% Inc. 16% The type1 rasterizer is copyrighted by IBM and the 17% X11-consortium. 18% ----- Warranties: Of course, there's NO WARRANTY OF ANY KIND :-) 19% ----- Credits: I want to thank IBM and the X11-consortium for making 20% their rasterizer freely available. 21% Also thanks to Piet Tutelaers for his ps2pk, from 22% which I took the rasterizer sources in a format 23% independ from X11. 24% Thanks to all people who make free software living! 25%---------------------------------------------------------------------------- 26 27\newpage 28\section{Using \tonelib} 29This section describes in detail how to use \tonelib. I have tried to 30to describe the stuff in the order a new user would learn best and a new user 31would need to use the functions. 32 33 34\subsection{Compiling and Linking \tonelib-Programs} 35\label{compilingprograms}% 36A program that wants to use functions from the library must include 37the appropriate headers at compile time and then be linked with the 38appropriate libraries. Since V. 0.6-beta the X11 interface is separated 39from the \tonelib\ pivotal stuff. This yields advantages for programs that 40don't use the X11 rastering functions on systems where X11 is 41installed. 42The following applies to programs that do not use the X11 rastering 43functions: 44\begin{itemize} 45\item Include the file \verb+t1lib.h+. All definitions and declarations 46 needed at compile time are included in this file. 47\item \verb+libt1.a+ or \verb+libt1.so+ respectively must be linked to the 48 program. 49\end{itemize} 50In contrast, a program that uses the X11 interface must adhere to the 51following scheme: 52\begin{itemize} 53\item \verb+t1lib.h+ and \verb+t1libx.h+ must be included in this 54 order. Furthermore, \verb+t1libx.h+ includes \verb+X11/Xlib.h+ if 55 it is not already included. 56\item The libraries \verb+libt1.a+/\verb+libt1.so+ and 57 \verb+libt1x.a+/\verb+libt1x.so+ must be linked to the executable. 58 The correct order is \verb+-lt1x -lt1+ since the X interface uses 59 functions from the latter. Also, the X11 library must appear in the 60 library list after \verb+-lt1x+. 61\end{itemize} 62The Makefiles for \verb+xglyph+ and \verb+type1afm+ are typical 63examples for both configurations. 64 65 66\subsection{Querying and Setting Fundamental Configuration Parameters of \tonelib} 67\label{queryconfiguration}% 68It might be necessary to know whether \tonelib\ is compiled with or without 69X11 interface. At compile time a programmer can check for the X11 interface by 70stating 71\begin{verbatim} 72#ifdef T1LIB_X11_SUPPORT 73\end{verbatim} 74after including \verb+t1libx.h+. If \verb+T1LIB_X11_SUPPORT+ is not defined, 75the X11 interface is not configured and compiled. 76 77At runtime, a program can check for the X11 interface by a call to 78\precorr 79\begin{verbatim} 80 int T1_QueryX11Support( void) 81\end{verbatim}\index{\verb+T1_QueryX11Support()+}\postcorr 82It returns \verb+1+ if the X11 interface is present and \verb+0+ otherwise. 83 84Notice that querying X11 support at runtime and compile time tends to 85be pretty useless starting with V.~0.6-beta. Any decision can be done 86by examining the existence of the \verb+t1x+-library and the 87\verb+t1libx.h+ header file. The definition and the function described 88above are thus only provided for compatibility with pre-0.6 versions 89of \tonelib. 90 91Some remarks on the general data format of bitmaps and should be given 92here. \tonelib\ internally always generates bitmaps in the way that appears to 93be natural for them: The first pixel corresponds to the least significant bit 94in a byte (or word/longword). Bytes are always arranged in memory the way, 95that the first byte is at the lowest address and the next byte at the 96following address. This convention is called LSBFirst which stands for Least 97Significant Bit/Byte First. It is the natural way of data alignment on 98machines with {\em Little Endian} data representation. In contrast MSBFirst 99stands for Most Significant Bit/Byte First which is the natural kind of data 100representation on Big Endian machines. 101A glyph's scanlines are always aligned in LSBFirst-type, no matter on what 102machine \tonelib\ is running. 103 104What has been said above, strictly does only apply to non antialiased glyphs, 105i.e., real bitmaps. Antialiased glyphs have their gray values coded in the 106representation that is natural for the machine \tonelib\ is running on. For 107example, if \tonelib\ runs on a Big Endian machine, the gray values are in Big 108Endian. The X11 displaying functions automatically handle this correct. 109 110Scanlines of \tonelib-glyphs may be padded to 8, 16 or 32 bit. Padding to 111higher values will consume more memory for the glyphs, but might speed up 112concatenating of bitmaps as described in \ref{generatingbitmaps}. This applies 113to machines with Little Endian representation as, for example, Intel's 114$x$86 series. On these machines 16 or 32 bits can be placed into the 115target bitmap in one step. On machines with Big Endian representation, for 116example, Motorola 680$x$0 series, this is currently not possible. However, 117using a higher padding value could still yield a better performance since the 118application could work on larger units than a byte. 119 120The default padding value in \tonelib\ is 8 bit. The padding value can be 121specified at runtime by means of calling 122\precorr 123\begin{verbatim} 124 int T1_SetBitmapPad( int pad) 125\end{verbatim}\index{\verb+T1_SetBitmapPad()+}\postcorr 126\verb+pad+ must be one of `8', `16' or `32'. The call will only be successful 127if executed before initialization of \tonelib. This a security mechanism which 128prevents from having glyphs with distinct padding values. The return value is 1290 if successful and -1 if \verb+pad+ was invalid or \tonelib\ had already been 130initialized. 131 132There is a further restriction concerning the padding value. Setting it to 32 133is only possible if the machine has an ANSI C integer type of 64 bits. This 134condition is automatically checked by the \verb+configure+ script of \tonelib. 135If such an integer type is not present (or has to be emulated as e.g.\ 136\verb+long long+ in \verb+gcc+) there would not result any performance gain. 137If a specified padding value is rejected, \verb+T1_errno+ is set 138appropriately. 139 140An application can query the current padding value by calling 141\precorr 142\begin{verbatim} 143 int T1_GetBitmapPad( void) 144\end{verbatim}\index{\verb+T1_GetBitmapPad()+}\postcorr 145The returned value is the padding value. This function can be called before or 146after initialization of \tonelib. 147 148Another function usually be called near 149initialization is 150\precorr 151\begin{verbatim} 152 int T1_SetDeviceResolutions(float x_res, float y_res) 153\end{verbatim}\index{\verb+T1_SetDeviceResolutions()+}\postcorr 154This function allows setting the resolution of 155your device (screen). The values must be given in dpi. The default 156resolution, 72 dpi, implies that a pixel in device space equals 1 157bp. This function may be called before or after initialization. The 158only restriction is that no size dependent data must be 159available. Changing the resolution when bitmaps are already cached would 160result in inconsistent bitmap-sizes for bitmaps generated before and 161after the call to \verb+T1_SetDeviceResolutions()+. 162The function checks whether initialization has already been done. If 163not, all is OK since no size-dependent data for any font can exist. If 164initialization has been done, it checks for every font whether size 165dependent data exists. If there's any size dependent data for any 166font, \verb+T1_SetDeviceResolutions()+ will return \verb+-1+ without 167having set the new resolution. Otherwise the specified resolution will 168be set and the function will return \verb+0+. 169If you really need to set 170another resolution in the middle of a session, all size-specific data 171should explicitly be removed from memory beforehand. This can be 172achieved using \verb+T1_DeleteAllSizes()+ (see \ref{deletingdata}). 173 174Notice that the device resolution need not be set at all if the default 175resolution of 72 dpi in horizontal and vertical direction is OK. This function 176is primarily intended to be prepared for applications with a device aspect 177ratio different from 1. 178 179\subsection{Initialization of \tonelib\ and Related Things} 180\label{initialization}% 181In this section we should cover the initialization, part of which has already 182been described in \ref{runtimesetup} in some more detail. This gives the user 183the chance to fine-tune the initialization for specific applications. 184 185Prior to be able to do anything useful with \tonelib, the library has to be 186initialized. Generally speaking, the purpose of the initialization is to tell 187\tonelib\ which font files are associated with which font ID's. The existence 188or accessibility of the font files is also assured at this point. Hence, file 189name search paths for Type 1 font files, AFM files and encoding files have 190also to be known at this time. 191 192The configuration file and the font database file play a central r\^ole 193during initialization. While the configuration file contains path 194specifications and a font database specification, the font database file 195specifies the relation between font ID's and font filenames. 196The format of both these files is described in \ref{runtimesetup} and not 197repeated here. 198 199A further purpose of the initialization is to set certain flags that prevent 200other quantities from being modified at a later time. For example, the padding 201value must be unique to all glyphs and consequently it is not allowed to be 202changed after initialization has been performed. 203 204The initialization is started by a call to the function 205\precorr 206\begin{verbatim} 207 void *T1_InitLib( int log) 208\end{verbatim}\index{\verb+T1_InitLib()+}\postcorr 209The parameter \verb+log+ can be interpreted as a mode specification that 210influences certain parts of the initialization. In fact it should consist of 211one or more \verb+#define+s from \verb+t1lib.h+. At minimum, \verb+log+ 212should be either \verb+LOGFILE+ or \verb+NO_LOGFILE+. If \verb+LOGFILE+ is 213specified, a log file is written while the application runs, and 214\verb+NO_LOGFILE+ suppresses the generation of a logfile. For information the 215\tonelib-logfile see \ref{logfile}. In addition to this, 216\verb+IGNORE_CONFIGFILE+ and \verb+IGNORE_FONTDATABASE+ can be bitwise OR'ed 217(using ``\verb+|+'') to the \verb+log+-value. The purpose of this is described 218later in this section. A further flag that might find its way into the value 219of \verb+log+ is \verb+T1_AA_CACHING+. A discussion of this topic is given in 220\ref{aacaching}. 221The \verb+T1_NO_AFM+ completely suppresses usage of AFM data, no matter if an 222AFM file could have been found using the current search paths or not. This 223saves time for loading a font and is recommended if an application is known to 224be restricted on functions that do not access AFM data. The consequences of 225using this flag are covered somewhat more detailed in \ref{generatingafminfo}. 226 227 228\subsubsection{Standard Initialization} 229\label{standardinitialization}% 230The term ``standard initialization'' means, that none of the path manipulating 231and font database manipulating actions described later has been 232performed. Also, a standard initialization excludes the use of 233\verb+IGNORE_CONFIGFILE+ and \verb+IGNORE_FONTDATABASE+. If these conditions 234are met, the following happens at initialization time: 235\begin{enumerate} 236\item The padding value, either being the default value or a value specified 237 by the user before, is assigned. 238\item Next, depending on the value of \verb+log+, a logfile is tried to be 239 opened. From this point on, depending on the loglevel and the value of 240 \verb+log+ the actions are logged. 241\item The endianess of the machine \tonelib\ is running on is checked. 242\item A configuration file is searched in the following order: 243 \begin{itemize} 244 \item The process' environment is checked for the entry \verb+T1LIB_CONFIG+ 245 and if found, its value is interpreted as the filename of the configuration 246 file (see \ref{runtimesetup}). 247 \item If no file was found, the user's home directory is searched for a file 248 named \verb+.t1librc+. In case it exists, it is used as a 249 \tonelib-configuration file. 250 \item If still no configuration file was found, the global configuration 251 file will be tried to be opened. 252 \item If this also does not succeed, all file search paths are left to be 253 ``.'' and the default font database is \verb+FontDataBase+. 254 \end{itemize} 255 It should be noted that the first match wins when searching the configuration 256 file. Only the first one found is examined. 257\item The font database file(s) are tried to be opened and read. This process 258 is in detail described in \ref{fontdatabase}. 259 260 If after scanning the complete list of font databases, no font definitions 261 have been performed, \verb+T1_InitLib()+ will return with a \verb+NULL+ 262 pointer indicating the initialization has failed. 263\item The number of fonts declared in the database is stored. Note that this 264 number of declared fonts must be greater than zero. 265\item A flag is set to indicate \tonelib\ is initialized and the pointer to 266 the top most area of the global data structures is returned to the 267 application. This pointer is guaranteed to be not \verb+NULL+. 268\end{enumerate} 269For some applications, the described initialization scheme appears to be too 270inflexible and overkill. It is well suited for large applications that use 271lots of fonts and where it should be possible to add new fonts without 272modifying the application itself. For small commandline applications like 273\verb+type1afm+ (see \ref{type1afm}), which are designed to read a few font file 274names from the commandline, the overhead in configuration file searching and 275path reading is much too large. Moreover, to insist on a font database file 276might grow to a real disadvantage. In the subsequent paragraphs we should thus 277discuss how we can deviate from the initialization scheme described above. 278 279\subsubsection{Fine Control over Font Databases and File Search Paths} 280\label{manipulatingpaths}% 281First, it is important to mention that it is generally possible to force 282\verb+T1_InitLib()+ to skip steps 4 and / or 5 as described above. 283 284The configuration file is discarded by OR'ing the parameter \verb+log+ of 285\verb+T1_InitLib()+ with \verb+IGNORE_CONFIGFILE+. 286The default paths or the paths explicitly specified by the application before 287are then left untouched during initialization. 288 289Discarding the font database specification from the configuration file is 290achieved by bitwise OR'ing \verb+log+ with \verb+IGNORE_FONTDATABASE+. The 291result after initialization will be an empty database. This is valid in V.\ 2920.5 and newer since fonts may be added to the database at runtime. 293 294Using the two flags described above, an installed setup can be ignored and an 295application may have complete control over its search paths. There are a 296number of functions for this purpose and each of these functions allows to 297specify exactly {\em one} path element at a given time. Using special 298characters like white space or path separators in a path element is thus not 299an issue. 300 301The font database may explicitly be specified by the 302application using \precorr 303\begin{verbatim} 304 int T1_SetFontDataBase( char *filename) 305\end{verbatim}\index{\verb+T1_SetFontDataBase()+}\postcorr 306\verb+filename+ is the pointer to a string containing the name of the font 307database file that is to be examined. This function replaces any set of font 308databases setup previously and is thus usually to be called before 309\verb+T1_InitLib()+. A call to this function after initialization will return 310the result -1 and \verb+T1_errno+ will be set to 311\verb+T1ERR_OP_NOT_PERMITTED+. For the special case that the font database is 312still epmty after initialization this function may also be called after 313initialization. But in any case, the database must be empty! For the latter 314cases, fonts specified in the new database file are then immediately inserted 315into the database. In case of success, the number of available fonts is returned. 316 317There is also the function \precorr 318\begin{verbatim} 319 int T1_AddFontDataBase( int mode, char *filename) 320\end{verbatim}\index{\verb+T1_AddFontDataBase()+}\postcorr 321It can be called at any time and \verb+filename+ is the string of the new font 322database's file name. If called before initialization, the parameter 323\verb+mode+ can be either \verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+ and 324the name of the new font database simply is either appended or prepended to 325the existing list of font databases. Then, the function returns $0$. 326 327If the function is called after initialization, the parameter \verb+mode+ is 328ignored and the new database is appended in any case, because this is the only 329meaningful action. Furthermore, the new database is immediately loaded and the 330function returns a number indicating the number of available fonts 331(which can also be 0). In the case of an error, \verb+T1_AddFontDataBase()+ 332returns $-1$. 333 334There is also a pair of functions that act on the list of XLFD font database 335files, 336\precorr 337\begin{verbatim} 338 int T1_SetFontDataBaseXLFD( char *filename) 339\end{verbatim}\index{\verb+T1_SetFontDataBaseXLFD()+}\postcorr 340\precorr 341\begin{verbatim} 342 int T1_AddFontDataBaseXLFD( char *filename) 343\end{verbatim}\index{\verb+T1_AddFontDataBaseXLFD()+}\postcorr 344These functions have exactly the same syntax and semantics as the functions 345just described above. Standard font database files and XLFD font database 346files are handled in separate lists internally, so that setting the XLFD font 347database will not affect explicit standard font database settings. However, 348the default standard font database (\verb+./FontDataBase+) will be cleared 349when at least one XLFD font database is specified. This is because the default 350font database is meant as a fallback, and the fallback case is no longer given 351if a XLFD font database has been specified. 352 353A similar manipulation as just described for font database files, is 354possible for the searchpaths. (Re-)Defining a search 355path is done by calling 356\precorr 357\begin{verbatim} 358 int T1_SetFileSearchPath( int type, char *pathname) 359\end{verbatim}\index{\verb+T1_SetFileSearchPath()+}\postcorr 360before calling \verb+T1_InitLib()+, or respectively, before the database 361contains any fonts. An attempt to set the file searchpaths when the database 362is no longer empty is denied. The reason is that it is not wise to override 363the searchpaths which had been valid previously during the verification of the 364existence of font files. Such paths should thus not be removed. The parameter 365\verb+pathname+ points to the string that contains the pathname that should be 366used as searchpath. The parameter \verb+type+ is any OR'ed combination of 367\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and \verb+T1_ENC_PATH+. These tell the 368function to set the search paths for Type 1 font files, AFM files and encoding 369files, respectively. In case of an error \verb+-1+ is returned and otherwise 370\verb+0+. 371 372Extending the file searchpaths before {\em and} after initialization 373is possible using 374\precorr 375\begin{verbatim} 376 int T1_AddToFileSearchPath( int pathtype, int mode, char *pathname) 377\end{verbatim}\index{\verb+T1_AddToFileSearchPath()+}\postcorr 378This might be useful to locate font files that were of no interest 379at the time of initialization. 380\verb+pathname+ is the pointer to the string that should be added to the 381searchpaths. Only {\em one} particular path element may be specified in one 382call. What searchpaths are affected is determined by the parameter 383\verb+pathtype+. Again, similar to described above, any 384OR'ed combination of \verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and 385\verb+T1_ENC_PATH+ is valid. There are two ways to extend an existing 386searchpath which are specified by the \verb+mode+ parameter. It must be either 387\verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+, which causes the new path 388element to be appended or prepended to the existent path respectively. 389Since an existent path specification is not overwritten by 390\verb+T1_AddToFileSearchPath()+, this function may be called at any time 391before or after initialization. 392 393It might also be of interest to query the current file search 394paths and font databases. \tonelib\ provides 395\precorr 396\begin{verbatim} 397 char *T1_GetFileSearchPath( int type) 398\end{verbatim}\index{\verb+T1_GetFileSearchPath()+}\postcorr 399for querying search paths. Again, the parameter \verb+type+ determines what 400search path is returned. Exactly one of \verb+T1_PFAB_PATH+, 401\verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and \verb+T1_FDB_PATH+ should be 402specified. If more than one path is specified, the first match wins and only 403one path is returned. The types will be checked in the order 404\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and 405\verb+T1_FDB_PATH+. Here, \verb+T1_FDB_PATH+ indicates an interest in the list 406of font databases. The paths are separated using the current path separator. 407 408 409\subsubsection{Adding Fonts to the Database} 410\label{addingfonts}% 411Extending the font database is possible at any time after initialization. In 412addition to using \verb+T1_AddFontDataBase()+ (see above), it is done via a 413call to \precorr 414\begin{verbatim} 415 int T1_AddFont( char *fontfilename) 416\end{verbatim}\index{\verb+T1_AddFont()+}\postcorr 417\verb+fontfilename+ is the pointer to the filename string. The following 418actions take place: 419\begin{itemize} 420\item The font file is searched using the current search path specifications. 421\item If the file has been located, it is checked whether the font database 422 contains enough memory to hose an additional font. 423 If so, the font filename 424 is stored and the function returns \verb+new_ID+, which is the font ID that 425 will be associated with this font in the future. 426\item If there was no free memory for an additional font, the memory is 427 reallocated to a greater size. This involves also resetting the new 428 area. Finally the value \verb+new_ID+ is returned. 429\end{itemize} 430If a negative value is returned the function failed. \verb+-1+ indicates the 431font file could not be located. \verb+-2+ or \verb+-3+ are returned if a 432memory allocation failure occurs. 433 434 435\subsubsection{Summary of Search Path Handling} 436 437Since the exact handling of search path specifications at the several stages 438may appear somewhat confusing we shall summarize the exact rules now: 439\begin{enumerate} 440\item {\bfseries Before Initialization}\\ 441 Default paths are not yet setup. Each call of one of the \verb+T1_Set...()+ 442 functions described above establishes a completely new respective path. Each 443 call of one of the \verb+T1_Add...()+ functions extends the respective path 444 in the desired manner, or creates a new respective path if previously no 445 path existed. 446\item {\bfseries At the Beginning of the Initialization}\\ 447 Each path type for which a path had not already been explicitly created 448 using the\\ \verb+T1_Set...()+ or \verb+T1_Add...()+ functions receives a 449 default value. This is ``\verb+.+'' for the file search paths and 450 \verb+./FontDataBase+ for the font database. 451\item {\bfseries During Initialization}\\ 452 Each path element read from the configuration file overwrites an existing 453 respective default path but preserves an existing respective explicitly 454 setup path by appending to the latter. The newly setup search path is used 455 to locate files while scanning the font database file(s). 456\item {\bfseries After Inititialization but before the Database is being 457 filled}\\ 458 At this stage, all \verb+T1_Set...()+ and \verb+T1_Add...()+ functions still 459 work as described under~(1). Notice that this phase usually is not 460 accessible when using the standard initialization scheme. It only becomes 461 accessible if no fonts have been added during initialization. 462\item {\bfseries After at least one Font is insterted into the Database}\\ 463 Once there are fonts in the database, the paths setup up 464 to now must be preserved in any case. Hence, the \verb+T1_Set...()+ may not 465 be called any longer. The \verb+T1_Add...()+ functions {\em extend} the 466 current set of search paths. In particular, possibly existing default search 467 path elements, then, are not overwritten any longer because they might have 468 been used before to verify the existance of required files. 469\end{enumerate} 470A call to \verb+T1_AddFontDataBase()+ will not only append the specified 471file name to the existing list of databases, but will also immediately 472locate the fonts specified therein and assign additional font IDs. 473 474 475\subsubsection{Bypassing the \tonelib\ File Search Machinery} 476\label{afmfilenames}% 477Usually, \tonelib\ takes care for locating files according to the path 478specifications in the configuration file. There might, however, arise the need 479to explicitly tell \tonelib\ which particular file to use. Forcing \tonelib\ to 480use particular Type 1 font files can be achieved using the function 481\verb+T1_AddFont()+, described just above. If a pathname passed to this 482function is a complete path, \tonelib\ will use this complete path to locate 483the font file, forgetting about its own search path list. A filename path is 484assumed to be complete if 485\begin{itemize} 486\item it starts with the directory separator character, usually 487 ``\verb+/+''. In this case it is an {\em absolute} path specification, meaning 488 that the start point is at the root of the filesystem, or 489\item if it starts with ``\verb+./+'' or ``\verb+../+'' (where it is assumed 490 that ``\verb+/+'' is the directory separator character). Here we have a {\em 491 relative} path specification in which ``\verb+.+'' refers to the current 492 working directory while ``\verb+..+'' refers to the parent directory of the 493 current working directory. Since the notion of the {\em current working 494 directory} is fundamental for every process that has access to a 495 filesystem, a relative path specification also uniquely identifies one 496 particular file in the filesystem. 497\end{itemize} 498If a font file whose complete path had been specified could not be found by 499\tonelib, the paths from the configuration file are searched as a fallback 500mechanism. 501 502What can be done for the Type 1 font files is also possible for AFM files, 503which are needed on a per-font basis. The function 504\precorr 505\begin{verbatim} 506 int T1_SetAfmFileName( int FontID, char *afm_name) 507\end{verbatim}\index{\verb+T1_SetAfmFileName()+}\postcorr 508allows to set the complete path of the AFM file belonging to the font 509identified by \verb+FontID+, overriding the internal 510search mechanism. This function is to be called after initialization but 511before the font \verb+FontID+ is loaded. It returns 0 if all goes right and 512$-1$ otherwise. In the latter case \verb+T1_errno+ will also be set 513appropriately. Notice that \verb+FontID+ must also be valid with respect to 514its upper limit, it is an error condition if the font database has less than 515\verb+FontID+ entries. 516 517There is also the function 518\precorr 519\begin{verbatim} 520 char *T1_GetAfmFileName( int FontID) 521\end{verbatim}\index{\verb+T1_GetAfmFileName()+}\postcorr 522which allows to query the AFM filename of a font. It returns a pointer to the 523filename if it had explicitly been specified or \verb+NULL+ 524otherwise. \verb+NULL+ will also be returned if \verb+FontID+ was invalid. In 525this case also \verb+T1_errno+ will be set. 526 527Just for the sake of completeness we should mention that what has been said 528about absolute and relative path specification 529also applies to pathnames for encoding files (see \ref{encoding}). 530 531 532 533 534\subsection{The \tonelib-Logfile} 535\label{logfile}% 536Since version 0.2-beta \tonelib\ supports a runtime logfile. 537It implements an uncomplicated way to keep track of errors, 538warnings, statistics and debug messages without overloading stdout/stderr. As 539seen in \ref{initialization} the user must specify whether or not to use a 540logfile when calling \verb+T1_InitLib()+. Specifying \verb+LOGFILE+ as 541argument leads to using a logfile and \verb+NO_LOGFILE+ suppresses the use of a 542logfile. 543 544The name of this logfile is by default \verb+t1lib.log+. This name is defined 545in \verb+t1misc.h+ and can be changed there as the user likes. 546 547Basically \tonelib\ distinguishes 4 types of runtime messages. Each type is 548associated a ``loglevel'': 549\begin{itemize} 550\item {\sl Errormessages/Level1:}\/ They are considered that important that the user is 551 in any case informed. Example: During initialization the memory allocation for 552 one of the basic data structures of \tonelib\ failed. 553\item {\sl Warningmessages/Level2:}\/ They are considered important but it is not 554 absolutely necessary to inform the user. Example: An AFM file could not be 555 loaded for a given font. This imposes several restrictions on what can be 556 done with that font but it is possible to generate bitmaps. 557\item {\sl Infomessages/Level3:}\/ They do not indicate a problem. Rather, the user 558 is notified about some facts and statistics that might be of 559 interest. Example: After loading a font the consumption of virtual memory is 560 displayed. 561\item {\sl Debugmessages/Level4:}\/ These can be pointers, numerical data 562 etc. Example: Print out the pointers that point to the memory area where the 563 PostScript dictionaries for a font just loaded are located. 564\end{itemize} 565The decision what message to put into the logfile is done by examining the 566value of an integer variable whose values can be \verb+T1LOG_ERROR+ (=1), 567\verb+T1LOG_WARNING+ (=2), \verb+T1LOG_STATISTIC+ (=3) or \verb+T1LOG_DEBUG+ 568(=4). All messages whose level is below or equal to this value are put into the 569logfile. The user may set this loglevel by calling 570\precorr 571\begin{verbatim} 572 void T1_SetLogLevel( int level) 573\end{verbatim}\index{\verb+T1_SetLogLevel()+}\postcorr 574The default value is \verb+T1LOG_WARNING+ which means that error and warning 575messages are stored in the logfile. 576 577If the usage of a logfile has been specified, \tonelib\ tries first to open 578it in the current directory. If this fails for some reason \tonelib\ tries 579to create it in the user's home directory. If this fails too, an error message 580is printed to stderr and no logfile is used. 581 582If the application programmer chose not to create a logfile, it would be hardly 583possible for a user to track down possible problems, e.g. in file 584searching. To overcome this disadvantage, the user may set an environment 585variable \verb+T1LIB_LOGMODE+ at runtime. This variable is evaluated by 586\tonelib\ when \verb+T1_InitLib()+ is called. If its value is one of the 587four strings \verb+logDebug+, \verb+logStatistic+ \verb+logWarning+ and 588\verb+logError+, the respective loglevel is set by \tonelib\ and a log file is 589created, even if the programmer chose not to do so. However, if the programmer 590had altered the log level after calling \verb+T1_InitLib()+, this cannot be 591catched by setting the environment variable. A log file is created anyhow so 592that at least error messages will be logged. 593 594The user himself may also put some messages into the logfile. This can be 595achieved using 596\precorr 597\begin{verbatim} 598 void T1_PrintLog( char *func_ident, char *msg_txt, int level, ...) 599\end{verbatim}\index{\verb+T1_PrintLog()+}\postcorr 600where \verb+func_ident+ is a pointer to a string identifying the function that 601generates the message. \verb+msg_txt+ points to the text string to put 602out. The distinction between a function identifier and a message text is only 603formal, indicating the user should identify the function that generates the 604message. 605 606The string \verb+msg_txt+ may contain format character sequences, \verb+%..+ , 607as known from the \verb+printf+- or \verb+scanf+ standard \verb+C+ 608functions. In this case, the ellipses indicate that a variable list of further 609arguments may follow. The \verb+level+ specification works as 610described above: The message is only put out if the internal loglevel is 611equal or greater than \verb+level+. 612 613Here is a typical example of a log file after a (short) 614\verb+xglyph+-session in which the loglevel was set 615\verb+T1LOG_STATISTIC+. Among several informative messages of type S, also two 616messages of type W have been generated. They stem from trying to 617raster the character ``\ss'' which was not in the current encoding. 618\par\noindent 619{% 620\tiny 621\begin{verbatim} 622(S) (Mon Jul 14 18:27:34 1997) T1_InitLib(): Initialization started 623(S) (Mon Jul 14 18:27:34 1997) T1_InitLib(): Initialization succesfully finished 624(S) (Mon Jul 14 18:27:44 1997) T1_LoadFont(): VM for Font 0: 35132 bytes 625(S) (Mon Jul 14 18:27:44 1997) CreateNewFontSize(): New Size 100.000000 created for FontID 0 (antialias=0) 626(S) (Mon Jul 14 18:27:53 1997) CreateNewFontSize(): New Size 100.000000 created for FontID 0 (antialias=1) 627(S) (Mon Jul 14 18:27:53 1997) CreateNewFontSize(): New Size 200.000000 created for FontID 0 (antialias=0) 628(W) (Mon Jul 14 18:27:53 1997) T1_SetChar(): No black pixels found for character 223 from font 0, returning NULL 629(W) (Mon Jul 14 18:27:53 1997) T1_SetStringX(): T1_SetChar() returned NULL-pointer! 630(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 200.000000 deleted for FontID 0 (antialias=0) 631(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 100.000000 deleted for FontID 0 (antialias=0) 632(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 100.000000 deleted for FontID 0 (antialias=1) 633\end{verbatim} 634} 635 636\subsection{Generating Bitmaps} 637\label{generatingbitmaps}% 638At this point, you are able to generate a bitmap. 639As said before, a character- or string-bitmap is given to the user as 640an object of type \verb+GLYPH+. We should briefly explain \verb+GLYPH+ 641here. The type is defined by 642\begin{verbatim} 643typedef struct 644{ 645 char *bits; 646 struct 647 { 648 int ascent; 649 int descent; 650 int leftSideBearing; 651 int rightSideBearing; 652 int advanceX; 653 int advanceY; 654 } metrics; 655 void *pFontCacheInfo; 656 unsigned long bpp; 657} GLYPH; 658\end{verbatim} 659\verb+bits+ is a pointer to the bitmap data. The 660bitmap is organized in lines, starting with the uppermost line. 661Each bitmap pixel is usually represented by one bit. If the width of 662the 663bitmap is not an integer multiple of 8, the lines are padded with 664zeros, so that each line starts at a byte boundary. Note that the 665bitmap has no margins taken into account. The bitmap occupies the 666minimum area the character needs to be painted. 667 668The bitmap pointer may also be 669the \verb+NULL+-pointer. In this case, the glyph contains no foreground 670pixels. The metrics of the corresponding glyph should be valid, 671though. Typically, this appears for the space character as well as in 672situations where an undefined or unencoded character had been substituted by 673the \verb+.notdef+-character within the rastering functions. 674 675Note that the \verb+pixmap+-entry which has been present in version 0.3-beta, 676has been removed with version 0.4-beta. See the discussion on the X11-interface 677in \ref{x11interface} for an explanation of this. 678 679The struct \verb+metrics+ contains metric information that is needed 680to position the character and to describe the character origin 681with respect to the bitmap. The members in detail: 682\begin{itemize} 683\item \verb+metrics.ascent+: describes how many lines the bitmap 684 ranges above the line $y=0$. 685\item \verb+metrics.descent+: describes how many lines the bitmap 686 ranges below the line $y=0$. Width below $y=0$ counts negative so that the 687 difference \verb+ascent+ $-$ \verb+descent+ is the 688 total height of the bitmap, the number of lines. 689\item \verb+metrics.leftSideBearing+: The amount of spacing between 690 the origin of a character and the x-coordinate of its leftmost 691 painted pixel. One could also name it ``left margin'' of the 692 character. 693\item \verb+metrics.rightSideBearing+: The horizontal difference between 694 the origin of a character and the x-coordinate of its rightmost 695 painted pixel. This definition stands in contrast to some other 696 interpretations of the right side bearing, where it is assumed as the 697 difference between the glyph's width and its right most pixel. 698\item \verb+metrics.advanceX+: The amount of position increment in 699 horizontal direction after this character 700 bitmap (or string bitmap) has been placed. It is almost always 701 larger than the bitmap width because most characters contain a 702 certain amount of margins. Note that this value is not suitable for internal 703 computations of character positions since it contains the horizontal 704 escapement rounded to the pixel grid. Using this value for such computations 705 leads to accumulating positioning errors. 706\item \verb+metrics.advanceY+: The amount of position increment in 707 vertical direction after this character 708 bitmap (or string bitmap) has been placed. Upper direction counts positive. 709\end{itemize} 710As seen, the width of the bitmap is given as the difference between 711\verb+rightSideBearing+ and \verb+leftSideBearing+ and the values 712\verb+metrics.leftSideBearing+, \verb+metrics.descent+,\\ 713\verb+metrics.rightSideBearing+ and \verb+metrics.ascent+ effectively describe 714the bounding box of the glyph. 715 716The entry \verb+pFontCacheInfo+ is not currently used but will 717probably later when font caching is really 718implemented. Moreover, there's a certain chance that some other 719entry will be added in future releases. 720 721The member \verb+bpp+ is used to store the depth of the bitmap. For 722true bitmaps, it is always 1. See \ref{antialiasing} for an 723explanation. 724 725There are three basic functions which produce pointer to glyph objects. In 726order to generate the glyph for a single character you would use the 727function 728\precorr 729\begin{verbatim} 730 GLYPH *T1_SetChar( int FontID, char charcode, 731 float size, T1_TMATRIX *transform) 732\end{verbatim}\index{\verb+T1_SetChar()+}\postcorr 733As in most other functions, \verb+FontID+ is a valid identification 734number of a font. It can range from 0 to $n-1$, where $n$ is number of 735fonts declared in the font database file. 736 737The second argument \verb+charcode+ determines the character that will 738be rasterized. 739As mentioned earlier, the encoding mechanism is used for 740accessing the output character. This means, if \verb+'A'+ is given as 741the character code, the machine representation of \verb+'A'+ is used 742as an index into the current encoding vector. In this encoding vector, 743the characters' name is looked up. Encoding vectors may be changed by 744the user (see \ref{encoding}). 745 746 747The parameter \verb+size+ is interpreted in Postscript's bigpoint-unit 748(bp). By default, 7491 bp equals one device pixel. 750 751\verb+transform+ specifies the transformation that will be applied to the 752character before rastering. If this pointer is \verb+NULL+, no transformation 753is used. Otherwise it should point to a valid \tonelib-transformation matrix. 754Please refer to \ref{transformations} for information on how to easily create 755\verb+T1_TMATRIX+ matrices. 756Hinting is only performed if the transformation is a pure rotation and if the 757the angle is one of 0, 90, 180 or 270 degrees. Otherwise font level and 758character level hinting information is ignored. 759 760Bitmaps of transformed characters are never saved in 761cache memory since I assume that they are rarely needed. The overhead 762to manage transformed characters in cache would be overkill and would 763significantly increase memory consuming. Anyhow, this would only work 764for some dedicated transformations. 765 766\verb+T1_SetChar()+ in fact does some more things than simply 767rastering the specified character: 768\begin{itemize} 769\item It checks whether the font in question is already loaded. If not, 770 it is loaded. 771\item If the size dependent data structures for the size in question 772 do not exist, it creates them and inserts them in the linked list of 773 size dependent data structures. 774\item It checks if the character is already existent in cache. If so, 775 it returns the data from cache. 776\end{itemize} 777 778Some words concerning memory management: The memory used by 779the \verb+GLYPH+-structure is static in this function. The memory 780required for the bitmap is also allocated by the function itself. 781This means, the user doesn't need to free any memory by 782himself. Every time \verb+T1_SetChar()+ is called, it starts by giving the 783memory needed for the last generated glyph free or respectively 784setting metric values to 0. Thus, do not free the 785returned glyph pointer since later \verb+T1_SetChar()+ will free 786memory that is no more allocated and probably used for some other purpose. 787If you really like to free the memory, set the pointer to \verb+NULL+ 788afterwards. 789 790If an error occurs at some point, \verb+T1_SetChar()+ returns a 791NULL-pointer to the user. 792 793Frequently it is advantageous to raster a series of 794characters at once. This has the advantage that internal accuracy may 795be used and the overhead for the user is minimal. For such cases, the 796function 797\precorr 798\begin{verbatim} 799 GLYPH *T1_SetString( int FontID, char *string, int len, 800 long spaceoff, int modflag, 801 float size, T1_TMATRIX *transform) 802\end{verbatim}\index{\verb+T1_SetString()+}\postcorr 803is provided. 804It can be considered an extended version of \verb+T1_SetChar()+. The 805same as said above applies to the arguments \verb+FontID+, 806\verb+size+ and \verb+transform+. But a few additional arguments are 807needed here. 808 809\verb+string+ is a series of bytes representing the indices into the current 810encoding vector. 811The \verb+len+-parameter is needed because we cannot imply that string 812is always an object like a string in C. For example, the Computer 813Modern Roman fonts contain the uppercase Greek Gamma (\char0) at 814position 0 in their internal encoding. In a string to be typeset the 815value 0 is thus a valid value and deserves no special 816treatment. Hence, we cannot not use the C-function \verb+strlen()+ to 817compute the length of the string. However, since in most usual encodings 818the special value 0 is not encoded (``\verb+.notdef+''), it makes 819sense to switch between 820standard situations and non-standard situations: 821\begin{itemize} 822\item If \verb+string+ is a string conforming with C-semantics, 823 \verb+len+ can be set to 0. Then, the length of the string is 824 internally computed. 825\item If \verb+string+ contains one or more control characters which make 826 processing impossible, the \verb+len+-value must be specified 827 explicitly. 828\end{itemize} 829 830The \verb+spaceoff+ parameter is important for word processing 831purposes. The value specified here is interpreted as an offset to the 832space width used during rastering. It is interpreted in charspace 833units, i.e., $1/1000$ bp. Every time a space character is requested, 834this amount of horizontal escapement is added to the natural 835spacewidth of the current font. Note that the space character itself 836is actually not rastered. All requests to the character with the 837charactername ``\verb+space+'' are caught by \tonelib\ and converted 838to a simple horizontal escapement. For computation of the resulting 839spacewidth, the width of the space-character is taken from the 840AFM data and merged with the specified offset, which may also be 841negative.\footnote{One consequence of this handling is, that---with a 842 little tricking---fonts that do not define a space character 843 themselves may be used for typesetting. This applies to the 844 dc-fonts, which only define a visible space, but no real space (see 845 \ref{fonts}).} 846 847The \verb+modflag+ argument may be used to specify some option to the 848rastering function. It is generally 0 or an OR'ed combination of the following 849names: 850\begin{itemize} 851\item \verb+T1_KERNING+: As the name implies, this argument 852 determines that pairwise kerning information from the AFM file is to be taken 853 into account during string rastering. Not specifying \verb+T1_KERNING+ 854 means: ``omit kerning''. It is generally 855 recommended to use kerning information since this improves the optical 856 appearance. However, many lower quality fonts do not have kerning 857 information. With \tonelib\ V.\ 0.4-beta, kerning information is accessible 858 much faster than before because it is based on char codes rather than on 859 characternames. 860\item \verb+T1_RIGHT_TO_LEFT+: Setting this flag will invert the writing 861 direction. In {\em Right-To-Left} mode the escapement in writing direction 862 (left) is inserted before placing the character with the result that the 863 character laps over to the left side. This principle is kept for all 864 characters in the string. Note that metrics of fonts that are intended for 865 {\em Right-To-Left} typesetting have the same meaning as for fonts intended 866 for standard ({\em Left-To-Right}) typesetting. 867\item \verb+T1_UNDERLINE+: The string to be rastered is to be underlined 868 according to the line specifications of the current font. 869\item \verb+T1_OVERLINE+: The string to be rastered is to be over lined. 870\item \verb+T1_OVERSTRIKE+: Same here for overstriking. 871\end{itemize} 872For a description of underlining and such, see \ref{underlining}. Notice also 873that the \verb+modflag+ argument is a replacement of the \verb+kerning+ 874argument from pre-0.7 versions of \tonelib. 875 876Concerning glyph-memory considerations, the same applies as said under 877the description of \verb+T1_SetChar()+: Never free a pointer to memory 878which was returned by \verb+T1_SetString()+. Or, alternatively, if freeing 879the pointer cannot be avoided set it to NULL after freeing it.\footnote{For 880 example, {\tt XDestroyImage()} gives the pixel memory for the image 881 data free although it might not have been allocated by any X11-function.} 882 883There are two generic ways how a string-glyph can be produced. The first is to 884take the paths of all characters needed, concatenate them, insert space and 885kerning amounts as needed and raster the resulting whole path. This will yield 886the best results since the average position accuracy of the pixels will be 887optimal. This applies especially for rotated strings. The drawback is, that 888every character must be rastered every time it is needed. There is no way to 889access the bitmap data of a character inside a rastered string separate from 890others. And the caching of string-glyphs at this programming level doesn't 891make any sense. So this principle takes significantly longer than 892concatenating bitmaps from a cache area. However, it is done when the 893specified rotation angle is not equal to $0^\circ$ or when even further 894transformation are to be applied. This condition should limit the total 895number of situations when this happens to an amount we can easily bear. 896 897If the \verb+transform+-argument is \verb+NULL+ we know transformations or 898rotation should not be applied and another approach is used. We are then able 899to construct the resulting bitmap by adjusting already existent bitmaps into 900proper positions. If a character does not already exist in the cache, it is 901generated just the way \verb+T1_SetChar()+ works. The calculation of the 902character-bitmap positions in the output bitmap is done with 903char space-precision. Nonetheless, there may be differences in the output 904compared with output of the above method. These are caused by the fact that 905rounding to pixel accuracy has already been achieved when generating the 906character bitmap. Thus, the output of the above principle should always be 907better since the positions of the black pixels are rounded with respect to the 908whole string, and not with respect to a single character glyph. On the other 909hand, concatenating character glyphs takes significantly less time than 910rastering a complete string. Theoretically, differences of up to two pixels 911horizontal shift may appear in the output of the two principles. You can 912check the effect by running the program \verb+xglyph+. Specify a string of 913enough length and raster it at angle $0^\circ$. Then specify a very small 914angle from 0 different, say, $0.001^\circ$, and raster the string again with 915the new setting. You might find that the representation of the string is a 916little different now. 917 918The third function that creates a glyph object is 919\precorr 920\begin{verbatim} 921 GLYPH* T1_SetRect( int FontID, float size, 922 float width, float height, 923 T1_TMATRIX *transform) 924\end{verbatim}\index{\verb+T1_SetRect()+}\postcorr 925Calling this function yields a filled rectangle. It is intended for situations 926where a \TeX-style \verb+\vrule+ would be appropriate, or, for equations in 927mathematical typesetting. 928 929First, the argument \verb+FontID+ identifies a valid font. At this time, it is 930not obvious why a valid font is required in order to create a rectangular 931glyph. The reason is, that some of the parameters that are associated to a 932particular font are also relevant for creating rectangles in the context of 933that font. Hence, specifying a font identifier in this case is a means of 934stating ``{\em draw a rectangle that visually fits to the style of the font 935 \verb+FontID+}''. Aside from this, I assume that each application that uses 936\tonelib\ deals with at least {\em one} font so that the \verb+FontID+ 937parameter actually does not hurt. 938 939The size of the rectangle is to be specified in charspace units by means of 940the parameters \verb+width+ and \verb+height+, and is moreover subject to 941scaling through the parameter \verb+size+. By definition, the typographical 942fundamental area of a font, known as the {\em em-square}, is just as high and 943as wide as the design size of the font. In charspace units, this rectangle 944exactly maps to a $1000 \times 1000$ grid. Or alternatively spoken, one 945charspace unit is 0.001bp (Big Point). For example, in order to draw an 946em-square for some font at 13 points, the correct parameters are 947\hbox{\verb+size+ $= 13$}, \hbox{\verb+width+ $= 1000$} and 948\hbox{\verb+height+ $= 1000$}. If absolute physical dimensions are desired, 949the scaling explicitly must be calculated by the user. For instance, in order to 950produce a $ 1 \mathrm{cm} \times 1 \mathrm{cm}$ square we find 951\begin{displaymath} 952h = w = 1\mathrm{cm} \frac{72\mathrm{bp}/\mathrm{in} \times 953 1000\mathrm{cs}/\mathrm{bp}}{2.54\mathrm{cm}/\mathrm{in}} 954\approx 28346\;\mathrm{cs.} 955\end{displaymath} 956Here ``cs'' designates charspace units and \verb+size+ is assumed to be $1$. 957Note that still the device resolution must be properly setup in order to make 958the dimensions appear accurately on the device. 959 960The parameter \verb+transform+ is a pointer to a \tonelib\ transformation 961matrix. If it is \verb+NULL+, the current transformation of the font in 962question is used. Depending on the kind of actual transformation, the 963rectangle might also image as a nonrectangular shape. This happens, if the 964current font is slanted, then the rectangle will be skewed. 965 966Glyphs produced by the rectangle function are never cached because there is 967no means in doing so. With respect to memory management, the same applies as 968for \verb+T1_SetChar()+ and \verb+T1_SetString()+. Since rectangles rarely are 969used to produce normal text flow, the glyphs produced by the rectangle 970function do not cause any escapement. 971 972 973If two glyphs with arbitrary orientation exist, 974\precorr 975\begin{verbatim} 976 GLYPH *T1_ConcatGlyphs( GLYPH *glyph1, GLYPH *glyph2, 977 int x_off, int y_off, int modflag) 978\end{verbatim}\index{\verb+T1_ConcatGlyphs()+}\postcorr 979can be used to concatenate them. First the size of the resulting glyph is 980computed and its metric values are filled. Then, the two glyphs are placed at 981their appropriate positions in the newly created bitmap. In order to be able 982to work, the following conditions must be met: 983\begin{enumerate} 984\item Either glyph must be different from \verb+NULL+. 985\item Both glyphs must have identical \verb+bpp+-values. If antialiased and 986 non-antialiased glyphs are to be concatenated, have a look at 987\item There must be enough memory for the new glyph (naturally). 988\end{enumerate} 989The quantities \verb+x_off+ and \verb+y_off+ describe the $x$- and 990$y$-component of an optional offset to be inserted between the two 991glyphs. This offset is interpreted as device pixels. The \verb+modflag+ 992argument is used to specify the direction in which the two glyphs are to be 993concatenated. That is, only the bit \verb+T1_LEFT_TO_RIGHT+ / 994\verb+T1_RIGHT_TO_LEFT+ is respected by this function. 995 996If problems occur, \verb+NULL+ is returned. 997It is generally not recommended to produce large glyphs with this function 998because the char space precision in placing the character bitmaps is lost. For 999example, three times rounding up an advance by 0.3 pixels accumulates to 1 1000pixel position error. A similar effect shows up when two rotated and underlined 1001glyphs are concatenated with this function. There might be a slight shift in the 1002baseline at the point where the two glyphs touch. 1003 1004A dilemma occurs, if two antialiased bitmaps have distinct background 1005colors. Then, it is not clear what the transparent color 1006is. \verb+T1_ConcatGlyphs()+ always assumes the {\em current} background color 1007to be transparent. 1008 1009 1010There is one more function that generates pointers to glyphs: 1011\precorr 1012\begin{verbatim} 1013 GLYPH *T1_CopyGlyph(GLYPH *glyph) 1014\end{verbatim}\index{\verb+T1_CopyGlyph()+}\postcorr 1015As mentioned earlier, the user doesn't have the possibility of keeping 1016the 1017glyphs longer than to the next call of the respective rastering function. If 1018someone wants to keep a bitmap some time longer, 1019\verb+T1_CopyGlyph()+ may be used 1020to copy the glyph to another area which is then completely under user's 1021control. This function simply does the following: 1022\begin{itemize} 1023\item Allocates the memory for the glyph-structure. 1024\item If bitmap data is present, it allocates memory for the bitmap data, 1025 taking the member \verb+bpp+ into account (see \ref{antialiasing}). 1026\item Copies the structure and the bitmap data to the respective locations. 1027\item Initializes the pointer \verb+glyph.bits+. 1028\end{itemize} 1029 1030Return value is the pointer to the allocated glyph-structure. If something 1031goes wrong, NULL is returned to indicate an error. A glyph pointer, 1032returned by a call to this function should be freed by a call to 1033\verb+T1_FreeGlyph()+ (see \ref{deletingdata}). 1034 1035 1036\subsection{Loading Fonts Explicitly} 1037\label{loading}% 1038Usually there is no need for a user to load a font into memory since this is 1039done automatically as needed by the rastering functions. But there are two 1040situations where it makes sense to explicitly load a font before generating 1041any size dependent data: 1042\begin{itemize} 1043\item A font is to be reencoded immediately after loading (see \ref{encoding}). 1044\item A font is to be transformed (see \ref{transformations}). 1045\end{itemize} 1046These operations require a font being loaded but not having any size specific 1047data. Loading a font explicitly is done by the function 1048\precorr 1049\begin{verbatim} 1050 int T1_LoadFont( int FontID) 1051\end{verbatim}\index{\verb+T1_LoadFont()+}\postcorr 1052Loading a font involves several actions: 1053\begin{itemize} 1054\item Locating and loading the Type 1 font file. 1055\item Locating and loading the font metrics data from AFM file. 1056\item Computing and filling the values of the \verb+FONTPRIVATE+ structure as 1057 described in section \ref{internals}. 1058\item Setting up some tables for fast access of metrics information. 1059\end{itemize} 1060\verb+T1_LoadFont()+ returns \verb+0+ if successful or \verb+-1+ if the font 1061could not be loaded. A failure may be due to \tonelib\ not having been 1062initialized or due to problems with file locations and file parsing. If a font 1063refuses to load, the logfile should be examined first. Furthermore, in case of 1064a failure \verb+T1_errno+ will be set appropriately. 1065 1066 1067\subsection{Functions for Encoding Handling} 1068\label{encoding}% 1069As mentioned earlier, the encoding mechanism used in the 1070PostScript-language allows a font to contain more than 256 different 1071characters, although only 256 are accessible at a given time. The 1072characters which are accessible are given by the elements of the 1073current {\em encoding vector}. In order to maximize flexibility, 1074\tonelib\ allows for changing the current encoding vector. This is 1075also called ``Reencoding a font''. A new encoding vector is defined 1076and made known to the library by creating an encoding-file and loading 1077its contents into memory. 1078Before describing the functions needed for this, we should 1079briefly describe the format of an encoding file. 1080 1081An encoding file is an ASCII text file. No 1082assumptions about filename extensions are made. Here are the rules for 1083scanning the file: 1084\begin{itemize} 1085\item The file contents are completely ignored until a line is encountered 1086 that starts with the string \verb+Encoding=+. This string may optionally be 1087 immediately followed by a string that is assumed to be the identifier of the 1088 {\em encoding scheme} that this file defines. Any further text on this line 1089 is ignored. 1090\item Now, 256 lines have to follow, each line describing one 1091 character's name. The string ranging from the beginning of the line 1092 to the first white space character is assumed to be a character 1093 name. The remainder of the lines is ignored and may (should) be used 1094 for comments, thereby describing the current character code. 1095\item All further lines of text are ignored. 1096\end{itemize} 1097As well known from PostScript, non-existent characters have to be 1098named \verb+.notdef+. 1099 1100Here's an example of such an encoding file: 1101\begin{verbatim} 1102Sample encoding file for t1lib! 1103The first two lines are considered to be comments! 1104Encoding=ISOLatin1Encoding 1105.notdef /* '000 000 "00 */ 1106.notdef /* '001 001 "01 */ 1107.notdef /* '002 002 "02 */ 1108 . . 1109 . . 1110 . . 1111greater /* '076 062 "3E */ 1112question /* '077 063 "3F */ 1113at /* '100 064 "40 */ 1114A /* '101 065 "41 */ 1115B /* '102 066 "42 */ 1116 . . 1117 . . 1118 . . 1119yacute /* '375 253 "FD */ 1120thorn /* '376 254 "FE */ 1121ydieresis /* '377 255 "FF */ 1122\end{verbatim} 1123 1124Since V.~1.2, \tonelib\ is also able to load encoding files in the format used 1125by \verb+dvips+. This makes a large set of existing encoding files available 1126to the user. When parsing \verb+dvips+ encoding files, \tonelib\ requires 1127PostScript syntax. This means white space may be interspersed freely and 1128line comments are defined by the character \%. The mark-characters, \verb+[+ 1129and\verb+]+, are considered as special tokens and need not be preceded or 1130followed by white space. Similarly, the literal escape character \verb+/+ 1131delimits a preceding token without interspersed white space. When parsing 1132\verb+dvips+ encoding files, \tonelib\ tolerates less than 256 character name 1133definitions. If characters are missing, they are substituted by \verb+.notdef+ 1134until the counter reaches $256$. Aside from comments, no PostScript tokens are 1135allowed after the encoding definition in a \verb+dvips+ encoding file is 1136complete. 1137 1138With the defining terms above, it turns out that a file which has successfully 1139been scanned as a \verb+dvips+ encoding file, cannot specify a valid \tonelib\ 1140encoding after the PostScript encoding definition is complete (because no 1141valid character name can start with \% and because at least a line such as 1142\verb+Encoding=+, would have to follow the PostScript encoding). Hence the 1143file format are mutually exclusive and it is possible to read both format 1144using one function. In a first pass \tonelib\ tries to read the file as a 1145\verb+dvips+ encoding file, and if that fails, it assumes to have a \tonelib\ 1146encoding file. 1147 1148 1149Once such an encoding file of either type has been created, it can be loaded 1150into memory. This is done with the function 1151\precorr 1152\begin{verbatim} 1153 char **T1_LoadEncoding( char *filename) 1154\end{verbatim}\index{\verb+T1_LoadEncoding()+}\postcorr 1155The function will use the search path definitions read from 1156the configuration file during initialization (see 1157\ref{runtimesetup}, \verb+ENCODING=+). If no 1158errors occur, an array of pointers to strings is created and 1159initialized. The start address of this pointer array is returned as a 1160double pointer to a char. This pointer is intended 1161to be used to reencode a font via \verb+T1_ReencodeFont()+. If the encoding 1162data structure could not be created, \verb+NULL+ is returned to indicate the 1163error. 1164 1165The memory allocated by \verb+T1_LoadEncoding()+ is organized in two 1166continuous blocks. One block is the pointer array of size 257\footnote{This 1167 number results from 256 charactername pointers plus one pointer to the 1168 encoding scheme identifier.} and the 1169other block contains the character name strings plus the encoding scheme 1170specification, separated by 1171ASCII-zeros. 1172This memory can be returned to the system using the function 1173\precorr 1174\begin{verbatim} 1175 int T1_DeleteEncoding( char **Encoding) 1176\end{verbatim}\index{\verb+T1_DeleteEncoding()+}\postcorr 1177\tonelib\ does not check whether a valid pointer value was passed. So be 1178careful to pass the correct pointer. An error in this function should almost 1179always be followed by a segmentation violation. 1180 1181A newly loaded encoding is applied to an existent font by 1182calling 1183\precorr 1184\begin{verbatim} 1185 int T1_ReencodeFont( int FontID, char **Encoding) 1186\end{verbatim}\index{\verb+T1_ReencodeFont()+}\postcorr 1187\verb+FontID+ must be a valid font identification and 1188\verb+Encoding+ a pointer returned from a 1189successful call to \verb+T1_LoadEncoding()+. 1190 1191There are two requirements 1192in order to reencode a font: 1193\begin{enumerate} 1194\item The font must already have been loaded into memory. 1195\item No size-dependent data exists for this font. If 1196 it does, it must be removed explicitly prior to calling 1197 \verb+T1_ReencodeFont()+. 1198\end{enumerate} 1199 1200It follows that there are two ways to reencode a font. The first is 1201to load a font explicitly and reencode it before any size dependent 1202data is created. The second is to use an automatically loaded font 1203and delete all of its size dependent data before reencoding it. 1204 1205The user may also specify the special pointer NULL as the 1206\verb+Encoding+-argument. This would reencode the font to its internal 1207encoding vector. 1208 1209In case of success, the function returns 0, otherwise -1 is returned. 1210 1211Reencoding a font takes a considerable amount of time since the mapping tables 1212have to be reorganized. In situations where it is \`a priori foreseeable that the 1213font will be reencoded using some standard encoding vector, it makes sense to 1214assign that particular encoding vector as the default encoding vector, 1215thereby overwriting the internal encoding vector of each font at load time 1216before the mapping tables are setup. Setting the default encoding can be 1217achieved using 1218\precorr 1219\begin{verbatim} 1220 int T1_SetDefaultEncoding( char **Encoding) 1221\end{verbatim}\index{\verb+T1_SetDefaultEncoding()+}\postcorr 1222Here \verb+Encoding+ encoding is assumed to be a valid \tonelib\ encoding 1223vector, e.g., created by a call to \verb+T1_LoadEncoding+. 1224\verb+T1_SetDefaultEncoding()+ has to be called after initialization. It 1225returns \verb+0+ if this condition is fulfilled and \verb+-1+ 1226otherwise. In the latter case \verb+T1_errno+ is set appropriately. 1227Notice that the internal encoding of the font is still accessible by 1228reencoding the font using \verb+NULL+ as encoding specification (see above). 1229Note further that the default encoding vector is only applied to those font 1230that have \verb+StandardEncoding+ as internal encoding. This is to prevent 1231fonts like ZapfDingbats, Symbol or Sonata\footnote{A musical notation font.} 1232from being reencoded automatically at load time because this would be 1233surely inappropriate for such fonts. 1234 1235It is also possible to query the encoding scheme that the font associated with 1236\verb+FontID+ uses. This is achieved with the function 1237\precorr 1238\begin{verbatim} 1239 char *T1_GetEncodingScheme( int FontID) 1240\end{verbatim}\index{\verb+T1_GetEncodingScheme()+}\postcorr 1241The return value is a pointer to a string which describes the encoding scheme 1242in question. The are 3 possible cases: 1243\begin{itemize} 1244\item The font uses Adobe StandardEncoding, which is internally known by the 1245 rasterizer. Then, \verb+StandardEncoding+ is returned. 1246\item The font defines its own encoding by \hbox{\verb+dup+ $n$ {\em 1247 LiteralName} \verb+put+} statements. In this case no particular name is 1248 associated with the encoding scheme and \verb+FontSpecific+ is returned. 1249\item The encoding is externally loaded by \verb+T1_LoadEncoding()+. Then the 1250 encoding scheme entry of this file is returned. If this (optional) entry is 1251 not specified in the file, \verb+Unspecified+ is returned. 1252\end{itemize} 1253Notice that the name of the encoding scheme is also accessible as 1254\verb+Encoding[256]+ where \verb+Encoding+ is the pointer returned by a 1255successful call to \verb+T1_LoadEncoding()+. 1256 1257\subsection{Deleting Data} 1258\label{deletingdata}% 1259In frequently appearing cases, it may be wise to return some memory 1260which was explicitly 1261or automatically allocated by the library back to the 1262system.\footnote{This is especially true, since there is presently no 1263 caching algorithm which automatically takes care of this.} For 1264this purpose 1265some functions are available. To understand how size dependent 1266data for a font is organized, see (\ref{internals}). 1267 1268The memory amount required by the size-dependent data of \verb+size+ 1269and font \verb+FontID+ is freed by calling the function 1270\precorr 1271\begin{verbatim} 1272 int T1_DeleteSize( int FontID, float size) 1273\end{verbatim}\index{\verb+T1_DeleteSize()+}\postcorr 1274The data deleted includes the metric 1275information for 256 characters, some pointers, associated bitmap data (if 1276already existent) as well as the font matrix for that size. 1277 1278As described in section \ref{internals}, the data structures containing 1279size-dependent information of a particular font are organized as a 1280linked list. \verb+T1_DeleteSize()+ takes care that a properly linked 1281list is left after deleting the data. 1282 1283If the combination of \verb+size+ and \verb+FontID+ does not exist, -1 1284is returned. If the operation was successful, the return value is 0. 1285 1286For the purpose of removing all size-dependent data for a particular 1287font, there is the function 1288\precorr 1289\begin{verbatim} 1290 int T1_DeleteAllSizes( int FontID) 1291\end{verbatim}\index{\verb+T1_DeleteAllSizes()+}\postcorr 1292It recursively removes all size-dependent data for the font 1293\verb+FontID+. This may be appropriate if a user knows some font not 1294to be needed any longer. This function is also to be used, if one intends to 1295reencode a font for 1296which size dependent data has already been generated. In addition, 1297 font transformations 1298such as {\em slanting} and {\em extending} 1299require a font having no size-specific data. 1300\verb+T1_DeleteAllSizes()+ recursively calls \verb+T1_DeleteSize()+ to 1301do its job. 1302It returns the number of sizes removed (including 0 if no sizes were 1303existent) or -1 if an error occurred. 1304 1305It is also possible to remove the entire data associated with a 1306particular font from memory using 1307\precorr 1308\begin{verbatim} 1309 int T1_DeleteFont( int FontID) 1310\end{verbatim}\index{\verb+T1_DeleteFont()+}\postcorr 1311\verb+T1_DeleteFont()+ goes one step beyond the above functions and 1312removes all the data associated with the font \verb+FontID+. This 1313includes: 1314\begin{itemize} 1315\item All size dependent data. 1316\item All data from the Type 1 font program, held in memory. 1317\item All AFM data kept in memory. 1318\end{itemize} 1319The memory reserved for a font in hierarchy-level 1 is not returned to 1320the system since it is simply one element in the array of structures of 1321type \verb+FONTPRIVATE+ (see \ref{internals}). But all entries in this 1322structure are reset to initial values. 1323 1324Whether it is useful or not, a font that has been removed using 1325\verb+T1_DeleteFont()+ may also be loaded again, explicitly or 1326implicitly. 1327 1328There is a restriction, which has not yet been mentioned: A font may only be 1329removed if it is a physical font (to be explained later) to which no logical 1330fonts refer or if it is a logical font.\footnote{See \ref{logicalfonts} for 1331 explanation of logical fonts.} A reference counter is maintained in each 1332physical font to check for this. If the font to be removed is a logical font, 1333the \verb+FONTPRIVATE+ area is reset and the reference counter of the 1334referenced physical font is decremented. Of course, size dependent data is 1335removed in every case. 1336 1337\verb+T1_DeleteFont()+ returns 0 if the font has been removed correctly or if 1338the font was not loaded. $n$ ($>0$) is returned if 1339the font was physical and was referenced by $n$ logical fonts. A 1340return value -1 indicates an invalid \verb+FontID+. 1341 1342The function 1343\precorr 1344\begin{verbatim} 1345 int T1_FreeGlyph( GLYPH *glyph) 1346\end{verbatim}\index{\verb+T1_FreeGlyph()+}\postcorr 1347returns memory allocated by 1348\verb+T1_CopyGlyph()+ back to the system. This function should not be 1349applied to the pointer to a glyph returned by one of the rastering 1350functions. As said earlier, these functions manage the memory areas by 1351themselves. 1352 1353Similarly, the function 1354\precorr 1355\begin{verbatim} 1356 int T1_FreeCompCharData( T1_COMP_CHAR_INFO *cci) 1357\end{verbatim}\index{\verb+T1_FreeCompCharData()+}\postcorr 1358returns memory associated to the composite caracter data structures, as 1359allocated and returned by \verb+T1_GetCompCharData()+ or 1360\verb+T1_GetCompCharDataByIndex()+ (see 1361Section~\ref{subsec:CompositeCharacters}), to the system. In order to avoid 1362memory leaks, each call of the latter two functions should be followed by a 1363call to this function. 1364 1365 1366In order to close the library and return all memory to the system, 1367\precorr 1368\begin{verbatim} 1369 int T1_CloseLib( void) 1370\end{verbatim}\index{\verb+T1_CloseLib()+}\postcorr 1371should be used. If no problems occur, 0 is returned. The value 1 indicates 1372problems during freeing data. In this case the logfile should be examined. 1373After having freed all data the file search paths, if different from the 1374defaults, are restored. Last, the logfile is closed. 1375 1376 1377\subsection{Underlining, Overlining and Overstriking} 1378\label{underlining}% 1379\tonelib\ supports underlining, overlining and overstriking for the string 1380rastering functions. These lines are always drawn on the fly as the bitmaps 1381are generated. In writing direction, the lines range from the glyph's origin 1382to the glyph's width. The vertical dimensions are set the following way by 1383default when a font is loaded: 1384\begin{itemize} 1385\item {\bf Underlining}: Underline position and thickness are taken from the 1386 Fontinfo dictionary of the respective font. The rule is vertically centered 1387 with respect to the mathematical line given by the position value. 1388\item {\bf Overlining}: The position is computed to be $y=a+|u|$ where $a$ 1389 corresponds to the typographic ascender and $u$ is the underline position 1390 from the Fontinfo dictionary. As above, the rule is vertically centered 1391 around this position value. The thickness is set to underline thickness. 1392\item {\bf Overstriking}: The position is $y=a/2$ where again $a$ is the 1393 typographic ascender of the font and vertical alignment of the rule is done 1394 by centering around the computed position. The thickness is set to underline 1395 thickness. 1396\end{itemize} 1397As all information in AFM files, thickness and position specifications are 1398interpreted in charspace units. 1399 1400Notice that the typographic ascender is not determined by the Type 1 font 1401program. It has to be guessed by \tonelib. The problem of guessing the 1402typographic ascender is discussed in more detail in \ref{writingafmfiles}. 1403When loading a font, this typographic ascender is assumed to be the vertical 1404coordinate of the upper right corner of the bounding box of the letter ``d''. 1405This is not as advanced as the procedure described in \ref{writingafmfiles}, 1406but it suffices because the underlining positions can later be overwritten by 1407the user (see below). 1408 1409From the mathematical point of view, the line rules are an integral part of 1410the rastered path. It follows that line rules may appear sheared if a font has 1411been artificially slanted and the size and/or thickness is sufficiently large. 1412 1413A look into real Type 1 font files shows that even fonts of the same family 1414possess incompatible values for underlining. For example, Bitstream Charter 1415Roman defines underline thickness to be 61 and its bold variant assigns a 1416value of 90. Underlining text consisting of Roman and bold words will not be 1417very pleasing using these values. For this reason \tonelib\ provides a way for 1418explicitly setting and overwriting the default values for line ruling on a 1419per-font level. The functions 1420\precorr 1421\begin{verbatim} 1422 int T1_SetLinePosition( int FontID, int linetype, float value) 1423\end{verbatim}\index{\verb+T1_SetLinePosition()+}\postcorr 1424and 1425\precorr 1426\begin{verbatim} 1427 int T1_SetLineThickness( int FontID, int linetype, float value) 1428\end{verbatim}\index{\verb+T1_SetLineThickness()+}\postcorr 1429set the respective value for font \verb+FontID+ to \verb+value+. 1430The \verb+linetype+ argument is assumed to be an OR'ed combination of 1431\verb+T1_UNDERLINE+, \verb+T1_OVERLINE+ and \verb+T1_OVERSTRIKE+. While it 1432generally does not make sense to specify identical positions for two or three 1433distinct line rule types, it is meaningful to specify identical thickness 1434values for two or all rules types. However both functions accept combinations 1435of linetype specification. 1436It follows that consistent line ruling for several fonts can be achieved by 1437setting the line rule parameters of the involved fonts to identical respective 1438values. 1439 1440Currently active line rule parameters can be queried using the functions 1441\precorr 1442\begin{verbatim} 1443 float T1_GetLinePosition( int FontID, int linetype) 1444\end{verbatim}\index{\verb+T1_GetLinePosition()+}\postcorr 1445and 1446\precorr 1447\begin{verbatim} 1448 float T1_GetLineThickness( int FontID, int linetype) 1449\end{verbatim}\index{\verb+T1_GetLineThickness()+}\postcorr 1450In case more than one line rule type is specified for 1451\verb+linetype+ the first matching value is returned, 1452since obviously the functions can only return {\em one} value. The order the 1453argument is checked is \verb+T1_UNDERLINE+, \verb+T1_OVERLINE+ and 1454finally \verb+T1_OVERSTRIKE+. 1455 1456These functions called with \verb+T1_UNDERLINE+ as line type argument should 1457not be confused with the functions \verb+T1_GetUnderlinePosition()+ and 1458\verb+T1_GetUnderlineThickness()+ respectively. The latter functions will 1459always return the values from the Fontinfo dictionary as opposed to the former 1460which will return the currently active values. 1461 1462Since line ruling is done on the fly, it is possible to change the involved 1463parameters in the middle of a session without confusing the cache or removing 1464size dependent data. 1465 1466 1467\subsection{Common Information on Fonts and Characters} 1468\label{common}% 1469This subsection describes some functions making common information 1470available. This includes Type 1 and AFM data. Thus, these 1471functions partially depend on the existence of AFM data. In order not 1472to have to specify this data every time, here are a few conventions: 1473\begin{enumerate} 1474\item \verb+FontID+ is the valid ID of a declared font. 1475\item All functions that require a character index as argument 1476 use the currently active encoding vector to determine the 1477 character's name 1478 belonging to this index and use the character's name to search for the 1479 information required. 1480\item Some functions do not allow to use the return value for error 1481 checking. For this reason every function described in this subsection will 1482 set \verb+T1_errno+ appropriately if something goes wrong. See 1483 \ref{errorhandling} for the description of the possible values of 1484 \verb+T1_errno+. 1485\item None of the functions described in this subsection will load a font 1486 automatically. 1487\end{enumerate} 1488 1489\subsubsection{Information from FontInfo-Dictionary} 1490\label{fontinfodict}% 1491\precorr 1492\begin{verbatim} 1493 char *T1_GetFontName( int FontID) 1494\end{verbatim}\index{\verb+T1_GetFontName()+}\postcorr 1495This function returns the string object \verb+FontName+ from the 1496fontinfo-dictionary of the specified font or a NULL pointer if the font is not 1497loaded. 1498 1499The memory for the returned string is static in this function and should thus 1500not be freed by the user. As another consequence, the returned 1501string is only constant until the function is called the next time. 1502 1503\precorr 1504\begin{verbatim} 1505 char *T1_GetFullName( int FontID) 1506\end{verbatim}\index{\verb+T1_GetFullName()+}\postcorr 1507This function returns the string object \verb+FullName+ from the 1508fontinfo-dictionary of the specified font or a NULL pointer if the font is not 1509loaded. 1510 1511The memory for the returned string is static in this function and should thus 1512not be freed by the user. As another consequence, the returned 1513string is only constant until the function is called the next time. 1514 1515\precorr 1516\begin{verbatim} 1517 char *T1_GetFamilyName( int FontID) 1518\end{verbatim}\index{\verb+T1_GetFamilyName()+}\postcorr 1519This function returns the string object \verb+FamilyName+ from the 1520fontinfo-dictionary of the specified font or a NULL pointer if the font is not 1521loaded. 1522 1523The memory for the returned string is static in this function and should thus 1524not be freed by the user. As another consequence, the returned 1525string is only constant until the function is called the next time. 1526 1527\precorr 1528\begin{verbatim} 1529 char *T1_GetWeight( int FontID) 1530\end{verbatim}\index{\verb+T1_GetWeight()+}\postcorr 1531It returns the Weight entry from fontinfo dictionary. It is a string 1532entry and represents a verbatim classification of the font rather than 1533a numerical quantity. In case of an error \verb+NULL+ is returned. 1534 1535\precorr 1536\begin{verbatim} 1537 float T1_GetItalicAngle( int FontID) 1538\end{verbatim}\index{\verb+T1_GetItalicAngle()+}\postcorr 1539The returned value is the italic angle of the font in degrees as a 1540float. Notice that the meaning of ItalicAngle is related to the slanting 1541of fonts, but not in the sense of \tonelib\ (see 1542\ref{transformations}). 1543An italic font may be artificially slanted and an artificially slanted 1544font in the sense of \tonelib\ may have an italic angle of zero. 1545 1546\precorr 1547\begin{verbatim} 1548 int T1_GetIsFixedPitch( int FontID) 1549\end{verbatim}\index{\verb+T1_GetIsFixedPitch()+}\postcorr 1550This function returns 0 if the font's spacing is proportional and 1 if 1551it is fixed. 1552 1553\precorr 1554\begin{verbatim} 1555 BBox T1_GetFontBBox( int FontID) 1556\end{verbatim}\index{\verb+T1_GetFontBBox()+}\postcorr 1557This function returns the bounding box of the font identified by 1558\verb+FontID+. It is the bounding box that 1559results if all characters of a font are overlayed with their reference point 1560falling on the point (0,0). All values are in charspace units. The members 1561\verb+lly+ and \verb+urx+ represent the fonts overall descent and ascent, 1562respectively. 1563 1564The font's bounding box is part of the AFM information as well as member in 1565the font's private dictionary. It turns out that the information from 1566\verb+.afm+- and \verb+.pfa+/\verb+.pfb+-file is not consistent for some 1567fonts. \tonelib\ returns the information stored in the font-file itself, since 1568I assume it is more consistent to the font's data. 1569 1570\precorr 1571\begin{verbatim} 1572 float T1_GetUnderlinePosition( int FontID) 1573\end{verbatim}\index{\verb+T1_GetUnderlinePosition()+}\postcorr 1574This function returns the underline position of the specified font as given in 1575the fontinfo-dictionary. The value is to be interpreted in charspace 1576units. If the font is not loaded, 0 is returned since an 1577underline position of 0 can be considered impossible for most fonts. 1578 1579\precorr 1580\begin{verbatim} 1581 float T1_GetUnderlineThickness( int FontID) 1582\end{verbatim}\index{\verb+T1_GetUnderlineThickness()+}\postcorr 1583This function returns the thickness of the underlining rule for this font or 0 1584if the font is not loaded. 0 is a safe index for an error since a rule of 1585height 0 would not be visible anyhow. 1586 1587\precorr 1588\begin{verbatim} 1589 char *T1_GetVersion( int FontID) 1590\end{verbatim}\index{\verb+T1_GetVersion()+}\postcorr 1591The version string from the Type 1 font file is returned. The memory 1592where the string is located is managed by the function itself. 1593 1594\precorr 1595\begin{verbatim} 1596 char *T1_GetNotice( int FontID) 1597\end{verbatim}\index{\verb+T1_GetNotice()+}\postcorr 1598The notice string from the Type 1 font file is returned. Again the 1599user should not touch the memory where the string is located. 1600 1601\subsubsection{Metric Information on Glyphs} 1602\label{metricinformation}% 1603\precorr 1604\begin{verbatim} 1605 int T1_GetCharWidth( int FontID, char char1) 1606\end{verbatim}\index{\verb+T1_GetCharWidth()+}\postcorr 1607The character width according to the AFM information is returned in charspace 1608units. If no AFM information is available, 0 is returned. 1609 1610The width of a 1611character is the amount of horizontal escapement that the next character is 1612shifted to the right with respect to the current position. This information is 1613not given in the character's bounding box. Also, the width corresponds to the 1614entry \verb+characterWidth+ in the \verb+glyph+-structure, as described in 1615\ref{generatingbitmaps}. But since \verb+T1_GetCharWidth()+, returns its 1616result in charspace units, the accuracy is much higher than using the value 1617of the \verb+glyph+-structure which has only pixel-accuracy. 1618 1619If there is an extension specified for the font in question, the characters 1620width is corrected correspondingly. 1621 1622\precorr 1623\begin{verbatim} 1624 BBox T1_GetCharBBox( int FontID, char char1) 1625\end{verbatim}\index{\verb+T1_GetCharBBox()+}\postcorr 1626The character's bounding box of \verb+char1+ is returned with the elements to 1627be interpreted in charspace units. The bounding box of a character is defined 1628to be smallest rectangle aligned parallel to the $x$- and $y$-axis of 1629the character 1630coordinate system which encloses the painted area of the character 1631completely. This rectangle is completely specified by specifying its 1632lower left and its upper 1633right corner. From a programmer's point of view, a characters bounding 1634box is defined by the following struct of type \verb+BBox+: 1635\begin{verbatim} 1636typedef struct 1637{ 1638 int llx; /* lower left x-position */ 1639 int lly; /* lower left y-position */ 1640 int urx; /* upper right x-position */ 1641 int ury; /* upper right y-position */ 1642} BBox; 1643\end{verbatim} 1644In case the character is not encoded or no AFM data is available, a box 1645containing only zeros is returned. 1646 1647The bounding box is corrected if an extension value has been applied 1648to the font in question. 1649 1650Since version 0.3-beta, slanted fonts are fully supported, meaning that for 1651slanted fonts too a correct bounding box will be returned. This is however 1652quite time expensive since the characters' real outline must be considered. 1653See the discussion on slanting a font (\ref{transformations}) for an 1654explanation of this. 1655 1656 1657\precorr 1658\begin{verbatim} 1659 int T1_GetStringWidth( int FontID, char *string, 1660 int len, long spaceoff, int kerning) 1661\end{verbatim}\index{\verb+T1_GetStringWidth()+}\postcorr 1662\precorr 1663\begin{verbatim} 1664 BBox T1_GetStringBBox( int FontID, char *string, 1665 int len, long spaceoff, int kerning) 1666\end{verbatim}\index{\verb+T1_GetStringBBox()+}\postcorr 1667These two functions represent the complement to the above functions on the level 1668of strings. All parameters that take influence on the resulting width and 1669bounding box must be given in the argument list. Their meaning is identical to 1670the meaning they have when calling string rastering functions (see 1671\ref{generatingbitmaps}). 1672 1673 1674\precorr 1675\begin{verbatim} 1676 METRICSINFO T1_GetMetricsInfo( int FontID, char *string, 1677 int len, long spaceoff, int kerning) 1678\end{verbatim}\index{\verb+T1_GetMetricsInfo()+}\postcorr 1679In certain situations bounding box and width of a glyph are required both. In 1680these cases it is more convenient to call \verb+T1_GetMetricsInfo()+ which 1681returns a structure that contains all information. \verb+METRICSINFO+ is 1682defined in \verb+t1lib.h+ as: 1683\begin{verbatim} 1684typedef struct 1685{ 1686 int width; 1687 BBox bbox; 1688 int numchars; 1689 int *charpos; 1690} METRICSINFO; 1691\end{verbatim} 1692All numbers are to be interpreted in character space units --- they are 1693directly taken from AFM data. \verb+width+ is the glyph's width and 1694\verb+bbox+ its bounding box which in turn is a struct as defined some 1695paragraphs above. 1696 1697\verb+numchars+ is assigned number of characters in string. If the argument 1698\verb+len+ is different from 0, \verb+numchars+ is assigned that value. 1699 1700\verb+charpos+ is a pointer to an integer array of size \verb+numchars+ 1701allocated by \verb+T1_GetMetricsInfo()+. During execution this array is filled 1702step by step with the horizontal escapement in character space units of the 1703respective character relative to the start point of the string glyph which 1704corresponds to 0. \verb+charpos+ remains valid until 1705\verb+T1_GetMetricsInfo()+ is called the next time. The user should not 1706free this memory because this is handled automatically. 1707 1708The terms concerning the bounding box of slanted fonts mentioned under the 1709description of \verb+T1_GetCharBBox()+ apply here as well. The first and the 1710last character of \verb+string+ have to be observed spending high effort. 1711But nevertheless the correct bounding box is returned. 1712 1713\precorr 1714\begin{verbatim} 1715 int T1_GetKerning( int FontID, char char1, char char2) 1716\end{verbatim}\index{\verb+T1_GetKerning()+}\postcorr 1717This function returns the amount of kerning for the specified character 1718pair \verb+char1+ and \verb+char2+. If an extension has been specified 1719for the font (see \ref{transformations}), the amount of 1720kerning is automatically corrected using the extension factor. The 1721value returned has to be interpreted in charspace units. 1722 1723If no AFM information is available for the font in question, simply 0 1724is returned. The same applies if the font is not loaded. 1725 1726The implementation of this function requires that the kerning pairs in 1727the AFM file are sorted in alphabetical order. I am not sure 1728whether this condition is found in the specification of the AFM file 1729format. If this function doesn't work although AFM kerning data is 1730available, this might be the reason. 1731 1732\precorr 1733\begin{verbatim} 1734 int T1_QueryLigs( int FontID, char char1, 1735 char **successors, char **ligatures) 1736\end{verbatim}\index{\verb+T1_QueryLigs()+}\postcorr 1737This function implements the interface to the ligature information in 1738the AFM data. Ligatures are special character-symbols which are 1739substituted if special pairs, 1740triples or whatever groups of characters appear in a string. For example, 1741``f{}i'' is replaced with the ligature ``fi''. In this example, the ``i'' is 1742called {\em successor} and the ``fi'' is the associated ligature. 1743 1744\verb+char1+ is the character 1745which has to be checked for ligatures, i.e., the first character of a possible 1746ligature group. \verb+successors+ and \verb+ligatures+ should be addresses of 1747pointers to \verb+char+s. These pointers are modified by the 1748\verb+T1_QueryLigs()+. 1749 1750First, \verb+T1_QueryLigs()+ checks how many ligatures are defined for the 1751character given by \verb+char1+. Assuming this number is $n$, it then 1752defines memory for two arrays of type \verb+char+ with size 1753$n$. These arrays are filled with the indices of the 1754successor-characters and with 1755the indices of the associated ligatures, respectively. The current 1756encoding vector is used for this. The addresses of these two arrays 1757are written to the 1758addresses of the respective pointers \verb+successors+ and \verb+ligatures+. 1759They are thus later available to the user in order to access the memory where 1760the successor-character and ligatures are specified. The value $n$ is returned 1761in order to tell the user how many ligatures were found and to give 1762the user information about the end of the two arrays. 1763 1764If the font is not loaded or AFM data is not available, -1 is returned. 1765 1766Since this may seem to be a little complicated, here is a programming example: 1767\begin{verbatim} 1768char *succ, *lig; 1769int n_lig, i; 1770char char1='f'; 1771 1772/* Get ligature information of character 'f' in font 0: */ 1773n_lig=T1_QueryLig( 0, char1, &suc, &lig); 1774 1775/* print out indices of characters and their ligatures */ 1776for ( i=0; i<n_lig; i++;){ 1777 printf("First char: %d, + next char: %d --> ligatur: %d\n", 1778 char1, 1779 succ[i], 1780 lig[i]); 1781\end{verbatim} 1782 1783Notice that the arrays where the successor indices and the respective 1784ligature indices are stored are static in 1785\verb+T1_QueryLigs()+. Thus, they may not be freed and moreover they 1786are only valid until the next time \verb+T1_QueryLigs()+ is called. 1787 1788 1789\subsubsection{Character-Encoding Relation} 1790\label{characterencodingrelation}% 1791 1792\precorr 1793\begin{verbatim} 1794 char *T1_GetCharName( int FontID, char char1) 1795\end{verbatim}\index{\verb+T1_GetCharName()+}\postcorr 1796This function returns the name of the character indexed by \verb+char1+ 1797according to the current encoding vector. As said above, the memory where the 1798string 1799is stored is static to this function so that the user should not free the 1800returned pointer. If the font is not loaded, NULL is returned. 1801 1802\precorr 1803\begin{verbatim} 1804 int T1_GetEncodingIndex( int FontID, char *char1) 1805\end{verbatim}\index{\verb+T1_GetEncodingIndex()+}\postcorr 1806This function is the complement to the above function. It returns the lowest 1807index of the character with the specified name in the current encoding vector 1808as an \verb+int+. If the charactername is not found in the current encoding 1809vector or if the font is not loaded, the value -1 is returned. 1810 1811\precorr 1812\begin{verbatim} 1813 int *T1_GetEncodingIndices( int FontID, char *char1) 1814\end{verbatim}\index{\verb+T1_GetEncodingIndices()+}\postcorr 1815This function is an extension of the above function. It is meant for cases 1816where all appearences of \verb+char1+ in the encoding vector are requested. 1817The return value is an integer array whose elements contain the encoding 1818indices where \verb+char1+ appears in increasing order. The first negative 1819entry in this array indicates that no more valid indices will follow. In the 1820most extreme case we can think of (i.e., where the complete encoding vector is 1821occupied by {\em one} character), \verb+T1_GetEncodingIndices()+ will return 1822an array of size 257 where the first 256 elements bear their own index and the 1823257th element is $-1$. If font \verb+FontID+ is not loaded, this function 1824returns \verb+NULL+ and \verb+T1_errno+ will be set appropriately. If 1825\verb+char1+ was not found in the encoding vector, a valid array is returned 1826but the first element will be $-1$. 1827 1828 1829\precorr 1830\begin{verbatim} 1831 char **T1_GetAllCharNames( int FontID) 1832\end{verbatim}\index{\verb+T1_GetAllCharNames()+}\postcorr 1833As described in \ref{encoding}, not all characters of a font need to be 1834encoded. A Type 1 may contain the outlines of an arbitrary number of 1835characters, but only 256 can be encoded---and thus 1836accessed---simultaneously. Since the characternames are inside the encrypted 1837portion of 1838the Type 1 font file, there is no easy way to find out which characters a font 1839defines. 1840 1841\tonelib\ provides \verb+T1_GetAllCharNames()+ for situations where a 1842programmer needs to know what characters are defined in the font file 1843identified by \verb+FontID+. The value returned is a pointer to an array of 1844\verb+char+ pointers which in turn point to the characternames. 1845The array's size is $(n+1)$ where $n$ is the number of defined outlines. The 1846$(n+1$)th pointer is \verb+NULL+ to indicate the end of the array. 1847An application programmer may use these characternames to construct a 1848specialized encoding vector. Here is an example of how to use 1849\verb+T1_GetAllCharNames()+. It prints a list of all defined characternames in 1850font 0. 1851\begin{verbatim} 1852 char **ptr; 1853 int i; 1854 . 1855 . 1856 . 1857 ptr=T1_GetAllCharNames( 0); 1858 i=0; 1859 while (ptr[i]!=NULL){ 1860 printf("Charstring %d = %s\n", i, ptr[i]); 1861 i++; 1862 } 1863\end{verbatim} 1864 1865The memory for storing the pointers and the charactername strings is static in\\ 1866\verb+T1_GetAllCharNames()+. Thus it remains valid until the function is 1867called the next time. The user should not free this memory or if he does, he 1868should set the pointer to \verb+NULL+ to indicate the memory has already been 1869freed. 1870 1871\precorr 1872\begin{verbatim} 1873 int T1_GetNoKernPairs( int FontID) 1874\end{verbatim}\index{\verb+T1_GetNoKernPairs()+}\postcorr 1875This function returns the number of kerning pairs defined for the font 1876identified by \verb+FontID+. The number -1 is returned if an error occured and 1877\verb+T1_errno+ will be set. All positive numbers including 0 should be 1878considered valid return values. 1879 1880 1881\subsubsection{Administrative Information} 1882\label{administrativeinformation}% 1883 1884 1885\precorr 1886\begin{verbatim} 1887 int T1_GetNoFonts( void) 1888\end{verbatim}\index{\verb+T1_GetNoFonts()+}\postcorr 1889Usually, this function returns the number of fonts declared in the font 1890database file, i.e., the integer quantity from the first line of the font 1891database file. However, if some new fonts have been created using 1892\verb+T1_CopyFont()+ (see \ref{logicalfonts}) or if some fonts have 1893been added to the database 1894after initialization (see \ref{addingfonts}), these are also taken into 1895account. The number returned by \verb+T1_GetNoFonts()+ minus 1 1896is thus the largest valid font ID specification. 1897 1898\precorr 1899\begin{verbatim} 1900 int T1_CheckForInit( void) 1901\end{verbatim}\index{\verb+T1_CheckForInit()+}\postcorr 1902Use this function in order to check whether \tonelib\ is initialized. It 1903returns $0$ if initialization has already happened and $-1$ otherwise. 1904 1905\precorr 1906\begin{verbatim} 1907 int T1_CheckForFontID( int FontID) 1908\end{verbatim}\index{\verb+T1_CheckForFontID()+}\postcorr 1909This functions gives information on the load status of the font associated to 1910\verb+FontID+. It returns $0$ if the font \verb+FontID+ has not yet been loaded, 1911$1$ if it has already been loaded. Finally, a return value of $-1$ indicates 1912that either \verb+FontID+ is an invalid specification or \tonelib\ is not 1913initialized. 1914 1915 1916\precorr 1917\begin{verbatim} 1918 char *T1_GetFontFileName( int FontID) 1919\end{verbatim}\index{\verb+T1_GetFontFileName()+}\postcorr 1920This function returns a pointer to the fontfilename identified by 1921\verb+FontID+. In no case, this pointer may be freed since the memory is 1922static to this function. The string also is only valid up to the next call of 1923this function. 1924 1925\precorr 1926\begin{verbatim} 1927 char *T1_GetFontFilePath( int FontID) 1928\end{verbatim}\index{\verb+T1_GetFontFilePath()+}\postcorr 1929This function returns a pointer to the fully qualified path of the font file 1930identified by \verb+FontID+. In no case, this pointer may be freed since the 1931memory is static to this function. The string also is only valid up to the 1932next call of this function. 1933 1934\precorr 1935\begin{verbatim} 1936 char *T1_GetAFMFilePath( int FontID) 1937\end{verbatim}\index{\verb+T1_GetAFMFilePath()+}\postcorr 1938This function returns a pointer to the fully qualified path of the AFM file of 1939the font identified by \verb+FontID+, as used by \tonelib. In case of an error 1940\verb+NULL+ is returned. It may also happen that there exists no AFM file for 1941the font either because AFM information was generated on the fly at the time 1942the font was loaded, or because AFM processing had been disabled at 1943initialization time. For those cases \verb+T1_errno+ is not set. 1944 1945In no case, the returned pointer may be freed since the memory is static to 1946this function. The string also is only valid up to the next call of this 1947function. 1948 1949\precorr 1950\begin{verbatim} 1951 char *T1_GetLibIdent( void) 1952\end{verbatim}\index{\verb+T1_GetLibIdent()+}\postcorr 1953This function returns the identifier string for the version of \tonelib. For 1954example, this could be \verb+0.8-beta+. The string is static in this function 1955and should thus not be freed by the user. 1956 1957 1958\subsection{Transformation of Fonts} 1959\label{transformations}% 1960Transformation of 1961Type 1 fonts is generally accomplished by means of concatenating 1962so-called transformation matrices. For example, rotation is 1963equivalent to concatenation of 1964the standard transformation matrix with a special matrix whose elements are 1965trigonometric functions evaluated at the rotation angle. In the sense of 1966\tonelib, we distinguish between {\em fontlevel transformations} and {\em 1967 characterlevel transformations}. 1968 1969\subsubsection{Fontlevel Transformations} 1970\tonelib\ supports three transformations that operate globally on a font's data. 1971After applying such a transformation to a font all characters generated from 1972then on will be rendered according to that transformation. Moreover, these 1973transformed characters are saved in cache for fast future access. This 1974principle is thus meant for transformed fonts which are semantically used as 1975ordinary text fonts. Creating a font Times-Oblique by slanting a Times-Roman 1976would be a typical example. 1977 1978The first fontlevel transformation is called ``extension'' since it extents a font 1979horizontally---makes its characters wider. A font is extended by a call to the 1980function 1981\precorr 1982\begin{verbatim} 1983 int T1_ExtendFont( int FontID, double extend) 1984\end{verbatim}\index{\verb+T1_ExtendFont()+}\postcorr 1985A font that is to be extended may not have size dependent data. If size 1986dependent data exists, it must 1987explicitly be removed before applying an extension-factor. This is simply a 1988security mechanism which prevents the user from mixing up extended and 1989non-extended bitmaps. If the font is not loaded or size-dependent data is 1990existent, -1 is returned. Otherwise, the function returns 0. 1991 1992All information on character metrics is automatically adapted to an 1993extension-factor different from 1 (see \ref{common}). 1994 1995Applying an extension-factor to a font is implemented by replacing the current 1996extension-factor---initially 1---with the supplied value. Thus, an extension 1997can be deleted by specifying a factor 1. Moreover, extending a font two 1998times, say, with factor 2, does not yield a font extended by 4. Rather the 1999last specified extension, here 2, is applied. 2000 2001The second type of fontlevel transformation supported by \tonelib\ is {\em 2002 slanting}. It is done by a call to the function \precorr 2003\begin{verbatim} 2004 int T1_SlantFont( int FontID, double slant) 2005\end{verbatim}\index{\verb+T1_SlantFont()+}\postcorr 2006The slant-factor $s$ tells the rastering algorithm to advance the $x$-coordinate 2007of a given point by the product of $s$ with the $y$-coordinate of that 2008point. Such fonts are sometimes called {\em oblique}. Another interpretation 2009is that we state: $s=\tan(\alpha)$, where $\alpha$ is the well-known 2010italic-angle of the font. 2011 2012Just as above, no size-dependent data may be existent and the font must be 2013loaded. In that case 0 is returned, otherwise -1. 2014 2015As above, the slanting operation is implemented by {\em setting} the 2016slant-factor so that a slant may be reset by means of specifying a 2017slant-factor of 0. 2018 2019There is one thing that makes handling of slanted fonts more difficult than 2020handling of extended fonts. When 2021typesetting strings by concatenating bitmaps, exact information on character 2022metrics is necessary. By slanting a character the character's width is not 2023affected. But the bounding box is. And while extension---which means 2024strictly horizontal scaling independent of the respective 2025y-coordinate---simply leads to an extension of the bounding box, there is no 2026way to compute the 2027bounding box of a slanted character from the bounding box of the respective 2028unslanted character. Here is an example. 2029\begin{itemize} 2030\item Let the character be \verb+\+. When slanting this character with a 2031 value of 1, the resulting character will be similar to a vertical line. The 2032 bounding box will thus be small in horizontal direction. 2033\item If character is \verb+/+, the resulting slanted 2034 character will tend to be more horizontal. Thus the resulting bounding box 2035 will be much extended in horizontal direction. 2036\end{itemize} 2037In conclusion 2038we can say that the effect of slanting on the bounding box of 2039a given character depends on the shape of the character itself. 2040 2041Since version 0.3-beta the problem with the bounding box of slanted characters 2042is handled as follows. The character in question is internally rastered at 20431000 bp and the bounding box of the resulting ``edgelist'' is examined. But no 2044bitmap is generated for the character, this limits the computational effort. 2045However the difference in time performance between getting a bounding box from 2046a ``simple-shaped'' slanted character like ``i'' and getting a bounding box of 2047a ``complex-shaped'' character like ``Q'' is clearly noticeable. 2048 2049The positioning algorithm for string bitmaps has been slightly improved in 2050\tonelib\ V.\ 0.3-beta so that now exclusively bitmap metrics are used where 2051the bounding boxes are needed. The limitation of slanted fonts appears thus 2052only if a user explicitly requests a bounding box of a character/string in an 2053artificially slanted font. 2054 2055The third and most common type of fontlevel transformation allows arbitrary 2056linear transformations. This is done by a call to the function 2057\precorr 2058\begin{verbatim} 2059 int T1_TransformFont( int FontID, T1_TMATRIX *matrix) 2060\end{verbatim}\index{\verb+T1_TransformFont()+} 2061\postcorr 2062The transformation is specified by \verb+matrix+ (as described below). 2063This function acts by setting the font's transformation matrix to the 2064matrix pointed to by \verb+matrix+. 2065 2066As a final consequence of what has been described so far in this section it 2067turns out that \verb+T1_TransformFont()+ overrides whatever slant and extension 2068values might have been set before. Conversely, if \verb+T1_SlantFont()+ or 2069\verb+T1_ExtendFont()+ are applied to a font after a call to 2070\verb+T1_TransformFont()+, the respective values are simply overridden, there 2071will be no concatenation. In the following description of transformation 2072matrices and their usage, we will also describe how to concatenate an 2073arbitrary series of linear transformations. 2074 2075There are also functions for querying the current values of the quantities 2076described above for fontlevel transformations. 2077\precorr 2078\begin{verbatim} 2079 double T1_GetExtend( int FontID) 2080\end{verbatim}\index{\verb+T1_GetExtend()+}\postcorr 2081and 2082\precorr 2083\begin{verbatim} 2084 double T1_GetSlant( int FontID) 2085\end{verbatim}\index{\verb+T1_GetExtend()+}\postcorr 2086return the current extension and slant values. The function 2087\precorr 2088\begin{verbatim} 2089 T1_TMATRIX T1_GetTransform( int FontID) 2090\end{verbatim}\index{\verb+T1_GetTransform()+}\postcorr 2091Returns the current transformation matrix as a structure of type 2092\verb+T1_TMATRIX+ which will be described in detail in the next subsubsection. 2093 2094\subsubsection{Transformation at Rastering Time} 2095This kind of transformation is the most generic one and allows arbitrary 2096transformations. A transformation $(x',y')^T$ of a given location $(x,y)^T$ is 2097given by the following set of linear equations: 2098\begin{eqnarray*} 2099x' & = a_{11} x + a_{21} y \\ 2100y' & = a_{12} x + a_{22} y 2101\end{eqnarray*} 2102Here, the matrix 2103\begin{displaymath} 2104\mathbf{A}= 2105\left( 2106\begin{array}{cc} 2107a_{11} & a_{21} \\ 2108a_{12} & a_{22} 2109\end{array} 2110\right) 2111\end{displaymath} 2112is referred to as the {\em transformation matrix}. In \tonelib\ the following 2113type definition is used for such transformation matrices: 2114\begin{verbatim} 2115typedef struct 2116{ 2117 double cxx; /* corresponds to a11 */ 2118 double cyx; /* corresponds to a21 */ 2119 double cxy; /* corresponds to a12 */ 2120 double cyy; /* corresponds to a22 */ 2121} T1_TMATRIX; 2122\end{verbatim} 2123Each of the rastering functions expects to get a pointer to an object of type 2124\verb+T1_MATRIX+, or \verb+NULL+ if no transformation is to be applied. 2125If any transformation has been specified, the resulting glyph is never kept in 2126cache memory. Thus, if for some reason caching should be disabled for 2127non-transformed characters, simply a pointer to the 2128unity matrix 2129%$\left( 2130%\begin{array}{cc} 2131%1.0 & 0 \\ 2132%0 & 1.0 2133%\end{array} 2134%\right)$ 2135could be specified to the rastering function to achieve this. 2136 2137The user has the possibility of either allocating and creating the 2138transformation matrices by himself or to use predefined functions of 2139\tonelib. There are 8 different functions for generating transformed 2140characters. Figure \ref{figure:transformations} gives an example of each 2141function using the character ``g''. 2142 2143\begin{figure}[t] 2144\hfill 2145\includegraphics[scale=0.5]{mirrorh} 2146\hfill 2147\includegraphics[scale=0.5]{mirrorv} 2148\hfill 2149\includegraphics[scale=0.5]{shearh} 2150\hfill\break 2151\noindent\vrule width 0pt\hfill\verb+T1_MirrorHMatrix()+\hfill 2152\verb+T1_MirrorVMatrix()+\hfill 2153\verb+T1_ShearHMatrix()+\hfill\break 2154% line 2 2155\vskip0.5cm 2156\hfill 2157\includegraphics[scale=0.5]{shearv} 2158\hfill 2159\includegraphics[scale=0.5]{extenth} 2160\hfill 2161\includegraphics[scale=0.5]{extentv} 2162\hfill\break 2163\noindent\vrule width 0pt\hfill\verb+T1_ShearVMatrix()+\hfill 2164\verb+T1_ExtendHMatrix()+\hfill 2165\verb+T1_ExtendVMatrix()+\hfill\break 2166% line 3 2167\vskip0.5cm 2168\hfill 2169\includegraphics[scale=0.5]{rotate} 2170\hfill 2171\includegraphics[scale=0.5]{arbitrary} 2172\hfill\break 2173\noindent\vrule width 0pt\hfill\verb+T1_RotateMatrix()+\hfill 2174\verb+T1_TransformMatrix()+\hfill\break 2175\vskip3mm 2176\hrule\vskip3mm\small 2177\caption{\label{figure:transformations}Typical examples for the predefined 2178 functions for generating transformation matrices in \tonelib, applied to the 2179 character ``g''.} 2180\end{figure} 2181 2182Before describing each particular function we should discuss the first 2183argument because this is common to all matrix transformation functions. This 2184first argument, in case it is not \verb+NULL+, is expected to be a pointer to 2185an already existent valid \verb+T1_TMATRIX+ object. The transformation to be 2186applied is then done by multiplying the existent matrix with the new 2187matrix. In other words, the existent matrix is replaced by the concatenation of 2188the two matrices. If a \verb+NULL+ is specified as argument, the new matrix is 2189allocated by the respective function and then set to the concatenation of the 2190unity matrix with the desired transformation. Thus, to remove a matrix from 2191memory, the pointer simply has to be given to \verb+free()+, no matter how 2192many transformations have been applied to this matrix before. 2193 2194We should now describe the functions for generating transformation matrices: 2195\precorr 2196\begin{verbatim} 2197 T1_TMATRIX *T1_MirrorHMatrix( T1_TMATRIX *matrix) 2198\end{verbatim}\index{\verb+T1_MirrorHMatrix()+}\postcorr 2199and 2200\precorr 2201\begin{verbatim} 2202 T1_TMATRIX *T1_MirrorVMatrix( T1_TMATRIX *matrix) 2203\end{verbatim}\index{\verb+T1_MirrorVMatrix()+}\postcorr 2204simply change the sign of the matrix coefficients $a_{11}$ and $a_{22}$ 2205respectively. This has the optical effect of mirroring the character at the 2206horizontal line $y=0$ or at the vertical line $x=0$, respectively. These 2207functions represent a specialized form of 2208\precorr 2209\begin{verbatim} 2210 T1_TMATRIX *T1_ExtendHMatrix( T1_TMATRIX *matrix, float extent) 2211\end{verbatim}\index{\verb+T1_ExtendHMatrix()+}\postcorr 2212and 2213\precorr 2214\begin{verbatim} 2215 T1_TMATRIX *T1_ExtendVMatrix( T1_TMATRIX *matrix, float extent) 2216\end{verbatim}\index{\verb+T1_ExtendVMatrix()+}\postcorr 2217These functions allow arbitrary scaling in the respective coordinate 2218direction. Specifying \\ 2219\verb+extent=-1+ exactly yields mirroring at the 2220corresponding axis. 2221 2222Furthermore, there are two transformations where one coordinate depends on 2223itself and on the other coordinate. This is called shearing, slanting or also 2224obliqueing. It is possible in both directions using the functions 2225\precorr 2226\begin{verbatim} 2227 T1_TMATRIX *T1_ShearHMatrix( T1_TMATRIX *matrix, float shear) 2228\end{verbatim}\index{\verb+T1_ShearHMatrix()+}\postcorr 2229and 2230\precorr 2231\begin{verbatim} 2232 T1_TMATRIX *T1_ShearVMatrix( T1_TMATRIX *matrix, float shear) 2233\end{verbatim}\index{\verb+T1_ShearVMatrix()+}\postcorr 2234In case of horizontal shearing, the factor \verb+shear+ is equal to 2235$\tan(\alpha)$, where $\alpha$ may be interpreted as the italic angle. It is 2236measured from the positive vertical axis in mathematical negative direction. 2237Correspondingly, for vertical shearing \verb+shear+ equals $\tan(\beta)$, 2238where $\beta$ is the angle measured from the horizontal axis in mathematically 2239positive direction. 2240 2241Rotation of glyphs is achieved using 2242\precorr 2243\begin{verbatim} 2244 T1_TMATRIX *T1_RotateMatrix( T1_TMATRIX *matrix, float angle) 2245\end{verbatim}\index{\verb+T1_RotateMatrix()+}\postcorr 2246This function evaluates the trigonometric functions at the value of 2247\verb+angle+ and concatenates the transformation matrix with 2248\begin{displaymath} 2249\left( 2250\begin{array}{cc} 2251\cos(\alpha) & -\sin(\alpha) \\ 2252\sin(\alpha) & \cos(\alpha) 2253\end{array} 2254\right) 2255\end{displaymath} 2256$\alpha$ is expected to be specified in degrees. It is measured according 2257standard mathematical conventions. 2258 2259There is one more function which allows to set all matrix coefficients 2260explicitly. It gives thus complete control over the transformation. This might 2261be necessary to typeset text in a circle, for example. The syntax of this 2262function is 2263\precorr 2264\begin{verbatim} 2265 T1_TMATRIX *T1_TransformMatrix( T1_TMATRIX *matrix, 2266 float cxx, float cyx, 2267 float cxy, float cyy) 2268\end{verbatim}\index{\verb+T1_TransformMatrix()+}\postcorr 2269 2270\subsubsection{{\tt t1lib} and PostScript: Notes on Transformation Matrices} 2271In order to avoid confusion about transformation matrices, we should briefly 2272discuss the differences between \tonelib- and PostScript transformation 2273matrices. In \tonelib-nomenclature a coordinate description is assumed to be 2274represented by a column vector $(x,y)^T$. In contrast, PostScript assumes a 2275coordinate to be represented by a row vector $(x,y)$. This leads to an 2276exchanged meaning of the second and third matrix element between \tonelib\ and 2277PostScript. From the mathematical point of view this is caused by matrix 2278transposition. To make this clear, let me quote the matrix 2279\begin{displaymath} 2280\mathbf{A}_{\mbox{\footnotesize PostScript}}= 2281\left( 2282\begin{array}{ccc} 2283a & b & 0\\ 2284c & d & 0\\ 2285t_x & t_y & 1 2286\end{array} 2287\right) 2288\end{displaymath} 2289from the PostScript Language Reference Manual (Adobe, Red Book). If we forget 2290about translation which in this sense is not implemented by \tonelib, we only 2291have to consider the top left submatrix consisting of $a$, $b$, $c$ and $d$. 2292The \tonelib-equivalent to this matrix would be written as 2293\begin{displaymath} 2294\mathbf{A}_{\mbox{\tt\footnotesize t1lib}}= 2295\left( 2296\begin{array}{cc} 2297a & c \\ 2298b & d \\ 2299\end{array} 2300\right) 2301\end{displaymath} 2302I.e., the meaning of $b$ and $c$ is exchanged. Notice that font matrices as 2303found in Type 1 font files have to be interpreted according to the PostScript 2304notation. But a user should never come close to something other than the 2305\tonelib\ transformation matrices 2306 2307 2308\subsection{Stroking of Character Outlines} 2309\label{stroking}% 2310Most available Type 1 fonts internally specify the numeric value 2311\verb+PaintType+ as $0$. This indicates that the mathematical outline 2312definitions of the characters consist of paths that represent the left and 2313right---or inner and outer---borders of the character area to be filled with 2314ink. In particular, this means that every subpath of a character definition 2315must be closed. When filling characters, the curves that describe the outline 2316are infinitely thin and the area between paths is of interest. 2317 2318By contrast, there are fonts that specify \verb+PaintType+ as $1$. These are 2319also known as {\em stroked fonts}. Basically, their characters' shapes are 2320generated by travelling along the mathematically thin defining curves using a 2321pen with some finite width. The penwidth used here usually is specified in the 2322font itself by means of the quantity \verb+StrokeWidth+. 2323 2324Using a somewhat unusual implementation, \tonelib\ can 2325\begin{itemize} 2326\item image stroked fonts with \verb+PaintType+ 1, 2327\item stroke fonts that have \verb+PaintType+ 0, 2328\item deal with variable strokewidths for both paint types. 2329\end{itemize} 2330In particular at low resolutions and when using large penwidths, the results 2331of stroking may fall short of the quality of other general graphics tools like 2332e.g.~native PostScript interpreters. Also hinting generally is disabled when 2333creating stroked character outlines. For the interested reader, the 2334implementation of stroking is outlined in \ref{strokingimplementation} 2335(page~\pageref{strokingimplementation}). 2336 2337The process of stroking in \tonelib\ is treated similar to the process of 2338transformation. Therefore, firstly, a font can be generally switched to be a 2339stroked font. This is achieved using 2340\precorr 2341\begin{verbatim} 2342 int T1_StrokeFont( int FontID, int dostroke) 2343\end{verbatim}\index{\verb+T1_StrokeFont()+}\postcorr 2344Here, \verb+FontID+ identifies the font to be switched. The parameter 2345\verb+dostroke+ determines the future rastering behavior. If it equals 0, the 2346font's characters will be filled and for any other value the characters will 2347be stroked. The function returns 0 in case of success. 2348\verb+T1_StrokeFont()+ requires the font \verb+FontID+ to be loaded. If the 2349font is not loaded \verb+T1_errno+ will be set appropriately and the function 2350returns -1. After switching a font to {\em stroked}, its characters are cached 2351as usual. It is therefore important that, at the time where 2352\verb+T1_StrokeFont()+ is called, no size-dependent data does exist. If this 2353condition is violated, the function will fail too and set \verb+T1_errno+ to 2354\verb+T1ERR_OP_NOT_PERMITTED+. 2355 2356The second method to control the rasterizer mode for the font \verb+FontID+ is 2357to use the function pair 2358\precorr 2359\begin{verbatim} 2360 int T1_SetStrokeFlag( int FontID) 2361\end{verbatim}\index{\verb+T1_SetStrokeFlag()+}\postcorr 2362and 2363\precorr 2364\begin{verbatim} 2365 int T1_ClearStrokeFlag( int FontID) 2366\end{verbatim}\index{\verb+T1_ClearStrokeFlag()+}\postcorr 2367for enabling and disabling stroking, respectively. These two functions return 23680 on successful completion and -1 in case of a failure. They can only fail if 2369\verb+FontID+ is not valid, in which case \verb+T1_errno+ is set to 2370\verb+T1ERR_INVALID_FONTID+. Using these functions, switching the stroking is 2371hence possible at any time. The netto effect is that caching will be disabled 2372if the actually selected rasterizer mode does not match the one of the cached 2373characters. The performance then will degrade for the rasterizer mode that is 2374not the base mode of the font in question. 2375 2376If stroked characters and filled characters are required for one particular 2377font while preserving good performance, using logical fonts is the tool of 2378choice (see Sec.~\ref{logicalfonts}, page~\pageref{logicalfonts}). 2379 2380The currently active rasterizer mode for the font \verb+FontID+ can also be 2381queried. This is done using 2382\precorr 2383\begin{verbatim} 2384 int T1_GetStrokeMode( int FontID) 2385\end{verbatim}\index{\verb+T1_GetStrokeMode()+}\postcorr 2386If \verb+FontID+ is not valid, $-1$ is returned and \verb+T1_errno+ is set to 2387\verb+T1ERR_INVALID_FONTID+. In any other case, the following values may be 2388returned: 2389\begin{itemize} 2390\item \verb+0+: The rasterizer mode is {\em Fill} and filled characters are 2391 cached. For stroked fonts with a \verb+PaintType+ of $1$, of course, the 2392 characters are stroked and these stroked characters are cached anyhow. 2393\item \verb+1+: Stroking is enabled, while filled characters are cached. Each 2394 rasterization request is performed on the fly, as for nontrivial 2395 transformations. 2396\item \verb+2+: Filling is enabled but stroked characters are 2397 cached. Rasterization again is performed on the fly. 2398\item \verb+3+: Stroking is enabled and stroked characters are cached. 2399\end{itemize} 2400 2401The width of the virtual pen used to trace the character outlines can also be 2402adjusted. The function 2403\precorr 2404\begin{verbatim} 2405 int T1_SetStrokeWidth( int FontID, float strokewidth) 2406\end{verbatim}\index{\verb+T1_SetStrokeWidth()+}\postcorr 2407sets up \verb+strokewidth+ as the pen width used to stroke characters from 2408font \verb+FontID+. It is interpreted in charspace units and hence directly 2409comparable to the \verb+StrokeWidth+ parameter of stroked fonts. 2410If this function succeeds, $0$ is returned. The function call might 2411also be unsuccessful, in which case $-1$ is returned. The value of 2412\verb+T1_errno+ then gives a hint to the reason of the failure. If set to 2413\verb+T1ERR_INVALID_FONTID+, the font was not loaded. The value 2414\verb+T1ERR_INVALID_PARAMETER+ indicates that a negative strokewidths has 2415been specified. Finally, \verb+T1ERR_OP_NOT_PERMITTED+ may appear if stroked 2416characters are cached for the font in question, size dependent data exists, 2417and the requested strokewidth did not equal the one used at the time where 2418the cache data initially has been built. Allowing to setup an arbitrary 2419strokewidth under the latter circumstances might fillup the cache for one font 2420with characters rasterized using inconsistent strokewidths, which has to be 2421avoided. From this discussion it becomes suggesting not to cache stroked 2422character at all, if stroking should be done using variable strokewidths. 2423 2424The pen width for a given font \verb+FontID+ may be queried at any time using 2425\precorr 2426\begin{verbatim} 2427 float T1_GetStrokeWidth( int FontID) 2428\end{verbatim}\index{\verb+T1_GetStrokeWidth()+}\postcorr 2429If the value $0.0$ is returned, this either indicates that the characters are 2430filled or that the font in question is not loaded. Then, \verb+T1_errno+ is 2431also set to \verb+T1ERR_INVALID_FONTID+. 2432 2433 2434\subsection{Antialiasing} 2435\label{antialiasing}% 2436\subsubsection{General Description} 2437When fonts are displayed on screen at low sizes, the shapes of characters often 2438get damaged because of rounding errors---a pixel can generally present two 2439states: painted or non-painted. But the human eye can be fooled in a 2440way that it 2441``thinks'' sub-pixel accuracy is given on the screen. This is done by 2442considering which pixels are filled with ink to what degree and 2443giving the 2444physical pixel an appropriate shade of gray. For example, a pixel whose area 2445would be covered 50\% would get a 50\% gray shade. This technique is called 2446{\em antialiasing}. 2447 2448There are several ways to implement antialiasing. \tonelib\ implements 2449antialiasing by internally generating a bitmap larger than needed 2450and then subsampling. Depending on the subsampling factor which may be 2 or 4, 2451this principle yields glyphs with 24525 or 17 shades of gray including black and white. 2453 2454There are three functions for generating antialiased glyphs: 2455\precorr 2456\begin{verbatim} 2457 GLYPH *T1_AASetChar( int FontID, char charcode, 2458 float size, T1_TMATRIX *transform) 2459\end{verbatim}\index{\verb+T1_AASetChar()+}\postcorr 2460\precorr 2461\begin{verbatim} 2462 GLYPH *T1_AASetString( int FontID, char *string, int len, 2463 long spaceoff, int modflag, 2464 float size, T1_TMATRIX *transform) 2465\end{verbatim}\index{\verb+T1_AASetString()+}\postcorr 2466\precorr 2467\begin{verbatim} 2468 GLYPH* T1_AASetRect( int FontID, float size, 2469 float width, float height, 2470 T1_TMATRIX *transform) 2471\end{verbatim}\index{\verb+T1_AASetRect()+}\postcorr 2472Note the ``\verb+AA+'' in the functions names which stand for 2473\underline{A}nti\underline{A}liasing. The usage is identical to the usage of 2474the functions \verb+T1_SetChar()+, \verb+T1_SetString()+ and 2475\verb+T1_SetRect()+. So see \ref{generatingbitmaps} for an explanation of the 2476arguments and their interpretation. 2477 2478When an antialiased glyph is requested, the supplied \verb+size+-value is 2479multiplied by the current subsampling factor. For now, let us assume it is 2. 2480Then the respective function for generating non-antialiased glyphs 2481is called with all other arguments unchanged. The result is a bitmap twice as 2482high and twice as wide as the user requested. Now, a $2\times2$ mask is moved 2483over this bitmap and the number of painted pixels in this mask is considered 2484at each place. According to the number of painted pixels one of 5 different 2485gray shades is assigned to the resulting pixel. Since the mask is moved with 2486an increment of 2 pixels in horizontal and vertical direction, the bitmap is 2487at the same time subsampled by 2. Thus, the resulting bitmap is just of the 2488size the user requested and its pixels each contain one of 5 gray shades. 2489 2490Conceptually, the same applies for subsampling with 4. In this case the mask is 2491of size $4\times4$ and there will be 17 distinct gray shades including black 2492and white. The computational effort is considerably larger so that 4 $\times$ 2493subsampling should only be used for very small sizes. 2494 2495When moving the mask over double-sized bitmap it is aligned properly with 2496respect to the characters' baseline (zero height) rather than with the 2497characters' top or bottom line. This principle ensures, that the most important 2498visual guideline in running text, the baseline, is represented in a consistent 2499manor. This is especially important if one is using a serif-font. 2500Thanks to Raph Levien, the algorithm described above in a verbose manor has 2501been replaced by a much 2502faster lookup-algorithm in \tonelib\ V.\ 0.4-beta. 2503 2504\subsubsection{Setting Operating Parameters} 2505Applications can use both $2\times$ and $4\times$ antialiasing arbitrary 2506mixed. Switching between the two modes is achieved using 2507\precorr 2508\begin{verbatim} 2509 int T1_AASetLevel( int level) 2510\end{verbatim}\index{\verb+T1_AASetLevel()+}\postcorr 2511The argument \verb+level+ should be either \verb+T1_AA_LOW+ ($=2$) or 2512\verb+T1_AA_HIGH+ ($=4$). Any other values are ignored and \verb+T1_errno+ is 2513set appropriately. This function is to be called after initialization. The 2514default value after initialization is \verb+T1_AA_LOW+. The current value can 2515also be queried by issuing a call to 2516\precorr 2517\begin{verbatim} 2518 int T1_AAGetLevel( void) 2519\end{verbatim}\index{\verb+T1_AASetLevel()+}\postcorr 2520The returned value is current level. Switching between the two antialiasing 2521modes should be quite fast since apart from a little error checking 2522essentially only one simple variable is set. 2523 2524There is one more value that may be specified for \verb+level+, namely 2525\verb+T1_AA_NONE+. \verb+T1_AA_NONE+ is identical to 1 which means that no 2526subsampling at all is done. But the resulting glyph, having only fore- and 2527background colors is returned as a bytemap instead of as a bitmap. This is 2528intended for situtations where an antialiased glyph should be concatenated 2529with a (possibly large) non-antialiased glyph using the function 2530\verb+T1_ConcatGlyphs()+. In that case, the depths of the two glyphs have to 2531be identical. There is probably not much more sense in setting \verb+level+ to 2532\verb+T1_AA_NONE+. 2533 2534As described before, the result of the \verb+T1_AASet..()+ functions is 2535strictly spoken no longer a 2536bitmap since more than one bit is used to 2537represent one pixel. The function 2538\precorr 2539\begin{verbatim} 2540 int T1_AASetBitsPerPixel( int bpp) 2541\end{verbatim}\index{\verb+T1_AASetBitsPerPixel()+}\postcorr 2542allows the user to specify how many bits should be used to represent one 2543pixel. Allowed values for \verb+bpp+ are 8, 16, 24 and 32. However, if 24 is 2544specified, internally 32 will be used since the pixel are then addressed as 2545objects of type \verb+long+. Antialiased glyphs may grow quite large, 2546especially when 2547using \verb+bpp+ = 32. The value of \verb+bpp+ is written into the member 2548\verb+bpp+ of the \verb+glyph+-structure (see \ref{generatingbitmaps} on page 2549\pageref{generatingbitmaps}). That way a user can check whether a 2550glyph is antialiased or not. It is possible to work with antialiased 2551and non-antialiased glyphs at the same time. 2552It is also possible to directly query the value of bits per pixel by using 2553\precorr 2554\begin{verbatim} 2555 int T1_AAGetBitsPerPixel( void) 2556\end{verbatim}\index{\verb+T1_AAGetBitsPerPixel()+}\postcorr 2557The value returned is the number of bits per pixel used. 2558 2559In order to make the handling of antialiased glyphs as flexible as possible, 2560the values to be written into the pixels for different gray values 2561may (and must) be explicitly specified. For low level antialiasing this is 2562done by calling the function 2563\precorr 2564\begin{verbatim} 2565 int T1_AASetGrayValues( unsigned long white, 2566 unsigned long gray75, 2567 unsigned long gray50, 2568 unsigned long gray25, 2569 unsigned long black) 2570\end{verbatim}\index{\verb+T1_AASetGrayValues()+}\postcorr 2571For lower \verb+bpp+ values only the lower bits are used. For high level 2572antialiasing this kind of graylevel specification is not economical since 17 2573arguments 2574would have to be specified. Instead, another function is used which expects a 2575pointer an array of \verb+unsigned long+'s: 2576\precorr 2577\begin{verbatim} 2578 int T1_AAHSetGrayValues( unsigned long *grayvals) 2579\end{verbatim}\index{\verb+T1_AAHSetGrayValues()+}\postcorr 2580The array \verb+grayvals+ points to must contain 17 entries. Element 0 is 2581expected to specify the background color's pixel value and element 16 2582represents the foreground color. Calling one of these two functions involves 2583also a new setup of the lookup tables. It should thus only be done if some 2584color value really has changed. 2585 2586In case the antialiasing level is set to \verb+T1_AA_NONE+ as described 2587above, the function 2588\precorr 2589\begin{verbatim} 2590 int T1_AANSetGrayValues( unsigned long bg, unsigned long fg) 2591\end{verbatim}\index{\verb+T1_AANSetGrayValues()+}\postcorr 2592must be used to set foreground and background color. In conclusion, it turns 2593out that each antialiasing level has its own lookup tables which have to be 2594initialized as soon as either foreground color, background color or both have 2595changed. 2596 2597Each of the three graylevel sets described above can also be queried by the 2598user. This is done using one of the functions 2599\precorr 2600\begin{verbatim} 2601 int T1_AAGetGrayValues( long *pgrayvals) 2602\end{verbatim}\index{\verb+T1_AAGetGrayValues()+}\postcorr 2603\precorr 2604\begin{verbatim} 2605 int T1_AAHGetGrayValues( long *pgrayvals) 2606\end{verbatim}\index{\verb+T1_AAHGetGrayValues()+}\postcorr 2607\precorr 2608\begin{verbatim} 2609 int T1_AANGetGrayValues( long *pgrayvals) 2610\end{verbatim}\index{\verb+T1_AANGetGrayValues()+}\postcorr 2611Here, \verb+pgrayvals+ is the start address of an array of \verb+long+-values 2612to which the respective grayvalues are written. This memory must thus be 2613supplied by the user. These functions will write 5 2614(\verb+T1_AAGetGrayValues+), 17 (\verb+T1_AAHGetGrayValues+) and 2 2615(\verb+T1_AANGetGrayValues+) respectively to the location given by 2616\verb+pgrayvals+. These functions are to be called after initialization. If 2617something goes wrong -1 is returned and \verb+T1_errno+ will be set 2618accordingly. Otherwise 0 is returned. 2619 2620 2621\subsubsection{Smart Antialiasing} 2622\label{smartantialiasing}% 2623Antialiasing improves legibility for small sizes but is not that much useful 2624for large sizes. To make a compromise between computation time, system 2625resources and optical appearance it might be advantageous to use 2626\verb+T1_AA_HIGH+ for small sizes, \verb+T1_AA_LOW+ for medium sizes and 2627\verb+T1_AA_NONE+ for large sizes. Of course, for large sizes the 2628non-antialiasing functions could be used which still need less resources. 2629 2630In order to free the user from having to switch the antialiasing level explicitly, 2631\tonelib\ can be told to do this switching 2632automatically, depending on the size requested. This is called {\em Smart 2633 Antialiasing}. It is disabled by default and can be toggled by a call to 2634\precorr 2635\begin{verbatim} 2636 int T1_AASetSmartMode( int smart) 2637\end{verbatim}\index{\verb+T1_AASetSmartMode()+}\postcorr 2638The quantity \verb+smart+ should be either be \verb+T1_YES+ (which corresponds 2639to 1) or \verb+T1_NO+ (which corresponds to 0. Notice that the current 2640antialiasing level as set by \verb+T1_AASetLevel()+ is not affected by 2641this. After having switched off smart antialiasing the former antialiasing 2642level is restored. When smart antialiasing is active still has to take care 2643for setting the lookup tables after a color change has happened. 2644 2645The numerical limits of the requested size at which \tonelib\ will switch 2646between the different antialiasing levels may be specified using 2647\precorr 2648\begin{verbatim} 2649 int T1_AASetSmartLimits( float limit1, float limit2) 2650\end{verbatim}\index{\verb+T1_AASetSmartLimits()+}\postcorr 2651Here, \verb+limit1+ is the value of size at which \tonelib\ switches from 2652\verb+T1_AA_HIGH+ to \verb+T1_AA_LOW+ and \verb+limit2+ is the value of size 2653at which \tonelib\ switches from \verb+T1_AA_LOW+ to \verb+T1_AA_NONE+. The 2654default values are 20.0 for \verb+limit1+ and 60.0 for \verb+limit2+. This 2655means for sizes smaller than 20.0 \verb+T1_AA_HIGH+ will be used and for sizes 2656equal to or greater than 60.0 \verb+T1_AA_NONE+ will be used. The intermediate 2657range is covered by \verb+T1_AA_LOW+. These values are suitable for 2658applications that display on screen when the device resolution has been left 2659at the default value of 72 dpi. 2660 2661 2662\subsubsection{Caching of Antialiased Character Glyphs} 2663\label{aacaching}% 2664Generally, antialiased glyphs are not cached in \tonelib\ because this 2665involves several problems which are hardly to solve. One main problem is shown 2666in figure \ref{figure:subpixelpositioning}. 2667\begin{figure} 2668\centerline{\includegraphics[scale=10]{Tee}}\relax 2669\vskip3mm 2670\hrule\vskip3mm\small 2671\caption{\label{figure:subpixelpositioning} The string ``Tee'' (which is the 2672 German word for ``tea'') rastered at 13~bp, using $4\times$ antialiasing. 2673 Notice the different representations of the character ``e''.} 2674\end{figure} 2675Obviously the character ``e'' appears twice in different representations. This 2676is intentional and is referred to as sub pixel positioning. In the left ``e'' 2677the letter is perceived somewhat more to the left with respect to the pixels 2678that represent the character. Conversely, the second ``e'' seems to lie 2679somewhat more to the right within the pixels. The advantage of this technique 2680is that characters can be shifted by some fractional amount of a pixel at low 2681sizes.\footnote{The opinions whether this and antialiasing in general is of 2682 advantage for readability vary, so please consider this the opinion of the 2683 author. } On the other hand the problem is introduced that each character 2684can have more than one representation in graylevels, depending on how much 2685subpixel shift is needed. 2686 2687One further problem caused by subsampling is that certain information is 2688irreversibly lost in the graylevel representation. For example, if you have a 2689graylevel pixel of intensity 50\% (whatever the real color is), then, in case 2690of $2\times$ antialiasing, you will know that in the $2\times 2$ input bitmap 2691two pixels had been set to foreground, but you would not know {\em which} two 2692these had been. But this information is important for concatenating and 2693blitting of antialiased bitmaps: it may well happen that two pixels with 50\% 2694gray that lie over each other had to produce an output pixel of 50\%, 75\% 2695or 100\% gray (where 100\% gray means full foreground intensity). 2696 2697To avoid these problems, \tonelib\ generally does not cache antialiased 2698glyphs. Instead, it works on true bitmaps which are then subsampled at the 2699last possible stage to an antialiased glyph. Applications that do not use 2700anything more than the functions that yield char bitmaps or bytemaps, could 2701profit from caching of antialiased characters. Such applications could specify 2702\verb+T1_AA_CACHING+ as an additional ingredient to the \verb+log+ argument of 2703the function \verb+T1_InitLib()+ which initializes \tonelib. This is done by 2704OR'ing the value of \verb+log+ with \verb+T1_AA_CACHING+ as described in 2705\ref{initialization}. If this flag had been specified at initialization time, 2706\verb+T1_AASetChar()+ will cache the bytemaps it has generated and will take 2707them from cache in future requests. 2708 2709When caching antialiased glyphs, each size gets up to four distinct cache 2710areas, one for bitmaps and one for $1\times$, $2\times$ and $4\times$ subsampled 2711bytemaps each. As soon as a string-generating function is called these cached 2712antialiased glyphs cannot be used for the reasons discussed before. The 2713developer of an application should thus carefully think about whether 2714a possibly marginal performance gain is really worth this much higher 2715effort. If in doubt, simply check it out. Applications like \verb+xdvi+ which 2716place isolated character glyphs on a sheet could use this feature, however, and 2717profit from it. 2718 2719 2720\subsection{Interface to Outlines} 2721\label{outlines}% 2722Although \tonelib\ is meant for generating bitmaps from Type 1 outline fonts, 2723there is a set of functions for accessing outline data. 2724There are several reasons for this. Firstly, outline 2725descriptions are, within the given arithmetic constraints, mathematically exact. 2726Secondly and related to the previous point, in certain cases where exact 2727subpixel positioning is needed, the functionality of grid-fitting before 2728rasterization is needed. This can only be done accurately based on 2729outlines. To illustrate this, consider figure \ref{figure:whyoutlines}. 2730% -parameters for this figure: size 50.0 2731% angle 35 2732% arg: --checkConcat[Glyphs|Outlines] 2733% 2734\begin{figure}[t] 2735\hfill 2736a) \includegraphics[scale=1.0]{concatglyphs} 2737\hfill 2738b) \includegraphics[scale=1.0]{concatoutlines} 2739\hfill\break 2740\vskip3mm 2741\hrule\vskip3mm\small 2742\caption{\label{figure:whyoutlines}Two concatenated bitmaps, a) concatenation 2743 done based on bitmaps by blitting and b) based on outlines and then filled.} 2744\end{figure} 2745When looking at the concatenated glyph a), it appears that the underline rule 2746has a small step where the two words touch.\footnote{Depending on the 2747 resolution and quality of the hardcopy you are reading, the effect might be 2748 hardly or not all noticeable.} The reason is, that the second part of the 2749glyph had been rastered with respect to a pixel coordinate of exactly $(0,0)$. 2750Since the start of the second word in the resulting glyph does not exactly 2751fall on an integer pixel location, bitmap blitting causes an artifact in the 2752visual line of the underlining rule. Strings rotated at angles that are not 2753multiples of $90^\circ$ are prone to produce such effects. In contrast the 2754concatenated glyph b) does not show such effects because both partial glyphs 2755are placed mathematically exact and then filled. Thirdly, if the outline of a 2756character is available, it can be used for whatever. For example, the outline 2757can be filled by another rasterizer, it can by altered, it can be stroked and 2758so on. \tonelib\ makes outlines as they are internally used by the rasterizer 2759available. We will discuss how to interprete and access outlines in the 2760remainder of this section. 2761\subsubsection{Outline Format} 2762\label{outlineformat}% 2763Before going into implementation details the general structure of a Type 1 2764outline is described. We will consider the simple fictive character whose 2765outline is shown in figure \ref{figure:generaloutline}. 2766\begin{figure}[t] 2767\hfill 2768\includegraphics[scale=1.0]{outlines} 2769\hfill\break 2770\vskip3mm 2771\hrule\vskip3mm\small 2772\caption{\label{figure:generaloutline}The outline of a fictive character.} 2773\end{figure} 2774We assume that scaling, grid fitting and hinting has already been carried out. 2775Then, the outline is given by set of points $P_i$ and segments connecting those 2776points. There are: 2777\begin{itemize} 2778\item Move-segments (type = \verb+T1_PATHTYPE_MOVE+): These are straight 2779 segments which cause the current position to be displaced by some offset. 2780 Since the starting point of a segment is always implicitly the current 2781 point, only one argument is needed, $P_{dest}$, the destination point. In 2782 the figure, $P_1$--$P_2$ and $P_{2}$--$P_{12}$ are Move-segments. In this 2783 simple case they displace from the characters origin to some starting point 2784 of the outline and from the ending point of the outline to the point where 2785 the next character would have to be placed (the horizontal escapement). 2786\item Line-segments (type = \verb+T1_PATHTYPE_LINE+): These are part of the 2787 path to be filled later. In analogy to the Move-segment, one argument, 2788 $P_{dest}$, is required for Line-segments. In the figure, $P_{11}$--$P_2$ is 2789 a Line-segment. 2790\item Bezier-segments (type = \verb+T1_PATHTYPE_BEZIER+): These are curve 2791 segments. Their shape is defined by a starting point (always the current 2792 point here), an ending point $P_{dest}$ and two control points $P_B$, 2793 $P_C$. These four points are the parameters of what is called a third order 2794 Bezier spline.\footnote{The mathematical defining equation represents a 2795 special case of a Bernstein polynom which was exploited by {\sc Bezier} in 2796 the context of solid modeling. The curve especially has the property that 2797 it may be approximated efficiently by straight line segments in a few 2798 iterations.} The resulting curve has the following 2799 properties: 2800 \begin{itemize} 2801 \item It starts at the first point $P_{current}$. 2802 \item It ends at the fourth point $P_{dest}$. 2803 \item The line that goes through the points $P_{current}$ and $P_{B}$ is the 2804 tangent to the curve from the right side at the starting point $P_{current}$. 2805 \item In analogy, the line that goes through the points $P_{C}$ and 2806 $P_{dest}$ is the tangent to the curve from the left side at the ending 2807 point $P_{dest}$. 2808 \item The resulting curve will be enclosed completely by the convex area 2809 that is defined by connecting the definition points with straight line 2810 segments. 2811 \end{itemize} 2812 Our fictive character outline in figure \ref{figure:generaloutline} 2813 has three Bezier-segments, $P_{2}$--$P_{3}$--$P_{4}$--$P_{5}$, 2814 $P_{5}$--$P_{6}$--$P_{7}$--$P_{8}$ and 2815 $P_{8}$--$P_{9}$--$P_{10}$--$P_{11}$. Notice that it is easily possible to 2816 achieve a smooth tangent transition from one curve-segment to the next by 2817 choosing the involved points from a straight line. 2818\end{itemize} 2819For Type 1 fonts in general, the following rules for interpreting coordinate 2820specifications hold: 2821\begin{itemize} 2822\item All point specifications are relative to the {\em current 2823 point}. 2824\item For Bezier-segments, $P_{B}$, $P_{C}$ and $P_{dest}$ all are relative to 2825 $P_{current}$. 2826\item Initially, i.e. when a character outline is started, the current point 2827 is at the origin $(0,0)$ of the character. 2828\end{itemize} 2829Additionally, for this special rasterizer implementation, the following terms 2830apply: 2831\begin{itemize} 2832\item The vertical coordinate is---in contrast to PostScript---inverted, i.e., 2833 the $y$-axis points down. 2834\item Once hinted and gridfitted, the outline point coordinates are described 2835 in {\em fractional pixels}. A ``fractpel'' is of type \verb+long+ and 2836 describes the location in $2^{16}$th fractions of a pixel. To convert from 2837 pixel to fractional pixel and vice versa, the macros 2838 \verb+T1_TOPATHPOINT(p)+\index{\verb+T1_TOPATHPOINT()+} and 2839 \verb+T1_NEARESTPOINT(fp)+\index{\verb+T1_NEARESTPOINT()+} are provided. 2840\end{itemize} 2841 2842Before describing the functions for retrieving outlines the format in which 2843outlines are presented in C will be described. A point specification is done 2844in the following structure: 2845\begin{verbatim} 2846typedef struct { 2847 T1_int32 x; 2848 T1_int32 y; 2849} T1_PATHPOINT; 2850\end{verbatim} 2851\verb+x+ and \verb+y+ are fractional pixels as described above. 2852 2853An outline is represented by a linked list of structures which describe path 2854segments of the type described above. 2855Line- and Move-segments are described by the following structure: 2856\begin{verbatim} 2857typedef struct pathsegment { 2858 char type; 2859 unsigned char flag; 2860 short references; 2861 unsigned char size; 2862 unsigned char context; 2863 struct pathsegment *link; 2864 struct pathsegment *last; 2865 T1_PATHPOINT dest; 2866} T1_PATHSEGMENT; 2867\end{verbatim} 2868\verb+type+ is either \verb+T1_PATHTYPE_MOVE+ or 2869\verb+T1_PATHTYPE_LINE+. \verb+flag+, \verb+references+, \verb+size+ and 2870\verb+context+ are internally used by the rasterizer. \verb+link+ is a pointer 2871to the next segment structure or \verb+NULL+ in case it is the last structure 2872in the list. Finally, the \verb+last+-entry is a pointer to 2873the last structure in the linked list. \verb+last+ is only set in the first 2874segment and is reset to \verb+NULL+ in the remaining segment structures. 2875A Bezier-segment is described by the following structure: 2876\begin{verbatim} 2877typedef struct bezierpathsegment { 2878 char type; 2879 unsigned char flag; 2880 short references; 2881 unsigned char size; 2882 unsigned char context; 2883 T1_PATHSEGMENT *link; 2884 T1_PATHSEGMENT *last; 2885 T1_PATHPOINT dest; 2886 T1_PATHPOINT B; 2887 T1_PATHPOINT C; 2888} T1_BEZIERSEGMENT; 2889\end{verbatim} 2890Obviously, the format is identical to that for straight path segments, extended 2891by the entries \verb+B+ and \verb+C+ which specify the control points as 2892described earlier in this subsection. 2893The common return type for the outline retrieving functions is a pointer to 2894\verb+T1_OUTLINE+, which is in fact identical to \verb+T1_PATHSEGMENT+. This 2895purely for convention. Although it is quite unlikely, an outline might start 2896with a Bezier-segment. To access Bezier-segment elements, a cast must be used. 2897 2898 2899\subsubsection{Using Outlines} 2900\label{usingoutlines}% 2901\tonelib\ provides three functions for retrieving outlines. The first is 2902\precorr 2903\begin{verbatim} 2904 T1_OUTLINE *T1_GetCharOutline( int FontID, char charcode, 2905 float size, T1_TMATRIX *transform) 2906\end{verbatim}\index{\verb+T1_GetCharOutline()+}\postcorr 2907The meaning of the arguments is as in the \verb+T1_SetChar()+-function. 2908Notice that the size specification is also required here. Outlines are, by 2909their nature in Type~1, generally defined in a $1000\times 1000$ grid and then 2910scaled down by the fontmatrix to 1 bp. The space is known as the 2911charspace. The reason for specifying a size at this place, instead of scaling 2912the outline later, is, that hinting is performed according to the scaled 2913outline. The returned outline is then hinted for the given size. If necessary, 2914it may still be scaled later. 2915 2916The outline for a complete string can be retrieved by 2917\precorr 2918\begin{verbatim} 2919 T1_OUTLINE *T1_GetStringOutline( int FontID, char *string, int len, 2920 long spaceoff, int modflag, 2921 float size, T1_TMATRIX *transform) 2922\end{verbatim}\index{\verb+T1_GetStringOutline()+}\postcorr 2923The meaning of the arguments is as in \verb+T1_SetString()+. 2924 2925Finally the ``outline'' for a displacement is available by the function 2926\precorr 2927\begin{verbatim} 2928 T1_OUTLINE *T1_GetMoveOutline( int FontID, int deltax, int deltay, int modflag, 2929 float size, T1_TMATRIX *transform) 2930\end{verbatim}\index{\verb+T1_GetMoveOutline()+}\postcorr 2931This function is intended to be used for concatenation of outlines. It needs 2932all the arguments because some quantities which are given on the font level 2933are required for constructing the outline. \verb+deltax+ and \verb+deltay+ are 2934the horizontal and vertical displacement measured in charspace units. From the 2935\verb+modflag+-argument, especially the underlining parameters are 2936evaluated. Although $x$- and $y$-displacement may be specified, the resulting 2937outline is still subject to scaling with \verb+size+ and transformation 2938according to \verb+transform+. 2939 2940Arbitrary outlines may be concatenated by using the function 2941\precorr 2942\begin{verbatim} 2943 T1_OUTLINE *T1_ConcatOutlines( T1_OUTLINE *path1, 2944 T1_OUTLINE *path2) 2945\end{verbatim}\index{\verb+T1_ConcatOutlines()+}\postcorr 2946Notice that this concatenation is done with high precision so that we can 2947expect that visual artefacts are reduced to a minimum (remember figure 2948\ref{figure:whyoutlines}). 2949 2950Scaling of outlines is done by the function 2951\precorr 2952\begin{verbatim} 2953 T1_OUTLINE *T1_ScaleOutline( T1_OUTLINE *path, float scale) 2954\end{verbatim}\index{\verb+T1_ScaleOutline()+}\postcorr 2955\verb+T1_ScaleOutline+ does nothing more than linearly scaling the coordinate 2956data with \verb+scale+ and storing the result in fractional pixels. No care is 2957taken for hinting (see above). 2958 2959An outline may be duplicated using the function 2960\precorr 2961\begin{verbatim} 2962 T1_OUTLINE *T1_CopyOutline( T1_OUTLINE *path) 2963\end{verbatim}\index{\verb+T1_CopyOutline()+}\postcorr 2964This is a direct entrypoint into the rasterizer. It works by allocating and 2965duplicating each segment of \verb+path+. This function may be useful if one 2966wants to do several things with one outline because the process of filling an 2967outline also consumes that outline. 2968 2969An outline that that a user decides not to fill can be destroyed by the 2970function 2971\precorr 2972\begin{verbatim} 2973 void T1_FreeOutline( T1_OUTLINE *path) 2974\end{verbatim}\index{\verb+T1_FreeOutline()+}\postcorr 2975It iterates through the segment list and frees each segment. 2976This must not be done after filling an outline because the filling process 2977consumes the outline! 2978 2979Finally, there are two functions that produce glyphs from outlines, namely 2980\precorr 2981\begin{verbatim} 2982 GLYPH *T1_FillOutline( T1_OUTLINE *path, int modflag) 2983\end{verbatim}\index{\verb+T1_FillOutline()+}\postcorr 2984and 2985\precorr 2986\begin{verbatim} 2987 GLYPH *T1_AAFillOutline( T1_OUTLINE *path, int modflag) 2988\end{verbatim}\index{\verb+T1_AAFillOutline()+}\postcorr 2989Their usage does not need any explanation. The value of \verb+modflag+ is 2990required for {\em Right-To-Left} typesetting. If the bit 2991\verb+T1_RIGHT_TO_LEFT+ is set, the dimension of the glyph are recomputed 2992accordingly. All other bits from \verb+modflag+ are ignored such that in the 2993usual case of {\em Left-To-Right} typesetting simply 0 can be specified. 2994While \verb+T1_FillOutline()+ produces bitmaps of depth 1, 2995\verb+T1_AAFillOutline()+ produces antialiased bytemaps of the current 2996graphics depth. It should be mentioned that Smart Antialiasing (see 2997\ref{smartantialiasing}) does not work with this function. The reason is that 2998\tonelib\ has no notion of the quantity ``size'' when it gets the outline to 2999process. Hence, Smart Antialiasing can't work in this case. As noted above, 3000the outline is consumed by the filling functions so that there is no need to 3001free it explicitly. 3002 3003 3004\subsubsection{Manipulation of Outlines} 3005\label{outlinemanipulation}% 3006\tonelib\ provides some limited further functionality to process 3007outlines. First of all, a user would expect a character to be defined in a 3008coordinate system in which $x$ points to the right and $y$ points up. Further, 3009a representation of the glyph where all points are specified in absolute 3010coordinates would be advantageous for manipulating outline-points. This is 3011because most transformations, linear or nonlinear, need to have an absolute 3012$x$-value to compute an $y$-value or vice versa. The function 3013\precorr 3014\begin{verbatim} 3015 void T1_AbsolutePath( T1_OUTLINE *rpath) 3016\end{verbatim}\index{\verb+T1_AbsolutePath()+}\postcorr 3017does exactly what has been described just before, (a) conversion of relative 3018coordinates into absolute coordinates and (b) inverting the 3019$y$-direction. 3020 3021Once a path has been converted into an absolute path, it is 3022suitable for possibly nonlinear manipulation.\footnote{A linear manipulation 3023 of path points would rather be realized using the transformation matrices as 3024 described in \ref{transformations}.} 3025As an example of what can be done, have a look at figure \ref{figure:manipulation}. 3026\begin{figure}[t] 3027\hfill 3028\includegraphics[scale=1.0]{manipulate} 3029\hfill\break 3030\vskip3mm 3031\hrule\vskip3mm\small 3032\caption{\label{figure:manipulation}A string with nonlinearly scaled coordinates.} 3033\end{figure} 3034The string displayed has been generated by essentially applying the 3035transformation $y'= y(1+cx^2)$, with appropriate $c$. To allow such 3036transformations by the user, \tonelib\ provides the function 3037\precorr 3038\begin{verbatim} 3039 void T1_ManipulatePath( T1_OUTLINE *path, 3040 void (*manipulate)(long *x,long *y, int type)) 3041\end{verbatim}\index{\verb+T1_ManipulatePath()+}\postcorr 3042Here, \verb+path+ should be an absolute path as described above. Notice that 3043\tonelib\ has no way to check whether the path is relative or absolute, this 3044is in the responsibility of the user. The second argument is a pointer to a 3045function that has a return type of \verb+void+ and that expects three 3046arguments: two pointers to \verb+long+-values one integer \verb+type+. 3047\verb+T1_ManipulatePath()+ works by iterating through all outline points of 3048\verb+path+ and calling the function \verb+*manipulate()+ for each outline 3049point. When the function \verb+*manipulate()+ is called, \verb+x+ and \verb+y+ 3050are pointers to the $x$- and $y$-coordinates respectively of the outline point 3051to be processed. That way, \verb+*manipulate()+ can alter the outline 3052points arbitrarily. The \verb+type+-argument will be set to the segment type 3053by \verb+T1_ManipulatePath()+. As described earlier, the segment type can be 3054one of \verb+T1_PATHTYPE_MOVE+, \verb+T1_PATHTYPE_LINE+ and 3055\verb+T1_PATHTYPE_BEZIER+. Of course, the function \verb+manipulate()+ has to 3056be written by the user. To make it clear, we consider a function which 3057stretches an outline horizontally by 1.5. The code fragment for this could be: 3058\begin{verbatim} 3059 . 3060 . 3061 . 3062void h_stretch( long *x, long *y, int type) 3063{ 3064 double dx; 3065 3066 dx=(double)*x; 3067 dx *=1.5; /* scale x coordinate by 1.5 */ 3068 *x=(long)dx; 3069} 3070 . 3071 . 3072 . 3073T1_OUTLINE *path=NULL; 3074path=T1_GetStringOutline(FontID,(char *)SomeString, 3075 0,0,T1_KERNING,20.0,NULL); 3076T1_AbsolutePath( path); 3077T1_ManipulatePath( path, &h_stretch); 3078T1_RelativePath( path); 3079glyph=T1_FillOutline( path, Modflag); 3080 . 3081 . 3082 . 3083\end{verbatim} 3084 3085As the example above already has shown, an absolute path, manipulated or not, 3086must converted back to a relative path before it finally can be interpreted by 3087the rasterizer. This conversion is done using 3088\precorr 3089\begin{verbatim} 3090 void T1_RelativePath( T1_OUTLINE *apath) 3091\end{verbatim}\index{\verb+T1_RelativePath()+}\postcorr 3092As already mentioned with respect to \verb+T1_AbsolutePath()+, \tonelib\ cannot 3093check whether the \verb+path+ specified is really absolute. The user has to 3094take care for this. 3095 3096A few general comments about manipulating paths are appropriate. Although the 3097mechanism implemented by \verb+T1_ManipulatePath()+ allows arbitrary 3098manipulation of path points, one must be very careful in doing so. Figure 3099\ref{figure:outlineproblems} exhibits some of the problems that may arise. A text 3100string aligned to a sine function is displayed. 3101%- parameters of figure: string: Text aligned along a sine wave function 3102% size: 50 3103% kerning on 3104\begin{figure}[t] 3105\hfill 3106a) \includegraphics[scale=0.5]{outlineproblems1} % period=500, 3107\hfill\break 3108 3109\hfill 3110b) \includegraphics[scale=0.5]{outlineproblems2} % period=200 3111\hfill\break 3112 3113\hfill 3114c) \includegraphics[scale=0.5]{outlineproblems3} % period=100 3115\hfill\break 3116 3117\hfill 3118d) \includegraphics[scale=0.5]{outlineproblems4} % period=50 3119\hfill\break 3120 3121\hfill 3122e) \includegraphics[scale=0.5]{outlineproblems5} % period=500 3123\hfill\break 3124\hrule\vskip3mm\small 3125\caption{\label{figure:outlineproblems}The string ``Text aligned along a sine wave 3126 function'' using a period of (a) 500, (b) 200, (c) 100, (d) 50 pixels and 3127 (e) again 500 pixels with underlining. The sine amplitude was 30 pixels 3128 (in screen resolution).} 3129\end{figure} 3130In part (a), a pleasing smooth text flow is shown and this also applies for 3131(b) where the period of the sine has been reduced to 200 pixels. In (c), where 3132the period has been reduced to 100 pixels, some artefacts already show up. For 3133example, the top bar of the uppercase ``T'' has noticeable variance in 3134thickness. In (d), where the period has been reduced again, the result is 3135hardly readable. Another artefact appears in figure 3136\ref{figure:outlineproblems} (e): since the underlining rule is defined by 3137four points only, these points and nothing else is transformed with the result 3138that the out coming line is still straight and not curved as we would 3139like. From this discussion we conclude, that such transformations can only be done 3140with reasonable results if the maximum distance between the outline points of 3141a shape is small compared to the variance of the outline points that the 3142transformation results in. This rule, although being very fuzzy and 3143non-mathematical, should give a good estimation of which transformations are valid. 3144 3145Another completely independent topic is that, at the level where \tonelib\ 3146provides outlines, their representation is strictly descriptive with respect 3147to points and their connections. There are no such things like 3148\verb+closepath+-segments which would take care that a path is really closed, 3149no matter what the transformation had been. This means, that identical points 3150$P_1 = P_2$ have to be transformed to identical points $P_1'=P_2'$, no matter 3151where they appear in the outline. However, 3152if the transformation is done by by a function $(x',y')=f(x,y)$ as suggested, 3153this should never be a problem. 3154 3155Finally, one should remember that all computations in the user function 3156\verb+manipulate()+ have to be done in units of fractional pixels, rather than in 3157pixels. When designing a sine wave as in figure \ref{figure:outlineproblems}, 3158this must be taken into account with respect to periodicity. 3159 3160\subsection{Logical Fonts} 3161\label{logicalfonts}% 3162It sometimes may be necessary to have a font and an extended or slanted 3163variant simultaneously. To enable such configurations without needing to 3164declare the fonts two or even more times in the font database file, 3165\tonelib\ provides the function 3166\precorr 3167\begin{verbatim} 3168 int T1_CopyFont( int FontID) 3169\end{verbatim}\index{\verb+T1_CopyFont()+}\postcorr 3170It copies the top level data structure of the font given by \verb+FontID+ to 3171another location. The newly created font refers in fact to the same 3172physical memory as the font \verb+FontID+ as far as Type 1 and AFM data are 3173concerned. However, no size specific data is copied from font \verb+FontID+, 3174you can thus do with the new font whatever you want to. It will get its own 3175size-specific memory area when the first bitmap is generated using its ID. 3176 3177It is also possible to reencode a copied font without affecting the 3178original font. This is possible because a logical font gets its own 3179mapping tables. This allows configurations with one font at different 3180encodings simultaneously. 3181 3182In order to keep track that another font is referring to data from 3183font \verb+FontID+, a reference counter is managed for every font. The 3184reference counter for font \verb+FontID+ is incremented after a call to 3185\verb+T1_CopyFont()+. 3186 3187If the font \verb+FontID+ is not loaded into memory, the function returns $-1$. 3188 3189Only {\em physical} fonts---those fonts defined in the font database 3190file or added via \verb+T1_AddFont()+---may be copied to another 3191font. If a user tries to copy a font 3192which is already logical, the function returns $-2$. 3193 3194If no memory is available for the new font the function return $-3$. But 3195this should not happen. 3196 3197If all goes the right way, \verb+T1_CopyFont()+ returns an integer---lets call 3198it \verb+new_ID+---which is from now on a valid font identification number. 3199 3200\subsection{Missing or Invalid AFM Files} 3201\label{missingafmfiles}% 3202\tonelib\ heavily relies on AFM information every time the relative position 3203of bitmaps is of importance. Because AFM information is of high resolution, 3204accumulating positioning errors are avoided in contrast to what the X11 text 3205drawing functions do. On the other hand, there are many freely available 3206Type~1 font programs that come without AFM files. This problem has been 3207addressed in \tonelib\ 0.5. \tonelib\ is now able to generate AFM information 3208on the fly and it even can generate AFM files from Type 1 font files. 3209 3210\subsubsection{Remarks on AFM Files} 3211\label{remarksonafmfiles}% 3212Information in AFM files is only relevant for placing character glyphs but not 3213for rasterizing. The metric values are based on the same coordinate system as 3214used in Type 1 font files, the so called {\em charspace coordinate system}. 3215One unit is $1/1000 \mbox{bp}$ when a font is not scaled or scaled to 1~bp, 3216respectively. 3217 3218Information in AFM files can divided into several groups: 3219\begin{enumerate} 3220\item {\em Global Font Information:} This information is generally not needed 3221 to place characters. Furthermore, most of this information is also 3222 contained in a Type 1 font file itself. This area is thus of marginal 3223 importance for \tonelib. 3224\item {\em Character Width's and Bounding Boxes:} These both are crucial for 3225 accurately placing the character glyphs. Fortunately, these are dimensions 3226 are exactly defined by the character outlines themselves. It is thus 3227 possible to compute them spending some computational effort. 3228\item {\em Ligature Information:} For \ae sthetic reasons, certain character 3229 groups are often replaced by ligatures and a font file may define several 3230 ligatures. It is however not intuitively clear what character groups should 3231 be replaced by what ligatures.\footnote{Well, at least not without some 3232 expert knowledge like ``I know this ligature's name is `f{}i', so I 3233 replace every series of `f' and `i' with it.''} 3234 Fortunately, ligatures are not crucially needed for quality typesetting. 3235\item {\em Pair Kerning Information:} This information is quite important for 3236 \ae sthetic reasons but it is entirely independent from the outline 3237 descriptions and can thus not be extracted from a font file. 3238\item {\em Track Kerning Information:} This information gives hints of how to 3239 typeset text generally closer or wider at varying point sizes. 3240 \tonelib\ does not use track kerning 3241 information and I personally do not consider using track kerning a good 3242 typographical style. 3243\item {\em Composite Character Data:} This is needed to construct characters 3244 from two single characters. Typical examples are accented 3245 characters. \tonelib\ currently does not deal with composite 3246 characters. Most of the composite characters needed are already existent 3247 internally. 3248\end{enumerate} 3249To come to a conclusion, for our purposes it is sufficient to generate the 3250characters' widths and their bounding boxes and we have all information we 3251need to construct string glyphs. 3252 3253\subsubsection{Generation of AFM Information} 3254\label{generatingafminfo}% 3255Next lets consider how to generate the AFM information. It is a series of 3256entirely independent steps: 3257\begin{itemize} 3258\item When we generate AFM information, we want to do this once and forever 3259 when the font is loaded. Consequently all characters, have to be examined, 3260 not only those that are currently encoded. 3261 We start by fetching all character names the font defines. This done with 3262 \verb+T1_GetAllCharNames()+ (see \ref{characterencodingrelation}). This 3263 yields a list of possibly more than 256 character names. 3264\item Each of the character addressed by the names above is now rastered at 3265 size 1000~bp. By rastering at 1000~bp we match exactly the charspace 3266 coordinate system which the character outline descriptions are 3267 based on. Width and bounding box are easily examined and saved at 3268 appropriate places. 3269\item The kerning pair area and ligatures are explicitly set to zero. 3270\end{itemize} 3271At the end of this procedure, there is a data area identical to what would 3272have been built when reading an AFM file without kerning-section and ligature 3273specifications. 3274 3275The decision of building AFM data is done on the fly without any user 3276interaction. Here is what happens on the metrics-area when loading a font: 3277\begin{itemize} 3278\item \tonelib\ tries to open an AFM file reading metrics and kerning pair 3279 information. 3280\item If this does not succeed, it tries to rescan the AFM file in a {\em 3281 sloppy} way, only requesting metrics information. 3282\item If this fails too, metrics information is generated on the fly as 3283 described above. 3284\end{itemize} 3285It should be noted that generating metric information the way described above 3286takes significant amount of time since every character has to be rastered at 32871000~bp. 3288 3289%~derekn 3290If the \verb+T1_NO_AFM+ flag is passed to \verb+T1_InitLib()+, 3291\tonelib\ will neither attempt to open AFM files nor generate AFM 3292information. This is useful to speed up applications which do not 3293need the metrics data. However, this slows down access to certain features, 3294mostly related to the string processing functions, and completely disables the 3295features that only are contained in AFM files (like kerning and ligatures). 3296 3297Obivously, the \tonelib\ functions that use 3298the AFM data will not work correctly in this case and should not be 3299used. 3300%~derekn 3301 3302\subsubsection{Writing AFM Files} 3303\label{writingafmfiles}% 3304In order to reduce the situations where AFM data has to be generated on the 3305fly, \tonelib\ provides the following function: 3306\precorr 3307\begin{verbatim} 3308 int T1_WriteAFMFallbackFile( int FontID) 3309\end{verbatim}\index{\verb+T1_WriteAFMFallbackFile()+}\postcorr 3310It writes an AFM file for the font identified by \verb+FontID+. This is done 3311executing the following steps: 3312\begin{enumerate} 3313\item The AFM filename is constructed by taking the fontfilename, cutting off 3314 the extension and appending \verb+.afm+. 3315\item A pointer array of size $256 + n$, where $n=\mbox{number of 3316 characters}$, is 3317 allocated and set to NULL. The leading 256 entries are reserved to point to 3318 encoded 3319 characters' metrics. The remaining entries are intended to point to metrics 3320 of unencoded characters. We see that this is a worst case speculation: The 3321 pointer array is large enough for the extremely unusual case that no 3322 characters are encoded. 3323\item Next the function steps through all character names and gets their 3324 encoding index $i$. If $i\geq0$, the character is encoded and the $i$th 3325 pointer element in the array is set to point to the metrics of this 3326 character. If $i=-1$, the character is not encoded and the lowest unused 3327 pointer in the second area is set to point to the metrics of this character. 3328\item Next the AFM file is opened and the header information as well as a 3329 comment by \tonelib\ are written. There are 5 entries that are not trivially 3330 to extract from the font file: \verb+Ascender+, \verb+Descender+, 3331 \verb+XHeight+, \verb+CapHeight+ and \verb+EncodingScheme+. Their 3332 discussion is deferred to later in this section. 3333\item After the header, the metrics information is written in the format 3334 required for AFM files. This is done by stepping through the pointer array 3335 until the first NULL pointer in the unencoded characters' area is 3336 reached. 3337\end{enumerate} 3338The result is a list of char-dimensions entries which is leaded by the encoded 3339characters in ascending order of their encoding index, followed by a list of 3340unencoded characters in alphabetical order. 3341 3342As seen above, the current encoding takes influence on the order the 3343characters appear in the AFM file. One should thus not produce AFM files from 3344reencoded fonts, although this is possible. This yields non-standard AFM files 3345and gives no performance gain, even not when used with \tonelib. 3346 3347The entry \verb+EncodingScheme+ is not always contained in the fontfile 3348itself. It is generated by comparison between encodings. \tonelib\ has only one 3349builtin encoding, \verb+AdobeStandardEncoding+, which 3350is recognized. Every further encoding, defined 3351by the font itself or applied by a user, is always marked as 3352\verb+FontSpecific+. 3353 3354The entries \verb+CapHeight+, \verb+XHeight+ \verb+Ascender+ and 3355\verb+Descender+ are not fully determined by a Type 1 font file 3356although they are existent with high probability. As rough definitions 3357can be considered: 3358\begin{itemize} 3359\item \verb+CapHeight+: The height a capital `H' reaches to. 3360\item \verb+XHeight+: The height a lower case `x' reaches to. 3361\item \verb+Ascender+: The height a lower case `d' reaches to. 3362\item \verb+Descender+: The depth a lower case `p' reaches down. 3363\end{itemize} 3364It is obvious that these definitions make only sense in certain font 3365definitions. For example, a musical notation font might not necessarily 3366define an ascender since no capital letters are provided. 3367 3368In the Type 1 notion these dimensions are referred to as top alignment 3369and bottom alignment values respectively. The corresponding alignment 3370``zone'', i.e., an interval, is defined by the alignment height and a 3371corresponding overshoot position. The alignment zones are specified in 3372the BlueValues array for top alignment zones and the OtherBlues 3373array for bottom alignment zones. A Type 1 font may define up to 7 top 3374alignment zones and 5 bottom alignment zones. It is unfortunately not 3375defined which of these alignment zones refer to \verb+CapHeight+, 3376\verb+XHeight+, \verb+Ascender+ and \verb+Descender+. 3377 3378\tonelib\ tries to get out of this dilemma by making a best guess: 3379\begin{enumerate} 3380\item For each of the characters `H', `x' and `d' it fetches the 3381 largest y-value and compares the result with each alignment zone in 3382 the BlueValues array. The alignment zone closest to the observed 3383 character dimension is assumed a candidate for the respective 3384 quantity. 3385\item It checks whether the difference between the alignment zone just 3386 selected and the character dimension is within a certain tolerance 3387 area. This tolerance width is $\pm 30$ charspace units. If the 3388 result is positive, the quantity in question is assigned the 3389 numerical value of the standard height (not the overshoot) of this 3390 alignment zone. Since we are currently considering top 3391 alignment zone, this will always be the lower value. 3392\item If the value is out of tolerance or the font even does not 3393 define the character, the corresponding entry in the AFM file is left 3394 out. 3395\item A comparable procedure is then done for \verb+Descender+, this 3396 time examining the OtherBlues array. 3397\end{enumerate} 3398Note that if the values do not seem to be correct, the corresponding 3399lines can be removed from the AFM file without doing any harm. These 3400entries are optional only. 3401 3402\verb+T1_WriteAFMFallBackFile()+ can indicate a number of error 3403conditions by returning appropriate values. These are: 3404\begin{itemize} 3405\item \verb+0+: No error occurred, AFM file was successfully written. 3406\item \verb+-1+: The AFM data for the font in question has been 3407 generated by reading an AFM file, there is no need to generate a new 3408 one. If you really want to force an AFM file to be written, take 3409 care that \tonelib\ does not find an AFM file when loading the 3410 font. 3411\item \verb+-2+: The font in question is not loaded. 3412\item \verb+-3+: The font in question is loaded but AFM data has not 3413 been generated. This definitely is an error condition because it 3414 indicates not all characters of the font could be rastered, either 3415 because the font file is damaged or because there were 3416 insufficient system resources. In any case the application should 3417 generate a logfile and this file should be examined. 3418\item \verb+-4+: The AFM file could not be opened. This could be a 3419 permission problem or something else. The file is always opened in 3420 the current working directory. 3421\item \verb+-5+: The file has successfully been opened but there was 3422 an error writing to the file. 3423\item \verb+-6+: A memory allocation error occurred. This should not 3424 happen because it indicates there are no system resources. 3425\end{itemize} 3426 3427 3428 3429\subsection{Font Subsetting} 3430\label{Font Subsetting}% 3431When applications have to setup Postscript files for printing, the problem is 3432that these files often grow large. Each font which is not known to the 3433Postscript interpeter, i.e., usually each font that is not part of the set of 343435 standard fonts, has to be downloaded as part of the file. The size of a 3435particular font file often can be reduced by font subsetting, because usually 3436only a small subset of the available character descriptions is actually 3437needed. 3438 3439 3440 3441\subsubsection{Font File Organization and Subsetting} 3442\label{Font File Organization and Subsetting}% 3443 3444Each Type~1 font file is a special Postscript program defining three 3445Postscript-dictionaries: 3446\begin{itemize} 3447\item \verb+FontInfo+\\ 3448 Global font information like font and family name and encoding scheme is 3449 stored here. This data is required even for a subsetted font. However, as 3450 will be described later, the encoding scheme may be reduced to those 3451 characters that are in the desired subset. 3452\item \verb+Private+\\ 3453 This dictionary is in the encrypted part of the file and stores global font 3454 data too. This data includes quantities parameterizing hinting and 3455 subroutines that might be called by the character descriptions. This data is 3456 required also. 3457\item \verb+Charstrings+\\ 3458 For each character defined in the font a binary and encrypted byte string 3459 (charstring) coding the character outline is stored in this dictionary. The 3460 number of charstrings may be considerably larger than the size of the 3461 encoding vector. This dictionary usually constitutes the largest part of the 3462 font file and, consequently, it is the place to reduce storage requirements. 3463\end{itemize} 3464The main principle in subsetting is to decrypt the font and reorganize it, 3465leaving out charstrings that are not required in the current context. For 3466example, if a document uses only the character 'A' from the font Garamond, 3467then this font may be subsetted preserving the character outline for 'A' 3468only. The resulting file, which will be much smaller than the original file, 3469can then be included verbatim into the Postscript file containing the 3470document. At the same time, optionally, the encoding vector could be redefined 3471to contain only the entry for 'A' at the appropriate location and 3472\verb+.notdef+ otherwise. 3473 3474A still more consequent subsetting would involve leaving out those subroutines 3475from the \verb+Private+-dictionary that are not needed by the preserved 3476charstrings. Leaving out some subroutines on the other hand would require to 3477interprete and check all charstrings for the subroutines they require and all 3478preserved charstrings would have to be adapted to the reorganized index. Since 3479the subroutines usually do not consume that much memory this is not considered 3480worth the effort. 3481 3482\subsubsection{Functions for Subsetting} 3483\label{Functions for Subsetting}% 3484 3485There are two ways to obtain a subsetted font from an existing file. The user 3486can (1)~do it step by step which requires reading, decrypting, reorganizing 3487and encrypting of the font file, and (2)~use a high level function to do it 3488without having to know anything about the details. For font subsetting, 3489\tonelib\ provides the function 3490\precorr 3491\begin{verbatim} 3492 char *T1_SubsetFont( int FontID, char *mask, 3493 unsigned int flags, int linewidth, 3494 unsigned long maxblocksize, 3495 unsigned long *bufsize) 3496\end{verbatim}\index{\verb+T1_SubsetFont()+}\postcorr 3497It returns a pointer to a memory block containing the subset data. The memory 3498is allocated in the function and it is the responsability of the user to 3499free this memory. The parameter \verb+FontID+ as usual is used to tell 3500\tonelib\ which file or font is to be used for the operation. 3501 3502\verb+mask+ points to an array of characters which has to be setup by the 3503user. This array must comprise exactly 256 characters and for the index of 3504each non-zero entry the charstring resulting from the current encoding is 3505preserved in the subsetted font. To give an instance, if the subset should 3506consist in the character 'A' only and we assume the current font specifies 3507\verb+StandardEncoding+, then the \verb+mask+-array should be initialized to 3508zeroes and \verb+mask['A']=1+ or some other non-zero value. 3509 3510The \verb+flags+ parameter allows to control the subsetting operation. It 3511usually should be set to \verb+T1_SUBSET_DEFAULT+. In this case, the subset is 3512ASCII-hex encrypted, that is, as in a \verb+.pfa+-file. It is thus well-suited 3513for the verbatim insertion into a Postscript file. If the source font file in 3514question defines the encoding to be \verb+StandardEncoding+, the encoding is 3515not adjusted to the subset specified by \verb+mask+. By contrast, if the font 3516defines a \verb+FontSpecific+ encoding, this encoding will be adjusted 3517according to the subset. This default behavior---which mimics what 3518e.g.~\verb+dvips+ seems to do---may be overwritten by OR'ing \verb+flags+ with 3519\verb+T1_SUBSET_FORCE_REENCODE+, which leads to adjusting the encoding vector 3520in any case. Conversely, reencoding can be suppressed unconditionally by OR'ing 3521\verb+flags+ with \verb+T1_SUBSET_SKIP_REENCODE+. If \verb+flags+ is OR'ed 3522with \verb+T1_SUBSET_ENCRYPT_BINARY+, a buffer of mixed ASCII, binary and EOF 3523segment types is created and encryption is performed in binary mode. The 3524buffer's contents in this case represents a valid compact binary format file 3525(\verb+.pfb+). It is considerably smaller than a comparable \verb+.pfa+-file 3526but it is not suitable to be inserted into Postscript files. 3527 3528The parameter \verb+linewidth+ is used to specify the line length if ASCII-hex 3529encryption is used. Since---according to the Adobe speification---the first 8 3530encrypted bytes have to be stored one after the other without interspersed 3531white space, the allowed range of \verb+linwidth+ is limited to 8 at the lower 3532bound. It is also limited at the upper bound by 1024, because writing that 3533long lines does not preserve the readability of the produced file. 3534 3535The parameter \verb+maxblocksize+ is important if binary encryption is 3536used. Then, this value specifies the maximum allowed segment size. For similar 3537reasons as discussed above, this value must be equal to or larger 3538than~4. There is no limit at the upper bound, because the maximum segment size 3539can be derived automatically follows from the target font file. 3540 3541\verb+bufsize+ must be a valid pointer to an \verb+unsigned long int+ in the 3542context of the calling function. The size of the memory area to which the 3543function returns a pointer, is written to \verb+bufsize+. The calling function 3544needs this number to process to buffers contents, e.g., to write it to a file. 3545 3546If errors occur in this function, \verb+NULL+ is returned and \verb+T1_errno+ 3547is set to an appropriate value. If the font corresponding to \verb+FontID+ is 3548not loaded, \verb+T1_errno+ is set to \verb+T1ERR_INVALID_FONTID+. 3549\verb+T1ERR_INVALID_PARAMETER+ is used to indicate that one of the further 3550arguments is out of range. \verb+T1ERR_ALLOC_MEM+ and 3551\verb+T1ERR_FILE_OPEN_ERR+ may also be set in this function. Finally, 3552\verb+T1ERR_UNSPECIFIED+ may also be set if the charstring definition for 3553\verb+.notdef+ could not be located. This is considered to be a fatal error. 3554 3555An example of how to use the function described above is given in the file 3556\verb+subset.c+ in the \verb+examples/+ subdirectory of the distribution. 3557 3558\subsubsection{Further Functions for Subsetting} 3559\label{Further Functions for Subsetting}% 3560 3561For the sake of completeness, there are a few further functions in the 3562subsetting module. The function 3563\precorr 3564\begin{verbatim} 3565 char *T1_GetCharString( int FontID, char *charname, int *len) 3566\end{verbatim}\index{\verb+T1_GetCharString()+}\postcorr 3567returns a pointer to the charstring of the character with name \verb+charname+ 3568of the font identified by \verb+FontID+. In case of an error, \verb+NULL+ is 3569returned and \verb+T1_errno+ is set to \verb+T1ERR_ALLOC_ERR+ if there was not 3570enough memory for storing the charstring, \verb+T1ERR_UNSPECIFIED+ if the 3571charstring was not found in the dictionary, \verb+T1ERR_INVALID_FONTID+ if the 3572font in question is not loaded or \verb+T1ERR_INVALID_PARAMETER+ if 3573\verb+charname+ or \verb+len+ is \verb+NULL+. The memory pointer which is 3574returned is managed static in this function. Thus, it should not be free'd by 3575the user, or, in case the memory block is free'd, the pointer must be set to 3576\verb+NULL+. 3577 3578In order to decrypt a charstring, the \verb+lenIV+-value of the font in 3579question must be known. It can be obtained using the function 3580\precorr 3581\begin{verbatim} 3582 int T1_GetlenIV( int FontID) 3583\end{verbatim}\index{\verb+T1_GetLenIV()+}\postcorr 3584The returned value indicates how many leading random bytes are used for 3585charstring encryption in the font \verb+FontID+. According to an undocumented 3586Adobe convention, the value $-1$ is also valid and indicates that the 3587charstring is not encrypted at all. Hence the return value $-2$ is used to 3588indicate an error. In this case, \verb+T1_errno+ is set to 3589\verb+T1ERR_INVALID_FONTID+, which indicates that the font in question is not 3590loaded. 3591 3592 3593\subsection{Composite Characters} 3594\label{subsec:CompositeCharacters}% 3595 3596This section discusses the composite character information that may be present 3597in AFM files and how this information is represented, accessed and handled in 3598\tonelib. 3599 3600\subsubsection{General remarks} 3601\label{subsubsec:General Remarks}% 3602 3603Composite characters are defined by the fact that they are constructed from at 3604least two independent symbols. In practice there frequently appear two 3605components, a base character and an accent, e.g., as in ``\"A''. Usually, the 3606accents (or secondary pieces) of a composite character are typeset first 3607without causing any horizontal escapement and finally the base character 3608itself is typeset and causes its escapement to become the escapement of the 3609whole composite character. Although some people recommend that the character 3610definition of an accent itself should not cause escapement, this generally is 3611not respected in real fonts and \tonelib\ does not require this condition to 3612be fulfilled. 3613 3614In order to construct a composite character the characters to be put together 3615have to be known and metric information about how to put these characters 3616together has to be known too. \tonelib\ defines two structures as new data types 3617for this purpose. The first is 3618\begin{verbatim} 3619typedef struct 3620 { 3621 int compchar; 3622 int numPieces; 3623 T1_COMP_PIECE *pieces; 3624 } T1_COMP_CHAR_INFO; 3625\end{verbatim} 3626Here, \verb+compchar+ is the index in the encoding vector of the composite 3627character. \verb+numPieces+ specifies how many pieces are 3628required to build the composite character. The third element is a pointer to 3629an array of type \verb+T1_COMP_PIECE+, whose actual length is given by 3630\verb+numPieces+: Each piece (or symbol) receives one slot in this 3631array. \verb+T1_COMP_PIECE+ is defined by 3632\begin{verbatim} 3633 typedef struct 3634 { 3635 int piece; 3636 int deltax; 3637 int deltay; 3638 } T1_COMP_PIECE; 3639\end{verbatim} 3640It contains the encoding index of the symbol in \verb+piece+ and information 3641where to place this symbol with respect to the composite character's orgin in 3642\verb+deltax+ and \verb+deltay+. The first slot is filled by what I refer to 3643as the base character, it is the one that causes spacing. As can be seen in 3644these data structures, composite character handling in \tonelib\ is based on 3645encoding indices rather than on character names, which, by contrast, are used 3646for the definition of composite character data in AFM files. 3647 3648The presence of composite character information in AFM files does not tell 3649anything about whether a font has an internal definition of this character or 3650not. For example, the font \verb+TimesRoman+ internally defines the CharString 3651\verb+Adieresis+ and hence this font provides the letter ``\"A'', assuming an 3652appropriate encoding, without any knowledge about composite 3653characters. However, the file \verb+TimesRoman.afm+ may still 3654provide composite character information for \verb+Adieresis+, just to tell an 3655application that this glyph consists of more elementary pieces and how to 3656construct it. On the other hand, if \verb+TimesRoman+ had no 3657CharString-definition for \verb+Adieresis+, the composite character 3658information of \verb+Adieresis+ provides an application with enough 3659information to be able construct \verb+Adiereis+ from the elementary units 3660\verb+A+ and \verb+dieresis+ that the font provides. 3661 3662 3663\subsubsection{Accessing Composite Character Data} 3664\label{subsubsec:Accessing Composite CHaracter Data}% 3665 3666This section describes a few functions that provide access to composite 3667character data of a font file. The data they return can be considered a 3668mapping of the original AFM data with respect to the current encoding. As 3669usual, \verb+FontID+ must be the identifier of a font loaded into memory, 3670otherwise an appropriate error indicator is returned. The functions described 3671in the following may also return some other error types. 3672 3673Firstly, 3674\precorr 3675\begin{verbatim} 3676 int T1_GetNoCompositeChars( int FontID) 3677\end{verbatim}\index{\verb+T1_GetNoCompositeChars()+}\postcorr 3678tells the user how many composite character definitions are given in the AFM 3679file. This, of course, does not depend on the current encoding vector and it 3680is even possible that the current encoding vector does not incorporate any 3681composite character at all. 3682 3683The function 3684\precorr 3685\begin{verbatim} 3686 int T1_QueryCompositeChar( int FontID, char char1) 3687\end{verbatim}\index{\verb+T1_QueryCompositeChar()+}\postcorr 3688checks whether composite character information exists for the encoding index 3689\verb+char1+. If so, it returns the index within in the AFM composite 3690character data array as a number equal to or greater than zero. If the result 3691is valid but no composite character information has been found for 3692\verb+char1+, $-1$ is returned. In case of an error, $-2$ is returned and 3693\verb+T1_errno+ is set to an appropriate value. 3694 3695The previous function does not tell anything about whether the font 3696\verb+FontID+ incorporates a character definition for the composite char or 3697not. This can be queried using 3698\precorr 3699\begin{verbatim} 3700 int T1_IsInternalChar( int FontID, char char1) 3701\end{verbatim}\index{\verb+T1_IsInternalChar()+}\postcorr 3702It returns $1$ if there exists a CharString for \verb+char1+ and $0$ if not. 3703In the latter case, the application is responsible for the construction of the 3704composite character (see later). \verb+T1_IsInternalChar()+ also might return 3705$-1$ and set \verb+T1_errno+, which indicates that the font in question is not 3706loaded. 3707 3708The information required to construct a composite character is retrieved by 3709calling the function 3710\precorr 3711\begin{verbatim} 3712 T1_COMP_CHAR_INFO *T1_GetCompCharData( int FontID, char char1) 3713\end{verbatim}\index{\verb+T1_GetCompCharData()+}\postcorr 3714It returns a pointer to a meaningfully filled struct of type 3715\verb+T1_COMP_CHAR_INFO+ as described above. The composite character and the 3716number 3717of pieces as well as a pointer to the array of type \verb+T1_COMP_PIECE+ are 3718stored in this structure. Once this information is obtained the composite 3719character can be constructed by 3720\begin{itemize} 3721\item placing the accent symbols in a loop that ranges from $1$ to 3722 \verb+numPieces+$-1$. In practice this loop will often be executed only 3723 once. The initial current point must always be restored. In this loop 3724 positioning information is accessed by \verb+ptr->pieces[+$i$\verb+].deltax+ 3725 and \verb+ptr->pieces[+$i$\verb+].deltay+, where \verb+ptr+ is the pointer 3726 returned by the above function. 3727\item placing the base character (\verb+pieces[0]+), which then also causes 3728 the horizontal escapement of the composite character. 3729\end{itemize} 3730 3731In cases where \verb+char1+ is not a composite 3732character, the \verb+compchar+ entry is set to \verb+char1+ itself and 3733\verb+numPieces+ becomes $1$, as would be expected. The \verb+pieces+ pointer 3734is then set to \verb+NULL+. In case of errors, this function returns 3735\verb+NULL+ and \verb+T1_errno+ is setup correspondingly. 3736 3737The pointer returned by this function should always be free'd using 3738\verb+T1_FreeCompCharData()+ in order to avoid memory leaks (see also 3739Section~\ref{deletingdata}). 3740 3741A function that provides the same functionality is 3742\precorr 3743\begin{verbatim} 3744 T1_COMP_CHAR_INFO *T1_GetCompCharDataByIndex( int FontID, int index) 3745\end{verbatim}\index{\verb+T1_GetCompCharDataByIndex()+}\postcorr 3746In this case, the information is requested by means of an index \verb+index+ 3747in the AFM composite character data array. This function is thus well-suited 3748for scanning the complete composite character information of a given font in a 3749given encoding. \verb+index+ may, for example, be obtained by a call to 3750\verb+T1_QueryCompCharData()+ as described above. The valid range for 3751\verb+index+ is from $0$ to the value returned by 3752\verb+T1_GetNoCompositeChars()+ minus one. The range of \verb+index+ is 3753validated and in case of an error \verb+T1_errno+ is to 3754\verb+T1ERR_INVALID_PARAMETER+. There may also appear other errors and under any 3755erroneous condition, \verb+NULL+ is returned. 3756 3757The parameter \verb+compchar+ of the \verb+T1_COMP_CHAR_INFO+ structure that 3758is referenced by the returned pointer, bears somewhat more information for 3759this function than in the case of \\ 3760\verb+T1_GetCompCharData()+. As said it contains the index in the encoding 3761vector where the composite glyph is encoded. It may also have the vaue $-1$, 3762which means that the composite character is not encoded. Note that this is not 3763an error condition. 3764 3765 3766\subsubsection{Transparent Handling of Composite Characters and User Extensions} 3767\label{subsubsec:Transparent Handling of Composite Characters and User 3768 Extensions}% 3769 3770Aside from the fact that composite character information may be accessed in 3771\tonelib, \tonelib\ can automatically---and completely transparently with 3772respect to the user---compose characters if it finds information on how to do 3773so. To give an instance, let us examine the font ComputerModern Roman 3774(cmr10). Because this font is specially encoded for the use with early (7-bit) 3775\TeX-systems, it does not incorporate a definition for \verb+Adieresis+. The 3776definition simply was not required because \TeX\ itself constructed the 3777composite character by means of its \verb+\accent+-primitive. If a font like 3778cmr10 is reencoded e.g.~to IsoLatin1 encoding, the character ``\"A'' will show 3779up as a blank because there is no definition for \verb+Adieresis+. Now, if the 3780corresponding AFM file is extended with the following lines, it becomes 3781possible to access an \verb+Adieresis+: 3782\begin{verbatim} 3783StartComposites 1 3784CC Adieresis 2; PCC A 0 0; PCC dieresis 100 200; 3785EndComposites 3786\end{verbatim} 3787This line in an AFM file provides information about how to construct an 3788\verb+Adieresis+ from the \verb+A+ and \verb+dieresis+ glyphs, and \tonelib\ 3789can utilize this information to construct the requested glyph without that 3790this will be be noticed by the user. 3791 3792Composite character are treated just the same way as standard characters. 3793They are cached, they can be scaled, transformed etc. Let us assume that the 3794cache is still empty and a character, identified by its encoding index, now is 3795to be rastered. The following happens in the rastering function: 3796\begin{enumerate} 3797\item \tonelib\ looks up the character's name in the encoding vector and tries 3798 to locate the CharString for that character. If this succeeds all works as 3799 usual, notwithstanding the fact that there might have been composite 3800 character information for that char. This means, font-internal 3801 CharString-definitions have highest priority: One cannot, for example, 3802 re-define an \verb+Adieresis+ by raising the umlaut ``\"{ }'' via a composite 3803 character definition, if \verb+Adieresis+ is defined internally. 3804\item However, if the CharString is not found, composite character information 3805 is examined and if possible, elementary units are used to construct the 3806 requested composite character by concatenating paths. 3807\end{enumerate} 3808In any case, the resulting character is put into the cache and is from then on 3809available as any other character. If pieces of a composite character are not 3810found in the CharStrings dictionary, those pieces are substituted by 3811\verb+.notdef+, so that for extreme cases the whole composite character might 3812be substituted by a \verb+.notdef+. Then, an appropriate message is put into 3813the log file with priority \verb+T1LOG_WARNING+ and \verb+T1_errno+ is set to 3814\verb+T1ERR_COMPOSITE_CHAR+. 3815 3816In the same way \tonelib\ composes characters without user intervention, the 3817functions for character metrics are aware of composite character information 3818and the returned result are also valid for those functions. 3819 3820 3821\subsubsection{Caveats} 3822\label{subsubsec:Caveats}% 3823 3824Although handling of composite character is widely automated, problems may 3825arise. Most importantly it is the responsibility of the user to take care that 3826font file and AFM file provide consistent data. Alas, this is not always true 3827for existing font and AFM files. If, for example, an AFM file is extended by 3828composite character definitions and these composite character definitions 3829reference symbols that are not defined in the CharsStrings dictionary, errors 3830will result. If composite character information is added to an AFM file, the 3831following rules have to be respected: 3832\begin{itemize} 3833\item The name of the composite character has to be encoded because it could 3834 not be accessed otherwise. Furthermore, no internal definition in the 3835 CharStrings dictionary may exist because this would override the composite 3836 character definition from the AFM file. 3837\item The user should verify that all components of a composite character 3838 definition have entries in the CharStrings dictionary. This can be checked 3839 for example by using\\ \verb+T1_GetAllCharNames()+ or by disassembling the font 3840 file. 3841\item Even being more restrictive, the user should take care that all pieces 3842 of a composite character are encoded. For \tonelib\, this is really 3843 irrelevant because, internally, characters may be accessed by the name of 3844 their CharString. This means \tonelib\ simultaneously has access to all 3845 characters defined in a font. However, an application that exports PostScript 3846 files can only access character definitions via their position in the 3847 encoding vector. Composing a character from pieces of different encodings 3848 will require two font definitions in a exported PostScript file for 3849 typesetting one character, which cannot be termed a clean strategy. 3850\end{itemize} 3851 3852 3853\subsection{Error Handling} 3854\label{errorhandling}% 3855Although every function usually returns meaningful values, there are 3856situations where indicating an error via the return value is not possible. For 3857example, requesting a charspace bounding box from a char of a font which is not 3858loaded will return a bounding box containing all zeroes. This cannot be 3859considered an error-condition since for characters like ``space'' it is 3860correct to return a bounding box containing all zeroes. Furthermore, there's no 3861consistent scheme which value should indicate what type of error. In order to 3862allow a unified error handling in applications, the global variable 3863\verb+T1_errno+ has been introduced. 3864 3865The functionality of \verb+T1_errno+ is analogous to that of the global 3866\verb+errno+ in C programs. \verb+T1_errno+ is once set to 0 when the library 3867is initialized and never reset by any \tonelib-function. It is set to specific 3868values when specific types of errors appear. An application may then act 3869appropriately and reset \verb+T1_errno+. 3870The errors that might appear can be roughly split into three categories as 3871described below. 3872 3873\subsubsection{Type 1 Font File Scan-Errors} 3874These types of errors can only appear at the time a font file is loaded. 3875These kinds of errors are indicated by negative values: 3876\begin{itemize} 3877\item \verb+T1ERR_SCAN_FONT_FORMAT+ (-5): A Multiple Master Font was attempted 3878 to be loaded. These are not supported by \tonelib. 3879\item \verb+T1ERR_SCAN_FILE_OPEN_ERR+ (-4): This value indicates that the Type 3880 1 font file could not be opened by the parser. It usually does not mean that 3881 the file does not exist because this problem would have shown up at the time 3882 the font database had been built. It is more likely a permission problem. 3883 Anyhow, the C library variable \verb+errno+ should be examined for getting 3884 an idea of what the problem was. 3885\item \verb+T1ERR_SCAN_OUT_OF_MEMORY+ (-3): A Type 1 font program required 3886 more than 262144 bytes of VM. This is a limit imposed by \tonelib\ because 3887 it usually means there goes something wrong. Typical values of VM 3888 consumption are between 30000 and 60000 bytes depending on the fonts' 3889 complexity. If this limit really does not suffice the constant 3890 \verb+MAXTRIAL+ (defined in \verb+lib/type1/fontfcn.c+) may be set to some 3891 larger value. 3892\item \verb+T1ERR_SCAN_ERROR+ (-2): An error occurred during scanning the font 3893 file. It usually means that the font file is damaged or does not comply to 3894 the conventions of Type 1 font files. For example, an encountered token might 3895 have been too long. Another reason could be, a literal name follows a literal 3896 name where a number was expected. There is no way to recover from this 3897 error. One last resort could be to disassemble the font (e.g., using 3898 \verb+t1disasm+ from the \verb+t1utils+ package) and scan the resulting 3899 human-readable file for possible violations of the Type 1 font format 3900 specifications. However, some knowledge about the format is in force. 3901\item \verb+T1ERR_SCAN_FILE_EOF+ (-1): A premature end of file was encountered 3902 during parsing. The file is damaged. 3903\end{itemize} 3904 3905 3906\subsubsection{Path Generation Errors} 3907Small positive number are reserved for errors that might appear during path 3908construction and rasterization. 3909\begin{itemize} 3910\item \verb+T1ERR_PATH_ERROR+ (1): An error occurred during path 3911 construction. The font file is most probably damaged. 3912\item \verb+T1ERR_PARSE_ERROR+ (2): This kind of error describes a kind of 3913 ``semantic'' error in the font file. A typical candidate for this is a font 3914 that does not define a character named \verb+.notdef+, although this is 3915 required by the format specification. Since under usual conditions the 3916 \verb+.notdef+ character is never accessed, this error would not show 3917 up. But if for some reason the \verb+.notdef+ has to be substituted for some 3918 other character the problem becomes evident. 3919\item \verb+T1ERR_TYPE1_ABORT+ (3): The \verb+abort()+-function of the 3920 rasterizer has been called. This may happen at several places during 3921 hinting, converting to edgelists etc. There is a certain chance that 3922 unfreed memory has been left. If this error appears and a logfile is used, 3923 an error string giving some more info is placed into the logfile. 3924 3925 This error should not appear, normally. If it does, either the font file is 3926 damaged or the font contains invalid outline descriptions such as unclosed 3927 paths. Especially the latter is quite unlikely. Of course this error can be 3928 raised, when an outline has been modified manually in an invalid way and is 3929 then rastered (see.~\ref{outlinemanipulation}). 3930\end{itemize} 3931 3932\subsubsection{\tonelib-Errors} 3933The remaining types of errors are detected by the management of \tonelib. Their 3934numbering starts with 10 (decimal). The list could be extended in future 3935releases. 3936\begin{itemize} 3937\item \verb+T1ERR_INVALID_FONTID+ (10): An invalid font ID has been 3938 specified. The exact meaning of this error depends on the specific 3939 situation, in any case the operation requested cannot be realized with the 3940 identified font. Possible reasons are: 3941 \begin{itemize} 3942 \item The font ID points to a font which is not loaded and which must be 3943 loaded in order to perform the operation. 3944 \item The specified font ID is a number which is generally out of the range 3945 of the valid font IDs, either because it is $<0$ or because it is $>$ the 3946 value of \verb+no_fonts+. 3947 \item The library is not yet initialized so that no font ID at all is valid. 3948 \end{itemize} 3949\item \verb+T1ERR_INVALID_PARAMETER+ (11): One or more of the parameters 3950 specified to a function call were assigned invalid values. For example, a 3951 size-value specified to a rastering function must always be $>0$. Just the 3952 same way, \verb+T1_ConcatGlyphs()+ cannot concatenate two glyphs if one of 3953 them is the \verb+NULL+ pointer. 3954\item \verb+T1ERR_OP_NOT_PERMITTED+ (12): An operation that was not allowed 3955 {\em at that time} has been requested. This error could result, for example, 3956 if an application tries to set a new bitmap padding value after \tonelib\ 3957 has been initialized. 3958\item \verb+T1ERR_ALLOC_MEM+ (13): This error indicates that \tonelib\ ran out 3959 of memory and a memory allocation failed. This error should not appear. 3960\item \verb+T1ERR_FILE_OPEN_ERR+ (14): A file that was needed could not be 3961 opened by \tonelib. The file might have been necessary for reading data or 3962 writing data. For example, \verb+T1_WriteAFMFallbackFile()+ returns this 3963 value if the AFM file could not be opened for writing and 3964 \verb+T1_LoadEncoding()+ returns it if the encoding file specified as 3965 argument could not be opened. Notice that there is no indication of the 3966 reason why the file opening failed. The C library 3967 variable \verb+errno+ should be examined to analyze this further. 3968 3969 It should be mentioned that \verb+T1ERR_FILE_OPEN_ERR+ is only set if a file 3970 operation failed which was really in force. This means that at the time a 3971 font is loaded a missing AFM file does not cause \verb+T1_errno+ caused to 3972 be set to \verb+T1ERR_FILE_OPEN_ERR+. This is because \tonelib\ can 3973 automatically recover from this by generating AFM information on the fly (at 3974 the cost of computation time). 3975\item \verb+T1ERR_UNSPECIFIED+ (15): This value indicates nothing apart from 3976 that an error occurred and this error was not one the other errors. It can 3977 be considered a fallback. 3978\item \verb+T1ERR_NO_AFM_DATA+ (16): A function has been called which needs 3979 AFM information and AFM information is not available, either because all 3980 attempts to generate AFM data failed or because the flag \verb+T1_NO_AFM+ 3981 has been specified as part of the flag for \verb+T1_InitLib()+. 3982\item \verb+T1ERR_X11+ (17): An error in an X11 library function occured. This 3983 could be caused by calling a function of the X11 interface without prior 3984 initialization of the X11 interface via \verb+T1_SetX11Params()+. 3985\item \verb+T1ERR_COMPOSITE_CHAR+ (18): A request to compose a composite 3986 character could not be fulfilled without problems because at least one part 3987 of the composite character was not found in the \verb+CharStrings+ 3988 dictionary. This is bad because it indicates that font file and AFM file do 3989 match. Further errors or unsatisfactory rastering results have to be 3990 expected. 3991\item \verb+T1ERR_SCAN_ENCODING+ (19): Scanning an encoding file failed. Since 3992 \tonelib\ uses a fallback approach---DVIPS-encoding is tried first and 3993 afterwards \tonelib-encoding---it is not clear at which place exactly a 3994 failure occured. However, further hints about what \tonelib\ thought about 3995 the file in question may be found in the log file. 3996\end{itemize} 3997In analogy to the Standard C Library function \verb+strerror()+, \tonelib\ 3998provides the function 3999\precorr 4000\begin{verbatim} 4001 const char *T1_StrError( int t1err) 4002\end{verbatim}\index{\verb+T1_StrError()+}\postcorr 4003It returns a pointer to a string describing the error corresponding to 4004\verb+t1err+. Usually, the argument should be directly specified as 4005\verb+T1_errno+. The memory where the returned string is stored is static in 4006\tonelib\ so that it may not be \verb+free()+'d. 4007 4008 4009\subsection{Other Useful Functions} 4010\label{otherfunctions}% 4011This subsection describes a few functions that had not been described up to 4012now but which however could be useful. 4013 4014\precorr 4015\begin{verbatim} 4016 int T1_CheckEndian( void) 4017\end{verbatim}\index{\verb+T1_CheckEndian()+}\postcorr 4018This function may be used to check the endianess of the hardware \tonelib\ is 4019running on. The return value is \verb+0+ for Little Endian and \verb+1+ for 4020Big Endian machines. 4021 4022\precorr 4023\begin{verbatim} 4024 void T1_DumpGlyph( GLYPH *glyph) 4025\end{verbatim}\index{\verb+T1_DumpGlyph()+}\postcorr 4026This function might be useful for debugging and testing \tonelib. It dumps an 4027ASCII representation of the glyph pointed to by \verb+glyph+ to the standard 4028output. A background pixel is represented by \verb+.+ while a foreground pixel 4029is represented by \verb+X+. After the number of bits that correspond to the 4030current padding value, an empty column is inserted. See the output of the 4031programming example in \ref{programmingexample}. In this case the padding 4032values has been 16. 4033 4034Note that the size of the glyph should be small enough that its padded width 4035does not exceed the terminals line width. Otherwise the result might become 4036illegible. 4037 4038\precorr 4039\begin{verbatim} 4040 void T1_DumpPath( T1_OUTLINE *path) 4041\end{verbatim}\index{\verb+T1_DumpPath()+}\postcorr 4042This function dumps a description of an outline to the standard output. It is 4043exclusively intended for debugging purposes. 4044 4045 4046\precorr 4047\begin{verbatim} 4048 void T1_SetRasterFlags( int flags) 4049\end{verbatim}\index{\verb+T1_SetRasterFlags()+}\postcorr 4050This function allows to enable or disable certain features of the 4051rasterizer. Let me emphasize that this is exclusively intended for debugging 4052and error tracking. The default value of \verb+flags+ is 0 which means that no 4053debugging output is shown and hinting is performed as suggested in the {\em Adobe 4054Type Font Format}. However there may arise situations where fiddling with the 4055\verb+flags+ might be helpful in rasterizer and font debugging. 4056 4057\verb+flags+ usually is an OR'ed combination of the following definitions: 4058\begin{itemize} 4059\item \verb+T1_IGNORE_FORCEBOLD+ 4060\item \verb+T1_IGNORE_FAMILYALIGNMENT+ 4061\item \verb+T1_IGNORE_HINTING+ 4062\item \verb+T1_DEBUG_LINE+ 4063\item \verb+T1_DEBUG_REGION+ 4064\item \verb+T1_DEBUG_PATH+ 4065\item \verb+T1_DEBUG_FONT+ 4066\item \verb+T1_DEBUG_HINT+ 4067\end{itemize} 4068The \verb+T1_IGNORE_...+ types allow to selectively disable hinting. They 4069might be useful if parts of a font are not properly rendered. For example, 4070substituting a font's alignment zones by the family's alignment zones might 4071result in visual artifacts if the values for \verb+FamilyBlues+ are not 4072correct. Disabling family alignment might reveal the problem in such cases. 4073 4074The \verb+T1_DEBUG_...+ types produce debugging output from the intermediate 4075rasterizing steps. Notice that to understand this output a thorough 4076understanding of what happens in the rasterizer is in force. Moreover, be 4077prepared that thousands of lines might be written to the terminal, depending 4078on the particular option. 4079 4080%%% Local Variables: 4081%%% mode: latex 4082%%% TeX-master: "t1lib_doc" 4083%%% End: 4084