ut1lib.tex

source code: Covert TXT to PDF

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 two 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