xglyph.tex

source code: Covert TXT to PDF

%----------------------------------------------------------------------------
% ----- File:        xglyph.tex 
% ----- Author:      Rainer Menzner ([e-mail])
% ----- Date:        2001-04-01
% ----- 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 toplevel
%                    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
%                    independent from X11.
%                    Thanks to all people who make free software living!
%----------------------------------------------------------------------------

\newpage
\section{The Program {\ttfamily xglyph}}
\label{xglyph}%
\verb+xglyph+ is a tool which makes most of the functionality of 
\tonelib\ visible to the user without the need of having to write an
own program and without the need of having to understand most of the
library 
before. This program---as the name indicates---needs X11. It is thus only
build if X11 is installed on the target system and if  X11 support has not
explicitly been disabled. All
necessary resources are set internally to default values so that the
program can be run out of the box without any installation. 

In case the user did not already create a custom configuration file and an
associated font database file, the program should be started from the
subdirectory \verb+xglyph+ of the distribution. When starting, \verb+xglyph+
checks for the environment entry \verb+T1LIB_CONFIG+ and if it does not exist
it adds the association \verb+T1LIB_CONFIG=./t1lib.config+ to the
environment. In other words it expects a valid configuration file in the
current directory.

There are several widgets which may be categorized into 5 types.

\subsection{Common Parameter Dialogs and Toggle Buttons}
These buttons modify the internal state of the program by setting some global
variables. These variables affect the execution of all rastering functions in
contrast to the buttons described in the next subsection which only take
influence on the X11 rastering functions. When changing
one of the following parameters nothing seems to happen at first. All
actions are deferred to the time when an action button is
clicked. Here is a list of the dialogs and toggles:
\begin{itemize}
\item \fbox{{\bfseries FontID}}\\
  This dialog allows to specify the font ID that will be used when
  the next action takes place. The allowed IDs range from 0 to $n-1$,
  where $n$ is the number of fonts declared in the font database
  file. If using the default configuration file together with the
  default font database file, 8 fonts are declared. If an invalid ID
  is specified, the next action generates an error message.
\item \fbox{{\bfseries Font-Size}}\\
  Here, the size of the font is specified. The value is interpreted in
  bigpoints, the default PostScript unit. If the size specified is
  invalid, an appropriate error message is generated at the time of
  the next action.
\item \fbox{{\bfseries Slant-Factor}}\\
  A slant factor $s$ may be specified. It is interpreted the following
  way. A point described by the coordinate-pair $(x,y)$ is transformed
  to the point with the coordinates $(x+sy,y)$. For instance,
  specifying a slant factor $s=1$ will generate a font slanted by
  $45^\circ$. Since version 0.3-beta slanted are nearly fully supported.
  For a discussion of the remaining problems see
  \ref{transformations} on page
  \pageref{transformations}. 
\item \fbox{{\bfseries Extension-Factor}}\\
  Horizontal extension of a font may be realized using this
  dialog. The default value is 1 which means the characters are
  presented at their natural width. Specification of an invalid value
  will generate an error message at the time of the next action.
\item \fbox{{\bfseries Transformation-Matrix}}\\
  This dialog gives complete Control over the transformation matrix that will
  be used in consequent rasterizations. The values have to be specified
  separated by commas. A specified rotation is still applied after this
  matrix.  
\item \fbox{{\bfseries Resolution}}\\
  The resolution of the output device (screen) may be specified in
  this dialog. Using the default value of 72 dpi means one bp in size
  corresponds to exactly one device pixel. 
\item \fbox{{\bfseries Encoding-File}}\\
  The name of an encoding file may be specified. Included in the
  distribution is only one file, \verb+IsoLatin1.enc+. It contains the
  standard X11 encoding in a format acceptable by \tonelib. If no name
  is given here, or the file with the name given here cannot not be
  parsed as an encoding file, the encoding is switched back to the fonts
  internal encoding. Again, this is done at the time of the next
  action. 
\item \fbox{{\bfseries Angle}}\\
  The angle at which the next character or string is rastered is
  specified here. There are no restrictions concerning the angle. Rotation is
  applied after setting the transformation matrix (see above).
\item \fbox{{\bfseries Space-Off}}\\
  The value specified here represents an offset added to the
  spacewidth when rastering the next string. For this, it is
  interpreted in PostScript charspace units and thus subject to
  scaling. 
\item \fbox{{\bfseries Character}}\\
  A number between 0 and 255 inclusive should be specified here. It is
  used as the index into the current encoding vector when rasterizing
  a character. This gives the user access to all currently encoded
  characters, regardless of the current X11 keyboard mapping. If an
  index is given whose encoding entry would produce no black pixels,
  an error message is generated at the next character-rastering
  time. The default value is 65, which corresponds 
  to the character ``A'' in most encoding vectors.
\item \fbox{{\bfseries Test-String}}\\
  In this dialog, a complete string may be specified. It will be
  rastered when the next string-rastering button is pressed. It can be
  of arbitrary length (well, almost). If this field is left empty, the
  standard string ``Test'' will be used for rastering.
\item \fbox{{\bfseries Kerning}}\\
  This is a toggle button. Its state determines whether pairwise
  kerning information from the AFM file will be used to correct the
  horizontal spacing during string rastering or not. A typical example
  is the word ``Test''; enabling kerning should---at least in
  fonts of good quality---move the ``T'' and the ``e'' significantly
  closer together.
\item \fbox{{\bfseries Ligature}}\\
  This is a toggle button. Its state specifies whether the
  string is checked for ligatures prior to rastering it. 
  Suitable character sequences are replaced with the corresponding
  ligature. For a good example, you should switch to
  font ID 4 and type in the string \verb+--difficult---+. If ligature
  detection is switched on, the two hyphens should be converted to an
  en-dash ``--'', the three hyphens should be converted to an em-dash
  ``---'' and the character series ``\verb+ffi+'' should be replaced
  with the ligature ``ffi'', rather than to be displayed as ``f{}f{}i''.
\item \fbox{$|\longrightarrow$} / \fbox{$\longleftarrow|$}  This button allows
  to change the writing direction that \tonelib\ will use in subsequent calls
  to the string rastering functions, the default being {\em Left To Right} as
  used in most European languages. This item is simply meant to demonstrate the
  capabilities of \tonelib. The package does not come with fonts that are
  intended to be used for {\em Right To Left} typesetting.
\item \fbox{{\bfseries Underline}}\\
  This toggle button determines whether strings are underlined or not. 
\item \fbox{{\bfseries Overline}}\\
  Same as above for overlining.
\item \fbox{{\bfseries Overstrike}}\\
  Same as above for overstriking.
\item \fbox{{\bfseries AA-Low}}/\fbox{{\bfseries AA-High}}\\
  This button allows to select the subsampling factor for antialiasing in
  subsequent rastering operations. {\em AA-Low} means subsampling by factor 2
  which gives 5 gray values including black and white, whereas {\em AA-High}
  means subsampling by 4 which yields 17 gray values including black and
  white.  
\end{itemize}
Notice that, aside from the latter, the toggle buttons only affect the string
rastering functions.  

\subsection{Buttons that Influence the X11 Rastering Functions}
The X11 rastering functions introduced in version 0.3-beta provide a
considerably higher level of abstraction than the standard rastering
functions. To show the effect in \verb+xglyph+, a few additional buttons are
provided.  
\begin{itemize}
\item \fbox{{\bfseries Transparent}}/\fbox{{\bfseries Opaque}}\\ 
  This button allows to switch between transparent and opaque mode in the X11
  rastering functions. In transparent mode, only non-background pixels are
  drawn and all other pixels are left untouched. In opaque mode the entire
  area that the bitmap will require is first filled with the background color
  and then the bitmap is placed on this area.
\item \fbox{{\bfseries Foreground}}\\
  This is a label field with six color fields to the right and one color field
  to the left. Clicking on one of the color fields located on the right side
  will set the foreground color to the respective value (white, black, gray,
  red, green or blue). The color field on the left side always shows the
  current color selection. 
\item \fbox{{\bfseries Background}}\\
  This also is a label field with six color fields to the right and one color
  field to the left. It works in analogy to the above and sets the current
  background color. Note that in order make the background color active, the
  drawing mode must be set to ``opaque''.
\end{itemize}

\subsection{Buttons that Generate Actions}
There are 10 buttons generating actions visible to the user. 
\begin{itemize}
\item \fbox{{\bfseries Char}}\\
  This button generates a bitmap of the character specified in the
  \fbox{{\bfseries Character}}-dialog box. All parameters changed
  earlier become effective at this time. The resulting bitmap is then
  shown in the output window of \verb+xglyph+. Some information about
  the generated bitmap and elapsed 
  time etc.\ is given in the message window. If an error occurred,
  the old contents of the output window are kept and a message is given
  to the user. 
\item \fbox{{\bfseries String}}\\
  This button generates a bitmap of the string specified in the
  \fbox{{\bfseries Test-String}}-dialog box. In addition to rastering
  characters, kerning and ligature settings may now take influence on
  the result of the operation (see \ref{fonts}). If no error occurs,
  the bitmap is shown in the output window and additional information is
  shown in the message area. Otherwise, an appropriate error message is
  given.
\item \fbox{{\bfseries AAChar}}
\item \fbox{{\bfseries AAString}}\\
  Both of these buttons do exactly the same as their non-antialiased
  counterparts. The only difference consists in the generation of an
  antialiased bitmap. The result is not a bitmap in fact.
  There are at least 8 bits per pixel and at most 32 bits per
  pixel in the resulting glyph. This depends on the depth of the
  X11-visual you use when starting xglyph. The result may consume
  quite a bit of memory
  if a {\ttfamily TrueColor} or {\tt DirectColor} visual is
  active.
\item \fbox{{\bfseries CharX}}
\item \fbox{{\bfseries StringX}}
\item \fbox{{\bfseries AACharX}}
\item \fbox{{\bfseries AAStringX}}\\
  These functions basically do the same as the counterparts lacking the ``X''
  in the name. But internally the X11 rastering functions are called to
  produce the output bitmap/pixmap. As a consequence the current foreground
  color, background color and drawing mode are taken into account. For a more
  complete discussion of the X11 rastering functions see \ref{x11interface} on
  page \pageref{x11interface}. 
\item \fbox{{\bfseries Font Table}}\\
  A character table of size $16 \times 16$ is shown in the output
  window. Each cell contains an antialiased representation of the character
  indexed by the field number. The function \verb+T1_AASetCharX()+ is
  used for drawing these characters. Current foreground and background colors
  are respected as well as are most other parameters accepted by the character
  rastering functions. Only the angle specification
  is ignored since I assume that it is not very useful to have an overview
  over a font at any angle different from 0. Notice that the default size
  (100) is probably too large to make the output window fit on the screen. No
  care is taken about this. The recommended size for viewing a font's