ut1lib.tex

source code: Covert TXT to PDF

%----------------------------------------------------------------------------
% ----- File:        ut1lib.tex 
% ----- Author:      Rainer Menzner ([e-mail])
% ----- Date:        2001-10-18
% ----- Description: This file is part of the t1lib-documentation.
% ----- Copyright:   t1lib is copyrighted (c) Rainer Menzner, 1996-2001. 
%                    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