summaryrefslogtreecommitdiff
path: root/Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex')
-rw-r--r--Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex4083
1 files changed, 0 insertions, 4083 deletions
diff --git a/Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex b/Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex
deleted file mode 100644
index b0fd2b42fe0..00000000000
--- a/Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex
+++ /dev/null
@@ -1,4083 +0,0 @@
-%----------------------------------------------------------------------------
-% ----- File: ut1lib.tex
-% ----- Author: Rainer Menzner (Rainer.Menzner@web.de)
-% ----- Date: 2005-05-18
-% ----- Description: This file is part of the t1lib-documentation.
-% ----- Copyright: t1lib is copyrighted (c) Rainer Menzner, 1996-2005.
-% As of version 0.5, t1lib is distributed under the
-% GNU General Public Library License. The
-% conditions can be found in the files LICENSE and
-% LGPL, which should reside in the top level
-% directory of the distribution. Please note that
-% there are parts of t1lib that are subject to
-% other licenses:
-% The parseAFM-package is copyrighted by Adobe Systems
-% Inc.
-% The type1 rasterizer is copyrighted by IBM and the
-% X11-consortium.
-% ----- Warranties: Of course, there's NO WARRANTY OF ANY KIND :-)
-% ----- Credits: I want to thank IBM and the X11-consortium for making
-% their rasterizer freely available.
-% Also thanks to Piet Tutelaers for his ps2pk, from
-% which I took the rasterizer sources in a format
-% independ from X11.
-% Thanks to all people who make free software living!
-%----------------------------------------------------------------------------
-
-\newpage
-\section{Using \tonelib}
-This section describes in detail how to use \tonelib. I have tried to
-to describe the stuff in the order a new user would learn best and a new user
-would need to use the functions.
-
-
-\subsection{Compiling and Linking \tonelib-Programs}
-\label{compilingprograms}%
-A program that wants to use functions from the library must include
-the appropriate headers at compile time and then be linked with the
-appropriate libraries. Since V. 0.6-beta the X11 interface is separated
-from the \tonelib\ pivotal stuff. This yields advantages for programs that
-don't use the X11 rastering functions on systems where X11 is
-installed.
-The following applies to programs that do not use the X11 rastering
-functions:
-\begin{itemize}
-\item Include the file \verb+t1lib.h+. All definitions and declarations
- needed at compile time are included in this file.
-\item \verb+libt1.a+ or \verb+libt1.so+ respectively must be linked to the
- program.
-\end{itemize}
-In contrast, a program that uses the X11 interface must adhere to the
-following scheme:
-\begin{itemize}
-\item \verb+t1lib.h+ and \verb+t1libx.h+ must be included in this
- order. Furthermore, \verb+t1libx.h+ includes \verb+X11/Xlib.h+ if
- it is not already included.
-\item The libraries \verb+libt1.a+/\verb+libt1.so+ and
- \verb+libt1x.a+/\verb+libt1x.so+ must be linked to the executable.
- The correct order is \verb+-lt1x -lt1+ since the X interface uses
- functions from the latter. Also, the X11 library must appear in the
- library list after \verb+-lt1x+.
-\end{itemize}
-The Makefiles for \verb+xglyph+ and \verb+type1afm+ are typical
-examples for both configurations.
-
-
-\subsection{Querying and Setting Fundamental Configuration Parameters of \tonelib}
-\label{queryconfiguration}%
-It might be necessary to know whether \tonelib\ is compiled with or without
-X11 interface. At compile time a programmer can check for the X11 interface by
-stating
-\begin{verbatim}
-#ifdef T1LIB_X11_SUPPORT
-\end{verbatim}
-after including \verb+t1libx.h+. If \verb+T1LIB_X11_SUPPORT+ is not defined,
-the X11 interface is not configured and compiled.
-
-At runtime, a program can check for the X11 interface by a call to
-\precorr
-\begin{verbatim}
- int T1_QueryX11Support( void)
-\end{verbatim}\index{\verb+T1_QueryX11Support()+}\postcorr
-It returns \verb+1+ if the X11 interface is present and \verb+0+ otherwise.
-
-Notice that querying X11 support at runtime and compile time tends to
-be pretty useless starting with V.~0.6-beta. Any decision can be done
-by examining the existence of the \verb+t1x+-library and the
-\verb+t1libx.h+ header file. The definition and the function described
-above are thus only provided for compatibility with pre-0.6 versions
-of \tonelib.
-
-Some remarks on the general data format of bitmaps and should be given
-here. \tonelib\ internally always generates bitmaps in the way that appears to
-be natural for them: The first pixel corresponds to the least significant bit
-in a byte (or word/longword). Bytes are always arranged in memory the way,
-that the first byte is at the lowest address and the next byte at the
-following address. This convention is called LSBFirst which stands for Least
-Significant Bit/Byte First. It is the natural way of data alignment on
-machines with {\em Little Endian} data representation. In contrast MSBFirst
-stands for Most Significant Bit/Byte First which is the natural kind of data
-representation on Big Endian machines.
-A glyph's scanlines are always aligned in LSBFirst-type, no matter on what
-machine \tonelib\ is running.
-
-What has been said above, strictly does only apply to non antialiased glyphs,
-i.e., real bitmaps. Antialiased glyphs have their gray values coded in the
-representation that is natural for the machine \tonelib\ is running on. For
-example, if \tonelib\ runs on a Big Endian machine, the gray values are in Big
-Endian. The X11 displaying functions automatically handle this correct.
-
-Scanlines of \tonelib-glyphs may be padded to 8, 16 or 32 bit. Padding to
-higher values will consume more memory for the glyphs, but might speed up
-concatenating of bitmaps as described in \ref{generatingbitmaps}. This applies
-to machines with Little Endian representation as, for example, Intel's
-$x$86 series. On these machines 16 or 32 bits can be placed into the
-target bitmap in one step. On machines with Big Endian representation, for
-example, Motorola 680$x$0 series, this is currently not possible. However,
-using a higher padding value could still yield a better performance since the
-application could work on larger units than a byte.
-
-The default padding value in \tonelib\ is 8 bit. The padding value can be
-specified at runtime by means of calling
-\precorr
-\begin{verbatim}
- int T1_SetBitmapPad( int pad)
-\end{verbatim}\index{\verb+T1_SetBitmapPad()+}\postcorr
-\verb+pad+ must be one of `8', `16' or `32'. The call will only be successful
-if executed before initialization of \tonelib. This a security mechanism which
-prevents from having glyphs with distinct padding values. The return value is
-0 if successful and -1 if \verb+pad+ was invalid or \tonelib\ had already been
-initialized.
-
-There is a further restriction concerning the padding value. Setting it to 32
-is only possible if the machine has an ANSI C integer type of 64 bits. This
-condition is automatically checked by the \verb+configure+ script of \tonelib.
-If such an integer type is not present (or has to be emulated as e.g.\
-\verb+long long+ in \verb+gcc+) there would not result any performance gain.
-If a specified padding value is rejected, \verb+T1_errno+ is set
-appropriately.
-
-An application can query the current padding value by calling
-\precorr
-\begin{verbatim}
- int T1_GetBitmapPad( void)
-\end{verbatim}\index{\verb+T1_GetBitmapPad()+}\postcorr
-The returned value is the padding value. This function can be called before or
-after initialization of \tonelib.
-
-Another function usually be called near
-initialization is
-\precorr
-\begin{verbatim}
- int T1_SetDeviceResolutions(float x_res, float y_res)
-\end{verbatim}\index{\verb+T1_SetDeviceResolutions()+}\postcorr
-This function allows setting the resolution of
-your device (screen). The values must be given in dpi. The default
-resolution, 72 dpi, implies that a pixel in device space equals 1
-bp. This function may be called before or after initialization. The
-only restriction is that no size dependent data must be
-available. Changing the resolution when bitmaps are already cached would
-result in inconsistent bitmap-sizes for bitmaps generated before and
-after the call to \verb+T1_SetDeviceResolutions()+.
-The function checks whether initialization has already been done. If
-not, all is OK since no size-dependent data for any font can exist. If
-initialization has been done, it checks for every font whether size
-dependent data exists. If there's any size dependent data for any
-font, \verb+T1_SetDeviceResolutions()+ will return \verb+-1+ without
-having set the new resolution. Otherwise the specified resolution will
-be set and the function will return \verb+0+.
-If you really need to set
-another resolution in the middle of a session, all size-specific data
-should explicitly be removed from memory beforehand. This can be
-achieved using \verb+T1_DeleteAllSizes()+ (see \ref{deletingdata}).
-
-Notice that the device resolution need not be set at all if the default
-resolution of 72 dpi in horizontal and vertical direction is OK. This function
-is primarily intended to be prepared for applications with a device aspect
-ratio different from 1.
-
-\subsection{Initialization of \tonelib\ and Related Things}
-\label{initialization}%
-In this section we should cover the initialization, part of which has already
-been described in \ref{runtimesetup} in some more detail. This gives the user
-the chance to fine-tune the initialization for specific applications.
-
-Prior to be able to do anything useful with \tonelib, the library has to be
-initialized. Generally speaking, the purpose of the initialization is to tell
-\tonelib\ which font files are associated with which font ID's. The existence
-or accessibility of the font files is also assured at this point. Hence, file
-name search paths for Type 1 font files, AFM files and encoding files have
-also to be known at this time.
-
-The configuration file and the font database file play a central r\^ole
-during initialization. While the configuration file contains path
-specifications and a font database specification, the font database file
-specifies the relation between font ID's and font filenames.
-The format of both these files is described in \ref{runtimesetup} and not
-repeated here.
-
-A further purpose of the initialization is to set certain flags that prevent
-other quantities from being modified at a later time. For example, the padding
-value must be unique to all glyphs and consequently it is not allowed to be
-changed after initialization has been performed.
-
-The initialization is started by a call to the function
-\precorr
-\begin{verbatim}
- void *T1_InitLib( int log)
-\end{verbatim}\index{\verb+T1_InitLib()+}\postcorr
-The parameter \verb+log+ can be interpreted as a mode specification that
-influences certain parts of the initialization. In fact it should consist of
-one or more \verb+#define+s from \verb+t1lib.h+. At minimum, \verb+log+
-should be either \verb+LOGFILE+ or \verb+NO_LOGFILE+. If \verb+LOGFILE+ is
-specified, a log file is written while the application runs, and
-\verb+NO_LOGFILE+ suppresses the generation of a logfile. For information the
-\tonelib-logfile see \ref{logfile}. In addition to this,
-\verb+IGNORE_CONFIGFILE+ and \verb+IGNORE_FONTDATABASE+ can be bitwise OR'ed
-(using ``\verb+|+'') to the \verb+log+-value. The purpose of this is described
-later in this section. A further flag that might find its way into the value
-of \verb+log+ is \verb+T1_AA_CACHING+. A discussion of this topic is given in
-\ref{aacaching}.
-The \verb+T1_NO_AFM+ completely suppresses usage of AFM data, no matter if an
-AFM file could have been found using the current search paths or not. This
-saves time for loading a font and is recommended if an application is known to
-be restricted on functions that do not access AFM data. The consequences of
-using this flag are covered somewhat more detailed in \ref{generatingafminfo}.
-
-
-\subsubsection{Standard Initialization}
-\label{standardinitialization}%
-The term ``standard initialization'' means, that none of the path manipulating
-and font database manipulating actions described later has been
-performed. Also, a standard initialization excludes the use of
-\verb+IGNORE_CONFIGFILE+ and \verb+IGNORE_FONTDATABASE+. If these conditions
-are met, the following happens at initialization time:
-\begin{enumerate}
-\item The padding value, either being the default value or a value specified
- by the user before, is assigned.
-\item Next, depending on the value of \verb+log+, a logfile is tried to be
- opened. From this point on, depending on the loglevel and the value of
- \verb+log+ the actions are logged.
-\item The endianess of the machine \tonelib\ is running on is checked.
-\item A configuration file is searched in the following order:
- \begin{itemize}
- \item The process' environment is checked for the entry \verb+T1LIB_CONFIG+
- and if found, its value is interpreted as the filename of the configuration
- file (see \ref{runtimesetup}).
- \item If no file was found, the user's home directory is searched for a file
- named \verb+.t1librc+. In case it exists, it is used as a
- \tonelib-configuration file.
- \item If still no configuration file was found, the global configuration
- file will be tried to be opened.
- \item If this also does not succeed, all file search paths are left to be
- ``.'' and the default font database is \verb+FontDataBase+.
- \end{itemize}
- It should be noted that the first match wins when searching the configuration
- file. Only the first one found is examined.
-\item The font database file(s) are tried to be opened and read. This process
- is in detail described in \ref{fontdatabase}.
-
- If after scanning the complete list of font databases, no font definitions
- have been performed, \verb+T1_InitLib()+ will return with a \verb+NULL+
- pointer indicating the initialization has failed.
-\item The number of fonts declared in the database is stored. Note that this
- number of declared fonts must be greater than zero.
-\item A flag is set to indicate \tonelib\ is initialized and the pointer to
- the top most area of the global data structures is returned to the
- application. This pointer is guaranteed to be not \verb+NULL+.
-\end{enumerate}
-For some applications, the described initialization scheme appears to be too
-inflexible and overkill. It is well suited for large applications that use
-lots of fonts and where it should be possible to add new fonts without
-modifying the application itself. For small commandline applications like
-\verb+type1afm+ (see \ref{type1afm}), which are designed to read a few font file
-names from the commandline, the overhead in configuration file searching and
-path reading is much too large. Moreover, to insist on a font database file
-might grow to a real disadvantage. In the subsequent paragraphs we should thus
-discuss how we can deviate from the initialization scheme described above.
-
-\subsubsection{Fine Control over Font Databases and File Search Paths}
-\label{manipulatingpaths}%
-First, it is important to mention that it is generally possible to force
-\verb+T1_InitLib()+ to skip steps 4 and / or 5 as described above.
-
-The configuration file is discarded by OR'ing the parameter \verb+log+ of
-\verb+T1_InitLib()+ with \verb+IGNORE_CONFIGFILE+.
-The default paths or the paths explicitly specified by the application before
-are then left untouched during initialization.
-
-Discarding the font database specification from the configuration file is
-achieved by bitwise OR'ing \verb+log+ with \verb+IGNORE_FONTDATABASE+. The
-result after initialization will be an empty database. This is valid in V.\
-0.5 and newer since fonts may be added to the database at runtime.
-
-Using the two flags described above, an installed setup can be ignored and an
-application may have complete control over its search paths. There are a
-number of functions for this purpose and each of these functions allows to
-specify exactly {\em one} path element at a given time. Using special
-characters like white space or path separators in a path element is thus not
-an issue.
-
-The font database may explicitly be specified by the
-application using \precorr
-\begin{verbatim}
- int T1_SetFontDataBase( char *filename)
-\end{verbatim}\index{\verb+T1_SetFontDataBase()+}\postcorr
-\verb+filename+ is the pointer to a string containing the name of the font
-database file that is to be examined. This function replaces any set of font
-databases setup previously and is thus usually to be called before
-\verb+T1_InitLib()+. A call to this function after initialization will return
-the result -1 and \verb+T1_errno+ will be set to
-\verb+T1ERR_OP_NOT_PERMITTED+. For the special case that the font database is
-still epmty after initialization this function may also be called after
-initialization. But in any case, the database must be empty! For the latter
-cases, fonts specified in the new database file are then immediately inserted
-into the database. In case of success, the number of available fonts is returned.
-
-There is also the function \precorr
-\begin{verbatim}
- int T1_AddFontDataBase( int mode, char *filename)
-\end{verbatim}\index{\verb+T1_AddFontDataBase()+}\postcorr
-It can be called at any time and \verb+filename+ is the string of the new font
-database's file name. If called before initialization, the parameter
-\verb+mode+ can be either \verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+ and
-the name of the new font database simply is either appended or prepended to
-the existing list of font databases. Then, the function returns $0$.
-
-If the function is called after initialization, the parameter \verb+mode+ is
-ignored and the new database is appended in any case, because this is the only
-meaningful action. Furthermore, the new database is immediately loaded and the
-function returns a number indicating the number of available fonts
-(which can also be 0). In the case of an error, \verb+T1_AddFontDataBase()+
-returns $-1$.
-
-There is also a pair of functions that act on the list of XLFD font database
-files,
-\precorr
-\begin{verbatim}
- int T1_SetFontDataBaseXLFD( char *filename)
-\end{verbatim}\index{\verb+T1_SetFontDataBaseXLFD()+}\postcorr
-\precorr
-\begin{verbatim}
- int T1_AddFontDataBaseXLFD( char *filename)
-\end{verbatim}\index{\verb+T1_AddFontDataBaseXLFD()+}\postcorr
-These functions have exactly the same syntax and semantics as the functions
-just described above. Standard font database files and XLFD font database
-files are handled in separate lists internally, so that setting the XLFD font
-database will not affect explicit standard font database settings. However,
-the default standard font database (\verb+./FontDataBase+) will be cleared
-when at least one XLFD font database is specified. This is because the default
-font database is meant as a fallback, and the fallback case is no longer given
-if a XLFD font database has been specified.
-
-A similar manipulation as just described for font database files, is
-possible for the searchpaths. (Re-)Defining a search
-path is done by calling
-\precorr
-\begin{verbatim}
- int T1_SetFileSearchPath( int type, char *pathname)
-\end{verbatim}\index{\verb+T1_SetFileSearchPath()+}\postcorr
-before calling \verb+T1_InitLib()+, or respectively, before the database
-contains any fonts. An attempt to set the file searchpaths when the database
-is no longer empty is denied. The reason is that it is not wise to override
-the searchpaths which had been valid previously during the verification of the
-existence of font files. Such paths should thus not be removed. The parameter
-\verb+pathname+ points to the string that contains the pathname that should be
-used as searchpath. The parameter \verb+type+ is any OR'ed combination of
-\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and \verb+T1_ENC_PATH+. These tell the
-function to set the search paths for Type 1 font files, AFM files and encoding
-files, respectively. In case of an error \verb+-1+ is returned and otherwise
-\verb+0+.
-
-Extending the file searchpaths before {\em and} after initialization
-is possible using
-\precorr
-\begin{verbatim}
- int T1_AddToFileSearchPath( int pathtype, int mode, char *pathname)
-\end{verbatim}\index{\verb+T1_AddToFileSearchPath()+}\postcorr
-This might be useful to locate font files that were of no interest
-at the time of initialization.
-\verb+pathname+ is the pointer to the string that should be added to the
-searchpaths. Only {\em one} particular path element may be specified in one
-call. What searchpaths are affected is determined by the parameter
-\verb+pathtype+. Again, similar to described above, any
-OR'ed combination of \verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and
-\verb+T1_ENC_PATH+ is valid. There are two ways to extend an existing
-searchpath which are specified by the \verb+mode+ parameter. It must be either
-\verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+, which causes the new path
-element to be appended or prepended to the existent path respectively.
-Since an existent path specification is not overwritten by
-\verb+T1_AddToFileSearchPath()+, this function may be called at any time
-before or after initialization.
-
-It might also be of interest to query the current file search
-paths and font databases. \tonelib\ provides
-\precorr
-\begin{verbatim}
- char *T1_GetFileSearchPath( int type)
-\end{verbatim}\index{\verb+T1_GetFileSearchPath()+}\postcorr
-for querying search paths. Again, the parameter \verb+type+ determines what
-search path is returned. Exactly one of \verb+T1_PFAB_PATH+,
-\verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and \verb+T1_FDB_PATH+ should be
-specified. If more than one path is specified, the first match wins and only
-one path is returned. The types will be checked in the order
-\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and
-\verb+T1_FDB_PATH+. Here, \verb+T1_FDB_PATH+ indicates an interest in the list
-of font databases. The paths are separated using the current path separator.
-
-
-\subsubsection{Adding Fonts to the Database}
-\label{addingfonts}%
-Extending the font database is possible at any time after initialization. In
-addition to using \verb+T1_AddFontDataBase()+ (see above), it is done via a
-call to \precorr
-\begin{verbatim}
- int T1_AddFont( char *fontfilename)
-\end{verbatim}\index{\verb+T1_AddFont()+}\postcorr
-\verb+fontfilename+ is the pointer to the filename string. The following
-actions take place:
-\begin{itemize}
-\item The font file is searched using the current search path specifications.
-\item If the file has been located, it is checked whether the font database
- contains enough memory to hose an additional font.
- If so, the font filename
- is stored and the function returns \verb+new_ID+, which is the font ID that
- will be associated with this font in the future.
-\item If there was no free memory for an additional font, the memory is
- reallocated to a greater size. This involves also resetting the new
- area. Finally the value \verb+new_ID+ is returned.
-\end{itemize}
-If a negative value is returned the function failed. \verb+-1+ indicates the
-font file could not be located. \verb+-2+ or \verb+-3+ are returned if a
-memory allocation failure occurs.
-
-
-\subsubsection{Summary of Search Path Handling}
-
-Since the exact handling of search path specifications at the several stages
-may appear somewhat confusing we shall summarize the exact rules now:
-\begin{enumerate}
-\item {\bfseries Before Initialization}\\
- Default paths are not yet setup. Each call of one of the \verb+T1_Set...()+
- functions described above establishes a completely new respective path. Each
- call of one of the \verb+T1_Add...()+ functions extends the respective path
- in the desired manner, or creates a new respective path if previously no
- path existed.
-\item {\bfseries At the Beginning of the Initialization}\\
- Each path type for which a path had not already been explicitly created
- using the\\ \verb+T1_Set...()+ or \verb+T1_Add...()+ functions receives a
- default value. This is ``\verb+.+'' for the file search paths and
- \verb+./FontDataBase+ for the font database.
-\item {\bfseries During Initialization}\\
- Each path element read from the configuration file overwrites an existing
- respective default path but preserves an existing respective explicitly
- setup path by appending to the latter. The newly setup search path is used
- to locate files while scanning the font database file(s).
-\item {\bfseries After Inititialization but before the Database is being
- filled}\\
- At this stage, all \verb+T1_Set...()+ and \verb+T1_Add...()+ functions still
- work as described under~(1). Notice that this phase usually is not
- accessible when using the standard initialization scheme. It only becomes
- accessible if no fonts have been added during initialization.
-\item {\bfseries After at least one Font is insterted into the Database}\\
- Once there are fonts in the database, the paths setup up
- to now must be preserved in any case. Hence, the \verb+T1_Set...()+ may not
- be called any longer. The \verb+T1_Add...()+ functions {\em extend} the
- current set of search paths. In particular, possibly existing default search
- path elements, then, are not overwritten any longer because they might have
- been used before to verify the existance of required files.
-\end{enumerate}
-A call to \verb+T1_AddFontDataBase()+ will not only append the specified
-file name to the existing list of databases, but will also immediately
-locate the fonts specified therein and assign additional font IDs.
-
-
-\subsubsection{Bypassing the \tonelib\ File Search Machinery}
-\label{afmfilenames}%
-Usually, \tonelib\ takes care for locating files according to the path
-specifications in the configuration file. There might, however, arise the need
-to explicitly tell \tonelib\ which particular file to use. Forcing \tonelib\ to
-use particular Type 1 font files can be achieved using the function
-\verb+T1_AddFont()+, described just above. If a pathname passed to this
-function is a complete path, \tonelib\ will use this complete path to locate
-the font file, forgetting about its own search path list. A filename path is
-assumed to be complete if
-\begin{itemize}
-\item it starts with the directory separator character, usually
- ``\verb+/+''. In this case it is an {\em absolute} path specification, meaning
- that the start point is at the root of the filesystem, or
-\item if it starts with ``\verb+./+'' or ``\verb+../+'' (where it is assumed
- that ``\verb+/+'' is the directory separator character). Here we have a {\em
- relative} path specification in which ``\verb+.+'' refers to the current
- working directory while ``\verb+..+'' refers to the parent directory of the
- current working directory. Since the notion of the {\em current working
- directory} is fundamental for every process that has access to a
- filesystem, a relative path specification also uniquely identifies one
- particular file in the filesystem.
-\end{itemize}
-If a font file whose complete path had been specified could not be found by
-\tonelib, the paths from the configuration file are searched as a fallback
-mechanism.
-
-What can be done for the Type 1 font files is also possible for AFM files,
-which are needed on a per-font basis. The function
-\precorr
-\begin{verbatim}
- int T1_SetAfmFileName( int FontID, char *afm_name)
-\end{verbatim}\index{\verb+T1_SetAfmFileName()+}\postcorr
-allows to set the complete path of the AFM file belonging to the font
-identified by \verb+FontID+, overriding the internal
-search mechanism. This function is to be called after initialization but
-before the font \verb+FontID+ is loaded. It returns 0 if all goes right and
-$-1$ otherwise. In the latter case \verb+T1_errno+ will also be set
-appropriately. Notice that \verb+FontID+ must also be valid with respect to
-its upper limit, it is an error condition if the font database has less than
-\verb+FontID+ entries.
-
-There is also the function
-\precorr
-\begin{verbatim}
- char *T1_GetAfmFileName( int FontID)
-\end{verbatim}\index{\verb+T1_GetAfmFileName()+}\postcorr
-which allows to query the AFM filename of a font. It returns a pointer to the
-filename if it had explicitly been specified or \verb+NULL+
-otherwise. \verb+NULL+ will also be returned if \verb+FontID+ was invalid. In
-this case also \verb+T1_errno+ will be set.
-
-Just for the sake of completeness we should mention that what has been said
-about absolute and relative path specification
-also applies to pathnames for encoding files (see \ref{encoding}).
-
-
-
-
-\subsection{The \tonelib-Logfile}
-\label{logfile}%
-Since version 0.2-beta \tonelib\ supports a runtime logfile.
-It implements an uncomplicated way to keep track of errors,
-warnings, statistics and debug messages without overloading stdout/stderr. As
-seen in \ref{initialization} the user must specify whether or not to use a
-logfile when calling \verb+T1_InitLib()+. Specifying \verb+LOGFILE+ as
-argument leads to using a logfile and \verb+NO_LOGFILE+ suppresses the use of a
-logfile.
-
-The name of this logfile is by default \verb+t1lib.log+. This name is defined
-in \verb+t1misc.h+ and can be changed there as the user likes.
-
-Basically \tonelib\ distinguishes 4 types of runtime messages. Each type is
-associated a ``loglevel'':
-\begin{itemize}
-\item {\sl Errormessages/Level1:}\/ They are considered that important that the user is
- in any case informed. Example: During initialization the memory allocation for
- one of the basic data structures of \tonelib\ failed.
-\item {\sl Warningmessages/Level2:}\/ They are considered important but it is not
- absolutely necessary to inform the user. Example: An AFM file could not be
- loaded for a given font. This imposes several restrictions on what can be
- done with that font but it is possible to generate bitmaps.
-\item {\sl Infomessages/Level3:}\/ They do not indicate a problem. Rather, the user
- is notified about some facts and statistics that might be of
- interest. Example: After loading a font the consumption of virtual memory is
- displayed.
-\item {\sl Debugmessages/Level4:}\/ These can be pointers, numerical data
- etc. Example: Print out the pointers that point to the memory area where the
- PostScript dictionaries for a font just loaded are located.
-\end{itemize}
-The decision what message to put into the logfile is done by examining the
-value of an integer variable whose values can be \verb+T1LOG_ERROR+ (=1),
-\verb+T1LOG_WARNING+ (=2), \verb+T1LOG_STATISTIC+ (=3) or \verb+T1LOG_DEBUG+
-(=4). All messages whose level is below or equal to this value are put into the
-logfile. The user may set this loglevel by calling
-\precorr
-\begin{verbatim}
- void T1_SetLogLevel( int level)
-\end{verbatim}\index{\verb+T1_SetLogLevel()+}\postcorr
-The default value is \verb+T1LOG_WARNING+ which means that error and warning
-messages are stored in the logfile.
-
-If the usage of a logfile has been specified, \tonelib\ tries first to open
-it in the current directory. If this fails for some reason \tonelib\ tries
-to create it in the user's home directory. If this fails too, an error message
-is printed to stderr and no logfile is used.
-
-If the application programmer chose not to create a logfile, it would be hardly
-possible for a user to track down possible problems, e.g. in file
-searching. To overcome this disadvantage, the user may set an environment
-variable \verb+T1LIB_LOGMODE+ at runtime. This variable is evaluated by
-\tonelib\ when \verb+T1_InitLib()+ is called. If its value is one of the
-four strings \verb+logDebug+, \verb+logStatistic+ \verb+logWarning+ and
-\verb+logError+, the respective loglevel is set by \tonelib\ and a log file is
-created, even if the programmer chose not to do so. However, if the programmer
-had altered the log level after calling \verb+T1_InitLib()+, this cannot be
-catched by setting the environment variable. A log file is created anyhow so
-that at least error messages will be logged.
-
-The user himself may also put some messages into the logfile. This can be
-achieved using
-\precorr
-\begin{verbatim}
- void T1_PrintLog( char *func_ident, char *msg_txt, int level, ...)
-\end{verbatim}\index{\verb+T1_PrintLog()+}\postcorr
-where \verb+func_ident+ is a pointer to a string identifying the function that
-generates the message. \verb+msg_txt+ points to the text string to put
-out. The distinction between a function identifier and a message text is only
-formal, indicating the user should identify the function that generates the
-message.
-
-The string \verb+msg_txt+ may contain format character sequences, \verb+%..+ ,
-as known from the \verb+printf+- or \verb+scanf+ standard \verb+C+
-functions. In this case, the ellipses indicate that a variable list of further
-arguments may follow. The \verb+level+ specification works as
-described above: The message is only put out if the internal loglevel is
-equal or greater than \verb+level+.
-
-Here is a typical example of a log file after a (short)
-\verb+xglyph+-session in which the loglevel was set
-\verb+T1LOG_STATISTIC+. Among several informative messages of type S, also two
-messages of type W have been generated. They stem from trying to
-raster the character ``\ss'' which was not in the current encoding.
-\par\noindent
-{%
-\tiny
-\begin{verbatim}
-(S) (Mon Jul 14 18:27:34 1997) T1_InitLib(): Initialization started
-(S) (Mon Jul 14 18:27:34 1997) T1_InitLib(): Initialization succesfully finished
-(S) (Mon Jul 14 18:27:44 1997) T1_LoadFont(): VM for Font 0: 35132 bytes
-(S) (Mon Jul 14 18:27:44 1997) CreateNewFontSize(): New Size 100.000000 created for FontID 0 (antialias=0)
-(S) (Mon Jul 14 18:27:53 1997) CreateNewFontSize(): New Size 100.000000 created for FontID 0 (antialias=1)
-(S) (Mon Jul 14 18:27:53 1997) CreateNewFontSize(): New Size 200.000000 created for FontID 0 (antialias=0)
-(W) (Mon Jul 14 18:27:53 1997) T1_SetChar(): No black pixels found for character 223 from font 0, returning NULL
-(W) (Mon Jul 14 18:27:53 1997) T1_SetStringX(): T1_SetChar() returned NULL-pointer!
-(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 200.000000 deleted for FontID 0 (antialias=0)
-(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 100.000000 deleted for FontID 0 (antialias=0)
-(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 100.000000 deleted for FontID 0 (antialias=1)
-\end{verbatim}
-}
-
-\subsection{Generating Bitmaps}
-\label{generatingbitmaps}%
-At this point, you are able to generate a bitmap.
-As said before, a character- or string-bitmap is given to the user as
-an object of type \verb+GLYPH+. We should briefly explain \verb+GLYPH+
-here. The type is defined by
-\begin{verbatim}
-typedef struct
-{
- char *bits;
- struct
- {
- int ascent;
- int descent;
- int leftSideBearing;
- int rightSideBearing;
- int advanceX;
- int advanceY;
- } metrics;
- void *pFontCacheInfo;
- unsigned long bpp;
-} GLYPH;
-\end{verbatim}
-\verb+bits+ is a pointer to the bitmap data. The
-bitmap is organized in lines, starting with the uppermost line.
-Each bitmap pixel is usually represented by one bit. If the width of
-the
-bitmap is not an integer multiple of 8, the lines are padded with
-zeros, so that each line starts at a byte boundary. Note that the
-bitmap has no margins taken into account. The bitmap occupies the
-minimum area the character needs to be painted.
-
-The bitmap pointer may also be
-the \verb+NULL+-pointer. In this case, the glyph contains no foreground
-pixels. The metrics of the corresponding glyph should be valid,
-though. Typically, this appears for the space character as well as in
-situations where an undefined or unencoded character had been substituted by
-the \verb+.notdef+-character within the rastering functions.
-
-Note that the \verb+pixmap+-entry which has been present in version 0.3-beta,
-has been removed with version 0.4-beta. See the discussion on the X11-interface
-in \ref{x11interface} for an explanation of this.
-
-The struct \verb+metrics+ contains metric information that is needed
-to position the character and to describe the character origin
-with respect to the bitmap. The members in detail:
-\begin{itemize}
-\item \verb+metrics.ascent+: describes how many lines the bitmap
- ranges above the line $y=0$.
-\item \verb+metrics.descent+: describes how many lines the bitmap
- ranges below the line $y=0$. Width below $y=0$ counts negative so that the
- difference \verb+ascent+ $-$ \verb+descent+ is the
- total height of the bitmap, the number of lines.
-\item \verb+metrics.leftSideBearing+: The amount of spacing between
- the origin of a character and the x-coordinate of its leftmost
- painted pixel. One could also name it ``left margin'' of the
- character.
-\item \verb+metrics.rightSideBearing+: The horizontal difference between
- the origin of a character and the x-coordinate of its rightmost
- painted pixel. This definition stands in contrast to some other
- interpretations of the right side bearing, where it is assumed as the
- difference between the glyph's width and its right most pixel.
-\item \verb+metrics.advanceX+: The amount of position increment in
- horizontal direction after this character
- bitmap (or string bitmap) has been placed. It is almost always
- larger than the bitmap width because most characters contain a
- certain amount of margins. Note that this value is not suitable for internal
- computations of character positions since it contains the horizontal
- escapement rounded to the pixel grid. Using this value for such computations
- leads to accumulating positioning errors.
-\item \verb+metrics.advanceY+: The amount of position increment in
- vertical direction after this character
- bitmap (or string bitmap) has been placed. Upper direction counts positive.
-\end{itemize}
-As seen, the width of the bitmap is given as the difference between
-\verb+rightSideBearing+ and \verb+leftSideBearing+ and the values
-\verb+metrics.leftSideBearing+, \verb+metrics.descent+,\\
-\verb+metrics.rightSideBearing+ and \verb+metrics.ascent+ effectively describe
-the bounding box of the glyph.
-
-The entry \verb+pFontCacheInfo+ is not currently used but will
-probably later when font caching is really
-implemented. Moreover, there's a certain chance that some other
-entry will be added in future releases.
-
-The member \verb+bpp+ is used to store the depth of the bitmap. For
-true bitmaps, it is always 1. See \ref{antialiasing} for an
-explanation.
-
-There are three basic functions which produce pointer to glyph objects. In
-order to generate the glyph for a single character you would use the
-function
-\precorr
-\begin{verbatim}
- GLYPH *T1_SetChar( int FontID, char charcode,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_SetChar()+}\postcorr
-As in most other functions, \verb+FontID+ is a valid identification
-number of a font. It can range from 0 to $n-1$, where $n$ is number of
-fonts declared in the font database file.
-
-The second argument \verb+charcode+ determines the character that will
-be rasterized.
-As mentioned earlier, the encoding mechanism is used for
-accessing the output character. This means, if \verb+'A'+ is given as
-the character code, the machine representation of \verb+'A'+ is used
-as an index into the current encoding vector. In this encoding vector,
-the characters' name is looked up. Encoding vectors may be changed by
-the user (see \ref{encoding}).
-
-
-The parameter \verb+size+ is interpreted in Postscript's bigpoint-unit
-(bp). By default,
-1 bp equals one device pixel.
-
-\verb+transform+ specifies the transformation that will be applied to the
-character before rastering. If this pointer is \verb+NULL+, no transformation
-is used. Otherwise it should point to a valid \tonelib-transformation matrix.
-Please refer to \ref{transformations} for information on how to easily create
-\verb+T1_TMATRIX+ matrices.
-Hinting is only performed if the transformation is a pure rotation and if the
-the angle is one of 0, 90, 180 or 270 degrees. Otherwise font level and
-character level hinting information is ignored.
-
-Bitmaps of transformed characters are never saved in
-cache memory since I assume that they are rarely needed. The overhead
-to manage transformed characters in cache would be overkill and would
-significantly increase memory consuming. Anyhow, this would only work
-for some dedicated transformations.
-
-\verb+T1_SetChar()+ in fact does some more things than simply
-rastering the specified character:
-\begin{itemize}
-\item It checks whether the font in question is already loaded. If not,
- it is loaded.
-\item If the size dependent data structures for the size in question
- do not exist, it creates them and inserts them in the linked list of
- size dependent data structures.
-\item It checks if the character is already existent in cache. If so,
- it returns the data from cache.
-\end{itemize}
-
-Some words concerning memory management: The memory used by
-the \verb+GLYPH+-structure is static in this function. The memory
-required for the bitmap is also allocated by the function itself.
-This means, the user doesn't need to free any memory by
-himself. Every time \verb+T1_SetChar()+ is called, it starts by giving the
-memory needed for the last generated glyph free or respectively
-setting metric values to 0. Thus, do not free the
-returned glyph pointer since later \verb+T1_SetChar()+ will free
-memory that is no more allocated and probably used for some other purpose.
-If you really like to free the memory, set the pointer to \verb+NULL+
-afterwards.
-
-If an error occurs at some point, \verb+T1_SetChar()+ returns a
-NULL-pointer to the user.
-
-Frequently it is advantageous to raster a series of
-characters at once. This has the advantage that internal accuracy may
-be used and the overhead for the user is minimal. For such cases, the
-function
-\precorr
-\begin{verbatim}
- GLYPH *T1_SetString( int FontID, char *string, int len,
- long spaceoff, int modflag,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_SetString()+}\postcorr
-is provided.
-It can be considered an extended version of \verb+T1_SetChar()+. The
-same as said above applies to the arguments \verb+FontID+,
-\verb+size+ and \verb+transform+. But a few additional arguments are
-needed here.
-
-\verb+string+ is a series of bytes representing the indices into the current
-encoding vector.
-The \verb+len+-parameter is needed because we cannot imply that string
-is always an object like a string in C. For example, the Computer
-Modern Roman fonts contain the uppercase Greek Gamma (\char0) at
-position 0 in their internal encoding. In a string to be typeset the
-value 0 is thus a valid value and deserves no special
-treatment. Hence, we cannot not use the C-function \verb+strlen()+ to
-compute the length of the string. However, since in most usual encodings
-the special value 0 is not encoded (``\verb+.notdef+''), it makes
-sense to switch between
-standard situations and non-standard situations:
-\begin{itemize}
-\item If \verb+string+ is a string conforming with C-semantics,
- \verb+len+ can be set to 0. Then, the length of the string is
- internally computed.
-\item If \verb+string+ contains one or more control characters which make
- processing impossible, the \verb+len+-value must be specified
- explicitly.
-\end{itemize}
-
-The \verb+spaceoff+ parameter is important for word processing
-purposes. The value specified here is interpreted as an offset to the
-space width used during rastering. It is interpreted in charspace
-units, i.e., $1/1000$ bp. Every time a space character is requested,
-this amount of horizontal escapement is added to the natural
-spacewidth of the current font. Note that the space character itself
-is actually not rastered. All requests to the character with the
-charactername ``\verb+space+'' are caught by \tonelib\ and converted
-to a simple horizontal escapement. For computation of the resulting
-spacewidth, the width of the space-character is taken from the
-AFM data and merged with the specified offset, which may also be
-negative.\footnote{One consequence of this handling is, that---with a
- little tricking---fonts that do not define a space character
- themselves may be used for typesetting. This applies to the
- dc-fonts, which only define a visible space, but no real space (see
- \ref{fonts}).}
-
-The \verb+modflag+ argument may be used to specify some option to the
-rastering function. It is generally 0 or an OR'ed combination of the following
-names:
-\begin{itemize}
-\item \verb+T1_KERNING+: As the name implies, this argument
- determines that pairwise kerning information from the AFM file is to be taken
- into account during string rastering. Not specifying \verb+T1_KERNING+
- means: ``omit kerning''. It is generally
- recommended to use kerning information since this improves the optical
- appearance. However, many lower quality fonts do not have kerning
- information. With \tonelib\ V.\ 0.4-beta, kerning information is accessible
- much faster than before because it is based on char codes rather than on
- characternames.
-\item \verb+T1_RIGHT_TO_LEFT+: Setting this flag will invert the writing
- direction. In {\em Right-To-Left} mode the escapement in writing direction
- (left) is inserted before placing the character with the result that the
- character laps over to the left side. This principle is kept for all
- characters in the string. Note that metrics of fonts that are intended for
- {\em Right-To-Left} typesetting have the same meaning as for fonts intended
- for standard ({\em Left-To-Right}) typesetting.
-\item \verb+T1_UNDERLINE+: The string to be rastered is to be underlined
- according to the line specifications of the current font.
-\item \verb+T1_OVERLINE+: The string to be rastered is to be over lined.
-\item \verb+T1_OVERSTRIKE+: Same here for overstriking.
-\end{itemize}
-For a description of underlining and such, see \ref{underlining}. Notice also
-that the \verb+modflag+ argument is a replacement of the \verb+kerning+
-argument from pre-0.7 versions of \tonelib.
-
-Concerning glyph-memory considerations, the same applies as said under
-the description of \verb+T1_SetChar()+: Never free a pointer to memory
-which was returned by \verb+T1_SetString()+. Or, alternatively, if freeing
-the pointer cannot be avoided set it to NULL after freeing it.\footnote{For
- example, {\tt XDestroyImage()} gives the pixel memory for the image
- data free although it might not have been allocated by any X11-function.}
-
-There are two generic ways how a string-glyph can be produced. The first is to
-take the paths of all characters needed, concatenate them, insert space and
-kerning amounts as needed and raster the resulting whole path. This will yield
-the best results since the average position accuracy of the pixels will be
-optimal. This applies especially for rotated strings. The drawback is, that
-every character must be rastered every time it is needed. There is no way to
-access the bitmap data of a character inside a rastered string separate from
-others. And the caching of string-glyphs at this programming level doesn't
-make any sense. So this principle takes significantly longer than
-concatenating bitmaps from a cache area. However, it is done when the
-specified rotation angle is not equal to $0^\circ$ or when even further
-transformation are to be applied. This condition should limit the total
-number of situations when this happens to an amount we can easily bear.
-
-If the \verb+transform+-argument is \verb+NULL+ we know transformations or
-rotation should not be applied and another approach is used. We are then able
-to construct the resulting bitmap by adjusting already existent bitmaps into
-proper positions. If a character does not already exist in the cache, it is
-generated just the way \verb+T1_SetChar()+ works. The calculation of the
-character-bitmap positions in the output bitmap is done with
-char space-precision. Nonetheless, there may be differences in the output
-compared with output of the above method. These are caused by the fact that
-rounding to pixel accuracy has already been achieved when generating the
-character bitmap. Thus, the output of the above principle should always be
-better since the positions of the black pixels are rounded with respect to the
-whole string, and not with respect to a single character glyph. On the other
-hand, concatenating character glyphs takes significantly less time than
-rastering a complete string. Theoretically, differences of up to two pixels
-horizontal shift may appear in the output of the two principles. You can
-check the effect by running the program \verb+xglyph+. Specify a string of
-enough length and raster it at angle $0^\circ$. Then specify a very small
-angle from 0 different, say, $0.001^\circ$, and raster the string again with
-the new setting. You might find that the representation of the string is a
-little different now.
-
-The third function that creates a glyph object is
-\precorr
-\begin{verbatim}
- GLYPH* T1_SetRect( int FontID, float size,
- float width, float height,
- T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_SetRect()+}\postcorr
-Calling this function yields a filled rectangle. It is intended for situations
-where a \TeX-style \verb+\vrule+ would be appropriate, or, for equations in
-mathematical typesetting.
-
-First, the argument \verb+FontID+ identifies a valid font. At this time, it is
-not obvious why a valid font is required in order to create a rectangular
-glyph. The reason is, that some of the parameters that are associated to a
-particular font are also relevant for creating rectangles in the context of
-that font. Hence, specifying a font identifier in this case is a means of
-stating ``{\em draw a rectangle that visually fits to the style of the font
- \verb+FontID+}''. Aside from this, I assume that each application that uses
-\tonelib\ deals with at least {\em one} font so that the \verb+FontID+
-parameter actually does not hurt.
-
-The size of the rectangle is to be specified in charspace units by means of
-the parameters \verb+width+ and \verb+height+, and is moreover subject to
-scaling through the parameter \verb+size+. By definition, the typographical
-fundamental area of a font, known as the {\em em-square}, is just as high and
-as wide as the design size of the font. In charspace units, this rectangle
-exactly maps to a $1000 \times 1000$ grid. Or alternatively spoken, one
-charspace unit is 0.001bp (Big Point). For example, in order to draw an
-em-square for some font at 13 points, the correct parameters are
-\hbox{\verb+size+ $= 13$}, \hbox{\verb+width+ $= 1000$} and
-\hbox{\verb+height+ $= 1000$}. If absolute physical dimensions are desired,
-the scaling explicitly must be calculated by the user. For instance, in order to
-produce a $ 1 \mathrm{cm} \times 1 \mathrm{cm}$ square we find
-\begin{displaymath}
-h = w = 1\mathrm{cm} \frac{72\mathrm{bp}/\mathrm{in} \times
- 1000\mathrm{cs}/\mathrm{bp}}{2.54\mathrm{cm}/\mathrm{in}}
-\approx 28346\;\mathrm{cs.}
-\end{displaymath}
-Here ``cs'' designates charspace units and \verb+size+ is assumed to be $1$.
-Note that still the device resolution must be properly setup in order to make
-the dimensions appear accurately on the device.
-
-The parameter \verb+transform+ is a pointer to a \tonelib\ transformation
-matrix. If it is \verb+NULL+, the current transformation of the font in
-question is used. Depending on the kind of actual transformation, the
-rectangle might also image as a nonrectangular shape. This happens, if the
-current font is slanted, then the rectangle will be skewed.
-
-Glyphs produced by the rectangle function are never cached because there is
-no means in doing so. With respect to memory management, the same applies as
-for \verb+T1_SetChar()+ and \verb+T1_SetString()+. Since rectangles rarely are
-used to produce normal text flow, the glyphs produced by the rectangle
-function do not cause any escapement.
-
-
-If two glyphs with arbitrary orientation exist,
-\precorr
-\begin{verbatim}
- GLYPH *T1_ConcatGlyphs( GLYPH *glyph1, GLYPH *glyph2,
- int x_off, int y_off, int modflag)
-\end{verbatim}\index{\verb+T1_ConcatGlyphs()+}\postcorr
-can be used to concatenate them. First the size of the resulting glyph is
-computed and its metric values are filled. Then, the two glyphs are placed at
-their appropriate positions in the newly created bitmap. In order to be able
-to work, the following conditions must be met:
-\begin{enumerate}
-\item Either glyph must be different from \verb+NULL+.
-\item Both glyphs must have identical \verb+bpp+-values. If antialiased and
- non-antialiased glyphs are to be concatenated, have a look at
-\item There must be enough memory for the new glyph (naturally).
-\end{enumerate}
-The quantities \verb+x_off+ and \verb+y_off+ describe the $x$- and
-$y$-component of an optional offset to be inserted between the two
-glyphs. This offset is interpreted as device pixels. The \verb+modflag+
-argument is used to specify the direction in which the two glyphs are to be
-concatenated. That is, only the bit \verb+T1_LEFT_TO_RIGHT+ /
-\verb+T1_RIGHT_TO_LEFT+ is respected by this function.
-
-If problems occur, \verb+NULL+ is returned.
-It is generally not recommended to produce large glyphs with this function
-because the char space precision in placing the character bitmaps is lost. For
-example, three times rounding up an advance by 0.3 pixels accumulates to 1
-pixel position error. A similar effect shows up when two rotated and underlined
-glyphs are concatenated with this function. There might be a slight shift in the
-baseline at the point where the two glyphs touch.
-
-A dilemma occurs, if two antialiased bitmaps have distinct background
-colors. Then, it is not clear what the transparent color
-is. \verb+T1_ConcatGlyphs()+ always assumes the {\em current} background color
-to be transparent.
-
-
-There is one more function that generates pointers to glyphs:
-\precorr
-\begin{verbatim}
- GLYPH *T1_CopyGlyph(GLYPH *glyph)
-\end{verbatim}\index{\verb+T1_CopyGlyph()+}\postcorr
-As mentioned earlier, the user doesn't have the possibility of keeping
-the
-glyphs longer than to the next call of the respective rastering function. If
-someone wants to keep a bitmap some time longer,
-\verb+T1_CopyGlyph()+ may be used
-to copy the glyph to another area which is then completely under user's
-control. This function simply does the following:
-\begin{itemize}
-\item Allocates the memory for the glyph-structure.
-\item If bitmap data is present, it allocates memory for the bitmap data,
- taking the member \verb+bpp+ into account (see \ref{antialiasing}).
-\item Copies the structure and the bitmap data to the respective locations.
-\item Initializes the pointer \verb+glyph.bits+.
-\end{itemize}
-
-Return value is the pointer to the allocated glyph-structure. If something
-goes wrong, NULL is returned to indicate an error. A glyph pointer,
-returned by a call to this function should be freed by a call to
-\verb+T1_FreeGlyph()+ (see \ref{deletingdata}).
-
-
-\subsection{Loading Fonts Explicitly}
-\label{loading}%
-Usually there is no need for a user to load a font into memory since this is
-done automatically as needed by the rastering functions. But there are two
-situations where it makes sense to explicitly load a font before generating
-any size dependent data:
-\begin{itemize}
-\item A font is to be reencoded immediately after loading (see \ref{encoding}).
-\item A font is to be transformed (see \ref{transformations}).
-\end{itemize}
-These operations require a font being loaded but not having any size specific
-data. Loading a font explicitly is done by the function
-\precorr
-\begin{verbatim}
- int T1_LoadFont( int FontID)
-\end{verbatim}\index{\verb+T1_LoadFont()+}\postcorr
-Loading a font involves several actions:
-\begin{itemize}
-\item Locating and loading the Type 1 font file.
-\item Locating and loading the font metrics data from AFM file.
-\item Computing and filling the values of the \verb+FONTPRIVATE+ structure as
- described in section \ref{internals}.
-\item Setting up some tables for fast access of metrics information.
-\end{itemize}
-\verb+T1_LoadFont()+ returns \verb+0+ if successful or \verb+-1+ if the font
-could not be loaded. A failure may be due to \tonelib\ not having been
-initialized or due to problems with file locations and file parsing. If a font
-refuses to load, the logfile should be examined first. Furthermore, in case of
-a failure \verb+T1_errno+ will be set appropriately.
-
-
-\subsection{Functions for Encoding Handling}
-\label{encoding}%
-As mentioned earlier, the encoding mechanism used in the
-PostScript-language allows a font to contain more than 256 different
-characters, although only 256 are accessible at a given time. The
-characters which are accessible are given by the elements of the
-current {\em encoding vector}. In order to maximize flexibility,
-\tonelib\ allows for changing the current encoding vector. This is
-also called ``Reencoding a font''. A new encoding vector is defined
-and made known to the library by creating an encoding-file and loading
-its contents into memory.
-Before describing the functions needed for this, we should
-briefly describe the format of an encoding file.
-
-An encoding file is an ASCII text file. No
-assumptions about filename extensions are made. Here are the rules for
-scanning the file:
-\begin{itemize}
-\item The file contents are completely ignored until a line is encountered
- that starts with the string \verb+Encoding=+. This string may optionally be
- immediately followed by a string that is assumed to be the identifier of the
- {\em encoding scheme} that this file defines. Any further text on this line
- is ignored.
-\item Now, 256 lines have to follow, each line describing one
- character's name. The string ranging from the beginning of the line
- to the first white space character is assumed to be a character
- name. The remainder of the lines is ignored and may (should) be used
- for comments, thereby describing the current character code.
-\item All further lines of text are ignored.
-\end{itemize}
-As well known from PostScript, non-existent characters have to be
-named \verb+.notdef+.
-
-Here's an example of such an encoding file:
-\begin{verbatim}
-Sample encoding file for t1lib!
-The first two lines are considered to be comments!
-Encoding=ISOLatin1Encoding
-.notdef /* '000 000 "00 */
-.notdef /* '001 001 "01 */
-.notdef /* '002 002 "02 */
- . .
- . .
- . .
-greater /* '076 062 "3E */
-question /* '077 063 "3F */
-at /* '100 064 "40 */
-A /* '101 065 "41 */
-B /* '102 066 "42 */
- . .
- . .
- . .
-yacute /* '375 253 "FD */
-thorn /* '376 254 "FE */
-ydieresis /* '377 255 "FF */
-\end{verbatim}
-
-Since V.~1.2, \tonelib\ is also able to load encoding files in the format used
-by \verb+dvips+. This makes a large set of existing encoding files available
-to the user. When parsing \verb+dvips+ encoding files, \tonelib\ requires
-PostScript syntax. This means white space may be interspersed freely and
-line comments are defined by the character \%. The mark-characters, \verb+[+
-and\verb+]+, are considered as special tokens and need not be preceded or
-followed by white space. Similarly, the literal escape character \verb+/+
-delimits a preceding token without interspersed white space. When parsing
-\verb+dvips+ encoding files, \tonelib\ tolerates less than 256 character name
-definitions. If characters are missing, they are substituted by \verb+.notdef+
-until the counter reaches $256$. Aside from comments, no PostScript tokens are
-allowed after the encoding definition in a \verb+dvips+ encoding file is
-complete.
-
-With the defining terms above, it turns out that a file which has successfully
-been scanned as a \verb+dvips+ encoding file, cannot specify a valid \tonelib\
-encoding after the PostScript encoding definition is complete (because no
-valid character name can start with \% and because at least a line such as
-\verb+Encoding=+, would have to follow the PostScript encoding). Hence the
-file format are mutually exclusive and it is possible to read both format
-using one function. In a first pass \tonelib\ tries to read the file as a
-\verb+dvips+ encoding file, and if that fails, it assumes to have a \tonelib\
-encoding file.
-
-
-Once such an encoding file of either type has been created, it can be loaded
-into memory. This is done with the function
-\precorr
-\begin{verbatim}
- char **T1_LoadEncoding( char *filename)
-\end{verbatim}\index{\verb+T1_LoadEncoding()+}\postcorr
-The function will use the search path definitions read from
-the configuration file during initialization (see
-\ref{runtimesetup}, \verb+ENCODING=+). If no
-errors occur, an array of pointers to strings is created and
-initialized. The start address of this pointer array is returned as a
-double pointer to a char. This pointer is intended
-to be used to reencode a font via \verb+T1_ReencodeFont()+. If the encoding
-data structure could not be created, \verb+NULL+ is returned to indicate the
-error.
-
-The memory allocated by \verb+T1_LoadEncoding()+ is organized in two
-continuous blocks. One block is the pointer array of size 257\footnote{This
- number results from 256 charactername pointers plus one pointer to the
- encoding scheme identifier.} and the
-other block contains the character name strings plus the encoding scheme
-specification, separated by
-ASCII-zeros.
-This memory can be returned to the system using the function
-\precorr
-\begin{verbatim}
- int T1_DeleteEncoding( char **Encoding)
-\end{verbatim}\index{\verb+T1_DeleteEncoding()+}\postcorr
-\tonelib\ does not check whether a valid pointer value was passed. So be
-careful to pass the correct pointer. An error in this function should almost
-always be followed by a segmentation violation.
-
-A newly loaded encoding is applied to an existent font by
-calling
-\precorr
-\begin{verbatim}
- int T1_ReencodeFont( int FontID, char **Encoding)
-\end{verbatim}\index{\verb+T1_ReencodeFont()+}\postcorr
-\verb+FontID+ must be a valid font identification and
-\verb+Encoding+ a pointer returned from a
-successful call to \verb+T1_LoadEncoding()+.
-
-There are two requirements
-in order to reencode a font:
-\begin{enumerate}
-\item The font must already have been loaded into memory.
-\item No size-dependent data exists for this font. If
- it does, it must be removed explicitly prior to calling
- \verb+T1_ReencodeFont()+.
-\end{enumerate}
-
-It follows that there are two ways to reencode a font. The first is
-to load a font explicitly and reencode it before any size dependent
-data is created. The second is to use an automatically loaded font
-and delete all of its size dependent data before reencoding it.
-
-The user may also specify the special pointer NULL as the
-\verb+Encoding+-argument. This would reencode the font to its internal
-encoding vector.
-
-In case of success, the function returns 0, otherwise -1 is returned.
-
-Reencoding a font takes a considerable amount of time since the mapping tables
-have to be reorganized. In situations where it is \`a priori foreseeable that the
-font will be reencoded using some standard encoding vector, it makes sense to
-assign that particular encoding vector as the default encoding vector,
-thereby overwriting the internal encoding vector of each font at load time
-before the mapping tables are setup. Setting the default encoding can be
-achieved using
-\precorr
-\begin{verbatim}
- int T1_SetDefaultEncoding( char **Encoding)
-\end{verbatim}\index{\verb+T1_SetDefaultEncoding()+}\postcorr
-Here \verb+Encoding+ encoding is assumed to be a valid \tonelib\ encoding
-vector, e.g., created by a call to \verb+T1_LoadEncoding+.
-\verb+T1_SetDefaultEncoding()+ has to be called after initialization. It
-returns \verb+0+ if this condition is fulfilled and \verb+-1+
-otherwise. In the latter case \verb+T1_errno+ is set appropriately.
-Notice that the internal encoding of the font is still accessible by
-reencoding the font using \verb+NULL+ as encoding specification (see above).
-Note further that the default encoding vector is only applied to those font
-that have \verb+StandardEncoding+ as internal encoding. This is to prevent
-fonts like ZapfDingbats, Symbol or Sonata\footnote{A musical notation font.}
-from being reencoded automatically at load time because this would be
-surely inappropriate for such fonts.
-
-It is also possible to query the encoding scheme that the font associated with
-\verb+FontID+ uses. This is achieved with the function
-\precorr
-\begin{verbatim}
- char *T1_GetEncodingScheme( int FontID)
-\end{verbatim}\index{\verb+T1_GetEncodingScheme()+}\postcorr
-The return value is a pointer to a string which describes the encoding scheme
-in question. The are 3 possible cases:
-\begin{itemize}
-\item The font uses Adobe StandardEncoding, which is internally known by the
- rasterizer. Then, \verb+StandardEncoding+ is returned.
-\item The font defines its own encoding by \hbox{\verb+dup+ $n$ {\em
- LiteralName} \verb+put+} statements. In this case no particular name is
- associated with the encoding scheme and \verb+FontSpecific+ is returned.
-\item The encoding is externally loaded by \verb+T1_LoadEncoding()+. Then the
- encoding scheme entry of this file is returned. If this (optional) entry is
- not specified in the file, \verb+Unspecified+ is returned.
-\end{itemize}
-Notice that the name of the encoding scheme is also accessible as
-\verb+Encoding[256]+ where \verb+Encoding+ is the pointer returned by a
-successful call to \verb+T1_LoadEncoding()+.
-
-\subsection{Deleting Data}
-\label{deletingdata}%
-In frequently appearing cases, it may be wise to return some memory
-which was explicitly
-or automatically allocated by the library back to the
-system.\footnote{This is especially true, since there is presently no
- caching algorithm which automatically takes care of this.} For
-this purpose
-some functions are available. To understand how size dependent
-data for a font is organized, see (\ref{internals}).
-
-The memory amount required by the size-dependent data of \verb+size+
-and font \verb+FontID+ is freed by calling the function
-\precorr
-\begin{verbatim}
- int T1_DeleteSize( int FontID, float size)
-\end{verbatim}\index{\verb+T1_DeleteSize()+}\postcorr
-The data deleted includes the metric
-information for 256 characters, some pointers, associated bitmap data (if
-already existent) as well as the font matrix for that size.
-
-As described in section \ref{internals}, the data structures containing
-size-dependent information of a particular font are organized as a
-linked list. \verb+T1_DeleteSize()+ takes care that a properly linked
-list is left after deleting the data.
-
-If the combination of \verb+size+ and \verb+FontID+ does not exist, -1
-is returned. If the operation was successful, the return value is 0.
-
-For the purpose of removing all size-dependent data for a particular
-font, there is the function
-\precorr
-\begin{verbatim}
- int T1_DeleteAllSizes( int FontID)
-\end{verbatim}\index{\verb+T1_DeleteAllSizes()+}\postcorr
-It recursively removes all size-dependent data for the font
-\verb+FontID+. This may be appropriate if a user knows some font not
-to be needed any longer. This function is also to be used, if one intends to
-reencode a font for
-which size dependent data has already been generated. In addition,
- font transformations
-such as {\em slanting} and {\em extending}
-require a font having no size-specific data.
-\verb+T1_DeleteAllSizes()+ recursively calls \verb+T1_DeleteSize()+ to
-do its job.
-It returns the number of sizes removed (including 0 if no sizes were
-existent) or -1 if an error occurred.
-
-It is also possible to remove the entire data associated with a
-particular font from memory using
-\precorr
-\begin{verbatim}
- int T1_DeleteFont( int FontID)
-\end{verbatim}\index{\verb+T1_DeleteFont()+}\postcorr
-\verb+T1_DeleteFont()+ goes one step beyond the above functions and
-removes all the data associated with the font \verb+FontID+. This
-includes:
-\begin{itemize}
-\item All size dependent data.
-\item All data from the Type 1 font program, held in memory.
-\item All AFM data kept in memory.
-\end{itemize}
-The memory reserved for a font in hierarchy-level 1 is not returned to
-the system since it is simply one element in the array of structures of
-type \verb+FONTPRIVATE+ (see \ref{internals}). But all entries in this
-structure are reset to initial values.
-
-Whether it is useful or not, a font that has been removed using
-\verb+T1_DeleteFont()+ may also be loaded again, explicitly or
-implicitly.
-
-There is a restriction, which has not yet been mentioned: A font may only be
-removed if it is a physical font (to be explained later) to which no logical
-fonts refer or if it is a logical font.\footnote{See \ref{logicalfonts} for
- explanation of logical fonts.} A reference counter is maintained in each
-physical font to check for this. If the font to be removed is a logical font,
-the \verb+FONTPRIVATE+ area is reset and the reference counter of the
-referenced physical font is decremented. Of course, size dependent data is
-removed in every case.
-
-\verb+T1_DeleteFont()+ returns 0 if the font has been removed correctly or if
-the font was not loaded. $n$ ($>0$) is returned if
-the font was physical and was referenced by $n$ logical fonts. A
-return value -1 indicates an invalid \verb+FontID+.
-
-The function
-\precorr
-\begin{verbatim}
- int T1_FreeGlyph( GLYPH *glyph)
-\end{verbatim}\index{\verb+T1_FreeGlyph()+}\postcorr
-returns memory allocated by
-\verb+T1_CopyGlyph()+ back to the system. This function should not be
-applied to the pointer to a glyph returned by one of the rastering
-functions. As said earlier, these functions manage the memory areas by
-themselves.
-
-Similarly, the function
-\precorr
-\begin{verbatim}
- int T1_FreeCompCharData( T1_COMP_CHAR_INFO *cci)
-\end{verbatim}\index{\verb+T1_FreeCompCharData()+}\postcorr
-returns memory associated to the composite caracter data structures, as
-allocated and returned by \verb+T1_GetCompCharData()+ or
-\verb+T1_GetCompCharDataByIndex()+ (see
-Section~\ref{subsec:CompositeCharacters}), to the system. In order to avoid
-memory leaks, each call of the latter two functions should be followed by a
-call to this function.
-
-
-In order to close the library and return all memory to the system,
-\precorr
-\begin{verbatim}
- int T1_CloseLib( void)
-\end{verbatim}\index{\verb+T1_CloseLib()+}\postcorr
-should be used. If no problems occur, 0 is returned. The value 1 indicates
-problems during freeing data. In this case the logfile should be examined.
-After having freed all data the file search paths, if different from the
-defaults, are restored. Last, the logfile is closed.
-
-
-\subsection{Underlining, Overlining and Overstriking}
-\label{underlining}%
-\tonelib\ supports underlining, overlining and overstriking for the string
-rastering functions. These lines are always drawn on the fly as the bitmaps
-are generated. In writing direction, the lines range from the glyph's origin
-to the glyph's width. The vertical dimensions are set the following way by
-default when a font is loaded:
-\begin{itemize}
-\item {\bf Underlining}: Underline position and thickness are taken from the
- Fontinfo dictionary of the respective font. The rule is vertically centered
- with respect to the mathematical line given by the position value.
-\item {\bf Overlining}: The position is computed to be $y=a+|u|$ where $a$
- corresponds to the typographic ascender and $u$ is the underline position
- from the Fontinfo dictionary. As above, the rule is vertically centered
- around this position value. The thickness is set to underline thickness.
-\item {\bf Overstriking}: The position is $y=a/2$ where again $a$ is the
- typographic ascender of the font and vertical alignment of the rule is done
- by centering around the computed position. The thickness is set to underline
- thickness.
-\end{itemize}
-As all information in AFM files, thickness and position specifications are
-interpreted in charspace units.
-
-Notice that the typographic ascender is not determined by the Type 1 font
-program. It has to be guessed by \tonelib. The problem of guessing the
-typographic ascender is discussed in more detail in \ref{writingafmfiles}.
-When loading a font, this typographic ascender is assumed to be the vertical
-coordinate of the upper right corner of the bounding box of the letter ``d''.
-This is not as advanced as the procedure described in \ref{writingafmfiles},
-but it suffices because the underlining positions can later be overwritten by
-the user (see below).
-
-From the mathematical point of view, the line rules are an integral part of
-the rastered path. It follows that line rules may appear sheared if a font has
-been artificially slanted and the size and/or thickness is sufficiently large.
-
-A look into real Type 1 font files shows that even fonts of the same family
-possess incompatible values for underlining. For example, Bitstream Charter
-Roman defines underline thickness to be 61 and its bold variant assigns a
-value of 90. Underlining text consisting of Roman and bold words will not be
-very pleasing using these values. For this reason \tonelib\ provides a way for
-explicitly setting and overwriting the default values for line ruling on a
-per-font level. The functions
-\precorr
-\begin{verbatim}
- int T1_SetLinePosition( int FontID, int linetype, float value)
-\end{verbatim}\index{\verb+T1_SetLinePosition()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- int T1_SetLineThickness( int FontID, int linetype, float value)
-\end{verbatim}\index{\verb+T1_SetLineThickness()+}\postcorr
-set the respective value for font \verb+FontID+ to \verb+value+.
-The \verb+linetype+ argument is assumed to be an OR'ed combination of
-\verb+T1_UNDERLINE+, \verb+T1_OVERLINE+ and \verb+T1_OVERSTRIKE+. While it
-generally does not make sense to specify identical positions for two or three
-distinct line rule types, it is meaningful to specify identical thickness
-values for two or all rules types. However both functions accept combinations
-of linetype specification.
-It follows that consistent line ruling for several fonts can be achieved by
-setting the line rule parameters of the involved fonts to identical respective
-values.
-
-Currently active line rule parameters can be queried using the functions
-\precorr
-\begin{verbatim}
- float T1_GetLinePosition( int FontID, int linetype)
-\end{verbatim}\index{\verb+T1_GetLinePosition()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- float T1_GetLineThickness( int FontID, int linetype)
-\end{verbatim}\index{\verb+T1_GetLineThickness()+}\postcorr
-In case more than one line rule type is specified for
-\verb+linetype+ the first matching value is returned,
-since obviously the functions can only return {\em one} value. The order the
-argument is checked is \verb+T1_UNDERLINE+, \verb+T1_OVERLINE+ and
-finally \verb+T1_OVERSTRIKE+.
-
-These functions called with \verb+T1_UNDERLINE+ as line type argument should
-not be confused with the functions \verb+T1_GetUnderlinePosition()+ and
-\verb+T1_GetUnderlineThickness()+ respectively. The latter functions will
-always return the values from the Fontinfo dictionary as opposed to the former
-which will return the currently active values.
-
-Since line ruling is done on the fly, it is possible to change the involved
-parameters in the middle of a session without confusing the cache or removing
-size dependent data.
-
-
-\subsection{Common Information on Fonts and Characters}
-\label{common}%
-This subsection describes some functions making common information
-available. This includes Type 1 and AFM data. Thus, these
-functions partially depend on the existence of AFM data. In order not
-to have to specify this data every time, here are a few conventions:
-\begin{enumerate}
-\item \verb+FontID+ is the valid ID of a declared font.
-\item All functions that require a character index as argument
- use the currently active encoding vector to determine the
- character's name
- belonging to this index and use the character's name to search for the
- information required.
-\item Some functions do not allow to use the return value for error
- checking. For this reason every function described in this subsection will
- set \verb+T1_errno+ appropriately if something goes wrong. See
- \ref{errorhandling} for the description of the possible values of
- \verb+T1_errno+.
-\item None of the functions described in this subsection will load a font
- automatically.
-\end{enumerate}
-
-\subsubsection{Information from FontInfo-Dictionary}
-\label{fontinfodict}%
-\precorr
-\begin{verbatim}
- char *T1_GetFontName( int FontID)
-\end{verbatim}\index{\verb+T1_GetFontName()+}\postcorr
-This function returns the string object \verb+FontName+ from the
-fontinfo-dictionary of the specified font or a NULL pointer if the font is not
-loaded.
-
-The memory for the returned string is static in this function and should thus
-not be freed by the user. As another consequence, the returned
-string is only constant until the function is called the next time.
-
-\precorr
-\begin{verbatim}
- char *T1_GetFullName( int FontID)
-\end{verbatim}\index{\verb+T1_GetFullName()+}\postcorr
-This function returns the string object \verb+FullName+ from the
-fontinfo-dictionary of the specified font or a NULL pointer if the font is not
-loaded.
-
-The memory for the returned string is static in this function and should thus
-not be freed by the user. As another consequence, the returned
-string is only constant until the function is called the next time.
-
-\precorr
-\begin{verbatim}
- char *T1_GetFamilyName( int FontID)
-\end{verbatim}\index{\verb+T1_GetFamilyName()+}\postcorr
-This function returns the string object \verb+FamilyName+ from the
-fontinfo-dictionary of the specified font or a NULL pointer if the font is not
-loaded.
-
-The memory for the returned string is static in this function and should thus
-not be freed by the user. As another consequence, the returned
-string is only constant until the function is called the next time.
-
-\precorr
-\begin{verbatim}
- char *T1_GetWeight( int FontID)
-\end{verbatim}\index{\verb+T1_GetWeight()+}\postcorr
-It returns the Weight entry from fontinfo dictionary. It is a string
-entry and represents a verbatim classification of the font rather than
-a numerical quantity. In case of an error \verb+NULL+ is returned.
-
-\precorr
-\begin{verbatim}
- float T1_GetItalicAngle( int FontID)
-\end{verbatim}\index{\verb+T1_GetItalicAngle()+}\postcorr
-The returned value is the italic angle of the font in degrees as a
-float. Notice that the meaning of ItalicAngle is related to the slanting
-of fonts, but not in the sense of \tonelib\ (see
-\ref{transformations}).
-An italic font may be artificially slanted and an artificially slanted
-font in the sense of \tonelib\ may have an italic angle of zero.
-
-\precorr
-\begin{verbatim}
- int T1_GetIsFixedPitch( int FontID)
-\end{verbatim}\index{\verb+T1_GetIsFixedPitch()+}\postcorr
-This function returns 0 if the font's spacing is proportional and 1 if
-it is fixed.
-
-\precorr
-\begin{verbatim}
- BBox T1_GetFontBBox( int FontID)
-\end{verbatim}\index{\verb+T1_GetFontBBox()+}\postcorr
-This function returns the bounding box of the font identified by
-\verb+FontID+. It is the bounding box that
-results if all characters of a font are overlayed with their reference point
-falling on the point (0,0). All values are in charspace units. The members
-\verb+lly+ and \verb+urx+ represent the fonts overall descent and ascent,
-respectively.
-
-The font's bounding box is part of the AFM information as well as member in
-the font's private dictionary. It turns out that the information from
-\verb+.afm+- and \verb+.pfa+/\verb+.pfb+-file is not consistent for some
-fonts. \tonelib\ returns the information stored in the font-file itself, since
-I assume it is more consistent to the font's data.
-
-\precorr
-\begin{verbatim}
- float T1_GetUnderlinePosition( int FontID)
-\end{verbatim}\index{\verb+T1_GetUnderlinePosition()+}\postcorr
-This function returns the underline position of the specified font as given in
-the fontinfo-dictionary. The value is to be interpreted in charspace
-units. If the font is not loaded, 0 is returned since an
-underline position of 0 can be considered impossible for most fonts.
-
-\precorr
-\begin{verbatim}
- float T1_GetUnderlineThickness( int FontID)
-\end{verbatim}\index{\verb+T1_GetUnderlineThickness()+}\postcorr
-This function returns the thickness of the underlining rule for this font or 0
-if the font is not loaded. 0 is a safe index for an error since a rule of
-height 0 would not be visible anyhow.
-
-\precorr
-\begin{verbatim}
- char *T1_GetVersion( int FontID)
-\end{verbatim}\index{\verb+T1_GetVersion()+}\postcorr
-The version string from the Type 1 font file is returned. The memory
-where the string is located is managed by the function itself.
-
-\precorr
-\begin{verbatim}
- char *T1_GetNotice( int FontID)
-\end{verbatim}\index{\verb+T1_GetNotice()+}\postcorr
-The notice string from the Type 1 font file is returned. Again the
-user should not touch the memory where the string is located.
-
-\subsubsection{Metric Information on Glyphs}
-\label{metricinformation}%
-\precorr
-\begin{verbatim}
- int T1_GetCharWidth( int FontID, char char1)
-\end{verbatim}\index{\verb+T1_GetCharWidth()+}\postcorr
-The character width according to the AFM information is returned in charspace
-units. If no AFM information is available, 0 is returned.
-
-The width of a
-character is the amount of horizontal escapement that the next character is
-shifted to the right with respect to the current position. This information is
-not given in the character's bounding box. Also, the width corresponds to the
-entry \verb+characterWidth+ in the \verb+glyph+-structure, as described in
-\ref{generatingbitmaps}. But since \verb+T1_GetCharWidth()+, returns its
-result in charspace units, the accuracy is much higher than using the value
-of the \verb+glyph+-structure which has only pixel-accuracy.
-
-If there is an extension specified for the font in question, the characters
-width is corrected correspondingly.
-
-\precorr
-\begin{verbatim}
- BBox T1_GetCharBBox( int FontID, char char1)
-\end{verbatim}\index{\verb+T1_GetCharBBox()+}\postcorr
-The character's bounding box of \verb+char1+ is returned with the elements to
-be interpreted in charspace units. The bounding box of a character is defined
-to be smallest rectangle aligned parallel to the $x$- and $y$-axis of
-the character
-coordinate system which encloses the painted area of the character
-completely. This rectangle is completely specified by specifying its
-lower left and its upper
-right corner. From a programmer's point of view, a characters bounding
-box is defined by the following struct of type \verb+BBox+:
-\begin{verbatim}
-typedef struct
-{
- int llx; /* lower left x-position */
- int lly; /* lower left y-position */
- int urx; /* upper right x-position */
- int ury; /* upper right y-position */
-} BBox;
-\end{verbatim}
-In case the character is not encoded or no AFM data is available, a box
-containing only zeros is returned.
-
-The bounding box is corrected if an extension value has been applied
-to the font in question.
-
-Since version 0.3-beta, slanted fonts are fully supported, meaning that for
-slanted fonts too a correct bounding box will be returned. This is however
-quite time expensive since the characters' real outline must be considered.
-See the discussion on slanting a font (\ref{transformations}) for an
-explanation of this.
-
-
-\precorr
-\begin{verbatim}
- int T1_GetStringWidth( int FontID, char *string,
- int len, long spaceoff, int kerning)
-\end{verbatim}\index{\verb+T1_GetStringWidth()+}\postcorr
-\precorr
-\begin{verbatim}
- BBox T1_GetStringBBox( int FontID, char *string,
- int len, long spaceoff, int kerning)
-\end{verbatim}\index{\verb+T1_GetStringBBox()+}\postcorr
-These two functions represent the complement to the above functions on the level
-of strings. All parameters that take influence on the resulting width and
-bounding box must be given in the argument list. Their meaning is identical to
-the meaning they have when calling string rastering functions (see
-\ref{generatingbitmaps}).
-
-
-\precorr
-\begin{verbatim}
- METRICSINFO T1_GetMetricsInfo( int FontID, char *string,
- int len, long spaceoff, int kerning)
-\end{verbatim}\index{\verb+T1_GetMetricsInfo()+}\postcorr
-In certain situations bounding box and width of a glyph are required both. In
-these cases it is more convenient to call \verb+T1_GetMetricsInfo()+ which
-returns a structure that contains all information. \verb+METRICSINFO+ is
-defined in \verb+t1lib.h+ as:
-\begin{verbatim}
-typedef struct
-{
- int width;
- BBox bbox;
- int numchars;
- int *charpos;
-} METRICSINFO;
-\end{verbatim}
-All numbers are to be interpreted in character space units --- they are
-directly taken from AFM data. \verb+width+ is the glyph's width and
-\verb+bbox+ its bounding box which in turn is a struct as defined some
-paragraphs above.
-
-\verb+numchars+ is assigned number of characters in string. If the argument
-\verb+len+ is different from 0, \verb+numchars+ is assigned that value.
-
-\verb+charpos+ is a pointer to an integer array of size \verb+numchars+
-allocated by \verb+T1_GetMetricsInfo()+. During execution this array is filled
-step by step with the horizontal escapement in character space units of the
-respective character relative to the start point of the string glyph which
-corresponds to 0. \verb+charpos+ remains valid until
-\verb+T1_GetMetricsInfo()+ is called the next time. The user should not
-free this memory because this is handled automatically.
-
-The terms concerning the bounding box of slanted fonts mentioned under the
-description of \verb+T1_GetCharBBox()+ apply here as well. The first and the
-last character of \verb+string+ have to be observed spending high effort.
-But nevertheless the correct bounding box is returned.
-
-\precorr
-\begin{verbatim}
- int T1_GetKerning( int FontID, char char1, char char2)
-\end{verbatim}\index{\verb+T1_GetKerning()+}\postcorr
-This function returns the amount of kerning for the specified character
-pair \verb+char1+ and \verb+char2+. If an extension has been specified
-for the font (see \ref{transformations}), the amount of
-kerning is automatically corrected using the extension factor. The
-value returned has to be interpreted in charspace units.
-
-If no AFM information is available for the font in question, simply 0
-is returned. The same applies if the font is not loaded.
-
-The implementation of this function requires that the kerning pairs in
-the AFM file are sorted in alphabetical order. I am not sure
-whether this condition is found in the specification of the AFM file
-format. If this function doesn't work although AFM kerning data is
-available, this might be the reason.
-
-\precorr
-\begin{verbatim}
- int T1_QueryLigs( int FontID, char char1,
- char **successors, char **ligatures)
-\end{verbatim}\index{\verb+T1_QueryLigs()+}\postcorr
-This function implements the interface to the ligature information in
-the AFM data. Ligatures are special character-symbols which are
-substituted if special pairs,
-triples or whatever groups of characters appear in a string. For example,
-``f{}i'' is replaced with the ligature ``fi''. In this example, the ``i'' is
-called {\em successor} and the ``fi'' is the associated ligature.
-
-\verb+char1+ is the character
-which has to be checked for ligatures, i.e., the first character of a possible
-ligature group. \verb+successors+ and \verb+ligatures+ should be addresses of
-pointers to \verb+char+s. These pointers are modified by the
-\verb+T1_QueryLigs()+.
-
-First, \verb+T1_QueryLigs()+ checks how many ligatures are defined for the
-character given by \verb+char1+. Assuming this number is $n$, it then
-defines memory for two arrays of type \verb+char+ with size
-$n$. These arrays are filled with the indices of the
-successor-characters and with
-the indices of the associated ligatures, respectively. The current
-encoding vector is used for this. The addresses of these two arrays
-are written to the
-addresses of the respective pointers \verb+successors+ and \verb+ligatures+.
-They are thus later available to the user in order to access the memory where
-the successor-character and ligatures are specified. The value $n$ is returned
-in order to tell the user how many ligatures were found and to give
-the user information about the end of the two arrays.
-
-If the font is not loaded or AFM data is not available, -1 is returned.
-
-Since this may seem to be a little complicated, here is a programming example:
-\begin{verbatim}
-char *succ, *lig;
-int n_lig, i;
-char char1='f';
-
-/* Get ligature information of character 'f' in font 0: */
-n_lig=T1_QueryLig( 0, char1, &suc, &lig);
-
-/* print out indices of characters and their ligatures */
-for ( i=0; i<n_lig; i++;){
- printf("First char: %d, + next char: %d --> ligatur: %d\n",
- char1,
- succ[i],
- lig[i]);
-\end{verbatim}
-
-Notice that the arrays where the successor indices and the respective
-ligature indices are stored are static in
-\verb+T1_QueryLigs()+. Thus, they may not be freed and moreover they
-are only valid until the next time \verb+T1_QueryLigs()+ is called.
-
-
-\subsubsection{Character-Encoding Relation}
-\label{characterencodingrelation}%
-
-\precorr
-\begin{verbatim}
- char *T1_GetCharName( int FontID, char char1)
-\end{verbatim}\index{\verb+T1_GetCharName()+}\postcorr
-This function returns the name of the character indexed by \verb+char1+
-according to the current encoding vector. As said above, the memory where the
-string
-is stored is static to this function so that the user should not free the
-returned pointer. If the font is not loaded, NULL is returned.
-
-\precorr
-\begin{verbatim}
- int T1_GetEncodingIndex( int FontID, char *char1)
-\end{verbatim}\index{\verb+T1_GetEncodingIndex()+}\postcorr
-This function is the complement to the above function. It returns the lowest
-index of the character with the specified name in the current encoding vector
-as an \verb+int+. If the charactername is not found in the current encoding
-vector or if the font is not loaded, the value -1 is returned.
-
-\precorr
-\begin{verbatim}
- int *T1_GetEncodingIndices( int FontID, char *char1)
-\end{verbatim}\index{\verb+T1_GetEncodingIndices()+}\postcorr
-This function is an extension of the above function. It is meant for cases
-where all appearences of \verb+char1+ in the encoding vector are requested.
-The return value is an integer array whose elements contain the encoding
-indices where \verb+char1+ appears in increasing order. The first negative
-entry in this array indicates that no more valid indices will follow. In the
-most extreme case we can think of (i.e., where the complete encoding vector is
-occupied by {\em one} character), \verb+T1_GetEncodingIndices()+ will return
-an array of size 257 where the first 256 elements bear their own index and the
-257th element is $-1$. If font \verb+FontID+ is not loaded, this function
-returns \verb+NULL+ and \verb+T1_errno+ will be set appropriately. If
-\verb+char1+ was not found in the encoding vector, a valid array is returned
-but the first element will be $-1$.
-
-
-\precorr
-\begin{verbatim}
- char **T1_GetAllCharNames( int FontID)
-\end{verbatim}\index{\verb+T1_GetAllCharNames()+}\postcorr
-As described in \ref{encoding}, not all characters of a font need to be
-encoded. A Type 1 may contain the outlines of an arbitrary number of
-characters, but only 256 can be encoded---and thus
-accessed---simultaneously. Since the characternames are inside the encrypted
-portion of
-the Type 1 font file, there is no easy way to find out which characters a font
-defines.
-
-\tonelib\ provides \verb+T1_GetAllCharNames()+ for situations where a
-programmer needs to know what characters are defined in the font file
-identified by \verb+FontID+. The value returned is a pointer to an array of
-\verb+char+ pointers which in turn point to the characternames.
-The array's size is $(n+1)$ where $n$ is the number of defined outlines. The
-$(n+1$)th pointer is \verb+NULL+ to indicate the end of the array.
-An application programmer may use these characternames to construct a
-specialized encoding vector. Here is an example of how to use
-\verb+T1_GetAllCharNames()+. It prints a list of all defined characternames in
-font 0.
-\begin{verbatim}
- char **ptr;
- int i;
- .
- .
- .
- ptr=T1_GetAllCharNames( 0);
- i=0;
- while (ptr[i]!=NULL){
- printf("Charstring %d = %s\n", i, ptr[i]);
- i++;
- }
-\end{verbatim}
-
-The memory for storing the pointers and the charactername strings is static in\\
-\verb+T1_GetAllCharNames()+. Thus it remains valid until the function is
-called the next time. The user should not free this memory or if he does, he
-should set the pointer to \verb+NULL+ to indicate the memory has already been
-freed.
-
-\precorr
-\begin{verbatim}
- int T1_GetNoKernPairs( int FontID)
-\end{verbatim}\index{\verb+T1_GetNoKernPairs()+}\postcorr
-This function returns the number of kerning pairs defined for the font
-identified by \verb+FontID+. The number -1 is returned if an error occured and
-\verb+T1_errno+ will be set. All positive numbers including 0 should be
-considered valid return values.
-
-
-\subsubsection{Administrative Information}
-\label{administrativeinformation}%
-
-
-\precorr
-\begin{verbatim}
- int T1_GetNoFonts( void)
-\end{verbatim}\index{\verb+T1_GetNoFonts()+}\postcorr
-Usually, this function returns the number of fonts declared in the font
-database file, i.e., the integer quantity from the first line of the font
-database file. However, if some new fonts have been created using
-\verb+T1_CopyFont()+ (see \ref{logicalfonts}) or if some fonts have
-been added to the database
-after initialization (see \ref{addingfonts}), these are also taken into
-account. The number returned by \verb+T1_GetNoFonts()+ minus 1
-is thus the largest valid font ID specification.
-
-\precorr
-\begin{verbatim}
- int T1_CheckForInit( void)
-\end{verbatim}\index{\verb+T1_CheckForInit()+}\postcorr
-Use this function in order to check whether \tonelib\ is initialized. It
-returns $0$ if initialization has already happened and $-1$ otherwise.
-
-\precorr
-\begin{verbatim}
- int T1_CheckForFontID( int FontID)
-\end{verbatim}\index{\verb+T1_CheckForFontID()+}\postcorr
-This functions gives information on the load status of the font associated to
-\verb+FontID+. It returns $0$ if the font \verb+FontID+ has not yet been loaded,
-$1$ if it has already been loaded. Finally, a return value of $-1$ indicates
-that either \verb+FontID+ is an invalid specification or \tonelib\ is not
-initialized.
-
-
-\precorr
-\begin{verbatim}
- char *T1_GetFontFileName( int FontID)
-\end{verbatim}\index{\verb+T1_GetFontFileName()+}\postcorr
-This function returns a pointer to the fontfilename identified by
-\verb+FontID+. In no case, this pointer may be freed since the memory is
-static to this function. The string also is only valid up to the next call of
-this function.
-
-\precorr
-\begin{verbatim}
- char *T1_GetFontFilePath( int FontID)
-\end{verbatim}\index{\verb+T1_GetFontFilePath()+}\postcorr
-This function returns a pointer to the fully qualified path of the font file
-identified by \verb+FontID+. In no case, this pointer may be freed since the
-memory is static to this function. The string also is only valid up to the
-next call of this function.
-
-\precorr
-\begin{verbatim}
- char *T1_GetAFMFilePath( int FontID)
-\end{verbatim}\index{\verb+T1_GetAFMFilePath()+}\postcorr
-This function returns a pointer to the fully qualified path of the AFM file of
-the font identified by \verb+FontID+, as used by \tonelib. In case of an error
-\verb+NULL+ is returned. It may also happen that there exists no AFM file for
-the font either because AFM information was generated on the fly at the time
-the font was loaded, or because AFM processing had been disabled at
-initialization time. For those cases \verb+T1_errno+ is not set.
-
-In no case, the returned pointer may be freed since the memory is static to
-this function. The string also is only valid up to the next call of this
-function.
-
-\precorr
-\begin{verbatim}
- char *T1_GetLibIdent( void)
-\end{verbatim}\index{\verb+T1_GetLibIdent()+}\postcorr
-This function returns the identifier string for the version of \tonelib. For
-example, this could be \verb+0.8-beta+. The string is static in this function
-and should thus not be freed by the user.
-
-
-\subsection{Transformation of Fonts}
-\label{transformations}%
-Transformation of
-Type 1 fonts is generally accomplished by means of concatenating
-so-called transformation matrices. For example, rotation is
-equivalent to concatenation of
-the standard transformation matrix with a special matrix whose elements are
-trigonometric functions evaluated at the rotation angle. In the sense of
-\tonelib, we distinguish between {\em fontlevel transformations} and {\em
- characterlevel transformations}.
-
-\subsubsection{Fontlevel Transformations}
-\tonelib\ supports three transformations that operate globally on a font's data.
-After applying such a transformation to a font all characters generated from
-then on will be rendered according to that transformation. Moreover, these
-transformed characters are saved in cache for fast future access. This
-principle is thus meant for transformed fonts which are semantically used as
-ordinary text fonts. Creating a font Times-Oblique by slanting a Times-Roman
-would be a typical example.
-
-The first fontlevel transformation is called ``extension'' since it extents a font
-horizontally---makes its characters wider. A font is extended by a call to the
-function
-\precorr
-\begin{verbatim}
- int T1_ExtendFont( int FontID, double extend)
-\end{verbatim}\index{\verb+T1_ExtendFont()+}\postcorr
-A font that is to be extended may not have size dependent data. If size
-dependent data exists, it must
-explicitly be removed before applying an extension-factor. This is simply a
-security mechanism which prevents the user from mixing up extended and
-non-extended bitmaps. If the font is not loaded or size-dependent data is
-existent, -1 is returned. Otherwise, the function returns 0.
-
-All information on character metrics is automatically adapted to an
-extension-factor different from 1 (see \ref{common}).
-
-Applying an extension-factor to a font is implemented by replacing the current
-extension-factor---initially 1---with the supplied value. Thus, an extension
-can be deleted by specifying a factor 1. Moreover, extending a font two
-times, say, with factor 2, does not yield a font extended by 4. Rather the
-last specified extension, here 2, is applied.
-
-The second type of fontlevel transformation supported by \tonelib\ is {\em
- slanting}. It is done by a call to the function \precorr
-\begin{verbatim}
- int T1_SlantFont( int FontID, double slant)
-\end{verbatim}\index{\verb+T1_SlantFont()+}\postcorr
-The slant-factor $s$ tells the rastering algorithm to advance the $x$-coordinate
-of a given point by the product of $s$ with the $y$-coordinate of that
-point. Such fonts are sometimes called {\em oblique}. Another interpretation
-is that we state: $s=\tan(\alpha)$, where $\alpha$ is the well-known
-italic-angle of the font.
-
-Just as above, no size-dependent data may be existent and the font must be
-loaded. In that case 0 is returned, otherwise -1.
-
-As above, the slanting operation is implemented by {\em setting} the
-slant-factor so that a slant may be reset by means of specifying a
-slant-factor of 0.
-
-There is one thing that makes handling of slanted fonts more difficult than
-handling of extended fonts. When
-typesetting strings by concatenating bitmaps, exact information on character
-metrics is necessary. By slanting a character the character's width is not
-affected. But the bounding box is. And while extension---which means
-strictly horizontal scaling independent of the respective
-y-coordinate---simply leads to an extension of the bounding box, there is no
-way to compute the
-bounding box of a slanted character from the bounding box of the respective
-unslanted character. Here is an example.
-\begin{itemize}
-\item Let the character be \verb+\+. When slanting this character with a
- value of 1, the resulting character will be similar to a vertical line. The
- bounding box will thus be small in horizontal direction.
-\item If character is \verb+/+, the resulting slanted
- character will tend to be more horizontal. Thus the resulting bounding box
- will be much extended in horizontal direction.
-\end{itemize}
-In conclusion
-we can say that the effect of slanting on the bounding box of
-a given character depends on the shape of the character itself.
-
-Since version 0.3-beta the problem with the bounding box of slanted characters
-is handled as follows. The character in question is internally rastered at
-1000 bp and the bounding box of the resulting ``edgelist'' is examined. But no
-bitmap is generated for the character, this limits the computational effort.
-However the difference in time performance between getting a bounding box from
-a ``simple-shaped'' slanted character like ``i'' and getting a bounding box of
-a ``complex-shaped'' character like ``Q'' is clearly noticeable.
-
-The positioning algorithm for string bitmaps has been slightly improved in
-\tonelib\ V.\ 0.3-beta so that now exclusively bitmap metrics are used where
-the bounding boxes are needed. The limitation of slanted fonts appears thus
-only if a user explicitly requests a bounding box of a character/string in an
-artificially slanted font.
-
-The third and most common type of fontlevel transformation allows arbitrary
-linear transformations. This is done by a call to the function
-\precorr
-\begin{verbatim}
- int T1_TransformFont( int FontID, T1_TMATRIX *matrix)
-\end{verbatim}\index{\verb+T1_TransformFont()+}
-\postcorr
-The transformation is specified by \verb+matrix+ (as described below).
-This function acts by setting the font's transformation matrix to the
-matrix pointed to by \verb+matrix+.
-
-As a final consequence of what has been described so far in this section it
-turns out that \verb+T1_TransformFont()+ overrides whatever slant and extension
-values might have been set before. Conversely, if \verb+T1_SlantFont()+ or
-\verb+T1_ExtendFont()+ are applied to a font after a call to
-\verb+T1_TransformFont()+, the respective values are simply overridden, there
-will be no concatenation. In the following description of transformation
-matrices and their usage, we will also describe how to concatenate an
-arbitrary series of linear transformations.
-
-There are also functions for querying the current values of the quantities
-described above for fontlevel transformations.
-\precorr
-\begin{verbatim}
- double T1_GetExtend( int FontID)
-\end{verbatim}\index{\verb+T1_GetExtend()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- double T1_GetSlant( int FontID)
-\end{verbatim}\index{\verb+T1_GetExtend()+}\postcorr
-return the current extension and slant values. The function
-\precorr
-\begin{verbatim}
- T1_TMATRIX T1_GetTransform( int FontID)
-\end{verbatim}\index{\verb+T1_GetTransform()+}\postcorr
-Returns the current transformation matrix as a structure of type
-\verb+T1_TMATRIX+ which will be described in detail in the next subsubsection.
-
-\subsubsection{Transformation at Rastering Time}
-This kind of transformation is the most generic one and allows arbitrary
-transformations. A transformation $(x',y')^T$ of a given location $(x,y)^T$ is
-given by the following set of linear equations:
-\begin{eqnarray*}
-x' & = a_{11} x + a_{21} y \\
-y' & = a_{12} x + a_{22} y
-\end{eqnarray*}
-Here, the matrix
-\begin{displaymath}
-\mathbf{A}=
-\left(
-\begin{array}{cc}
-a_{11} & a_{21} \\
-a_{12} & a_{22}
-\end{array}
-\right)
-\end{displaymath}
-is referred to as the {\em transformation matrix}. In \tonelib\ the following
-type definition is used for such transformation matrices:
-\begin{verbatim}
-typedef struct
-{
- double cxx; /* corresponds to a11 */
- double cyx; /* corresponds to a21 */
- double cxy; /* corresponds to a12 */
- double cyy; /* corresponds to a22 */
-} T1_TMATRIX;
-\end{verbatim}
-Each of the rastering functions expects to get a pointer to an object of type
-\verb+T1_MATRIX+, or \verb+NULL+ if no transformation is to be applied.
-If any transformation has been specified, the resulting glyph is never kept in
-cache memory. Thus, if for some reason caching should be disabled for
-non-transformed characters, simply a pointer to the
-unity matrix
-%$\left(
-%\begin{array}{cc}
-%1.0 & 0 \\
-%0 & 1.0
-%\end{array}
-%\right)$
-could be specified to the rastering function to achieve this.
-
-The user has the possibility of either allocating and creating the
-transformation matrices by himself or to use predefined functions of
-\tonelib. There are 8 different functions for generating transformed
-characters. Figure \ref{figure:transformations} gives an example of each
-function using the character ``g''.
-
-\begin{figure}[t]
-\hfill
-\includegraphics[scale=0.5]{mirrorh}
-\hfill
-\includegraphics[scale=0.5]{mirrorv}
-\hfill
-\includegraphics[scale=0.5]{shearh}
-\hfill\break
-\noindent\vrule width 0pt\hfill\verb+T1_MirrorHMatrix()+\hfill
-\verb+T1_MirrorVMatrix()+\hfill
-\verb+T1_ShearHMatrix()+\hfill\break
-% line 2
-\vskip0.5cm
-\hfill
-\includegraphics[scale=0.5]{shearv}
-\hfill
-\includegraphics[scale=0.5]{extenth}
-\hfill
-\includegraphics[scale=0.5]{extentv}
-\hfill\break
-\noindent\vrule width 0pt\hfill\verb+T1_ShearVMatrix()+\hfill
-\verb+T1_ExtendHMatrix()+\hfill
-\verb+T1_ExtendVMatrix()+\hfill\break
-% line 3
-\vskip0.5cm
-\hfill
-\includegraphics[scale=0.5]{rotate}
-\hfill
-\includegraphics[scale=0.5]{arbitrary}
-\hfill\break
-\noindent\vrule width 0pt\hfill\verb+T1_RotateMatrix()+\hfill
-\verb+T1_TransformMatrix()+\hfill\break
-\vskip3mm
-\hrule\vskip3mm\small
-\caption{\label{figure:transformations}Typical examples for the predefined
- functions for generating transformation matrices in \tonelib, applied to the
- character ``g''.}
-\end{figure}
-
-Before describing each particular function we should discuss the first
-argument because this is common to all matrix transformation functions. This
-first argument, in case it is not \verb+NULL+, is expected to be a pointer to
-an already existent valid \verb+T1_TMATRIX+ object. The transformation to be
-applied is then done by multiplying the existent matrix with the new
-matrix. In other words, the existent matrix is replaced by the concatenation of
-the two matrices. If a \verb+NULL+ is specified as argument, the new matrix is
-allocated by the respective function and then set to the concatenation of the
-unity matrix with the desired transformation. Thus, to remove a matrix from
-memory, the pointer simply has to be given to \verb+free()+, no matter how
-many transformations have been applied to this matrix before.
-
-We should now describe the functions for generating transformation matrices:
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_MirrorHMatrix( T1_TMATRIX *matrix)
-\end{verbatim}\index{\verb+T1_MirrorHMatrix()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_MirrorVMatrix( T1_TMATRIX *matrix)
-\end{verbatim}\index{\verb+T1_MirrorVMatrix()+}\postcorr
-simply change the sign of the matrix coefficients $a_{11}$ and $a_{22}$
-respectively. This has the optical effect of mirroring the character at the
-horizontal line $y=0$ or at the vertical line $x=0$, respectively. These
-functions represent a specialized form of
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_ExtendHMatrix( T1_TMATRIX *matrix, float extent)
-\end{verbatim}\index{\verb+T1_ExtendHMatrix()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_ExtendVMatrix( T1_TMATRIX *matrix, float extent)
-\end{verbatim}\index{\verb+T1_ExtendVMatrix()+}\postcorr
-These functions allow arbitrary scaling in the respective coordinate
-direction. Specifying \\
-\verb+extent=-1+ exactly yields mirroring at the
-corresponding axis.
-
-Furthermore, there are two transformations where one coordinate depends on
-itself and on the other coordinate. This is called shearing, slanting or also
-obliqueing. It is possible in both directions using the functions
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_ShearHMatrix( T1_TMATRIX *matrix, float shear)
-\end{verbatim}\index{\verb+T1_ShearHMatrix()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_ShearVMatrix( T1_TMATRIX *matrix, float shear)
-\end{verbatim}\index{\verb+T1_ShearVMatrix()+}\postcorr
-In case of horizontal shearing, the factor \verb+shear+ is equal to
-$\tan(\alpha)$, where $\alpha$ may be interpreted as the italic angle. It is
-measured from the positive vertical axis in mathematical negative direction.
-Correspondingly, for vertical shearing \verb+shear+ equals $\tan(\beta)$,
-where $\beta$ is the angle measured from the horizontal axis in mathematically
-positive direction.
-
-Rotation of glyphs is achieved using
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_RotateMatrix( T1_TMATRIX *matrix, float angle)
-\end{verbatim}\index{\verb+T1_RotateMatrix()+}\postcorr
-This function evaluates the trigonometric functions at the value of
-\verb+angle+ and concatenates the transformation matrix with
-\begin{displaymath}
-\left(
-\begin{array}{cc}
-\cos(\alpha) & -\sin(\alpha) \\
-\sin(\alpha) & \cos(\alpha)
-\end{array}
-\right)
-\end{displaymath}
-$\alpha$ is expected to be specified in degrees. It is measured according
-standard mathematical conventions.
-
-There is one more function which allows to set all matrix coefficients
-explicitly. It gives thus complete control over the transformation. This might
-be necessary to typeset text in a circle, for example. The syntax of this
-function is
-\precorr
-\begin{verbatim}
- T1_TMATRIX *T1_TransformMatrix( T1_TMATRIX *matrix,
- float cxx, float cyx,
- float cxy, float cyy)
-\end{verbatim}\index{\verb+T1_TransformMatrix()+}\postcorr
-
-\subsubsection{{\tt t1lib} and PostScript: Notes on Transformation Matrices}
-In order to avoid confusion about transformation matrices, we should briefly
-discuss the differences between \tonelib- and PostScript transformation
-matrices. In \tonelib-nomenclature a coordinate description is assumed to be
-represented by a column vector $(x,y)^T$. In contrast, PostScript assumes a
-coordinate to be represented by a row vector $(x,y)$. This leads to an
-exchanged meaning of the second and third matrix element between \tonelib\ and
-PostScript. From the mathematical point of view this is caused by matrix
-transposition. To make this clear, let me quote the matrix
-\begin{displaymath}
-\mathbf{A}_{\mbox{\footnotesize PostScript}}=
-\left(
-\begin{array}{ccc}
-a & b & 0\\
-c & d & 0\\
-t_x & t_y & 1
-\end{array}
-\right)
-\end{displaymath}
-from the PostScript Language Reference Manual (Adobe, Red Book). If we forget
-about translation which in this sense is not implemented by \tonelib, we only
-have to consider the top left submatrix consisting of $a$, $b$, $c$ and $d$.
-The \tonelib-equivalent to this matrix would be written as
-\begin{displaymath}
-\mathbf{A}_{\mbox{\tt\footnotesize t1lib}}=
-\left(
-\begin{array}{cc}
-a & c \\
-b & d \\
-\end{array}
-\right)
-\end{displaymath}
-I.e., the meaning of $b$ and $c$ is exchanged. Notice that font matrices as
-found in Type 1 font files have to be interpreted according to the PostScript
-notation. But a user should never come close to something other than the
-\tonelib\ transformation matrices
-
-
-\subsection{Stroking of Character Outlines}
-\label{stroking}%
-Most available Type 1 fonts internally specify the numeric value
-\verb+PaintType+ as $0$. This indicates that the mathematical outline
-definitions of the characters consist of paths that represent the left and
-right---or inner and outer---borders of the character area to be filled with
-ink. In particular, this means that every subpath of a character definition
-must be closed. When filling characters, the curves that describe the outline
-are infinitely thin and the area between paths is of interest.
-
-By contrast, there are fonts that specify \verb+PaintType+ as $1$. These are
-also known as {\em stroked fonts}. Basically, their characters' shapes are
-generated by travelling along the mathematically thin defining curves using a
-pen with some finite width. The penwidth used here usually is specified in the
-font itself by means of the quantity \verb+StrokeWidth+.
-
-Using a somewhat unusual implementation, \tonelib\ can
-\begin{itemize}
-\item image stroked fonts with \verb+PaintType+ 1,
-\item stroke fonts that have \verb+PaintType+ 0,
-\item deal with variable strokewidths for both paint types.
-\end{itemize}
-In particular at low resolutions and when using large penwidths, the results
-of stroking may fall short of the quality of other general graphics tools like
-e.g.~native PostScript interpreters. Also hinting generally is disabled when
-creating stroked character outlines. For the interested reader, the
-implementation of stroking is outlined in \ref{strokingimplementation}
-(page~\pageref{strokingimplementation}).
-
-The process of stroking in \tonelib\ is treated similar to the process of
-transformation. Therefore, firstly, a font can be generally switched to be a
-stroked font. This is achieved using
-\precorr
-\begin{verbatim}
- int T1_StrokeFont( int FontID, int dostroke)
-\end{verbatim}\index{\verb+T1_StrokeFont()+}\postcorr
-Here, \verb+FontID+ identifies the font to be switched. The parameter
-\verb+dostroke+ determines the future rastering behavior. If it equals 0, the
-font's characters will be filled and for any other value the characters will
-be stroked. The function returns 0 in case of success.
-\verb+T1_StrokeFont()+ requires the font \verb+FontID+ to be loaded. If the
-font is not loaded \verb+T1_errno+ will be set appropriately and the function
-returns -1. After switching a font to {\em stroked}, its characters are cached
-as usual. It is therefore important that, at the time where
-\verb+T1_StrokeFont()+ is called, no size-dependent data does exist. If this
-condition is violated, the function will fail too and set \verb+T1_errno+ to
-\verb+T1ERR_OP_NOT_PERMITTED+.
-
-The second method to control the rasterizer mode for the font \verb+FontID+ is
-to use the function pair
-\precorr
-\begin{verbatim}
- int T1_SetStrokeFlag( int FontID)
-\end{verbatim}\index{\verb+T1_SetStrokeFlag()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- int T1_ClearStrokeFlag( int FontID)
-\end{verbatim}\index{\verb+T1_ClearStrokeFlag()+}\postcorr
-for enabling and disabling stroking, respectively. These two functions return
-0 on successful completion and -1 in case of a failure. They can only fail if
-\verb+FontID+ is not valid, in which case \verb+T1_errno+ is set to
-\verb+T1ERR_INVALID_FONTID+. Using these functions, switching the stroking is
-hence possible at any time. The netto effect is that caching will be disabled
-if the actually selected rasterizer mode does not match the one of the cached
-characters. The performance then will degrade for the rasterizer mode that is
-not the base mode of the font in question.
-
-If stroked characters and filled characters are required for one particular
-font while preserving good performance, using logical fonts is the tool of
-choice (see Sec.~\ref{logicalfonts}, page~\pageref{logicalfonts}).
-
-The currently active rasterizer mode for the font \verb+FontID+ can also be
-queried. This is done using
-\precorr
-\begin{verbatim}
- int T1_GetStrokeMode( int FontID)
-\end{verbatim}\index{\verb+T1_GetStrokeMode()+}\postcorr
-If \verb+FontID+ is not valid, $-1$ is returned and \verb+T1_errno+ is set to
-\verb+T1ERR_INVALID_FONTID+. In any other case, the following values may be
-returned:
-\begin{itemize}
-\item \verb+0+: The rasterizer mode is {\em Fill} and filled characters are
- cached. For stroked fonts with a \verb+PaintType+ of $1$, of course, the
- characters are stroked and these stroked characters are cached anyhow.
-\item \verb+1+: Stroking is enabled, while filled characters are cached. Each
- rasterization request is performed on the fly, as for nontrivial
- transformations.
-\item \verb+2+: Filling is enabled but stroked characters are
- cached. Rasterization again is performed on the fly.
-\item \verb+3+: Stroking is enabled and stroked characters are cached.
-\end{itemize}
-
-The width of the virtual pen used to trace the character outlines can also be
-adjusted. The function
-\precorr
-\begin{verbatim}
- int T1_SetStrokeWidth( int FontID, float strokewidth)
-\end{verbatim}\index{\verb+T1_SetStrokeWidth()+}\postcorr
-sets up \verb+strokewidth+ as the pen width used to stroke characters from
-font \verb+FontID+. It is interpreted in charspace units and hence directly
-comparable to the \verb+StrokeWidth+ parameter of stroked fonts.
-If this function succeeds, $0$ is returned. The function call might
-also be unsuccessful, in which case $-1$ is returned. The value of
-\verb+T1_errno+ then gives a hint to the reason of the failure. If set to
-\verb+T1ERR_INVALID_FONTID+, the font was not loaded. The value
-\verb+T1ERR_INVALID_PARAMETER+ indicates that a negative strokewidths has
-been specified. Finally, \verb+T1ERR_OP_NOT_PERMITTED+ may appear if stroked
-characters are cached for the font in question, size dependent data exists,
-and the requested strokewidth did not equal the one used at the time where
-the cache data initially has been built. Allowing to setup an arbitrary
-strokewidth under the latter circumstances might fillup the cache for one font
-with characters rasterized using inconsistent strokewidths, which has to be
-avoided. From this discussion it becomes suggesting not to cache stroked
-character at all, if stroking should be done using variable strokewidths.
-
-The pen width for a given font \verb+FontID+ may be queried at any time using
-\precorr
-\begin{verbatim}
- float T1_GetStrokeWidth( int FontID)
-\end{verbatim}\index{\verb+T1_GetStrokeWidth()+}\postcorr
-If the value $0.0$ is returned, this either indicates that the characters are
-filled or that the font in question is not loaded. Then, \verb+T1_errno+ is
-also set to \verb+T1ERR_INVALID_FONTID+.
-
-
-\subsection{Antialiasing}
-\label{antialiasing}%
-\subsubsection{General Description}
-When fonts are displayed on screen at low sizes, the shapes of characters often
-get damaged because of rounding errors---a pixel can generally present two
-states: painted or non-painted. But the human eye can be fooled in a
-way that it
-``thinks'' sub-pixel accuracy is given on the screen. This is done by
-considering which pixels are filled with ink to what degree and
-giving the
-physical pixel an appropriate shade of gray. For example, a pixel whose area
-would be covered 50\% would get a 50\% gray shade. This technique is called
-{\em antialiasing}.
-
-There are several ways to implement antialiasing. \tonelib\ implements
-antialiasing by internally generating a bitmap larger than needed
-and then subsampling. Depending on the subsampling factor which may be 2 or 4,
-this principle yields glyphs with
-5 or 17 shades of gray including black and white.
-
-There are three functions for generating antialiased glyphs:
-\precorr
-\begin{verbatim}
- GLYPH *T1_AASetChar( int FontID, char charcode,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_AASetChar()+}\postcorr
-\precorr
-\begin{verbatim}
- GLYPH *T1_AASetString( int FontID, char *string, int len,
- long spaceoff, int modflag,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_AASetString()+}\postcorr
-\precorr
-\begin{verbatim}
- GLYPH* T1_AASetRect( int FontID, float size,
- float width, float height,
- T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_AASetRect()+}\postcorr
-Note the ``\verb+AA+'' in the functions names which stand for
-\underline{A}nti\underline{A}liasing. The usage is identical to the usage of
-the functions \verb+T1_SetChar()+, \verb+T1_SetString()+ and
-\verb+T1_SetRect()+. So see \ref{generatingbitmaps} for an explanation of the
-arguments and their interpretation.
-
-When an antialiased glyph is requested, the supplied \verb+size+-value is
-multiplied by the current subsampling factor. For now, let us assume it is 2.
-Then the respective function for generating non-antialiased glyphs
-is called with all other arguments unchanged. The result is a bitmap twice as
-high and twice as wide as the user requested. Now, a $2\times2$ mask is moved
-over this bitmap and the number of painted pixels in this mask is considered
-at each place. According to the number of painted pixels one of 5 different
-gray shades is assigned to the resulting pixel. Since the mask is moved with
-an increment of 2 pixels in horizontal and vertical direction, the bitmap is
-at the same time subsampled by 2. Thus, the resulting bitmap is just of the
-size the user requested and its pixels each contain one of 5 gray shades.
-
-Conceptually, the same applies for subsampling with 4. In this case the mask is
-of size $4\times4$ and there will be 17 distinct gray shades including black
-and white. The computational effort is considerably larger so that 4 $\times$
-subsampling should only be used for very small sizes.
-
-When moving the mask over double-sized bitmap it is aligned properly with
-respect to the characters' baseline (zero height) rather than with the
-characters' top or bottom line. This principle ensures, that the most important
-visual guideline in running text, the baseline, is represented in a consistent
-manor. This is especially important if one is using a serif-font.
-Thanks to Raph Levien, the algorithm described above in a verbose manor has
-been replaced by a much
-faster lookup-algorithm in \tonelib\ V.\ 0.4-beta.
-
-\subsubsection{Setting Operating Parameters}
-Applications can use both $2\times$ and $4\times$ antialiasing arbitrary
-mixed. Switching between the two modes is achieved using
-\precorr
-\begin{verbatim}
- int T1_AASetLevel( int level)
-\end{verbatim}\index{\verb+T1_AASetLevel()+}\postcorr
-The argument \verb+level+ should be either \verb+T1_AA_LOW+ ($=2$) or
-\verb+T1_AA_HIGH+ ($=4$). Any other values are ignored and \verb+T1_errno+ is
-set appropriately. This function is to be called after initialization. The
-default value after initialization is \verb+T1_AA_LOW+. The current value can
-also be queried by issuing a call to
-\precorr
-\begin{verbatim}
- int T1_AAGetLevel( void)
-\end{verbatim}\index{\verb+T1_AASetLevel()+}\postcorr
-The returned value is current level. Switching between the two antialiasing
-modes should be quite fast since apart from a little error checking
-essentially only one simple variable is set.
-
-There is one more value that may be specified for \verb+level+, namely
-\verb+T1_AA_NONE+. \verb+T1_AA_NONE+ is identical to 1 which means that no
-subsampling at all is done. But the resulting glyph, having only fore- and
-background colors is returned as a bytemap instead of as a bitmap. This is
-intended for situtations where an antialiased glyph should be concatenated
-with a (possibly large) non-antialiased glyph using the function
-\verb+T1_ConcatGlyphs()+. In that case, the depths of the two glyphs have to
-be identical. There is probably not much more sense in setting \verb+level+ to
-\verb+T1_AA_NONE+.
-
-As described before, the result of the \verb+T1_AASet..()+ functions is
-strictly spoken no longer a
-bitmap since more than one bit is used to
-represent one pixel. The function
-\precorr
-\begin{verbatim}
- int T1_AASetBitsPerPixel( int bpp)
-\end{verbatim}\index{\verb+T1_AASetBitsPerPixel()+}\postcorr
-allows the user to specify how many bits should be used to represent one
-pixel. Allowed values for \verb+bpp+ are 8, 16, 24 and 32. However, if 24 is
-specified, internally 32 will be used since the pixel are then addressed as
-objects of type \verb+long+. Antialiased glyphs may grow quite large,
-especially when
-using \verb+bpp+ = 32. The value of \verb+bpp+ is written into the member
-\verb+bpp+ of the \verb+glyph+-structure (see \ref{generatingbitmaps} on page
-\pageref{generatingbitmaps}). That way a user can check whether a
-glyph is antialiased or not. It is possible to work with antialiased
-and non-antialiased glyphs at the same time.
-It is also possible to directly query the value of bits per pixel by using
-\precorr
-\begin{verbatim}
- int T1_AAGetBitsPerPixel( void)
-\end{verbatim}\index{\verb+T1_AAGetBitsPerPixel()+}\postcorr
-The value returned is the number of bits per pixel used.
-
-In order to make the handling of antialiased glyphs as flexible as possible,
-the values to be written into the pixels for different gray values
-may (and must) be explicitly specified. For low level antialiasing this is
-done by calling the function
-\precorr
-\begin{verbatim}
- int T1_AASetGrayValues( unsigned long white,
- unsigned long gray75,
- unsigned long gray50,
- unsigned long gray25,
- unsigned long black)
-\end{verbatim}\index{\verb+T1_AASetGrayValues()+}\postcorr
-For lower \verb+bpp+ values only the lower bits are used. For high level
-antialiasing this kind of graylevel specification is not economical since 17
-arguments
-would have to be specified. Instead, another function is used which expects a
-pointer an array of \verb+unsigned long+'s:
-\precorr
-\begin{verbatim}
- int T1_AAHSetGrayValues( unsigned long *grayvals)
-\end{verbatim}\index{\verb+T1_AAHSetGrayValues()+}\postcorr
-The array \verb+grayvals+ points to must contain 17 entries. Element 0 is
-expected to specify the background color's pixel value and element 16
-represents the foreground color. Calling one of these two functions involves
-also a new setup of the lookup tables. It should thus only be done if some
-color value really has changed.
-
-In case the antialiasing level is set to \verb+T1_AA_NONE+ as described
-above, the function
-\precorr
-\begin{verbatim}
- int T1_AANSetGrayValues( unsigned long bg, unsigned long fg)
-\end{verbatim}\index{\verb+T1_AANSetGrayValues()+}\postcorr
-must be used to set foreground and background color. In conclusion, it turns
-out that each antialiasing level has its own lookup tables which have to be
-initialized as soon as either foreground color, background color or both have
-changed.
-
-Each of the three graylevel sets described above can also be queried by the
-user. This is done using one of the functions
-\precorr
-\begin{verbatim}
- int T1_AAGetGrayValues( long *pgrayvals)
-\end{verbatim}\index{\verb+T1_AAGetGrayValues()+}\postcorr
-\precorr
-\begin{verbatim}
- int T1_AAHGetGrayValues( long *pgrayvals)
-\end{verbatim}\index{\verb+T1_AAHGetGrayValues()+}\postcorr
-\precorr
-\begin{verbatim}
- int T1_AANGetGrayValues( long *pgrayvals)
-\end{verbatim}\index{\verb+T1_AANGetGrayValues()+}\postcorr
-Here, \verb+pgrayvals+ is the start address of an array of \verb+long+-values
-to which the respective grayvalues are written. This memory must thus be
-supplied by the user. These functions will write 5
-(\verb+T1_AAGetGrayValues+), 17 (\verb+T1_AAHGetGrayValues+) and 2
-(\verb+T1_AANGetGrayValues+) respectively to the location given by
-\verb+pgrayvals+. These functions are to be called after initialization. If
-something goes wrong -1 is returned and \verb+T1_errno+ will be set
-accordingly. Otherwise 0 is returned.
-
-
-\subsubsection{Smart Antialiasing}
-\label{smartantialiasing}%
-Antialiasing improves legibility for small sizes but is not that much useful
-for large sizes. To make a compromise between computation time, system
-resources and optical appearance it might be advantageous to use
-\verb+T1_AA_HIGH+ for small sizes, \verb+T1_AA_LOW+ for medium sizes and
-\verb+T1_AA_NONE+ for large sizes. Of course, for large sizes the
-non-antialiasing functions could be used which still need less resources.
-
-In order to free the user from having to switch the antialiasing level explicitly,
-\tonelib\ can be told to do this switching
-automatically, depending on the size requested. This is called {\em Smart
- Antialiasing}. It is disabled by default and can be toggled by a call to
-\precorr
-\begin{verbatim}
- int T1_AASetSmartMode( int smart)
-\end{verbatim}\index{\verb+T1_AASetSmartMode()+}\postcorr
-The quantity \verb+smart+ should be either be \verb+T1_YES+ (which corresponds
-to 1) or \verb+T1_NO+ (which corresponds to 0. Notice that the current
-antialiasing level as set by \verb+T1_AASetLevel()+ is not affected by
-this. After having switched off smart antialiasing the former antialiasing
-level is restored. When smart antialiasing is active still has to take care
-for setting the lookup tables after a color change has happened.
-
-The numerical limits of the requested size at which \tonelib\ will switch
-between the different antialiasing levels may be specified using
-\precorr
-\begin{verbatim}
- int T1_AASetSmartLimits( float limit1, float limit2)
-\end{verbatim}\index{\verb+T1_AASetSmartLimits()+}\postcorr
-Here, \verb+limit1+ is the value of size at which \tonelib\ switches from
-\verb+T1_AA_HIGH+ to \verb+T1_AA_LOW+ and \verb+limit2+ is the value of size
-at which \tonelib\ switches from \verb+T1_AA_LOW+ to \verb+T1_AA_NONE+. The
-default values are 20.0 for \verb+limit1+ and 60.0 for \verb+limit2+. This
-means for sizes smaller than 20.0 \verb+T1_AA_HIGH+ will be used and for sizes
-equal to or greater than 60.0 \verb+T1_AA_NONE+ will be used. The intermediate
-range is covered by \verb+T1_AA_LOW+. These values are suitable for
-applications that display on screen when the device resolution has been left
-at the default value of 72 dpi.
-
-
-\subsubsection{Caching of Antialiased Character Glyphs}
-\label{aacaching}%
-Generally, antialiased glyphs are not cached in \tonelib\ because this
-involves several problems which are hardly to solve. One main problem is shown
-in figure \ref{figure:subpixelpositioning}.
-\begin{figure}
-\centerline{\includegraphics[scale=10]{Tee}}\relax
-\vskip3mm
-\hrule\vskip3mm\small
-\caption{\label{figure:subpixelpositioning} The string ``Tee'' (which is the
- German word for ``tea'') rastered at 13~bp, using $4\times$ antialiasing.
- Notice the different representations of the character ``e''.}
-\end{figure}
-Obviously the character ``e'' appears twice in different representations. This
-is intentional and is referred to as sub pixel positioning. In the left ``e''
-the letter is perceived somewhat more to the left with respect to the pixels
-that represent the character. Conversely, the second ``e'' seems to lie
-somewhat more to the right within the pixels. The advantage of this technique
-is that characters can be shifted by some fractional amount of a pixel at low
-sizes.\footnote{The opinions whether this and antialiasing in general is of
- advantage for readability vary, so please consider this the opinion of the
- author. } On the other hand the problem is introduced that each character
-can have more than one representation in graylevels, depending on how much
-subpixel shift is needed.
-
-One further problem caused by subsampling is that certain information is
-irreversibly lost in the graylevel representation. For example, if you have a
-graylevel pixel of intensity 50\% (whatever the real color is), then, in case
-of $2\times$ antialiasing, you will know that in the $2\times 2$ input bitmap
-two pixels had been set to foreground, but you would not know {\em which} two
-these had been. But this information is important for concatenating and
-blitting of antialiased bitmaps: it may well happen that two pixels with 50\%
-gray that lie over each other had to produce an output pixel of 50\%, 75\%
-or 100\% gray (where 100\% gray means full foreground intensity).
-
-To avoid these problems, \tonelib\ generally does not cache antialiased
-glyphs. Instead, it works on true bitmaps which are then subsampled at the
-last possible stage to an antialiased glyph. Applications that do not use
-anything more than the functions that yield char bitmaps or bytemaps, could
-profit from caching of antialiased characters. Such applications could specify
-\verb+T1_AA_CACHING+ as an additional ingredient to the \verb+log+ argument of
-the function \verb+T1_InitLib()+ which initializes \tonelib. This is done by
-OR'ing the value of \verb+log+ with \verb+T1_AA_CACHING+ as described in
-\ref{initialization}. If this flag had been specified at initialization time,
-\verb+T1_AASetChar()+ will cache the bytemaps it has generated and will take
-them from cache in future requests.
-
-When caching antialiased glyphs, each size gets up to four distinct cache
-areas, one for bitmaps and one for $1\times$, $2\times$ and $4\times$ subsampled
-bytemaps each. As soon as a string-generating function is called these cached
-antialiased glyphs cannot be used for the reasons discussed before. The
-developer of an application should thus carefully think about whether
-a possibly marginal performance gain is really worth this much higher
-effort. If in doubt, simply check it out. Applications like \verb+xdvi+ which
-place isolated character glyphs on a sheet could use this feature, however, and
-profit from it.
-
-
-\subsection{Interface to Outlines}
-\label{outlines}%
-Although \tonelib\ is meant for generating bitmaps from Type 1 outline fonts,
-there is a set of functions for accessing outline data.
-There are several reasons for this. Firstly, outline
-descriptions are, within the given arithmetic constraints, mathematically exact.
-Secondly and related to the previous point, in certain cases where exact
-subpixel positioning is needed, the functionality of grid-fitting before
-rasterization is needed. This can only be done accurately based on
-outlines. To illustrate this, consider figure \ref{figure:whyoutlines}.
-% -parameters for this figure: size 50.0
-% angle 35
-% arg: --checkConcat[Glyphs|Outlines]
-%
-\begin{figure}[t]
-\hfill
-a) \includegraphics[scale=1.0]{concatglyphs}
-\hfill
-b) \includegraphics[scale=1.0]{concatoutlines}
-\hfill\break
-\vskip3mm
-\hrule\vskip3mm\small
-\caption{\label{figure:whyoutlines}Two concatenated bitmaps, a) concatenation
- done based on bitmaps by blitting and b) based on outlines and then filled.}
-\end{figure}
-When looking at the concatenated glyph a), it appears that the underline rule
-has a small step where the two words touch.\footnote{Depending on the
- resolution and quality of the hardcopy you are reading, the effect might be
- hardly or not all noticeable.} The reason is, that the second part of the
-glyph had been rastered with respect to a pixel coordinate of exactly $(0,0)$.
-Since the start of the second word in the resulting glyph does not exactly
-fall on an integer pixel location, bitmap blitting causes an artifact in the
-visual line of the underlining rule. Strings rotated at angles that are not
-multiples of $90^\circ$ are prone to produce such effects. In contrast the
-concatenated glyph b) does not show such effects because both partial glyphs
-are placed mathematically exact and then filled. Thirdly, if the outline of a
-character is available, it can be used for whatever. For example, the outline
-can be filled by another rasterizer, it can by altered, it can be stroked and
-so on. \tonelib\ makes outlines as they are internally used by the rasterizer
-available. We will discuss how to interprete and access outlines in the
-remainder of this section.
-\subsubsection{Outline Format}
-\label{outlineformat}%
-Before going into implementation details the general structure of a Type 1
-outline is described. We will consider the simple fictive character whose
-outline is shown in figure \ref{figure:generaloutline}.
-\begin{figure}[t]
-\hfill
-\includegraphics[scale=1.0]{outlines}
-\hfill\break
-\vskip3mm
-\hrule\vskip3mm\small
-\caption{\label{figure:generaloutline}The outline of a fictive character.}
-\end{figure}
-We assume that scaling, grid fitting and hinting has already been carried out.
-Then, the outline is given by set of points $P_i$ and segments connecting those
-points. There are:
-\begin{itemize}
-\item Move-segments (type = \verb+T1_PATHTYPE_MOVE+): These are straight
- segments which cause the current position to be displaced by some offset.
- Since the starting point of a segment is always implicitly the current
- point, only one argument is needed, $P_{dest}$, the destination point. In
- the figure, $P_1$--$P_2$ and $P_{2}$--$P_{12}$ are Move-segments. In this
- simple case they displace from the characters origin to some starting point
- of the outline and from the ending point of the outline to the point where
- the next character would have to be placed (the horizontal escapement).
-\item Line-segments (type = \verb+T1_PATHTYPE_LINE+): These are part of the
- path to be filled later. In analogy to the Move-segment, one argument,
- $P_{dest}$, is required for Line-segments. In the figure, $P_{11}$--$P_2$ is
- a Line-segment.
-\item Bezier-segments (type = \verb+T1_PATHTYPE_BEZIER+): These are curve
- segments. Their shape is defined by a starting point (always the current
- point here), an ending point $P_{dest}$ and two control points $P_B$,
- $P_C$. These four points are the parameters of what is called a third order
- Bezier spline.\footnote{The mathematical defining equation represents a
- special case of a Bernstein polynom which was exploited by {\sc Bezier} in
- the context of solid modeling. The curve especially has the property that
- it may be approximated efficiently by straight line segments in a few
- iterations.} The resulting curve has the following
- properties:
- \begin{itemize}
- \item It starts at the first point $P_{current}$.
- \item It ends at the fourth point $P_{dest}$.
- \item The line that goes through the points $P_{current}$ and $P_{B}$ is the
- tangent to the curve from the right side at the starting point $P_{current}$.
- \item In analogy, the line that goes through the points $P_{C}$ and
- $P_{dest}$ is the tangent to the curve from the left side at the ending
- point $P_{dest}$.
- \item The resulting curve will be enclosed completely by the convex area
- that is defined by connecting the definition points with straight line
- segments.
- \end{itemize}
- Our fictive character outline in figure \ref{figure:generaloutline}
- has three Bezier-segments, $P_{2}$--$P_{3}$--$P_{4}$--$P_{5}$,
- $P_{5}$--$P_{6}$--$P_{7}$--$P_{8}$ and
- $P_{8}$--$P_{9}$--$P_{10}$--$P_{11}$. Notice that it is easily possible to
- achieve a smooth tangent transition from one curve-segment to the next by
- choosing the involved points from a straight line.
-\end{itemize}
-For Type 1 fonts in general, the following rules for interpreting coordinate
-specifications hold:
-\begin{itemize}
-\item All point specifications are relative to the {\em current
- point}.
-\item For Bezier-segments, $P_{B}$, $P_{C}$ and $P_{dest}$ all are relative to
- $P_{current}$.
-\item Initially, i.e. when a character outline is started, the current point
- is at the origin $(0,0)$ of the character.
-\end{itemize}
-Additionally, for this special rasterizer implementation, the following terms
-apply:
-\begin{itemize}
-\item The vertical coordinate is---in contrast to PostScript---inverted, i.e.,
- the $y$-axis points down.
-\item Once hinted and gridfitted, the outline point coordinates are described
- in {\em fractional pixels}. A ``fractpel'' is of type \verb+long+ and
- describes the location in $2^{16}$th fractions of a pixel. To convert from
- pixel to fractional pixel and vice versa, the macros
- \verb+T1_TOPATHPOINT(p)+\index{\verb+T1_TOPATHPOINT()+} and
- \verb+T1_NEARESTPOINT(fp)+\index{\verb+T1_NEARESTPOINT()+} are provided.
-\end{itemize}
-
-Before describing the functions for retrieving outlines the format in which
-outlines are presented in C will be described. A point specification is done
-in the following structure:
-\begin{verbatim}
-typedef struct {
- T1_int32 x;
- T1_int32 y;
-} T1_PATHPOINT;
-\end{verbatim}
-\verb+x+ and \verb+y+ are fractional pixels as described above.
-
-An outline is represented by a linked list of structures which describe path
-segments of the type described above.
-Line- and Move-segments are described by the following structure:
-\begin{verbatim}
-typedef struct pathsegment {
- char type;
- unsigned char flag;
- short references;
- unsigned char size;
- unsigned char context;
- struct pathsegment *link;
- struct pathsegment *last;
- T1_PATHPOINT dest;
-} T1_PATHSEGMENT;
-\end{verbatim}
-\verb+type+ is either \verb+T1_PATHTYPE_MOVE+ or
-\verb+T1_PATHTYPE_LINE+. \verb+flag+, \verb+references+, \verb+size+ and
-\verb+context+ are internally used by the rasterizer. \verb+link+ is a pointer
-to the next segment structure or \verb+NULL+ in case it is the last structure
-in the list. Finally, the \verb+last+-entry is a pointer to
-the last structure in the linked list. \verb+last+ is only set in the first
-segment and is reset to \verb+NULL+ in the remaining segment structures.
-A Bezier-segment is described by the following structure:
-\begin{verbatim}
-typedef struct bezierpathsegment {
- char type;
- unsigned char flag;
- short references;
- unsigned char size;
- unsigned char context;
- T1_PATHSEGMENT *link;
- T1_PATHSEGMENT *last;
- T1_PATHPOINT dest;
- T1_PATHPOINT B;
- T1_PATHPOINT C;
-} T1_BEZIERSEGMENT;
-\end{verbatim}
-Obviously, the format is identical to that for straight path segments, extended
-by the entries \verb+B+ and \verb+C+ which specify the control points as
-described earlier in this subsection.
-The common return type for the outline retrieving functions is a pointer to
-\verb+T1_OUTLINE+, which is in fact identical to \verb+T1_PATHSEGMENT+. This
-purely for convention. Although it is quite unlikely, an outline might start
-with a Bezier-segment. To access Bezier-segment elements, a cast must be used.
-
-
-\subsubsection{Using Outlines}
-\label{usingoutlines}%
-\tonelib\ provides three functions for retrieving outlines. The first is
-\precorr
-\begin{verbatim}
- T1_OUTLINE *T1_GetCharOutline( int FontID, char charcode,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_GetCharOutline()+}\postcorr
-The meaning of the arguments is as in the \verb+T1_SetChar()+-function.
-Notice that the size specification is also required here. Outlines are, by
-their nature in Type~1, generally defined in a $1000\times 1000$ grid and then
-scaled down by the fontmatrix to 1 bp. The space is known as the
-charspace. The reason for specifying a size at this place, instead of scaling
-the outline later, is, that hinting is performed according to the scaled
-outline. The returned outline is then hinted for the given size. If necessary,
-it may still be scaled later.
-
-The outline for a complete string can be retrieved by
-\precorr
-\begin{verbatim}
- T1_OUTLINE *T1_GetStringOutline( int FontID, char *string, int len,
- long spaceoff, int modflag,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_GetStringOutline()+}\postcorr
-The meaning of the arguments is as in \verb+T1_SetString()+.
-
-Finally the ``outline'' for a displacement is available by the function
-\precorr
-\begin{verbatim}
- T1_OUTLINE *T1_GetMoveOutline( int FontID, int deltax, int deltay, int modflag,
- float size, T1_TMATRIX *transform)
-\end{verbatim}\index{\verb+T1_GetMoveOutline()+}\postcorr
-This function is intended to be used for concatenation of outlines. It needs
-all the arguments because some quantities which are given on the font level
-are required for constructing the outline. \verb+deltax+ and \verb+deltay+ are
-the horizontal and vertical displacement measured in charspace units. From the
-\verb+modflag+-argument, especially the underlining parameters are
-evaluated. Although $x$- and $y$-displacement may be specified, the resulting
-outline is still subject to scaling with \verb+size+ and transformation
-according to \verb+transform+.
-
-Arbitrary outlines may be concatenated by using the function
-\precorr
-\begin{verbatim}
- T1_OUTLINE *T1_ConcatOutlines( T1_OUTLINE *path1,
- T1_OUTLINE *path2)
-\end{verbatim}\index{\verb+T1_ConcatOutlines()+}\postcorr
-Notice that this concatenation is done with high precision so that we can
-expect that visual artefacts are reduced to a minimum (remember figure
-\ref{figure:whyoutlines}).
-
-Scaling of outlines is done by the function
-\precorr
-\begin{verbatim}
- T1_OUTLINE *T1_ScaleOutline( T1_OUTLINE *path, float scale)
-\end{verbatim}\index{\verb+T1_ScaleOutline()+}\postcorr
-\verb+T1_ScaleOutline+ does nothing more than linearly scaling the coordinate
-data with \verb+scale+ and storing the result in fractional pixels. No care is
-taken for hinting (see above).
-
-An outline may be duplicated using the function
-\precorr
-\begin{verbatim}
- T1_OUTLINE *T1_CopyOutline( T1_OUTLINE *path)
-\end{verbatim}\index{\verb+T1_CopyOutline()+}\postcorr
-This is a direct entrypoint into the rasterizer. It works by allocating and
-duplicating each segment of \verb+path+. This function may be useful if one
-wants to do several things with one outline because the process of filling an
-outline also consumes that outline.
-
-An outline that that a user decides not to fill can be destroyed by the
-function
-\precorr
-\begin{verbatim}
- void T1_FreeOutline( T1_OUTLINE *path)
-\end{verbatim}\index{\verb+T1_FreeOutline()+}\postcorr
-It iterates through the segment list and frees each segment.
-This must not be done after filling an outline because the filling process
-consumes the outline!
-
-Finally, there are two functions that produce glyphs from outlines, namely
-\precorr
-\begin{verbatim}
- GLYPH *T1_FillOutline( T1_OUTLINE *path, int modflag)
-\end{verbatim}\index{\verb+T1_FillOutline()+}\postcorr
-and
-\precorr
-\begin{verbatim}
- GLYPH *T1_AAFillOutline( T1_OUTLINE *path, int modflag)
-\end{verbatim}\index{\verb+T1_AAFillOutline()+}\postcorr
-Their usage does not need any explanation. The value of \verb+modflag+ is
-required for {\em Right-To-Left} typesetting. If the bit
-\verb+T1_RIGHT_TO_LEFT+ is set, the dimension of the glyph are recomputed
-accordingly. All other bits from \verb+modflag+ are ignored such that in the
-usual case of {\em Left-To-Right} typesetting simply 0 can be specified.
-While \verb+T1_FillOutline()+ produces bitmaps of depth 1,
-\verb+T1_AAFillOutline()+ produces antialiased bytemaps of the current
-graphics depth. It should be mentioned that Smart Antialiasing (see
-\ref{smartantialiasing}) does not work with this function. The reason is that
-\tonelib\ has no notion of the quantity ``size'' when it gets the outline to
-process. Hence, Smart Antialiasing can't work in this case. As noted above,
-the outline is consumed by the filling functions so that there is no need to
-free it explicitly.
-
-
-\subsubsection{Manipulation of Outlines}
-\label{outlinemanipulation}%
-\tonelib\ provides some limited further functionality to process
-outlines. First of all, a user would expect a character to be defined in a
-coordinate system in which $x$ points to the right and $y$ points up. Further,
-a representation of the glyph where all points are specified in absolute
-coordinates would be advantageous for manipulating outline-points. This is
-because most transformations, linear or nonlinear, need to have an absolute
-$x$-value to compute an $y$-value or vice versa. The function
-\precorr
-\begin{verbatim}
- void T1_AbsolutePath( T1_OUTLINE *rpath)
-\end{verbatim}\index{\verb+T1_AbsolutePath()+}\postcorr
-does exactly what has been described just before, (a) conversion of relative
-coordinates into absolute coordinates and (b) inverting the
-$y$-direction.
-
-Once a path has been converted into an absolute path, it is
-suitable for possibly nonlinear manipulation.\footnote{A linear manipulation
- of path points would rather be realized using the transformation matrices as
- described in \ref{transformations}.}
-As an example of what can be done, have a look at figure \ref{figure:manipulation}.
-\begin{figure}[t]
-\hfill
-\includegraphics[scale=1.0]{manipulate}
-\hfill\break
-\vskip3mm
-\hrule\vskip3mm\small
-\caption{\label{figure:manipulation}A string with nonlinearly scaled coordinates.}
-\end{figure}
-The string displayed has been generated by essentially applying the
-transformation $y'= y(1+cx^2)$, with appropriate $c$. To allow such
-transformations by the user, \tonelib\ provides the function
-\precorr
-\begin{verbatim}
- void T1_ManipulatePath( T1_OUTLINE *path,
- void (*manipulate)(long *x,long *y, int type))
-\end{verbatim}\index{\verb+T1_ManipulatePath()+}\postcorr
-Here, \verb+path+ should be an absolute path as described above. Notice that
-\tonelib\ has no way to check whether the path is relative or absolute, this
-is in the responsibility of the user. The second argument is a pointer to a
-function that has a return type of \verb+void+ and that expects three
-arguments: two pointers to \verb+long+-values one integer \verb+type+.
-\verb+T1_ManipulatePath()+ works by iterating through all outline points of
-\verb+path+ and calling the function \verb+*manipulate()+ for each outline
-point. When the function \verb+*manipulate()+ is called, \verb+x+ and \verb+y+
-are pointers to the $x$- and $y$-coordinates respectively of the outline point
-to be processed. That way, \verb+*manipulate()+ can alter the outline
-points arbitrarily. The \verb+type+-argument will be set to the segment type
-by \verb+T1_ManipulatePath()+. As described earlier, the segment type can be
-one of \verb+T1_PATHTYPE_MOVE+, \verb+T1_PATHTYPE_LINE+ and
-\verb+T1_PATHTYPE_BEZIER+. Of course, the function \verb+manipulate()+ has to
-be written by the user. To make it clear, we consider a function which
-stretches an outline horizontally by 1.5. The code fragment for this could be:
-\begin{verbatim}
- .
- .
- .
-void h_stretch( long *x, long *y, int type)
-{
- double dx;
-
- dx=(double)*x;
- dx *=1.5; /* scale x coordinate by 1.5 */
- *x=(long)dx;
-}
- .
- .
- .
-T1_OUTLINE *path=NULL;
-path=T1_GetStringOutline(FontID,(char *)SomeString,
- 0,0,T1_KERNING,20.0,NULL);
-T1_AbsolutePath( path);
-T1_ManipulatePath( path, &h_stretch);
-T1_RelativePath( path);
-glyph=T1_FillOutline( path, Modflag);
- .
- .
- .
-\end{verbatim}
-
-As the example above already has shown, an absolute path, manipulated or not,
-must converted back to a relative path before it finally can be interpreted by
-the rasterizer. This conversion is done using
-\precorr
-\begin{verbatim}
- void T1_RelativePath( T1_OUTLINE *apath)
-\end{verbatim}\index{\verb+T1_RelativePath()+}\postcorr
-As already mentioned with respect to \verb+T1_AbsolutePath()+, \tonelib\ cannot
-check whether the \verb+path+ specified is really absolute. The user has to
-take care for this.
-
-A few general comments about manipulating paths are appropriate. Although the
-mechanism implemented by \verb+T1_ManipulatePath()+ allows arbitrary
-manipulation of path points, one must be very careful in doing so. Figure
-\ref{figure:outlineproblems} exhibits some of the problems that may arise. A text
-string aligned to a sine function is displayed.
-%- parameters of figure: string: Text aligned along a sine wave function
-% size: 50
-% kerning on
-\begin{figure}[t]
-\hfill
-a) \includegraphics[scale=0.5]{outlineproblems1} % period=500,
-\hfill\break
-
-\hfill
-b) \includegraphics[scale=0.5]{outlineproblems2} % period=200
-\hfill\break
-
-\hfill
-c) \includegraphics[scale=0.5]{outlineproblems3} % period=100
-\hfill\break
-
-\hfill
-d) \includegraphics[scale=0.5]{outlineproblems4} % period=50
-\hfill\break
-
-\hfill
-e) \includegraphics[scale=0.5]{outlineproblems5} % period=500
-\hfill\break
-\hrule\vskip3mm\small
-\caption{\label{figure:outlineproblems}The string ``Text aligned along a sine wave
- function'' using a period of (a) 500, (b) 200, (c) 100, (d) 50 pixels and
- (e) again 500 pixels with underlining. The sine amplitude was 30 pixels
- (in screen resolution).}
-\end{figure}
-In part (a), a pleasing smooth text flow is shown and this also applies for
-(b) where the period of the sine has been reduced to 200 pixels. In (c), where
-the period has been reduced to 100 pixels, some artefacts already show up. For
-example, the top bar of the uppercase ``T'' has noticeable variance in
-thickness. In (d), where the period has been reduced again, the result is
-hardly readable. Another artefact appears in figure
-\ref{figure:outlineproblems} (e): since the underlining rule is defined by
-four points only, these points and nothing else is transformed with the result
-that the out coming line is still straight and not curved as we would
-like. From this discussion we conclude, that such transformations can only be done
-with reasonable results if the maximum distance between the outline points of
-a shape is small compared to the variance of the outline points that the
-transformation results in. This rule, although being very fuzzy and
-non-mathematical, should give a good estimation of which transformations are valid.
-
-Another completely independent topic is that, at the level where \tonelib\
-provides outlines, their representation is strictly descriptive with respect
-to points and their connections. There are no such things like
-\verb+closepath+-segments which would take care that a path is really closed,
-no matter what the transformation had been. This means, that identical points
-$P_1 = P_2$ have to be transformed to identical points $P_1'=P_2'$, no matter
-where they appear in the outline. However,
-if the transformation is done by by a function $(x',y')=f(x,y)$ as suggested,
-this should never be a problem.
-
-Finally, one should remember that all computations in the user function
-\verb+manipulate()+ have to be done in units of fractional pixels, rather than in
-pixels. When designing a sine wave as in figure \ref{figure:outlineproblems},
-this must be taken into account with respect to periodicity.
-
-\subsection{Logical Fonts}
-\label{logicalfonts}%
-It sometimes may be necessary to have a font and an extended or slanted
-variant simultaneously. To enable such configurations without needing to
-declare the fonts two or even more times in the font database file,
-\tonelib\ provides the function
-\precorr
-\begin{verbatim}
- int T1_CopyFont( int FontID)
-\end{verbatim}\index{\verb+T1_CopyFont()+}\postcorr
-It copies the top level data structure of the font given by \verb+FontID+ to
-another location. The newly created font refers in fact to the same
-physical memory as the font \verb+FontID+ as far as Type 1 and AFM data are
-concerned. However, no size specific data is copied from font \verb+FontID+,
-you can thus do with the new font whatever you want to. It will get its own
-size-specific memory area when the first bitmap is generated using its ID.
-
-It is also possible to reencode a copied font without affecting the
-original font. This is possible because a logical font gets its own
-mapping tables. This allows configurations with one font at different
-encodings simultaneously.
-
-In order to keep track that another font is referring to data from
-font \verb+FontID+, a reference counter is managed for every font. The
-reference counter for font \verb+FontID+ is incremented after a call to
-\verb+T1_CopyFont()+.
-
-If the font \verb+FontID+ is not loaded into memory, the function returns $-1$.
-
-Only {\em physical} fonts---those fonts defined in the font database
-file or added via \verb+T1_AddFont()+---may be copied to another
-font. If a user tries to copy a font
-which is already logical, the function returns $-2$.
-
-If no memory is available for the new font the function return $-3$. But
-this should not happen.
-
-If all goes the right way, \verb+T1_CopyFont()+ returns an integer---lets call
-it \verb+new_ID+---which is from now on a valid font identification number.
-
-\subsection{Missing or Invalid AFM Files}
-\label{missingafmfiles}%
-\tonelib\ heavily relies on AFM information every time the relative position
-of bitmaps is of importance. Because AFM information is of high resolution,
-accumulating positioning errors are avoided in contrast to what the X11 text
-drawing functions do. On the other hand, there are many freely available
-Type~1 font programs that come without AFM files. This problem has been
-addressed in \tonelib\ 0.5. \tonelib\ is now able to generate AFM information
-on the fly and it even can generate AFM files from Type 1 font files.
-
-\subsubsection{Remarks on AFM Files}
-\label{remarksonafmfiles}%
-Information in AFM files is only relevant for placing character glyphs but not
-for rasterizing. The metric values are based on the same coordinate system as
-used in Type 1 font files, the so called {\em charspace coordinate system}.
-One unit is $1/1000 \mbox{bp}$ when a font is not scaled or scaled to 1~bp,
-respectively.
-
-Information in AFM files can divided into several groups:
-\begin{enumerate}
-\item {\em Global Font Information:} This information is generally not needed
- to place characters. Furthermore, most of this information is also
- contained in a Type 1 font file itself. This area is thus of marginal
- importance for \tonelib.
-\item {\em Character Width's and Bounding Boxes:} These both are crucial for
- accurately placing the character glyphs. Fortunately, these are dimensions
- are exactly defined by the character outlines themselves. It is thus
- possible to compute them spending some computational effort.
-\item {\em Ligature Information:} For \ae sthetic reasons, certain character
- groups are often replaced by ligatures and a font file may define several
- ligatures. It is however not intuitively clear what character groups should
- be replaced by what ligatures.\footnote{Well, at least not without some
- expert knowledge like ``I know this ligature's name is `f{}i', so I
- replace every series of `f' and `i' with it.''}
- Fortunately, ligatures are not crucially needed for quality typesetting.
-\item {\em Pair Kerning Information:} This information is quite important for
- \ae sthetic reasons but it is entirely independent from the outline
- descriptions and can thus not be extracted from a font file.
-\item {\em Track Kerning Information:} This information gives hints of how to
- typeset text generally closer or wider at varying point sizes.
- \tonelib\ does not use track kerning
- information and I personally do not consider using track kerning a good
- typographical style.
-\item {\em Composite Character Data:} This is needed to construct characters
- from two single characters. Typical examples are accented
- characters. \tonelib\ currently does not deal with composite
- characters. Most of the composite characters needed are already existent
- internally.
-\end{enumerate}
-To come to a conclusion, for our purposes it is sufficient to generate the
-characters' widths and their bounding boxes and we have all information we
-need to construct string glyphs.
-
-\subsubsection{Generation of AFM Information}
-\label{generatingafminfo}%
-Next lets consider how to generate the AFM information. It is a series of
-entirely independent steps:
-\begin{itemize}
-\item When we generate AFM information, we want to do this once and forever
- when the font is loaded. Consequently all characters, have to be examined,
- not only those that are currently encoded.
- We start by fetching all character names the font defines. This done with
- \verb+T1_GetAllCharNames()+ (see \ref{characterencodingrelation}). This
- yields a list of possibly more than 256 character names.
-\item Each of the character addressed by the names above is now rastered at
- size 1000~bp. By rastering at 1000~bp we match exactly the charspace
- coordinate system which the character outline descriptions are
- based on. Width and bounding box are easily examined and saved at
- appropriate places.
-\item The kerning pair area and ligatures are explicitly set to zero.
-\end{itemize}
-At the end of this procedure, there is a data area identical to what would
-have been built when reading an AFM file without kerning-section and ligature
-specifications.
-
-The decision of building AFM data is done on the fly without any user
-interaction. Here is what happens on the metrics-area when loading a font:
-\begin{itemize}
-\item \tonelib\ tries to open an AFM file reading metrics and kerning pair
- information.
-\item If this does not succeed, it tries to rescan the AFM file in a {\em
- sloppy} way, only requesting metrics information.
-\item If this fails too, metrics information is generated on the fly as
- described above.
-\end{itemize}
-It should be noted that generating metric information the way described above
-takes significant amount of time since every character has to be rastered at
-1000~bp.
-
-%~derekn
-If the \verb+T1_NO_AFM+ flag is passed to \verb+T1_InitLib()+,
-\tonelib\ will neither attempt to open AFM files nor generate AFM
-information. This is useful to speed up applications which do not
-need the metrics data. However, this slows down access to certain features,
-mostly related to the string processing functions, and completely disables the
-features that only are contained in AFM files (like kerning and ligatures).
-
-Obivously, the \tonelib\ functions that use
-the AFM data will not work correctly in this case and should not be
-used.
-%~derekn
-
-\subsubsection{Writing AFM Files}
-\label{writingafmfiles}%
-In order to reduce the situations where AFM data has to be generated on the
-fly, \tonelib\ provides the following function:
-\precorr
-\begin{verbatim}
- int T1_WriteAFMFallbackFile( int FontID)
-\end{verbatim}\index{\verb+T1_WriteAFMFallbackFile()+}\postcorr
-It writes an AFM file for the font identified by \verb+FontID+. This is done
-executing the following steps:
-\begin{enumerate}
-\item The AFM filename is constructed by taking the fontfilename, cutting off
- the extension and appending \verb+.afm+.
-\item A pointer array of size $256 + n$, where $n=\mbox{number of
- characters}$, is
- allocated and set to NULL. The leading 256 entries are reserved to point to
- encoded
- characters' metrics. The remaining entries are intended to point to metrics
- of unencoded characters. We see that this is a worst case speculation: The
- pointer array is large enough for the extremely unusual case that no
- characters are encoded.
-\item Next the function steps through all character names and gets their
- encoding index $i$. If $i\geq0$, the character is encoded and the $i$th
- pointer element in the array is set to point to the metrics of this
- character. If $i=-1$, the character is not encoded and the lowest unused
- pointer in the second area is set to point to the metrics of this character.
-\item Next the AFM file is opened and the header information as well as a
- comment by \tonelib\ are written. There are 5 entries that are not trivially
- to extract from the font file: \verb+Ascender+, \verb+Descender+,
- \verb+XHeight+, \verb+CapHeight+ and \verb+EncodingScheme+. Their
- discussion is deferred to later in this section.
-\item After the header, the metrics information is written in the format
- required for AFM files. This is done by stepping through the pointer array
- until the first NULL pointer in the unencoded characters' area is
- reached.
-\end{enumerate}
-The result is a list of char-dimensions entries which is leaded by the encoded
-characters in ascending order of their encoding index, followed by a list of
-unencoded characters in alphabetical order.
-
-As seen above, the current encoding takes influence on the order the
-characters appear in the AFM file. One should thus not produce AFM files from
-reencoded fonts, although this is possible. This yields non-standard AFM files
-and gives no performance gain, even not when used with \tonelib.
-
-The entry \verb+EncodingScheme+ is not always contained in the fontfile
-itself. It is generated by comparison between encodings. \tonelib\ has only one
-builtin encoding, \verb+AdobeStandardEncoding+, which
-is recognized. Every further encoding, defined
-by the font itself or applied by a user, is always marked as
-\verb+FontSpecific+.
-
-The entries \verb+CapHeight+, \verb+XHeight+ \verb+Ascender+ and
-\verb+Descender+ are not fully determined by a Type 1 font file
-although they are existent with high probability. As rough definitions
-can be considered:
-\begin{itemize}
-\item \verb+CapHeight+: The height a capital `H' reaches to.
-\item \verb+XHeight+: The height a lower case `x' reaches to.
-\item \verb+Ascender+: The height a lower case `d' reaches to.
-\item \verb+Descender+: The depth a lower case `p' reaches down.
-\end{itemize}
-It is obvious that these definitions make only sense in certain font
-definitions. For example, a musical notation font might not necessarily
-define an ascender since no capital letters are provided.
-
-In the Type 1 notion these dimensions are referred to as top alignment
-and bottom alignment values respectively. The corresponding alignment
-``zone'', i.e., an interval, is defined by the alignment height and a
-corresponding overshoot position. The alignment zones are specified in
-the BlueValues array for top alignment zones and the OtherBlues
-array for bottom alignment zones. A Type 1 font may define up to 7 top
-alignment zones and 5 bottom alignment zones. It is unfortunately not
-defined which of these alignment zones refer to \verb+CapHeight+,
-\verb+XHeight+, \verb+Ascender+ and \verb+Descender+.
-
-\tonelib\ tries to get out of this dilemma by making a best guess:
-\begin{enumerate}
-\item For each of the characters `H', `x' and `d' it fetches the
- largest y-value and compares the result with each alignment zone in
- the BlueValues array. The alignment zone closest to the observed
- character dimension is assumed a candidate for the respective
- quantity.
-\item It checks whether the difference between the alignment zone just
- selected and the character dimension is within a certain tolerance
- area. This tolerance width is $\pm 30$ charspace units. If the
- result is positive, the quantity in question is assigned the
- numerical value of the standard height (not the overshoot) of this
- alignment zone. Since we are currently considering top
- alignment zone, this will always be the lower value.
-\item If the value is out of tolerance or the font even does not
- define the character, the corresponding entry in the AFM file is left
- out.
-\item A comparable procedure is then done for \verb+Descender+, this
- time examining the OtherBlues array.
-\end{enumerate}
-Note that if the values do not seem to be correct, the corresponding
-lines can be removed from the AFM file without doing any harm. These
-entries are optional only.
-
-\verb+T1_WriteAFMFallBackFile()+ can indicate a number of error
-conditions by returning appropriate values. These are:
-\begin{itemize}
-\item \verb+0+: No error occurred, AFM file was successfully written.
-\item \verb+-1+: The AFM data for the font in question has been
- generated by reading an AFM file, there is no need to generate a new
- one. If you really want to force an AFM file to be written, take
- care that \tonelib\ does not find an AFM file when loading the
- font.
-\item \verb+-2+: The font in question is not loaded.
-\item \verb+-3+: The font in question is loaded but AFM data has not
- been generated. This definitely is an error condition because it
- indicates not all characters of the font could be rastered, either
- because the font file is damaged or because there were
- insufficient system resources. In any case the application should
- generate a logfile and this file should be examined.
-\item \verb+-4+: The AFM file could not be opened. This could be a
- permission problem or something else. The file is always opened in
- the current working directory.
-\item \verb+-5+: The file has successfully been opened but there was
- an error writing to the file.
-\item \verb+-6+: A memory allocation error occurred. This should not
- happen because it indicates there are no system resources.
-\end{itemize}
-
-
-
-\subsection{Font Subsetting}
-\label{Font Subsetting}%
-When applications have to setup Postscript files for printing, the problem is
-that these files often grow large. Each font which is not known to the
-Postscript interpeter, i.e., usually each font that is not part of the set of
-35 standard fonts, has to be downloaded as part of the file. The size of a
-particular font file often can be reduced by font subsetting, because usually
-only a small subset of the available character descriptions is actually
-needed.
-
-
-
-\subsubsection{Font File Organization and Subsetting}
-\label{Font File Organization and Subsetting}%
-
-Each Type~1 font file is a special Postscript program defining three
-Postscript-dictionaries:
-\begin{itemize}
-\item \verb+FontInfo+\\
- Global font information like font and family name and encoding scheme is
- stored here. This data is required even for a subsetted font. However, as
- will be described later, the encoding scheme may be reduced to those
- characters that are in the desired subset.
-\item \verb+Private+\\
- This dictionary is in the encrypted part of the file and stores global font
- data too. This data includes quantities parameterizing hinting and
- subroutines that might be called by the character descriptions. This data is
- required also.
-\item \verb+Charstrings+\\
- For each character defined in the font a binary and encrypted byte string
- (charstring) coding the character outline is stored in this dictionary. The
- number of charstrings may be considerably larger than the size of the
- encoding vector. This dictionary usually constitutes the largest part of the
- font file and, consequently, it is the place to reduce storage requirements.
-\end{itemize}
-The main principle in subsetting is to decrypt the font and reorganize it,
-leaving out charstrings that are not required in the current context. For
-example, if a document uses only the character 'A' from the font Garamond,
-then this font may be subsetted preserving the character outline for 'A'
-only. The resulting file, which will be much smaller than the original file,
-can then be included verbatim into the Postscript file containing the
-document. At the same time, optionally, the encoding vector could be redefined
-to contain only the entry for 'A' at the appropriate location and
-\verb+.notdef+ otherwise.
-
-A still more consequent subsetting would involve leaving out those subroutines
-from the \verb+Private+-dictionary that are not needed by the preserved
-charstrings. Leaving out some subroutines on the other hand would require to
-interprete and check all charstrings for the subroutines they require and all
-preserved charstrings would have to be adapted to the reorganized index. Since
-the subroutines usually do not consume that much memory this is not considered
-worth the effort.
-
-\subsubsection{Functions for Subsetting}
-\label{Functions for Subsetting}%
-
-There are two ways to obtain a subsetted font from an existing file. The user
-can (1)~do it step by step which requires reading, decrypting, reorganizing
-and encrypting of the font file, and (2)~use a high level function to do it
-without having to know anything about the details. For font subsetting,
-\tonelib\ provides the function
-\precorr
-\begin{verbatim}
- char *T1_SubsetFont( int FontID, char *mask,
- unsigned int flags, int linewidth,
- unsigned long maxblocksize,
- unsigned long *bufsize)
-\end{verbatim}\index{\verb+T1_SubsetFont()+}\postcorr
-It returns a pointer to a memory block containing the subset data. The memory
-is allocated in the function and it is the responsability of the user to
-free this memory. The parameter \verb+FontID+ as usual is used to tell
-\tonelib\ which file or font is to be used for the operation.
-
-\verb+mask+ points to an array of characters which has to be setup by the
-user. This array must comprise exactly 256 characters and for the index of
-each non-zero entry the charstring resulting from the current encoding is
-preserved in the subsetted font. To give an instance, if the subset should
-consist in the character 'A' only and we assume the current font specifies
-\verb+StandardEncoding+, then the \verb+mask+-array should be initialized to
-zeroes and \verb+mask['A']=1+ or some other non-zero value.
-
-The \verb+flags+ parameter allows to control the subsetting operation. It
-usually should be set to \verb+T1_SUBSET_DEFAULT+. In this case, the subset is
-ASCII-hex encrypted, that is, as in a \verb+.pfa+-file. It is thus well-suited
-for the verbatim insertion into a Postscript file. If the source font file in
-question defines the encoding to be \verb+StandardEncoding+, the encoding is
-not adjusted to the subset specified by \verb+mask+. By contrast, if the font
-defines a \verb+FontSpecific+ encoding, this encoding will be adjusted
-according to the subset. This default behavior---which mimics what
-e.g.~\verb+dvips+ seems to do---may be overwritten by OR'ing \verb+flags+ with
-\verb+T1_SUBSET_FORCE_REENCODE+, which leads to adjusting the encoding vector
-in any case. Conversely, reencoding can be suppressed unconditionally by OR'ing
-\verb+flags+ with \verb+T1_SUBSET_SKIP_REENCODE+. If \verb+flags+ is OR'ed
-with \verb+T1_SUBSET_ENCRYPT_BINARY+, a buffer of mixed ASCII, binary and EOF
-segment types is created and encryption is performed in binary mode. The
-buffer's contents in this case represents a valid compact binary format file
-(\verb+.pfb+). It is considerably smaller than a comparable \verb+.pfa+-file
-but it is not suitable to be inserted into Postscript files.
-
-The parameter \verb+linewidth+ is used to specify the line length if ASCII-hex
-encryption is used. Since---according to the Adobe speification---the first 8
-encrypted bytes have to be stored one after the other without interspersed
-white space, the allowed range of \verb+linwidth+ is limited to 8 at the lower
-bound. It is also limited at the upper bound by 1024, because writing that
-long lines does not preserve the readability of the produced file.
-
-The parameter \verb+maxblocksize+ is important if binary encryption is
-used. Then, this value specifies the maximum allowed segment size. For similar
-reasons as discussed above, this value must be equal to or larger
-than~4. There is no limit at the upper bound, because the maximum segment size
-can be derived automatically follows from the target font file.
-
-\verb+bufsize+ must be a valid pointer to an \verb+unsigned long int+ in the
-context of the calling function. The size of the memory area to which the
-function returns a pointer, is written to \verb+bufsize+. The calling function
-needs this number to process to buffers contents, e.g., to write it to a file.
-
-If errors occur in this function, \verb+NULL+ is returned and \verb+T1_errno+
-is set to an appropriate value. If the font corresponding to \verb+FontID+ is
-not loaded, \verb+T1_errno+ is set to \verb+T1ERR_INVALID_FONTID+.
-\verb+T1ERR_INVALID_PARAMETER+ is used to indicate that one of the further
-arguments is out of range. \verb+T1ERR_ALLOC_MEM+ and
-\verb+T1ERR_FILE_OPEN_ERR+ may also be set in this function. Finally,
-\verb+T1ERR_UNSPECIFIED+ may also be set if the charstring definition for
-\verb+.notdef+ could not be located. This is considered to be a fatal error.
-
-An example of how to use the function described above is given in the file
-\verb+subset.c+ in the \verb+examples/+ subdirectory of the distribution.
-
-\subsubsection{Further Functions for Subsetting}
-\label{Further Functions for Subsetting}%
-
-For the sake of completeness, there are a few further functions in the
-subsetting module. The function
-\precorr
-\begin{verbatim}
- char *T1_GetCharString( int FontID, char *charname, int *len)
-\end{verbatim}\index{\verb+T1_GetCharString()+}\postcorr
-returns a pointer to the charstring of the character with name \verb+charname+
-of the font identified by \verb+FontID+. In case of an error, \verb+NULL+ is
-returned and \verb+T1_errno+ is set to \verb+T1ERR_ALLOC_ERR+ if there was not
-enough memory for storing the charstring, \verb+T1ERR_UNSPECIFIED+ if the
-charstring was not found in the dictionary, \verb+T1ERR_INVALID_FONTID+ if the
-font in question is not loaded or \verb+T1ERR_INVALID_PARAMETER+ if
-\verb+charname+ or \verb+len+ is \verb+NULL+. The memory pointer which is
-returned is managed static in this function. Thus, it should not be free'd by
-the user, or, in case the memory block is free'd, the pointer must be set to
-\verb+NULL+.
-
-In order to decrypt a charstring, the \verb+lenIV+-value of the font in
-question must be known. It can be obtained using the function
-\precorr
-\begin{verbatim}
- int T1_GetlenIV( int FontID)
-\end{verbatim}\index{\verb+T1_GetLenIV()+}\postcorr
-The returned value indicates how many leading random bytes are used for
-charstring encryption in the font \verb+FontID+. According to an undocumented
-Adobe convention, the value $-1$ is also valid and indicates that the
-charstring is not encrypted at all. Hence the return value $-2$ is used to
-indicate an error. In this case, \verb+T1_errno+ is set to
-\verb+T1ERR_INVALID_FONTID+, which indicates that the font in question is not
-loaded.
-
-
-\subsection{Composite Characters}
-\label{subsec:CompositeCharacters}%
-
-This section discusses the composite character information that may be present
-in AFM files and how this information is represented, accessed and handled in
-\tonelib.
-
-\subsubsection{General remarks}
-\label{subsubsec:General Remarks}%
-
-Composite characters are defined by the fact that they are constructed from at
-least two independent symbols. In practice there frequently appear two
-components, a base character and an accent, e.g., as in ``\"A''. Usually, the
-accents (or secondary pieces) of a composite character are typeset first
-without causing any horizontal escapement and finally the base character
-itself is typeset and causes its escapement to become the escapement of the
-whole composite character. Although some people recommend that the character
-definition of an accent itself should not cause escapement, this generally is
-not respected in real fonts and \tonelib\ does not require this condition to
-be fulfilled.
-
-In order to construct a composite character the characters to be put together
-have to be known and metric information about how to put these characters
-together has to be known too. \tonelib\ defines two structures as new data types
-for this purpose. The first is
-\begin{verbatim}
-typedef struct
- {
- int compchar;
- int numPieces;
- T1_COMP_PIECE *pieces;
- } T1_COMP_CHAR_INFO;
-\end{verbatim}
-Here, \verb+compchar+ is the index in the encoding vector of the composite
-character. \verb+numPieces+ specifies how many pieces are
-required to build the composite character. The third element is a pointer to
-an array of type \verb+T1_COMP_PIECE+, whose actual length is given by
-\verb+numPieces+: Each piece (or symbol) receives one slot in this
-array. \verb+T1_COMP_PIECE+ is defined by
-\begin{verbatim}
- typedef struct
- {
- int piece;
- int deltax;
- int deltay;
- } T1_COMP_PIECE;
-\end{verbatim}
-It contains the encoding index of the symbol in \verb+piece+ and information
-where to place this symbol with respect to the composite character's orgin in
-\verb+deltax+ and \verb+deltay+. The first slot is filled by what I refer to
-as the base character, it is the one that causes spacing. As can be seen in
-these data structures, composite character handling in \tonelib\ is based on
-encoding indices rather than on character names, which, by contrast, are used
-for the definition of composite character data in AFM files.
-
-The presence of composite character information in AFM files does not tell
-anything about whether a font has an internal definition of this character or
-not. For example, the font \verb+TimesRoman+ internally defines the CharString
-\verb+Adieresis+ and hence this font provides the letter ``\"A'', assuming an
-appropriate encoding, without any knowledge about composite
-characters. However, the file \verb+TimesRoman.afm+ may still
-provide composite character information for \verb+Adieresis+, just to tell an
-application that this glyph consists of more elementary pieces and how to
-construct it. On the other hand, if \verb+TimesRoman+ had no
-CharString-definition for \verb+Adieresis+, the composite character
-information of \verb+Adieresis+ provides an application with enough
-information to be able construct \verb+Adiereis+ from the elementary units
-\verb+A+ and \verb+dieresis+ that the font provides.
-
-
-\subsubsection{Accessing Composite Character Data}
-\label{subsubsec:Accessing Composite CHaracter Data}%
-
-This section describes a few functions that provide access to composite
-character data of a font file. The data they return can be considered a
-mapping of the original AFM data with respect to the current encoding. As
-usual, \verb+FontID+ must be the identifier of a font loaded into memory,
-otherwise an appropriate error indicator is returned. The functions described
-in the following may also return some other error types.
-
-Firstly,
-\precorr
-\begin{verbatim}
- int T1_GetNoCompositeChars( int FontID)
-\end{verbatim}\index{\verb+T1_GetNoCompositeChars()+}\postcorr
-tells the user how many composite character definitions are given in the AFM
-file. This, of course, does not depend on the current encoding vector and it
-is even possible that the current encoding vector does not incorporate any
-composite character at all.
-
-The function
-\precorr
-\begin{verbatim}
- int T1_QueryCompositeChar( int FontID, char char1)
-\end{verbatim}\index{\verb+T1_QueryCompositeChar()+}\postcorr
-checks whether composite character information exists for the encoding index
-\verb+char1+. If so, it returns the index within in the AFM composite
-character data array as a number equal to or greater than zero. If the result
-is valid but no composite character information has been found for
-\verb+char1+, $-1$ is returned. In case of an error, $-2$ is returned and
-\verb+T1_errno+ is set to an appropriate value.
-
-The previous function does not tell anything about whether the font
-\verb+FontID+ incorporates a character definition for the composite char or
-not. This can be queried using
-\precorr
-\begin{verbatim}
- int T1_IsInternalChar( int FontID, char char1)
-\end{verbatim}\index{\verb+T1_IsInternalChar()+}\postcorr
-It returns $1$ if there exists a CharString for \verb+char1+ and $0$ if not.
-In the latter case, the application is responsible for the construction of the
-composite character (see later). \verb+T1_IsInternalChar()+ also might return
-$-1$ and set \verb+T1_errno+, which indicates that the font in question is not
-loaded.
-
-The information required to construct a composite character is retrieved by
-calling the function
-\precorr
-\begin{verbatim}
- T1_COMP_CHAR_INFO *T1_GetCompCharData( int FontID, char char1)
-\end{verbatim}\index{\verb+T1_GetCompCharData()+}\postcorr
-It returns a pointer to a meaningfully filled struct of type
-\verb+T1_COMP_CHAR_INFO+ as described above. The composite character and the
-number
-of pieces as well as a pointer to the array of type \verb+T1_COMP_PIECE+ are
-stored in this structure. Once this information is obtained the composite
-character can be constructed by
-\begin{itemize}
-\item placing the accent symbols in a loop that ranges from $1$ to
- \verb+numPieces+$-1$. In practice this loop will often be executed only
- once. The initial current point must always be restored. In this loop
- positioning information is accessed by \verb+ptr->pieces[+$i$\verb+].deltax+
- and \verb+ptr->pieces[+$i$\verb+].deltay+, where \verb+ptr+ is the pointer
- returned by the above function.
-\item placing the base character (\verb+pieces[0]+), which then also causes
- the horizontal escapement of the composite character.
-\end{itemize}
-
-In cases where \verb+char1+ is not a composite
-character, the \verb+compchar+ entry is set to \verb+char1+ itself and
-\verb+numPieces+ becomes $1$, as would be expected. The \verb+pieces+ pointer
-is then set to \verb+NULL+. In case of errors, this function returns
-\verb+NULL+ and \verb+T1_errno+ is setup correspondingly.
-
-The pointer returned by this function should always be free'd using
-\verb+T1_FreeCompCharData()+ in order to avoid memory leaks (see also
-Section~\ref{deletingdata}).
-
-A function that provides the same functionality is
-\precorr
-\begin{verbatim}
- T1_COMP_CHAR_INFO *T1_GetCompCharDataByIndex( int FontID, int index)
-\end{verbatim}\index{\verb+T1_GetCompCharDataByIndex()+}\postcorr
-In this case, the information is requested by means of an index \verb+index+
-in the AFM composite character data array. This function is thus well-suited
-for scanning the complete composite character information of a given font in a
-given encoding. \verb+index+ may, for example, be obtained by a call to
-\verb+T1_QueryCompCharData()+ as described above. The valid range for
-\verb+index+ is from $0$ to the value returned by
-\verb+T1_GetNoCompositeChars()+ minus one. The range of \verb+index+ is
-validated and in case of an error \verb+T1_errno+ is to
-\verb+T1ERR_INVALID_PARAMETER+. There may also appear other errors and under any
-erroneous condition, \verb+NULL+ is returned.
-
-The parameter \verb+compchar+ of the \verb+T1_COMP_CHAR_INFO+ structure that
-is referenced by the returned pointer, bears somewhat more information for
-this function than in the case of \\
-\verb+T1_GetCompCharData()+. As said it contains the index in the encoding
-vector where the composite glyph is encoded. It may also have the vaue $-1$,
-which means that the composite character is not encoded. Note that this is not
-an error condition.
-
-
-\subsubsection{Transparent Handling of Composite Characters and User Extensions}
-\label{subsubsec:Transparent Handling of Composite Characters and User
- Extensions}%
-
-Aside from the fact that composite character information may be accessed in
-\tonelib, \tonelib\ can automatically---and completely transparently with
-respect to the user---compose characters if it finds information on how to do
-so. To give an instance, let us examine the font ComputerModern Roman
-(cmr10). Because this font is specially encoded for the use with early (7-bit)
-\TeX-systems, it does not incorporate a definition for \verb+Adieresis+. The
-definition simply was not required because \TeX\ itself constructed the
-composite character by means of its \verb+\accent+-primitive. If a font like
-cmr10 is reencoded e.g.~to IsoLatin1 encoding, the character ``\"A'' will show
-up as a blank because there is no definition for \verb+Adieresis+. Now, if the
-corresponding AFM file is extended with the following lines, it becomes
-possible to access an \verb+Adieresis+:
-\begin{verbatim}
-StartComposites 1
-CC Adieresis 2; PCC A 0 0; PCC dieresis 100 200;
-EndComposites
-\end{verbatim}
-This line in an AFM file provides information about how to construct an
-\verb+Adieresis+ from the \verb+A+ and \verb+dieresis+ glyphs, and \tonelib\
-can utilize this information to construct the requested glyph without that
-this will be be noticed by the user.
-
-Composite character are treated just the same way as standard characters.
-They are cached, they can be scaled, transformed etc. Let us assume that the
-cache is still empty and a character, identified by its encoding index, now is
-to be rastered. The following happens in the rastering function:
-\begin{enumerate}
-\item \tonelib\ looks up the character's name in the encoding vector and tries
- to locate the CharString for that character. If this succeeds all works as
- usual, notwithstanding the fact that there might have been composite
- character information for that char. This means, font-internal
- CharString-definitions have highest priority: One cannot, for example,
- re-define an \verb+Adieresis+ by raising the umlaut ``\"{ }'' via a composite
- character definition, if \verb+Adieresis+ is defined internally.
-\item However, if the CharString is not found, composite character information
- is examined and if possible, elementary units are used to construct the
- requested composite character by concatenating paths.
-\end{enumerate}
-In any case, the resulting character is put into the cache and is from then on
-available as any other character. If pieces of a composite character are not
-found in the CharStrings dictionary, those pieces are substituted by
-\verb+.notdef+, so that for extreme cases the whole composite character might
-be substituted by a \verb+.notdef+. Then, an appropriate message is put into
-the log file with priority \verb+T1LOG_WARNING+ and \verb+T1_errno+ is set to
-\verb+T1ERR_COMPOSITE_CHAR+.
-
-In the same way \tonelib\ composes characters without user intervention, the
-functions for character metrics are aware of composite character information
-and the returned result are also valid for those functions.
-
-
-\subsubsection{Caveats}
-\label{subsubsec:Caveats}%
-
-Although handling of composite character is widely automated, problems may
-arise. Most importantly it is the responsibility of the user to take care that
-font file and AFM file provide consistent data. Alas, this is not always true
-for existing font and AFM files. If, for example, an AFM file is extended by
-composite character definitions and these composite character definitions
-reference symbols that are not defined in the CharsStrings dictionary, errors
-will result. If composite character information is added to an AFM file, the
-following rules have to be respected:
-\begin{itemize}
-\item The name of the composite character has to be encoded because it could
- not be accessed otherwise. Furthermore, no internal definition in the
- CharStrings dictionary may exist because this would override the composite
- character definition from the AFM file.
-\item The user should verify that all components of a composite character
- definition have entries in the CharStrings dictionary. This can be checked
- for example by using\\ \verb+T1_GetAllCharNames()+ or by disassembling the font
- file.
-\item Even being more restrictive, the user should take care that all pieces
- of a composite character are encoded. For \tonelib\, this is really
- irrelevant because, internally, characters may be accessed by the name of
- their CharString. This means \tonelib\ simultaneously has access to all
- characters defined in a font. However, an application that exports PostScript
- files can only access character definitions via their position in the
- encoding vector. Composing a character from pieces of different encodings
- will require two font definitions in a exported PostScript file for
- typesetting one character, which cannot be termed a clean strategy.
-\end{itemize}
-
-
-\subsection{Error Handling}
-\label{errorhandling}%
-Although every function usually returns meaningful values, there are
-situations where indicating an error via the return value is not possible. For
-example, requesting a charspace bounding box from a char of a font which is not
-loaded will return a bounding box containing all zeroes. This cannot be
-considered an error-condition since for characters like ``space'' it is
-correct to return a bounding box containing all zeroes. Furthermore, there's no
-consistent scheme which value should indicate what type of error. In order to
-allow a unified error handling in applications, the global variable
-\verb+T1_errno+ has been introduced.
-
-The functionality of \verb+T1_errno+ is analogous to that of the global
-\verb+errno+ in C programs. \verb+T1_errno+ is once set to 0 when the library
-is initialized and never reset by any \tonelib-function. It is set to specific
-values when specific types of errors appear. An application may then act
-appropriately and reset \verb+T1_errno+.
-The errors that might appear can be roughly split into three categories as
-described below.
-
-\subsubsection{Type 1 Font File Scan-Errors}
-These types of errors can only appear at the time a font file is loaded.
-These kinds of errors are indicated by negative values:
-\begin{itemize}
-\item \verb+T1ERR_SCAN_FONT_FORMAT+ (-5): A Multiple Master Font was attempted
- to be loaded. These are not supported by \tonelib.
-\item \verb+T1ERR_SCAN_FILE_OPEN_ERR+ (-4): This value indicates that the Type
- 1 font file could not be opened by the parser. It usually does not mean that
- the file does not exist because this problem would have shown up at the time
- the font database had been built. It is more likely a permission problem.
- Anyhow, the C library variable \verb+errno+ should be examined for getting
- an idea of what the problem was.
-\item \verb+T1ERR_SCAN_OUT_OF_MEMORY+ (-3): A Type 1 font program required
- more than 262144 bytes of VM. This is a limit imposed by \tonelib\ because
- it usually means there goes something wrong. Typical values of VM
- consumption are between 30000 and 60000 bytes depending on the fonts'
- complexity. If this limit really does not suffice the constant
- \verb+MAXTRIAL+ (defined in \verb+lib/type1/fontfcn.c+) may be set to some
- larger value.
-\item \verb+T1ERR_SCAN_ERROR+ (-2): An error occurred during scanning the font
- file. It usually means that the font file is damaged or does not comply to
- the conventions of Type 1 font files. For example, an encountered token might
- have been too long. Another reason could be, a literal name follows a literal
- name where a number was expected. There is no way to recover from this
- error. One last resort could be to disassemble the font (e.g., using
- \verb+t1disasm+ from the \verb+t1utils+ package) and scan the resulting
- human-readable file for possible violations of the Type 1 font format
- specifications. However, some knowledge about the format is in force.
-\item \verb+T1ERR_SCAN_FILE_EOF+ (-1): A premature end of file was encountered
- during parsing. The file is damaged.
-\end{itemize}
-
-
-\subsubsection{Path Generation Errors}
-Small positive number are reserved for errors that might appear during path
-construction and rasterization.
-\begin{itemize}
-\item \verb+T1ERR_PATH_ERROR+ (1): An error occurred during path
- construction. The font file is most probably damaged.
-\item \verb+T1ERR_PARSE_ERROR+ (2): This kind of error describes a kind of
- ``semantic'' error in the font file. A typical candidate for this is a font
- that does not define a character named \verb+.notdef+, although this is
- required by the format specification. Since under usual conditions the
- \verb+.notdef+ character is never accessed, this error would not show
- up. But if for some reason the \verb+.notdef+ has to be substituted for some
- other character the problem becomes evident.
-\item \verb+T1ERR_TYPE1_ABORT+ (3): The \verb+abort()+-function of the
- rasterizer has been called. This may happen at several places during
- hinting, converting to edgelists etc. There is a certain chance that
- unfreed memory has been left. If this error appears and a logfile is used,
- an error string giving some more info is placed into the logfile.
-
- This error should not appear, normally. If it does, either the font file is
- damaged or the font contains invalid outline descriptions such as unclosed
- paths. Especially the latter is quite unlikely. Of course this error can be
- raised, when an outline has been modified manually in an invalid way and is
- then rastered (see.~\ref{outlinemanipulation}).
-\end{itemize}
-
-\subsubsection{\tonelib-Errors}
-The remaining types of errors are detected by the management of \tonelib. Their
-numbering starts with 10 (decimal). The list could be extended in future
-releases.
-\begin{itemize}
-\item \verb+T1ERR_INVALID_FONTID+ (10): An invalid font ID has been
- specified. The exact meaning of this error depends on the specific
- situation, in any case the operation requested cannot be realized with the
- identified font. Possible reasons are:
- \begin{itemize}
- \item The font ID points to a font which is not loaded and which must be
- loaded in order to perform the operation.
- \item The specified font ID is a number which is generally out of the range
- of the valid font IDs, either because it is $<0$ or because it is $>$ the
- value of \verb+no_fonts+.
- \item The library is not yet initialized so that no font ID at all is valid.
- \end{itemize}
-\item \verb+T1ERR_INVALID_PARAMETER+ (11): One or more of the parameters
- specified to a function call were assigned invalid values. For example, a
- size-value specified to a rastering function must always be $>0$. Just the
- same way, \verb+T1_ConcatGlyphs()+ cannot concatenate two glyphs if one of
- them is the \verb+NULL+ pointer.
-\item \verb+T1ERR_OP_NOT_PERMITTED+ (12): An operation that was not allowed
- {\em at that time} has been requested. This error could result, for example,
- if an application tries to set a new bitmap padding value after \tonelib\
- has been initialized.
-\item \verb+T1ERR_ALLOC_MEM+ (13): This error indicates that \tonelib\ ran out
- of memory and a memory allocation failed. This error should not appear.
-\item \verb+T1ERR_FILE_OPEN_ERR+ (14): A file that was needed could not be
- opened by \tonelib. The file might have been necessary for reading data or
- writing data. For example, \verb+T1_WriteAFMFallbackFile()+ returns this
- value if the AFM file could not be opened for writing and
- \verb+T1_LoadEncoding()+ returns it if the encoding file specified as
- argument could not be opened. Notice that there is no indication of the
- reason why the file opening failed. The C library
- variable \verb+errno+ should be examined to analyze this further.
-
- It should be mentioned that \verb+T1ERR_FILE_OPEN_ERR+ is only set if a file
- operation failed which was really in force. This means that at the time a
- font is loaded a missing AFM file does not cause \verb+T1_errno+ caused to
- be set to \verb+T1ERR_FILE_OPEN_ERR+. This is because \tonelib\ can
- automatically recover from this by generating AFM information on the fly (at
- the cost of computation time).
-\item \verb+T1ERR_UNSPECIFIED+ (15): This value indicates nothing apart from
- that an error occurred and this error was not one the other errors. It can
- be considered a fallback.
-\item \verb+T1ERR_NO_AFM_DATA+ (16): A function has been called which needs
- AFM information and AFM information is not available, either because all
- attempts to generate AFM data failed or because the flag \verb+T1_NO_AFM+
- has been specified as part of the flag for \verb+T1_InitLib()+.
-\item \verb+T1ERR_X11+ (17): An error in an X11 library function occured. This
- could be caused by calling a function of the X11 interface without prior
- initialization of the X11 interface via \verb+T1_SetX11Params()+.
-\item \verb+T1ERR_COMPOSITE_CHAR+ (18): A request to compose a composite
- character could not be fulfilled without problems because at least one part
- of the composite character was not found in the \verb+CharStrings+
- dictionary. This is bad because it indicates that font file and AFM file do
- match. Further errors or unsatisfactory rastering results have to be
- expected.
-\item \verb+T1ERR_SCAN_ENCODING+ (19): Scanning an encoding file failed. Since
- \tonelib\ uses a fallback approach---DVIPS-encoding is tried first and
- afterwards \tonelib-encoding---it is not clear at which place exactly a
- failure occured. However, further hints about what \tonelib\ thought about
- the file in question may be found in the log file.
-\end{itemize}
-In analogy to the Standard C Library function \verb+strerror()+, \tonelib\
-provides the function
-\precorr
-\begin{verbatim}
- const char *T1_StrError( int t1err)
-\end{verbatim}\index{\verb+T1_StrError()+}\postcorr
-It returns a pointer to a string describing the error corresponding to
-\verb+t1err+. Usually, the argument should be directly specified as
-\verb+T1_errno+. The memory where the returned string is stored is static in
-\tonelib\ so that it may not be \verb+free()+'d.
-
-
-\subsection{Other Useful Functions}
-\label{otherfunctions}%
-This subsection describes a few functions that had not been described up to
-now but which however could be useful.
-
-\precorr
-\begin{verbatim}
- int T1_CheckEndian( void)
-\end{verbatim}\index{\verb+T1_CheckEndian()+}\postcorr
-This function may be used to check the endianess of the hardware \tonelib\ is
-running on. The return value is \verb+0+ for Little Endian and \verb+1+ for
-Big Endian machines.
-
-\precorr
-\begin{verbatim}
- void T1_DumpGlyph( GLYPH *glyph)
-\end{verbatim}\index{\verb+T1_DumpGlyph()+}\postcorr
-This function might be useful for debugging and testing \tonelib. It dumps an
-ASCII representation of the glyph pointed to by \verb+glyph+ to the standard
-output. A background pixel is represented by \verb+.+ while a foreground pixel
-is represented by \verb+X+. After the number of bits that correspond to the
-current padding value, an empty column is inserted. See the output of the
-programming example in \ref{programmingexample}. In this case the padding
-values has been 16.
-
-Note that the size of the glyph should be small enough that its padded width
-does not exceed the terminals line width. Otherwise the result might become
-illegible.
-
-\precorr
-\begin{verbatim}
- void T1_DumpPath( T1_OUTLINE *path)
-\end{verbatim}\index{\verb+T1_DumpPath()+}\postcorr
-This function dumps a description of an outline to the standard output. It is
-exclusively intended for debugging purposes.
-
-
-\precorr
-\begin{verbatim}
- void T1_SetRasterFlags( int flags)
-\end{verbatim}\index{\verb+T1_SetRasterFlags()+}\postcorr
-This function allows to enable or disable certain features of the
-rasterizer. Let me emphasize that this is exclusively intended for debugging
-and error tracking. The default value of \verb+flags+ is 0 which means that no
-debugging output is shown and hinting is performed as suggested in the {\em Adobe
-Type Font Format}. However there may arise situations where fiddling with the
-\verb+flags+ might be helpful in rasterizer and font debugging.
-
-\verb+flags+ usually is an OR'ed combination of the following definitions:
-\begin{itemize}
-\item \verb+T1_IGNORE_FORCEBOLD+
-\item \verb+T1_IGNORE_FAMILYALIGNMENT+
-\item \verb+T1_IGNORE_HINTING+
-\item \verb+T1_DEBUG_LINE+
-\item \verb+T1_DEBUG_REGION+
-\item \verb+T1_DEBUG_PATH+
-\item \verb+T1_DEBUG_FONT+
-\item \verb+T1_DEBUG_HINT+
-\end{itemize}
-The \verb+T1_IGNORE_...+ types allow to selectively disable hinting. They
-might be useful if parts of a font are not properly rendered. For example,
-substituting a font's alignment zones by the family's alignment zones might
-result in visual artifacts if the values for \verb+FamilyBlues+ are not
-correct. Disabling family alignment might reveal the problem in such cases.
-
-The \verb+T1_DEBUG_...+ types produce debugging output from the intermediate
-rasterizing steps. Notice that to understand this output a thorough
-understanding of what happens in the rasterizer is in force. Moreover, be
-prepared that thousands of lines might be written to the terminal, depending
-on the particular option.
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "t1lib_doc"
-%%% End: