ut1lib.tex

source code: Covert TXT to PDF

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.

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