ut1lib.tex

source code: Covert TXT to PDF

  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_FreeG