File: VFlib-36.html

package info (click to toggle)
vflib3 3.6.14.dfsg-3%2Bnmu3
links: PTS
area: main
in suites: stretch
size: 11,536 kB
ctags: 3,710
sloc: ansic: 35,811; sh: 10,357; asm: 3,290; makefile: 962; lisp: 123; perl: 109; awk: 43
file content (8655 lines) | stat: -rw-r--r-- 257,808 bytes
parent folder | download | duplicates (7)
<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from VFlib-36.texi on 27 February 2006 -->

<TITLE>VFlib 3.6.14</TITLE>
</HEAD>
<BODY>
<H1>A Font Library VFlib </H1>
<H2>VFlib version 3.6.14 User's manual</H2>
<H2>Final Revision: 26 Feb 2006</H2>
<ADDRESS>Hirotsugu Kakugawa</ADDRESS>
<P>
<P><HR><P>


<H1><A NAME="SEC1" HREF="VFlib-36_toc.html#TOC1">Copyright</A></H1>

<P>
<A NAME="IDX1"></A>
<A NAME="IDX2"></A>
<A NAME="IDX3"></A>


<P>
Copyright (C) 1996-2006 Hirotsugu Kakugawa. 
All rights reserved.


<P>
This file is part of the VFlib Library.  This library is free
software; you can redistribute it and/or modify it under the terms of
the GNU Library General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your
option) any later version.  This library is distributed in the hope
that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.  See the GNU Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.




<H1><A NAME="SEC2" HREF="VFlib-36_toc.html#TOC2">Copying</A></H1>

<P>
GNU LIBRARY GENERAL PUBLIC LICENSE
Version 2, June 1991



<PRE>
Copyright (C) 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[This is the first released version of the library GPL.  It is
 numbered 2 because it goes with version 2 of the ordinary GPL.]
</PRE>



<H2><A NAME="SEC3" HREF="VFlib-36_toc.html#TOC3">Preamble</A></H2>

<P>
  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.


<P>
  This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it.  You can use it for
your libraries, too.


<P>
  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.


<P>
  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if
you distribute copies of the library, or if you modify it.


<P>
  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link a program with the library, you must provide
complete object files to the recipients so that they can relink them
with the library, after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.


<P>
  Our method of protecting your rights has two steps: (1) copyright
the library, and (2) offer you this license which gives you legal
permission to copy, distribute and/or modify the library.


<P>
  Also, for each distributor's protection, we want to make certain
that everyone understands that there is no warranty for this free
library.  If the library is modified by someone else and passed on, we
want its recipients to know that what they have is not the original
version, so that any problems introduced by others will not reflect on
the original authors' reputations.


<P>
  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that companies distributing free
software will individually obtain patent licenses, thus in effect
transforming the program into proprietary software.  To prevent this,
we have made it clear that any patent must be licensed for everyone's
free use or not licensed at all.


<P>
  Most GNU software, including some libraries, is covered by the ordinary
GNU General Public License, which was designed for utility programs.  This
license, the GNU Library General Public License, applies to certain
designated libraries.  This license is quite different from the ordinary
one; be sure to read it in full, and don't assume that anything in it is
the same as in the ordinary license.


<P>
  The reason we have a separate public license for some libraries is that
they blur the distinction we usually make between modifying or adding to a
program and simply using it.  Linking a program with a library, without
changing the library, is in some sense simply using the library, and is
analogous to running a utility program or application program.  However, in
a textual and legal sense, the linked executable is a combined work, a
derivative of the original library, and the ordinary General Public License
treats it as such.


<P>
  Because of this blurred distinction, using the ordinary General
Public License for libraries did not effectively promote software
sharing, because most developers did not use the libraries.  We
concluded that weaker conditions might promote sharing better.


<P>
  However, unrestricted linking of non-free programs would deprive the
users of those programs of all benefit from the free status of the
libraries themselves.  This Library General Public License is intended to
permit developers of non-free programs to use free libraries, while
preserving your freedom as a user of such programs to change the free
libraries that are incorporated in them.  (We have not seen how to achieve
this as regards changes in header files, but we have achieved it as regards
changes in the actual functions of the Library.)  The hope is that this
will lead to faster development of free libraries.


<P>
  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, while the latter only
works together with the library.


<P>
  Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one.




<H2><A NAME="SEC4" HREF="VFlib-36_toc.html#TOC4">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H2>
<P>
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION



<OL>
<LI>

This License Agreement applies to any software library which
contains a notice placed by the copyright holder or other authorized
party saying it may be distributed under the terms of this Library
General Public License (also called "this License").  Each licensee is
addressed as "you".

  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.

  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)

  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.

  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.
  
<LI>

You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.

  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.

<LI>

You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:


<OL>
<LI>

    The modified work must itself be a software library.

<LI>

    You must cause the files modified to carry prominent notices
    stating that you changed the files and the date of any change.

<LI>

     You must cause the whole of the work to be licensed at no
    charge to all third parties under the terms of this License.

<LI>

    If a facility in the modified Library refers to a function or a
    table of data to be supplied by an application program that uses
    the facility, other than as an argument passed when the facility
    is invoked, then you must make a good faith effort to ensure that,
    in the event an application does not supply such function or
    table, the facility still operates, and performs whatever part of
    its purpose remains meaningful.

    (For example, a function in a library to compute square roots has
    a purpose that is entirely well-defined independent of the
    application.  Therefore, Subsection 2d requires that any
    application-supplied function or table used by this function must
    be optional: if the application does not supply it, the square
    root function must still compute square roots.)
</OL>

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

<LI>

You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.

  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.

  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.

<LI>

You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.

  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.

<LI>

A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.

  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.

  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.

  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)

  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.

<LI>

As an exception to the Sections above, you may also compile or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:


<OL>
<LI>

    Accompany the work with the complete corresponding
    machine-readable source code for the Library including whatever
    changes were used in the work (which must be distributed under
    Sections 1 and 2 above); and, if the work is an executable linked
    with the Library, with the complete machine-readable "work that
    uses the Library", as object code and/or source code, so that the
    user can modify the Library and then relink to produce a modified
    executable containing the modified Library.  (It is understood
    that the user who changes the contents of definitions files in the
    Library will not necessarily be able to recompile the application
    to use the modified definitions.)

<LI>

    Accompany the work with a written offer, valid for at
    least three years, to give the same user the materials
    specified in Subsection 6a, above, for a charge no more
    than the cost of performing this distribution.

<LI>

    If distribution of the work is made by offering access to copy
    from a designated place, offer equivalent access to copy the above
    specified materials from the same place.

<LI>

    Verify that the user has already received a copy of these
    materials or that you have already sent this user a copy.
</OL>

  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.

  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.

<LI>

You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:


<OL>
<LI>

    Accompany the combined library with a copy of the same work
    based on the Library, uncombined with any other library
    facilities.  This must be distributed under the terms of the
    Sections above.

<LI>

    Give prominent notice with the combined library of the fact
    that part of it is a work based on the Library, and explaining
    where to find the accompanying uncombined form of the same work.
</OL>

<LI>

 You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

<LI>

You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.

<LI>

 Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

<LI>

If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

<LI>

If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.

<LI>

The Free Software Foundation may publish revised and/or new
versions of the Library General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.

<LI>

If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.



<P><STRONG>NO WARRANTY</STRONG>

<LI>

BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

<LI>

 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
</OL>


<H2>END OF TERMS AND CONDITIONS</H2>



<H2><A NAME="SEC5" HREF="VFlib-36_toc.html#TOC5">Appendix: How to Apply These Terms to Your New Libraries</A></H2>

<P>
  If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).


<P>
  To apply these terms, attach the following notices to the library.  It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.



<PRE>
<VAR>one line to give the library's name and a brief idea of what it does.</VAR>
Copyright (C) <VAR>year</VAR>  <VAR>name of author</VAR>

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
</PRE>

<P>
Also add information on how to contact you by electronic and paper mail.


<P>
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary.  Here is a sample; alter the names:



<PRE>
  Yoyodyne, Inc., hereby disclaims all copyright interest in the
  library `Frob' (a library for tweaking knobs) written by James Random Hacker.

  <VAR>signature of Ty Coon</VAR>, 1 April 1990
  Ty Coon, President of Vice
</PRE>

<P>
That's all there is to it!




<H1><A NAME="SEC6" HREF="VFlib-36_toc.html#TOC6">Introduction</A></H1>

<P>
Today many font files are available in various font file formats. 
When we need a software to display or print characters which does not
depend on a windowing system and/or an operating system, we must
write interface routines for accessing font files in each application
software again and again.  To do this, programmers must have
knowledge on font file formats; it will be a hard task for
programmers if the number of font formats that an application
software supports becomes large.


<P>
  VFlib is a font library written in C providing several functions to
obtain bitmaps of characters.  VFlib hides the font format of font
files and provides a unified API for all supported font formats. 
Thus, programmers for application software need not have knowledge on
font file formats.  Instead, any software using VFlib can support
various font file formats immediately.


<P>
  This document describes the fundamental concepts of VFlib and gives
a brief introduction in writing programs using VFlib.


<P>
As described above, VFlib supports many font file formats and
absorbs differences between font file formats.
Currently, VFlib supports the following font file formats: 
PCF, BDF, HBF, TrueType, Type1, GF, PK, Virtual Fonts, TFM, 
SyotaiKurabu (a vector font format for Japanese Kanji characters), 
JG (another vector font format for Japanese Kanji characters), and
eKanji (a bitmap font format for Kanji characters).


<P>
The VFlib system consists of two parts:


<DL COMPACT>

<DT>A library (<TT>`libVFlib.a'</TT> and/or <TT>`libVFlib.so'</TT>)
<DD>
<A NAME="IDX4"></A>
<A NAME="IDX5"></A>

It provides several C functions.  Any application software
using VFlib must link this library.

VFlib (optionally) uses kpathsea, FreeType, and T1Lib libraries.
Application software linked with VFlib must be linked with
these external libraries, if you want to use them.
Application software must be linked against
kpathsea, FreeType and T1Lib in addition to VFlib 
if you configured VFlib to use them. 

<DT>A font database file (<TT>`vflibcap'</TT>)
<DD>
<A NAME="IDX6"></A>

When we open a font, information about the font file (font
format, location, possibly necessary glyph modifications
etc.) is necessary.  This file describes such information;
it is read when the initialization function of VFlib is called.
</DL>

<P>
Basic concept of VFlib


<DL COMPACT>

<DT><B>Font Classes and Font Drivers</B>
<DD>
<A NAME="IDX7"></A>
<A NAME="IDX8"></A>

VFlib can handle multiple font file formats.  Reading a font file
according to its font file format is done by an internal module in
VFlib corresponding to its font file format.  This internal module
is called a <EM>font driver</EM>.  Service units provided by a font driver
is called <EM>font class</EM>.  From an end-user's point of view,
various font formats are distinguished by various names of font
classes.  Font drivers themselves are internal of VFlib and invisible
for end-users.

 Some font drivers may not read font files on disk; they may
generate glyph and outlines by internal computation only.  In
addition, some font drivers may return glyph which are obtained as
glyph by another font class (hence the name `Virtual Font library').
<A NAME="IDX9"></A>

<DT><B>A View of VFlib Font From The End-User</B>
<DD>
Each (virtual) font by VFlib has its inherent information of point
size, pixel size, and resolution of the target device.  In addition
to these font metrics are defined for each glyph.

 Some font file formats does not have such concepts; in such case,
(1) lacking information is given in a font database file <TT>`vflibcap'</TT>
or (2) the specific font driver gives such information as default
values.  For instance, a TrueType font file is a vector font file
and does not has information on point size and resolution of the
target device (such information is unnecessary since vector fonts
can be scaled at any size).  SyotaiKurabu font format (a vector
font for Japanese Kanji) does not have font metric information at
all.  A font driver for this font format virtually generates font
metrics by information given in a vflibcap file.

<DT><B>Font Names and Font Searching Mechanism</B>
<DD>
In VFlib, a font is specified by a font name when a font is requested to open.
First, VFlib checks whether the font name is given in vflibcap or not.  
If the font name is found, VFlib reads the description for the
font in vflibcap.  The description contains a font class name; 
VFlib then invokes a font driver corresponding to the font class name.
Finally the font driver opens the font file (if necessary).

If the font name is not given in a vflibcap file, a font searching
mechanism is invoked.  Since there are many font files for X Window
and TeX, this feature is introduced to avoid writing an entry for
each font file.  
Various font drivers will be called to see whether
the font can be opened.  
If a font driver succeeds in opening the font, font searching finishes 
and the VFlib font opening function returns successfully.  
Otherwise, font open fails.

Fonts described in a vflibcap file are called <EM>explicit fonts</EM> and
fonts that are searched for by the font search feature are called 
<EM>implicit fonts</EM>.
Support for explicit and implicit fonts depends on font driver.

<DT><B>Obtaining Bitmaps (Glyph)</B>
<DD>
Two interfaces are provided to obtain glyph (bitmaps) of a font.

<DL COMPACT>

<DT>High resolution device oriented glyph
<DD>
<A NAME="IDX10"></A>

This method is suitable for devices of high resolution such as
laser printers. The size of glyph is specified by the
physical size of glyph and device resolution.  When the size
of a glyph in the source font is different from the target
size, VFlib scales the source glyph internally.

<DT>Low resolution device oriented glyph
<DD>
<A NAME="IDX11"></A>

This method is suitable for low resolution devices such as CRT
displays.  Glyph sizes are specified by pixel size rather than
by device resolution.  When the size of a glyph in the source
font is different from the target size, VFlib scales the
source glyph internally.

</DL>
</DL>



<H1><A NAME="SEC7" HREF="VFlib-36_toc.html#TOC7">Installing VFlib</A></H1>
<P>
<A NAME="IDX12"></A>


<P>
VFlib uses GNU autoconf and GNU libtool to compile.
According to the following procedure, 
compile and install VFlib.


<P>
VFlib (optionally) uses FreeType 1.3.0 or later, 
T1Lib 5.1 or later, and kpathsea 3.2 libraries.
They must be installed before compiling VFlib if you want use them.
They are available from the following sites:



<UL>

<LI>FreeType

VFlib is tested with FreeType 1.3.
(FreeType 1.0 does not work with current VFlib3.)

<UL>
<LI><A HREF="http://www.freetype.org/">http://www.freetype.org/</A>

<LI><A HREF="ftp://ftp.freetype.org/pub/freetype/freetype-1.3.tar.gz">ftp://ftp.freetype.org/pub/freetype/freetype-1.3.tar.gz</A>

</UL>

<LI>T1Lib

VFlib is tested with T1Lib 5.1.

<UL>
<LI><A HREF="ftp://sunsite.unc.edu/pub/Linux/libs/graphics/">ftp://sunsite.unc.edu/pub/Linux/libs/graphics/</A>

<LI><A HREF="http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html">http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html</A>

<LI><A HREF="ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/">ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/</A>

</UL>

<LI>kpathsea

VFlib is tested with kpathsea 3.2 in web2c-7.2b.

<UL>
<LI><A HREF="ftp://ftp.ctan.org/tex-archive/system/web2c/">ftp://ftp.ctan.org/tex-archive/system/web2c/</A>

</UL>

</UL>

<P>
 

<OL>
<LI>

  VFlib is tested on the following platforms:

<UL>
<LI>FreeBSD 2.2.2 and 3.2 on IBM PC-clones

<LI>Solaris 2.5.1 on Sun SPARC Stations

</UL>

Porting to Unix-like system is easy since the source code
is not specific system dependent.
Porting to non-Unix-like system is not difficult; please try.

<LI>

 Go into the directory <TT>`VFlib3-3.6.14'</TT>.

<LI>

 Run the @command{configure} script.


<PRE>
% ./configure  [RET]
</PRE>

<A NAME="IDX13"></A>
<A NAME="IDX14"></A>
<A NAME="IDX15"></A>
<A NAME="IDX16"></A>
By default, VFlib does <EM>not</EM> support for TrueType and Type1 fonts 
and TeX font searching by kpathsea library
for searching TeX-related font files such as GF, PK, TFM, VF.
For such features, VFlib (optionally) uses FreeType library 
version 1.2 or later for rendering TrueType font files,
T1Lib library version 5.1 or later for rendering Type 1 font files,
and kpathsea library version 3.2.

VFlib can be built to use these libraries
by giving  options when you run @command{configure} script.
Probably, the following is the typical options to configure script to use
TrueType and Type 1 fonts and font search feature by kpathsea library.


<PRE>
% ./configure \
       --with-kpathsea \
       --with-kpathsea-includedir=/usr/local/include \
       --with-kpathsea-libdir=/usr/local/lib
       --with-freetype \
       --with-freetype-includedir=/usr/local/include/freetype \
       --with-freetype-libdir=/usr/local/lib"
       --with-t1lib \
       --with-t1lib-includedir=/usr/local/include \
       --with-t1lib-libdir=/usr/local/lib            [RET]
</PRE>

<EM>Note:</EM>
See the @command{configure-site} script; 
it invokes the @command{configure} script with typical settings shown above.

Options for configure script is as follows:

<DL COMPACT>

<DT><TT>--enable-shared</TT>
<DD>
   Enable to build a shared library version of VFlib.
   By default, shared library version is created, 
   if the target system supports shared library.

<DT><TT>--disable-shared</TT>
<DD>
   Disable to build a shared library version of VFlib.

<DT><TT>--disable-static</TT>
<DD>
   Disable to build a static library version of VFlib.
   By default, static library version is not created, 
   if the target system supports shared library.

<DT><TT>--enable-static</TT>
<DD>
   Enable to build a shared library version of VFlib.

<DT><TT>--disable-bdf</TT>
<DD>
   VFlib is built without the BDF font driver.

<DT><TT>--disable-pcf</TT>
<DD>
   VFlib is built without the PCF font driver.

<DT><TT>--disable-hbf</TT>
<DD>
   VFlib is built without the HBF font driver.

<DT><TT>--disable-gf</TT>
<DD>
   VFlib is built without the TeX GF font driver.

<DT><TT>--disable-pk</TT>
<DD>
   VFlib is built without the TeX PK font driver.

<DT><TT>--disable-tfm</TT>
<DD>
   VFlib is built without the TeX TFM font driver.

<DT><TT>--disable-jtex</TT>
<DD>
   VFlib is built without the Japanese TeX Kanji font driver.

<DT><TT>--disable-tex-fonts</TT>
<DD>
   VFlib is built without all TeX-related font drivers, i.e., 
   GF, PK, VF, TFM, and ASCII Japanese TeX Kanji.

<DT><TT>--disable-zeit</TT>
<DD>
   VFlib is built without the Zeit (Syotai Kurabu) font driver.

<DT><TT>--disable-jg</TT>
<DD>
   VFlib is built without the JG font driver.

<DT><TT>--disable-ekanji</TT>
<DD>
   VFlib is built without the eKanji font driver.

<DT><TT>--disable-comic</TT>
<DD>
   VFlib is built without the Japanese comic font driver.

<DT><TT>--disable-try</TT>
<DD>
   VFlib is built without the Try font driver.

<DT><TT>--disable-mojikmap</TT>
<DD>
   VFlib is built without the Mojikyo font mapping driver.

<DT><TT>--with-freetype<VAR>[=LIB]</VAR></TT>
<DD>
   FreeType library file is <VAR>LIB</VAR>. 
   Default value is <CODE>ttf</CODE>.
  (Application programs must be linked against 
   <TT>`lib<VAR>LIB</VAR>.a'</TT> or <TT>`lib<VAR>LIB</VAR>.so'</TT>.)

<DT><TT>--with-freetype-includedir=<VAR>DIR</VAR></TT>
<DD>
   FreeType include files are in <VAR>DIR</VAR>.

<DT><TT>--with-freetype-libdir=<VAR>DIR</VAR></TT>
<DD>
   FreeType library files are in <VAR>DIR</VAR>.

<DT><TT>--with-t1lib<VAR>[=LIB]</VAR></TT>
<DD>
   T1Lib library file is <VAR>LIB</VAR>. 
   Default value is <CODE>t1</CODE>.
  (Application programs must be linked against 
   <TT>`lib<VAR>LIB</VAR>.a'</TT> or <TT>`lib<VAR>LIB</VAR>.so'</TT>.)

<DT><TT>--with-t1lib-includedir=<VAR>DIR</VAR></TT>
<DD>
   T1Lib include files are in <VAR>DIR</VAR>.

<DT><TT>--with-t1lib-libdir=<VAR>DIR</VAR></TT>
<DD>
   T1lib library files are in <VAR>DIR</VAR>.

<DT><TT>--with-kpathsea<VAR>=LIB</VAR></TT>
<DD>
   Kpathsea library file is <VAR>LIB</VAR>. 
   Default value is <CODE>kpathsea</CODE>.
  (Application programs must be linked against 
   <TT>`lib<VAR>LIB</VAR>.a'</TT> or <TT>`lib<VAR>LIB</VAR>.so'</TT>.)

<DT><TT>--with-kpathsea-includedir=<VAR>DIR</VAR></TT>
<DD>
   Kpathsea include files are in <VAR>DIR</VAR>.

<DT><TT>--with-kpathsea-libdir=<VAR>DIR</VAR></TT>
<DD>
   Kpathsea library files are in <VAR>DIR</VAR>.

</DL>

<LI>

 Run @command{make} to compile VFlib.


<PRE>
% make  [RET]
</PRE>

<LI>

Become a super user (root) and 
run @command{make} with @option{install} option to install.
(Run @command{make} with @option{uninstall} option to uninstall.)


<PRE>
# make  install [RET]
</PRE>

<LI>

If installation is successful, the following has been created:

<DL COMPACT>

<DT><TT>`libVFlib.a'</TT> and/or <TT>`libVFlib.so'</TT>
<DD>
<A NAME="IDX17"></A>
<A NAME="IDX18"></A>
These are the library files and linked with application programs.

<DT>@command{vflserver, @command{vflmkcaptex}, @command{vflx11}, @command{vfltest}, etc.}
<DD>
 -- A VFlib server and test programs on X11
<A NAME="IDX19"></A>

By @command{vflserver}, the functionality of VFlib is available 
via network if @command{vflserver} is registered in <TT>`/etc/inetd.conf'</TT>. 
It can be used
interactively by invocation from shell.  Interactive use of
VFlib is useful for testing or debugging purposes.

@command{vflx11} is a test program that displays characters on X Window System.
You can use it to test if a font is correctly 
configured in vflibcap file.

@command{vflmkcaptex} is an automatic vflibcap generator
for TeX DVI drivers, especially software in the TeX-Guy package.
It is a Unix Shell script, and it invokes many subprograms
(written in C) to generate font definitions for each font format.

@command{vfltest} is a test program that displays characters 
on terminal by ascii-art form.
</DL>

</OL>

<P>
Installation directories are as follows:


<DL COMPACT>

<DT><TT>`/usr/local/share/VFlib/3.6.14/'</TT> (= <TT>`$prefix/share/VFlib/3.6.14/'</TT>)
<DD>
Runtime files such as vflibcap are installed here.

This runtime root directory can be changed on runtime by
an environment variable <CODE>VFLIB_RUNTIME_DIRECTORY</CODE>.
If this environment variable is not set, the default
directory (<TT>`/usr/local/share/VFlib/3.6.14/'</TT>) is used.

Under this directory, there are following subdirectories:

<DL COMPACT>

<DT><TT>`ccv'</TT>
<DD>
In this directory, code conversion files are installed.
This directory can be changed on runtime by setting 
an environment variable <CODE>VFLIB_CCV_DIRECTORY</CODE>.
If this variable is set, default runtime directory and 
the value by <CODE>VFLIB_RUNTIME_DIRECTORY</CODE> variable are ignored.

<DT><TT>`t1lib'</TT>
<DD>
Encoding vector files for T1Lib (for Type 1 fonts) 
are stored in this directory.
Note that the file format for encoding vector files used by T1Lib is 
different from those used by standard PostScript.
To convert standard PostScript encoding vector files
into T1Lib format, use <TT>`mkt1enc.sh'</TT> program in this directory.
By default, this directory contains files 
converted from encoding vector files in the @command{dvips} distribution. 

<DT><TT>`ascii-jtex'</TT>
<DD>
In this directory, runtime files for Japanese TeX 
by ASCII Coop. are installed.
This directory can be changed on runtime by setting 
an environment variable <CODE>VFLIB_ASCII_JTEX_DIRECTORY</CODE>.
If this variable is set, default runtime directory and 
the value by <CODE>VFLIB_RUNTIME_DIRECTORY</CODE> variable are ignored.

<DT><TT>`doc'</TT>
<DD>
This directory contains several papers on VFlib, written 
by Hirotsugu Kakugawa.
</DL>

<DT><TT>`/usr/local/share/VFlib/site/'</TT>
<DD>
Runtime files (vflibcap, ccv files, etc.) that are created by each site
should be placed here.
For each versiion of VFlib, it has own runtime directory
(<TT>`/usr/local/share/VFlib/<VAR>x.y.z</VAR>/'</TT>) for default settings; 
and therefore, the directory where runtime files such as vflibcap in
differs by versions of VFlib.
In oder to use your own runtime files regardless VFlib versions,
runtime files modified for your system environment should be installed 
in <TT>`/usr/local/share/VFlib/site/'</TT>, which is called 
"site directory".

Before searching in <TT>`/usr/local/share/VFlib/<VAR>x.y.z</VAR>/'</TT>,
VFlib searches a runtime file in site directory.
Note that there is no directory hierarchy in 
site directory; all  runtime files are in the same directory.
The site directory can be changed by an environment variable
<CODE>VFLIB_RUNTIME_SITE_DIRECTORY</CODE>.

<DT><TT>`/usr/local/bin/'</TT>
<DD>
Binary programs such as @command{vflserver}, @command{vflx11}, etc 
are installed here. 

<DT><TT>`/usr/local/include/'</TT>
<DD>
Include file for C programs 
<TT>`VFlib-3_6.h'</TT> 
is installed here.

<DT><TT>`/usr/local/lib/'</TT>
<DD>
VFlib library files such as <TT>`libVFlib.a'</TT>, <TT>`libVFlib.so'</TT> 
are installed here.

</DL>

<P>
Install directories can be changed when you run <CODE>configure</CODE> 
script by the @option{--prefix=} option, for example.
Invoke @command{configure} with @option{--help} option for details.




<H1><A NAME="SEC8" HREF="VFlib-36_toc.html#TOC8">Programming with VFlib</A></H1>



<H2><A NAME="SEC9" HREF="VFlib-36_toc.html#TOC9">Data types</A></H2>



<H3><A NAME="SEC10" HREF="VFlib-36_toc.html#TOC10">bitmap type</A></H3>

<P>
A bitmap object is a structure of the following:



<PRE>
struct vf_s_bitmap {
  int              bbx_width, bbx_height; /* in pixels */
  int              off_x, off_y;          /* in pixels */
  int              mv_x,  mv_y;           /* in pixels */
  unsigned char*   bitmap;
  int              raster;
};
typedef struct vf_s_bitmap*  VF_BITMAP;
</PRE>

<P>
<A NAME="IDX20"></A>
<A NAME="IDX21"></A>


<P>
<CODE>bbx_width</CODE> and <CODE>bbx_height</CODE> are the bitmap width and height. 
A pair of <CODE>off_x</CODE> and <CODE>off_y</CODE>) forms a vector to the 
left-upper corner of the bitmap from the reference point.  
A pair of <CODE>mv_x</CODE> and <CODE>mv_y</CODE> is a vector
to the next reference point from the current reference point. 
(Positive values indicate a move into the right and upper
direction respectively.)


<P>
The unit of <CODE>bbx_width</CODE>, <CODE>bbx_height</CODE>, 
<CODE>off_x</CODE>, <CODE>off_y</CODE>, <CODE>mv_x</CODE>, and <CODE>mv_y</CODE> is pixels.
<CODE>bitmap</CODE> is a pointer to the bitmap data;  one pixel
corresponds to one bit.  


<P>
The left upper corner is the beginning
of the bitmap data, and a raster line is defined as a horizontal
line from the left to the right corner of the glyph bitmap. 
<CODE>bitmap</CODE> is a sequence of raster lines starting from the top to
the bottom.  The distance (in bytes) of two consecutive raster
lines in memory is given by <CODE>raster</CODE>.  Although the raster line
length of a bitmap is (<CODE>bbx_width</CODE>+7)/8, it is not guaranteed that
this value is the same as <CODE>raster</CODE>.
The type of <CODE>bitmap</CODE> is a pointer to <CODE>unsigned char</CODE> data object,
and each <CODE>unsigned char</CODE> data object contains eight pixels.  
Let <CODE>P[0]</CODE> be the start address of a raster line.  The <CODE>x</CODE>-th 
pixel counted from the leftmost pixel (which is pixel 0) is 1 if and only if 
<CODE>P[x/8] &#38; (0x80&#62;&#62;(x%8))</CODE> is non-zero.  


<P>
If <CODE>bbx_width</CODE>
is not a multiple of 8, there exist bits that do not correspond 
to any pixels but their values are always zero.
Even if <CODE>bbx_width</CODE> and/or <CODE>bbx_height</CODE> are zero, at least one
byte is allocated for the bitmap data.  Thus, <CODE>bitmap</CODE> is always
non-NULL.




<H3><A NAME="SEC11" HREF="VFlib-36_toc.html#TOC11">metric1 type</A></H3>

<P>
A metric1 object is a structure of the following:



<PRE>
struct vf_s_metric1 {
  double    bbx_width, bbx_height;  /* in points */
  double    off_x, off_y;           /* in points */
  double    mv_x, mv_y;             /* in points */
};
typedef struct vf_s_metric1*  VF_METRIC1;
</PRE>

<P>
<A NAME="IDX22"></A>
<A NAME="IDX23"></A>


<P>
The members of this structure are the same as the members of a
bitmap object but the members' unit is point.




<H3><A NAME="SEC12" HREF="VFlib-36_toc.html#TOC12">metric2 type</A></H3>

<P>
A metric2 object is a structure of the following: 



<PRE>
struct vf_s_metric2 {
  int    bbx_width, bbx_height;     /* in pixels */
  int    off_x, off_y;              /* in pixels */
  int    mv_x, mv_y;                /* in pixels */
};
typedef struct vf_s_metric2*  VF_METRIC2;
</PRE>

<P>
<A NAME="IDX24"></A>
<A NAME="IDX25"></A>


<P>
The members of this structure are the same as the members of a
bitmap object, and the members' unit is pixel also.




<H3><A NAME="SEC13" HREF="VFlib-36_toc.html#TOC13">outline type</A></H3>

<P>
VFlib defines its private outline data formats for presenting
vector data of characters.
This data format is used by VFlib API functions 
<CODE>VF_GetOutline()</CODE> and <CODE>VF_OutlineToBitmap()</CODE>.


<P>
Each font driver returns a outline data of a character of a font
if a font driver of that font supports <CODE>VF_GetOutline()</CODE> function. 
Even if data format of a font is different from VFlib-format,
a font driver converts outline data to VFlib-format data.
For instance, the PCF font driver (note that PCF is a bitmap font format)
supports <CODE>VF_GetOutline()</CODE> function and it constructs and return 
an outline data which is a set of square; each square corresponds
to a pixel of a bitmap.


<P>
Note that not all font drivers support <CODE>VF_GetOutline()</CODE> function,
but most of them do.
The developer of font drivers are strongly recommented to
implement this feature even if the font font format is bitmap-based.
(The function is supported by BDF, PCF, HBF, PK, GF, TFM, Zeit, JG, 
TrueType, and Type 1 font drivers.)


<P>
Outline data is defined as follows:



<PRE>
/* Outline data */
typedef long              VF_OUTLINE_ELEM;
typedef VF_OUTLINE_ELEM   *VF_OUTLINE;
</PRE>

<P>
<A NAME="IDX26"></A>
<A NAME="IDX27"></A>


<P>
According to CPU architecture, <CODE>VF_OUTLINE_ELEM</CODE>
is defined as <CODE>int</CODE> if size of <CODE>long</CODE> is 8.



<PRE>
typedef long              VF_OUTLINE_ELEM;
</PRE>

<P>
Outline data is an array of VF_OUTLINE_ELEM type 
(<CODE>long</CODE> or <CODE>int</CODE> type).
Outline data consists from two parts: header and outline.
The header part contains metric data and outline part contains
outline representation of a character.


<P>
Documentation for this feature is not finished.
See the source code (e.g., <CODE>VFlib-3_6.h</CODE>, <CODE>raster.c</CODE>, 
<CODE>bm2ol</CODE>, for example) for further information.




<H2><A NAME="SEC14" HREF="VFlib-36_toc.html#TOC14">Functions and variables</A></H2>



<H3><A NAME="SEC15" HREF="VFlib-36_toc.html#TOC15"><CODE>VF_Init()</CODE></A></H3>


<PRE>
int  VF_Init(char* <VAR>vflibcap</VAR>, char* <VAR>variable_list</VAR>)
</PRE>

<P>
<A NAME="IDX28"></A>


<DL COMPACT>

<DT>Functionality
<DD>
  Initialization of VFlib.

<DT>Arguments
<DD>
 <VAR>vflibcap</VAR> is a file name of vflibcap (this file is 
 a font database).  If the null pointer is given, the default
 path name given on compile time is used (a typical default
 value is <CODE>/usr/local/lib/VFlib/3.6.14/vflibcap</CODE>). 
 Searching of a vflibcap file is done in the following way.
 First, VFlib try to open a file as given to the first argument.
 (That is, VFlib searches it relative to current working directory.)
 If not found, then VFlib try to open the file under
 default runtime directory (e.g., <CODE>/usr/local/lib/VFlib/3.6.14/</CODE>).
 For example, <CODE>vflibcap-tex</CODE> is given, VFlib first look for 
 <CODE>vflibcap-tex</CODE> in current directory, and then, it looks for 
 the file under runtime directory.

 Default runtime directory can be changed by an environment variable
 <CODE>VFLIB_RUNTIME_DIRECTORY</CODE> on runtime.  
 If an environment variable <CODE>VFLIB_VFLIBCAP_PATH</CODE> is set,
 the first argument of this function is ignored and 
 its value is used.
 If an environment variable <CODE>VFLIB_VFLIBCAP_DIRECTORY</CODE> is set,
 a vflibcap file is searched under a directory sepecified by this 
 environment variable. 

 <VAR>variable_list</VAR> is a list of parameters passed to VFlib. 
 This is used to specify values of parameterized vflibcap
 files.  (See basic.txt for parameterized vflibcap file.) 
 The type of this argument is a string and its syntax is a sequence of 
 <VAR>Variable=Value</VAR>, separated by a comma <CODE>,</CODE>.
 For example, <CODE>DPI=400, LEVEL=1, FOO=bar</CODE>.

<DT>Return value
<DD>
 If initialization succeeds, a non-negative integer
 is returned.  If initialization fails, a negative integer is returned.
</DL>



<H3><A NAME="SEC16" HREF="VFlib-36_toc.html#TOC16"><CODE>vf_error</CODE></A></H3>
<P>
<A NAME="IDX29"></A>



<PRE>
int  vf_error 
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 This is a global variable.
 Holding the error code of VFlib.  If no error, it keeps 0.  
 If an error occurs, the corresponding error code is set.
</DL>



<H3><A NAME="SEC17" HREF="VFlib-36_toc.html#TOC17"><CODE>VF_ClearError()</CODE></A></H3>
<P>
<A NAME="IDX30"></A>



<PRE>
void  VF_ClearError(void)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Clear the error code variable of VFlib.
</DL>



<H3><A NAME="SEC18" HREF="VFlib-36_toc.html#TOC18"><CODE>VF_OpenFont1()</CODE></A></H3>
<P>
<A NAME="IDX31"></A>



<PRE>
int  VF_OpenFont1(char* <VAR>font_name</VAR>,
                  double <VAR>dpi_x</VAR>, double <VAR>dpi_y</VAR>, double <VAR>point_size</VAR>, 
                  double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Open a font.  (If the same font is opened
 multiple times, VFlib keeps track of the number of opened
 font instances of the font.)  
 Since the font is opened with device resolution, point
 size and magnification, a font opened by this function 
 may be useful for high resolution devices such as laser printers.

<DT>Arguments
<DD>
 The argument <VAR>font_name</VAR> is a name of the font to be
 opened.  The device resolution of the target device is 
 specified by <VAR>dpi_x</VAR> (horizontal) <VAR>dpi_y</VAR> (vertical).  
 These values are given in DPI (dots per inch).
 The argument <VAR>point_size</VAR> specifies the size of the bitmap. 
 If this argument is negative the bitmap size will be the
 inherent size of the font.

 To obtain a magnified bitmap, give a magnification factor
 to the argument <VAR>mag_x</VAR> (horizontal) and <VAR>mag_y</VAR> (vertical).  
 If  the argument <VAR>point_size</VAR> is non-negative, font size
 will be <VAR>point_size</VAR> times <VAR>mag_x</VAR> (<VAR>mag_y</VAR>) large for
 horizontal (vertical) direction.

<DT>Return Value
<DD>
 A non-negative integer is returned on success. 
 This value is a font identifier (font id); it is used to
 specify a font for further font operations.  If <CODE>VF_OpenFont1()</CODE>
 fails, a negative integer is returned.
</DL>



<H3><A NAME="SEC19" HREF="VFlib-36_toc.html#TOC19"><CODE>VF_OpenFont2()</CODE></A></H3>
<P>
<A NAME="IDX32"></A>



<PRE>
int  VF_OpenFont2(char* <VAR>font_name</VAR>,
                  int <VAR>pixel_size</VAR>, double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Open a font.  (If the same font is opened
 multiple times, VFlib keeps track of the number of opened
 font instances of the font.)  
 Since the font is opened with pixel size and magnification,
 a font opened by this function may be useful for 
 low resolution devices such as CRT display.

<DT>Arguments
<DD>
 The argument <VAR>font</VAR> is a name of the font to be opened.  
 The argument <VAR>pixel_size</VAR> specifies the size of the bitmap. 
 If this argument is negative the bitmap size will be the
 inherent size of the font.
 To obtain a magnified bitmap, give a magnification factor
 to the argument <VAR>mag_x</VAR> (horizontal) and <VAR>mag_y</VAR> (vertical).  
 If  the argument <VAR>point_size</VAR> is non-negative, font size
 will be <VAR>pixel_size</VAR> times <VAR>mag_x</VAR> (<VAR>mag_y</VAR>) large for
 horizontal (vertical) direction.

<DT>Return Value
<DD>
 A non-negative integer is returned on success. 
 This value is a font identifier (font id); it is used to
 specify a font for further font operations.  If <CODE>VF_OpenFont2()</CODE>
 fails, a negative integer is returned.
</DL>



<H3><A NAME="SEC20" HREF="VFlib-36_toc.html#TOC20"><CODE>VF_CloseFont()</CODE></A></H3>
<P>
<A NAME="IDX33"></A>



<PRE>
int  VF_CloseFont(int <VAR>font_id</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Close a font.

<DT>Arguments
<DD>
 The argument <VAR>font_id</VAR> is a font id to be closed.

<DT>Return Value
<DD>
 A non-negative integer is returned on success.  
 A negative integer is returned on failure.
</DL>



<H3><A NAME="SEC21" HREF="VFlib-36_toc.html#TOC21"><CODE>VF_GetBitmap1()</CODE></A></H3>
<P>
<A NAME="IDX34"></A>



<PRE>
VF_BITMAP  VF_GetBitmap1(int <VAR>font_id</VAR>, long <VAR>code_point</VAR>,
                         double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
  Obtain a glyph bitmap of given font id and code
  point.  The font id <VAR>font_id</VAR> must be an id by <CODE>VF_OpenFont1()</CODE>.
  Size of bitmap to be obtained can be specified by 
  <VAR>mag_x</VAR> and <VAR>mag_y</VAR> arguments.

<DT>Arguments
<DD>
 <VAR>font_id</VAR> specifies the font; <VAR>code_point</VAR> specifies
  the code point of a character. 
  To obtain a magnified bitmap, give a magnification factor
  to the argument <VAR>mag_x</VAR> (horizontal) and <VAR>mag_y</VAR> (vertical).
  If a font is opened with magnification factor 2 and an bitmap
  is obtained by this function with magnification factor 2,
  then the size of yielding bitmap will be 4 times larger than
  the original size.

<DT>Return Value
<DD>
  The return value is a pointer to a newly
  allocated bitmap object.  If it fails to obtain a bitmap, the
  null pointer is returned.  If the bitmap object is no longer
  needed, it must be released by the function <CODE>VF_FreeBitmap()</CODE>.
  The font may not have the specified size; in such case,
  VFlib internally enlarges or shrinks the glyph to obtain 
  a bitmap of the requested size.
</DL>



<H3><A NAME="SEC22" HREF="VFlib-36_toc.html#TOC22"><CODE>VF_GetBitmap2()</CODE></A></H3>
<P>
<A NAME="IDX35"></A>



<PRE>
VF_BITMAP  VF_GetBitmap2(int <VAR>font_id</VAR>, long <VAR>code_point</VAR>,
                         double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain a glyph bitmap of given font id and code
 point.  The font id 'font_id' must be an id by <CODE>VF_OpenFont2()</CODE>.
 Size of bitmap to be obtained can be specified by <VAR>pixel_size</VAR>,
 <VAR>mag_x</VAR> and <VAR>mag_y</VAR> arguments.

<DT>Arguments
<DD>
 <VAR>font_id</VAR> specifies the font; <VAR>code_point</VAR> specifies
 the code point of a character. 
 To obtain a magnified bitmap, give a magnification factor
 to the argument <VAR>mag_x</VAR> (horizontal) and <VAR>mag_y</VAR> (vertical).
 If a font is opened with magnification factor 2 and an bitmap
 is obtained by this function with magnification factor 2,
 then the size of yielding bitmap will be 4 times larger than
 the original size.

<DT>Return Value
<DD>
 The return value is a pointer to a newly
 allocated bitmap object.  If it fails to obtain a bitmap, the
 null pointer is returned.  If the bitmap object is no longer
 needed, it must be released by the function <CODE>VF_FreeBitmap()</CODE>.
 The font may not have the specified size; in such case,
 VFlib internally enlarges or shrinks the glyph to obtain 
 a bitmap of the requested size.
</DL>



<H3><A NAME="SEC23" HREF="VFlib-36_toc.html#TOC23"><CODE>VF_GetMetric1()</CODE></A></H3>
<P>
<A NAME="IDX36"></A>



<PRE>
VF_METRIC1  VF_GetMetric1(int <VAR>font_id</VAR>, long <VAR>code_point</VAR>,
                          VF_METRIC1 <VAR>metric1</VAR>,
                          double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain font metrics of a given font and code point.

<DT>Arguments
<DD>
  Same arguments as of <CODE>VF_GetBitmap1()</CODE>.

<DT>Return Value
<DD>
  A pointer to a metric1 object is returned.  If an
  error occurs, the NULL pointer is returned.  The obtained
  metric is a metric for a bitmap obtained by <CODE>VF_GetBitmap1()</CODE>
  with the same arguments, but the unit of the obtained metric
  is point. If the metric1 object is no longer needed it must be
  released by the function <CODE>VF_FreeMetric1()</CODE>.
</DL>



<H3><A NAME="SEC24" HREF="VFlib-36_toc.html#TOC24"><CODE>VF_GetMetric2()</CODE></A></H3>
<P>
<A NAME="IDX37"></A>



<PRE>
VF_METRIC2  VF_GetMetric2(int <VAR>font_id</VAR>, long <VAR>code_point</VAR>,
                          VF_METRIC2 <VAR>metric2</VAR>,
                          double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain font metrics of a given font and code point.

<DT>Arguments
<DD>
 Same arguments as of <CODE>VF_GetBitmap2()</CODE>.

<DT>Return Value
<DD>
  A pointer to a metric2 object is returned.  If an
  error occurs, the NULL pointer is returned.  The obtained
  metric is a metric for a bitmap obtained by <CODE>VF_GetBitmap2()</CODE>
  with the same arguments, but the unit of the obtained metric
  is pixel.  If the metric2 object is no longer needed, it must be
  released by the function <CODE>VF_FreeMetric2()</CODE>.
</DL>



<H3><A NAME="SEC25" HREF="VFlib-36_toc.html#TOC25"><CODE>VF_GetOutline()</CODE></A></H3>
<P>
<A NAME="IDX38"></A>



<PRE>
VF_OUTLINE  VF_GetOutline(int <VAR>font_id</VAR>, long <VAR>code_point</VAR>,
                          double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain outline data from a given font and code point.

<DT>Arguments
<DD>
 Same as <CODE>VF_GetBitmap1()</CODE>.

<DT>Return Value
<DD>
  Return value is a pointer to a newly allocated
  outline data object.  If it fails to obtain a outline data,
  the NULL pointer is returned.
  Even if the original font is a bitmap, VFlib internally
  creates outline data from the bitmap.  If the source font is
  a vector font, VFlib internally converts the data format to
  VFlib outline data style.  A bitmap of any specified size can
  be obtained from outline data by the function
  <CODE>VF_Outline2Bitmap()</CODE>.  (Default point size and device
  resolution is also kept in the outline data.)
</DL>



<H3><A NAME="SEC26" HREF="VFlib-36_toc.html#TOC26"><CODE>VF_OutlineToBitmap()</CODE></A></H3>
<P>
<A NAME="IDX39"></A>



<PRE>
VF_OUTLINE  VF_OutlineToBitmap(VF_OUTLINE <VAR>outline</VAR>,
                               double <VAR>dpi_x</VAR>, double <VAR>dpi_y</VAR>, 
                               double <VAR>point_size</VAR>,
                               double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain a bitmap from outline data.

<DT>Arguments
<DD>
 The argument <VAR>outline</VAR> is a pointer to an outline
 object to be rasterised.  The arguments <VAR>dpi_x</VAR>, <VAR>dpi_y</VAR>,
 <VAR>point_size</VAR>, <VAR>mag_x</VAR> and <VAR>mag_y</VAR>  are the same as the
 corresponding arguments of <CODE>VF_GetBitmap1()</CODE>.  The outline data
 contains information on device resolution and point size
 specified by <CODE>VF_GetOutline()</CODE>.  (If not specified, default
 values are used. Thus, bitmaps with a default size can be
 obtained by giving -1 for the arguments).

<DT>Return Value
<DD>
  A pointer to a bitmap object is returned.  
  The NULL pointer is returned on failure.  If the bitmap object is
  no longer needed it must be released by the function
  <CODE>VF_FreeBitmap()</CODE>.
</DL>



<H3><A NAME="SEC27" HREF="VFlib-36_toc.html#TOC27"><CODE>VF_GetFontBoundingBox1()</CODE></A></H3>
<P>
<A NAME="IDX40"></A>



<PRE>
int  VF_GetFontBoundingBox1(int <VAR>font_id</VAR>, 
                            double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>,
                            double* <VAR>w</VAR>, double* <VAR>h</VAR>,
                            double* <VAR>xoff</VAR>, double* <VAR>yoff</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain font bounding box information of a given font.

<DT>Arguments
<DD>
 The argument <VAR>font_id</VAR> specify a font in interest.
 The function writes the bounding box information to the locations
 pointed by <VAR>w</VAR>, <VAR>h</VAR>, <VAR>xoff</VAR>, and <VAR>yoff</VAR>.  
 <VAR>w</VAR> and <VAR>h</VAR> point to data objects for width and height
 of bounding box, respectively.
 <VAR>xoff</VAR> and <VAR>yoff</VAR> point to data objects for largest 
 horizontal and vertical displacement of lower left corner of 
 bounding box from reference points.
 Note that these values does not guarantee the minimality;
 they only guarantee that all characters can be contained in
 a box descrived by them.
 If some values of <VAR>w</VAR>, <VAR>h</VAR>, <VAR>xoff</VAR>, or <VAR>yoff</VAR> are 
 not in interest, NULL pointer can be given.

 The argument <VAR>mag_x</VAR> and <VAR>mag_y</VAR> are maginification factor
 to be scaled for a given font <VAR>font_id</VAR>.

<DT>Return Value
<DD>
  If font bounding information is successfully obtained, 
 a non-negative integer is returned; otherwize, negative integer is 
 returned.

 Units of bounding box information is in point.
</DL>



<H3><A NAME="SEC28" HREF="VFlib-36_toc.html#TOC28"><CODE>VF_GetFontBoundingBox2()</CODE></A></H3>
<P>
<A NAME="IDX41"></A>



<PRE>
int  VF_GetFontBoundingBox2(int <VAR>font_id</VAR>, 
                            double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>,
                            int* <VAR>w</VAR>, int* <VAR>h</VAR>,
                            int* <VAR>xoff</VAR>, int* <VAR>yoff</VAR>)
</PRE>

<P>
Same as <CODE>VF_GetFontBoundingBox1()</CODE> except units of 
font bounding box parameters are pixel.




<H3><A NAME="SEC29" HREF="VFlib-36_toc.html#TOC29"><CODE>VF_GetProp()</CODE></A></H3>
<P>
<A NAME="IDX42"></A>



<PRE>
char*  VF_GetProp(int <VAR>font_id</VAR>, char* <VAR>prop_name</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Obtain a property of given font.  (This function
 is font class dependent. You must be very careful to use it!)

<DT>Arguments
<DD>
 The argument <VAR>font_id</VAR> specifies a font from which to
 obtain a property. <VAR>property_name</VAR> specifies the property name.

<DT>Return Value
<DD>
 If the given property exists, its value is
 returned as a string.  The string for the property value is
 newly allocated and must be released by <VAR>free()</VAR> if it is no
 longer needed.  If the given property is undefined, the NULL
 pointer is returned.
</DL>



<H3><A NAME="SEC30" HREF="VFlib-36_toc.html#TOC30"><CODE>VF_CopyBitmap()</CODE></A></H3>
<P>
<A NAME="IDX43"></A>



<PRE>
VF_BITMAP  VF_CopyBitmap(VF_BITMAP <VAR>bm</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Make a copy of a bitmap object.

<DT>Arguments
<DD>
 The argument <VAR>bm</VAR> is a pointer to a bitmap object to be copied.

<DT>Return Value
<DD>
 A new bitmap object is allocated; all values are
 copied.  Return value is a pointer to a new bitmap.  The
 source bitmap <VAR>bm</VAR> remains unaffected.  If an error occurs,
 the NULL pointer is returned.
 The obtained bitmap object must be released by
 <CODE>VF_FreeBitmap()</CODE> if it is no longer needed.
</DL>



<H3><A NAME="SEC31" HREF="VFlib-36_toc.html#TOC31"><CODE>VF_MakeScaledBitmap()</CODE></A></H3>
<P>
<A NAME="IDX44"></A>



<PRE>
VF_BITMAP  VF_MakeScaledBitmap(VF_BITMAP <VAR>bm</VAR>, 
                               double <VAR>mag_x</VAR>, double <VAR>mag_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Make an enlarged or shrinked bitmap.

<DT>Arguments
<DD>
 The argument <VAR>bm</VAR> specifies the source bitmap object,
 <VAR>mag_x</VAR> and <VAR>mag_y</VAR> give the magnification factor in the
 horizontal and vertical direction respectively.  If the
 magnification factor is less than 1, a shrinked bitmap is
 obtained.  Values for <VAR>mag_x</VAR> and <VAR>mag_y</VAR> can be arbitrary
 such as 
 (<EM><VAR>mag_x</VAR> &#62; 1</EM> and <EM><VAR>mag_y</VAR> &#60; 1</EM>)
 or (<EM><VAR>mag_x</VAR> &#60; 1</EM> and <EM><VAR>mag_y</VAR> &#62; 1</EM>).

<DT>Return Value
<DD>
 A bitmap object whose bitmap is enlarged or
 shrinked is created and a pointer to the new bitmap is
 returned.  If an error occurs, the NULL pointer is returned. 
 The source bitmap <VAR>bm</VAR> remains unaffected.
 Use <CODE>VF_FreeBitmap()</CODE> if the returned bitmap object 
 is no longer necessary.
</DL>



<H3><A NAME="SEC32" HREF="VFlib-36_toc.html#TOC32"><CODE>VF_ReflectedBitmap()</CODE></A></H3>
<P>
<A NAME="IDX45"></A>



<PRE>
VF_BITMAP  VF_ReflectedBitmap(VF_BITMAP <VAR>bm</VAR>, 
                              int <VAR>refl_x</VAR>, double <VAR>refl_y</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Make a bitmap with horizontally and/or vertically reflected image.

<DT>Arguments
<DD>
 The argument <VAR>bm</VAR> specifies the source bitmap object,
 <VAR>refl_x</VAR> and <VAR>refl_y</VAR> specify the reflection, respectively.
 If <VAR>refl_x</VAR> is non-zero, the image is holizontally reflected;
 if <VAR>refl_y</VAR> is non-zero, the image is vertically reflected.
 In case <VAR>relf_x</VAR> and <VAR>refl_y</VAR> are both zero,
 the effect is the same as <CODE>VF_CopyBitmap()</CODE>.

<DT>Return Value
<DD>
 A new bitmap object is created and a pointer to the new bitmap is
 returned.  If an error occurs, the NULL pointer is returned. 
 Metrics of created bitmap is the same as that of the original bitmap.
 The source bitmap <VAR>bm</VAR> remains unaffected.
 Use <CODE>VF_FreeBitmap()</CODE> if the returned bitmap object 
 is no longer necessary.
</DL>



<H3><A NAME="SEC33" HREF="VFlib-36_toc.html#TOC33"><CODE>VF_RotatedBitmap()</CODE></A></H3>
<P>
<A NAME="IDX46"></A>



<PRE>
VF_BITMAP  VF_RotatedBitmap(VF_BITMAP <VAR>bm</VAR>, int <VAR>angle</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Make a bitmap image with rotated image.

<DT>Arguments
<DD>
 The argument <VAR>bm</VAR> specifies the source bitmap object,
 <VAR>angle</VAR> gives rotation angle in degree.
 By the limitation of implementation, rotatin angle must be multiple of 90.
 The rotation angle <VAR>angle</VAR> must be one of the following:
<DL COMPACT>

<DT><CODE>VF_BM_ROTATE_0</CODE>
<DD>
  Rotation angle is zero.
  Thus,  the effect is the same as <CODE>VF_CopyBitmap()</CODE>.
<DT><CODE>VF_BM_ROTATE_90</CODE>
<DD>
  Rotation angle is 90 degree.
<DT><CODE>VF_BM_ROTATE_180</CODE>
<DD>
  Rotation angle is 180 degree.
<DT><CODE>VF_BM_ROTATE_270</CODE>
<DD>
  Rotation angle is 270 degree.
</DL>

<DT>Return Value
<DD>
 A bitmap object whose bitmap is rotated is created and 
 a pointer to the new bitmap is returned.  
 If an error occurs, the NULL pointer is returned. 
 The source bitmap <VAR>bm</VAR> remains unaffected.
 Use <CODE>VF_FreeBitmap()</CODE> if the bitmap object is no longer necessary.

 This function rotates a bitmap with the reference point as origin.
 The vector to the next reference point is also rotated.
 Therefore, position of the reference point 
 and a vector to the next reference point 
 of 
   <CODE>VF_RotatedBitmap(<VAR>bm</VAR>, VF_BM_ROTATE_180)</CODE>
 and that of 
   <CODE>VF_ReflectedBitmap(<VAR>bm</VAR>, 1, 1)</CODE>
 are different.
</DL>



<H3><A NAME="SEC34" HREF="VFlib-36_toc.html#TOC34"><CODE>VF_DumpBitmap()</CODE></A></H3>
<P>
<A NAME="IDX47"></A>



<PRE>
void  VF_DumpBitmap(VF_BITMAP <VAR>bm</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap in ASCII-art-style to stdout.

<DT>Arguments
<DD>
 The argument <VAR>bm</VAR> specifies a bitmap to be displayed.

</DL>



<H3><A NAME="SEC35" HREF="VFlib-36_toc.html#TOC35"><CODE>VF_ImageOut_PBMAscii()</CODE></A></H3>
<P>
<A NAME="IDX48"></A>



<PRE>
int  VF_ImageOut_PBMAscii(VF_BITMAP <VAR>bm</VAR>, FILE *<VAR>fp</VAR>, 
                          int <VAR>image_width</VAR>, int <VAR>image_height</VAR>,
                          int <VAR>position_x</VAR>, int <VAR>position_y</VAR>, 
                          int <VAR>margin_l</VAR>, int <VAR>margin_r</VAR>,
                          int <VAR>margin_t</VAR>, int <VAR>margin_b</VAR>,
                          int <VAR>reverse</VAR>, int <VAR>shrink</VAR>,
                          char *<VAR>prog</VAR>, char *<VAR>title</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap <VAR>bm</VAR> in PBM ASCII format to a file stream <VAR>fp</VAR>.

<DT>Arguments
<DD>
 <VAR>bm</VAR> is a bitmap to be written to a file stream <VAR>fp</VAR>.
Size of output image (in pixel) is specified by <VAR>image_width</VAR> 
and <VAR>image_height</VAR>.
If -1 is given for these arguments, the image size should be minimum
to contain the bitmap <VAR>bm</VAR>.

Arguments <VAR>position_x</VAR> and <VAR>position_y</VAR> specifies 
the horizontal and vertical position of a source bitmap <VAR>bm</VAR> 
in an output image file, respectively.
These parameters have effect when <VAR>image_width</VAR> and <VAR>image_height</VAR>
are specified.
Possible values for <VAR>position_x</VAR> is
<DL COMPACT>

<DT><CODE>VF_IMAGEOUT_POSITION_NONE</CODE>
<DD>
  Same as <CODE>VF_IMAGEOUT_POSITION_LEFT</CODE>.
<DT><CODE>VF_IMAGEOUT_POSITION_CENTER</CODE>
<DD>
  <VAR>bm</VAR> is centered in output image.
<DT><CODE>VF_IMAGEOUT_POSITION_LEFT</CODE>
<DD>
  <VAR>bm</VAR> is flushed left in output image.
<DT><CODE>VF_IMAGEOUT_POSITION_RIGHT</CODE>
<DD>
  <VAR>bm</VAR> is flushed righted in output image.
</DL>

Possible values for <VAR>position_y</VAR> is
<DL COMPACT>

<DT><CODE>VF_IMAGEOUT_POSITION_NONE</CODE>
<DD>
  Same as <CODE>VF_IMAGEOUT_POSITION_TOP</CODE>.
<DT><CODE>VF_IMAGEOUT_POSITION_CENTER</CODE>
<DD>
  <VAR>bm</VAR> is centered in output image.
<DT><CODE>VF_IMAGEOUT_POSITION_TOP</CODE>
<DD>
  <VAR>bm</VAR> is placed at the top in output image.
<DT><CODE>VF_IMAGEOUT_POSITION_BOTTOM</CODE>
<DD>
  <VAR>bm</VAR> is placed at the bottom in output image.
</DL>

Arguments <VAR>margin_l</VAR>, int <VAR>margin_r</VAR> are used to speficy 
left and right margins, respectively.
Arguments <VAR>margin_t</VAR>, int <VAR>margin_b</VAR> are used to speficy 
top and bottom margins, respectively.

If the argument <VAR>reverse</VAR> is not 0, black and white in an output image
is reversed.
Argument <VAR>shrink</VAR> specifys shrink factor of image <VAR>bm</VAR>.
(If this value is 1, <VAR>bm</VAR> is not shrinked.
Note: Currently, shrinking image is not supported in PBM ASCII format.)

Arguments <VAR>prog</VAR> and <VAR>title</VAR> are used to emmbed program name
and title in an image file.

</DL>



<H3><A NAME="SEC36" HREF="VFlib-36_toc.html#TOC36"><CODE>VF_ImageOut_PGMAscii()</CODE></A></H3>
<P>
<A NAME="IDX49"></A>



<PRE>
int  VF_ImageOut_PGMAscii(VF_BITMAP <VAR>bm</VAR>, FILE *<VAR>fp</VAR>, 
                          int <VAR>image_width</VAR>, int <VAR>image_height</VAR>,
                          int <VAR>position_x</VAR>, int <VAR>position_y</VAR>, 
                          int <VAR>margin_l</VAR>, int <VAR>margin_r</VAR>,
                          int <VAR>margin_t</VAR>, int <VAR>margin_b</VAR>,
                          int <VAR>reverse</VAR>, int <VAR>shrink</VAR>,
                          char *<VAR>prog</VAR>, char *<VAR>title</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap <VAR>bm</VAR> in PGM ASCII format to a file stream <VAR>fp</VAR>.

<DT>Arguments
<DD>
 Arguments are the same as that of <CODE>VF_ImageOut_PGMAscii()</CODE>.
If <VAR>shrink</VAR> is greater than 1, output image is anti-aliased (gray-scaled).
</DL>



<H3><A NAME="SEC37" HREF="VFlib-36_toc.html#TOC37"><CODE>VF_ImageOut_PGMRaw()</CODE></A></H3>
<P>
<A NAME="IDX50"></A>



<PRE>
int  VF_ImageOut_PGMRaw(VF_BITMAP <VAR>bm</VAR>, FILE *<VAR>fp</VAR>, 
                        int <VAR>image_width</VAR>, int <VAR>image_height</VAR>,
                        int <VAR>position_x</VAR>, int <VAR>position_y</VAR>, 
                        int <VAR>margin_l</VAR>, int <VAR>margin_r</VAR>,
                        int <VAR>margin_t</VAR>, int <VAR>margin_b</VAR>,
                        int <VAR>reverse</VAR>, int <VAR>shrink</VAR>,
                        char *<VAR>prog</VAR>, char *<VAR>title</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap <VAR>bm</VAR> in PGM Raw format to a file stream <VAR>fp</VAR>.

<DT>Arguments
<DD>
 Arguments are the same as that of <CODE>VF_ImageOut_PGMAscii()</CODE>.
If <VAR>shrink</VAR> is greater than 1, output image is anti-aliased (gray-scaled).
</DL>



<H3><A NAME="SEC38" HREF="VFlib-36_toc.html#TOC38"><CODE>VF_ImageOut_EPS()</CODE></A></H3>
<P>
<A NAME="IDX51"></A>



<PRE>
int  VF_ImageOut_EPS(VF_BITMAP <VAR>bm</VAR>, FILE *<VAR>fp</VAR>, 
                     int <VAR>image_width</VAR>, int <VAR>image_height</VAR>,
                     int <VAR>position_x</VAR>, int <VAR>position_y</VAR>, 
                     int <VAR>margin_l</VAR>, int <VAR>margin_r</VAR>,
                     int <VAR>margin_t</VAR>, int <VAR>margin_b</VAR>,
                     int <VAR>reverse</VAR>, int <VAR>shrink</VAR>,
                     char *<VAR>prog</VAR>, char *<VAR>title</VAR>,
                     double <VAR>ptsize</VAR>, int <VAR>pixsize</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap <VAR>bm</VAR> in EPS (Encapsulated PostScript)
format to a file stream <VAR>fp</VAR>.

<DT>Arguments
<DD>
 Arguments are the same as that of <CODE>VF_ImageOut_PGMAscii()</CODE>.
If <VAR>shrink</VAR> is greater than 1, output image is anti-aliased (gray-scaled).
Arguments <VAR>ptsize</VAR> and <VAR>pixsize</VAR> specify size of EPS bounding box;
<VAR>pixsize</VAR> pixels occupy <VAR>ptsize</VAR> points in physical paper.
</DL>



<H3><A NAME="SEC39" HREF="VFlib-36_toc.html#TOC39"><CODE>VF_ImageOut_ASCIIArt()</CODE></A></H3>
<P>
<A NAME="IDX52"></A>



<PRE>
int  VF_ImageOut_ASCIIArt(VF_BITMAP <VAR>bm</VAR>, FILE *<VAR>fp</VAR>, 
                          int <VAR>image_width</VAR>, int <VAR>image_height</VAR>,
                          int <VAR>position_x</VAR>, int <VAR>position_y</VAR>, 
                          int <VAR>margin_l</VAR>, int <VAR>margin_r</VAR>,
                          int <VAR>margin_t</VAR>, int <VAR>margin_b</VAR>,
                          int <VAR>reverse</VAR>, int <VAR>shrink</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap <VAR>bm</VAR> in ASCII art format to a file stream <VAR>fp</VAR>.

<DT>Arguments
<DD>
 Arguments are the same as that of <CODE>VF_ImageOut_PGMAscii()</CODE>.
</DL>



<H3><A NAME="SEC40" HREF="VFlib-36_toc.html#TOC40"><CODE>VF_ImageOut_ASCIIArtV()</CODE></A></H3>
<P>
<A NAME="IDX53"></A>



<PRE>
int  VF_ImageOut_ASCIIArtV(VF_BITMAP <VAR>bm</VAR>, FILE *<VAR>fp</VAR>, 
                           int <VAR>image_width</VAR>, int <VAR>image_height</VAR>,
                           int <VAR>position_x</VAR>, int <VAR>position_y</VAR>, 
                           int <VAR>margin_l</VAR>, int <VAR>margin_r</VAR>,
                           int <VAR>margin_t</VAR>, int <VAR>margin_b</VAR>,
                           int <VAR>reverse</VAR>, int <VAR>shrink</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Print a bitmap <VAR>bm</VAR> in ASCII art format to a file stream <VAR>fp</VAR>.
Image is rotated in clockwise, 90 degree.

<DT>Arguments
<DD>
 Arguments are the same as that of <CODE>VF_ImageOut_PGMAscii()</CODE>.
</DL>



<H3><A NAME="SEC41" HREF="VFlib-36_toc.html#TOC41"><CODE>VF_FreeBitmap()</CODE></A></H3>
<P>
<A NAME="IDX54"></A>



<PRE>
void  VF_FreeBitmap(VF_BITMAP <VAR>bm</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Release a bitmap object.

<DT>Arguments
<DD>
 The argument <VAR>bm</VAR> is a pointer to a bitmap object to be released.
</DL>
<P>
       




<H3><A NAME="SEC42" HREF="VFlib-36_toc.html#TOC42"><CODE>VF_FreeMetric1()</CODE></A></H3>
<P>
<A NAME="IDX55"></A>



<PRE>
void  VF_FreeMetric1(VF_METRIC1 <VAR>metric</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Release a metric1 object.

<DT>Arguments
<DD>
 The argument <VAR>metric</VAR> is a pointer to a metric1 object.
</DL>



<H3><A NAME="SEC43" HREF="VFlib-36_toc.html#TOC43"><CODE>VF_FreeMetric2()</CODE></A></H3>
<P>
<A NAME="IDX56"></A>



<PRE>
void  VF_FreeMetric2(VF_METRIC2 <VAR>metric</VAR>)
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Release a metric2 object.

<DT>Arguments
<DD>
 The argument <VAR>metric</VAR> is a pointer to a metric2 object.

</DL>



<H3><A NAME="SEC44" HREF="VFlib-36_toc.html#TOC44"><CODE>VF_InstallFontDriver()</CODE></A></H3>
<P>
<A NAME="IDX57"></A>



<PRE>
int  VF_InstallFontDriver(char* <VAR>class_name</VAR>, 
                          int(*driver)(VF_FONT <VAR>font</VAR>, 
                                       char* <VAR>class_name</VAR>,
                                       char* <VAR>font_name</VAR>,
                                       int <VAR>implicit_flag</VAR>));
</PRE>

<DL COMPACT>

<DT>Functionality
<DD>
 Install a font driver.

<DT>Arguments
<DD>
<VAR>class_name</VAR> is a font class name, <VAR>driver</VAR> is a
pointer to a function of a font driver of the font class. 
The function given by <VAR>driver</VAR> is called when a font of this
font class is opened by <CODE>VF_OpenFont1()</CODE> and <CODE>VF_OpenFont2()</CODE>.
The function <VAR>driver</VAR> is called with parameters of the font
to be opened: <VAR>font</VAR> is a data object for font management
defined by VFlib internally.  <VAR>class_name</VAR> is the font
class name.  <VAR>font_name</VAR> is the name of the font to be
opened.  This argument is the same as the argument of
<CODE>VF_OpenFont1()</CODE> and <CODE>VF_OpenFont2()</CODE>.  
<VAR>implicit_font</VAR> is 
a flag whose value is 1 if a font is to be opened as an 
implicit font (a font which does not explicitly appear in 
vflibcap) and 0 if it is to be opened as an explicit font 
(a font that does appear in vflibcap).

<DT>Return Value
<DD>
If successful, a non-negative integer is returned. 
A negative integer is returned if the installation of the
font driver fails.
</DL>



<H2><A NAME="SEC45" HREF="VFlib-36_toc.html#TOC45">Building an application software with VFlib</A></H2>

<P>
An application software that use VFlib must include 
a header file 
<TT>`VFlib-3_6.h'</TT>.
<A NAME="IDX58"></A>
Typically, this file is installed <TT>`/usr/local/include/'</TT> directory.


<P>
Never forget, that application software that uses VFlib 
must be linked against
FreeType 1.2 or later (<TT>`libttf.a'</TT> or <TT>`libttf.so'</TT>), 
T1Lib 5.1 or later (<TT>`libt1.a'</TT> or <TT>`libt1.so'</TT>), and 
kpathsea 3.2 (<TT>`libkpathsea.a'</TT> or <TT>`libkpathsea.so'</TT>),
if you configure VFlib to use them.
(If VFlib is configured not to use them, they are not necessary.)


<P>
I recommend shared library versions for these optional libraries
if you built a shared library version of VFlib.



<PRE>
#include &#60;VFlib-3_6.h&#62;
</PRE>

<P>
VFlib must be initialized before it is used.



<PRE>
char* vflibcap = "vflibcap";
char* params =  "TeX_DPI=300, KPATHSEA_MODE=cx";

if (VF_Init(vflibcap, params) &#60; 0){
  fprintf(stderr, "Initializing VFlib: failed\n");
  exit(1);
}
</PRE>

<P>
Following program fragment opens a font, obtains a bitmap, and
print obtained bitmap. 



<PRE>
int         fid;
VF_BITMAP   bm;

if ((fid = VF_OpenFont2("timR24.pcf", -1, 1.0, 1.0)) &#60; 0){
  fprintf(stderr, "Opening font: failed\n");
  exit(1);
}

bm = VF_GetBitmap2(fid, 0x67, 1.0, 1.0);

VF_DumpBitmap(bm);
</PRE>



<H2><A NAME="SEC46" HREF="VFlib-36_toc.html#TOC46">A simple example</A></H2>

<P>
<A NAME="IDX59"></A>
The following program code is a "banner" like using VFlib.
For simplicity, this program accepts only 1-byte encoded characters.
It reads an input from standard input and prints characters
in ascii-art form to standard output.



<PRE>
/* 
 * vflbanner.c - a banner by VFlib
 * by Hirotsugu Kakugawa
 *
 *
 */
/*
 * Copyright (C) 1998 Hirotsugu Kakugawa. 
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  
 */

#include "config.h"
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;ctype.h&#62;
#include "VFlib-3_6.h"

#define  DEFAULT_FONT  "timR18.pcf"

char    *vflibcap;
char    *fontname;

void  usage(void);
void  vflbanner(FILE *fp);

int
main(int argc, char **argv)
{
  vflibcap = NULL;
  fontname = DEFAULT_FONT;

  --argc; argv++;
  while (argc &#62; 0){
    if ((argc &#62;= 1)
        &#38;&#38; ((strcmp(argv[0], "-h") == 0) || (strcmp(argv[0], "--help") == 0))){
      usage();
      exit(0);
    } else if ((argc &#62;= 2) &#38;&#38; (strcmp(argv[0], "-v") == 0)){
      --argc; argv++;
      vflibcap = argv[0];
      --argc; argv++;
    } else if ((argc &#62;= 2) &#38;&#38; (strcmp(argv[0], "-f") == 0)){
      --argc; argv++;
      fontname = argv[0];
      --argc; argv++;
    } else {
      break;
    }
  }

  vflbanner(stdin);

  return 0;
}

void usage(void)
{
  printf("vflbanner - a banner program using VFlib\n");
  printf("Usage: vflbanner [-v vflibcap] [-f fontname]\n"); 
  printf("This program reads a text from standard input.  It supports\n");
  printf("1-bit encoded font only. Thus, `ctextpgm' is better than this.\n");
}

void
vflbanner(FILE  *fp)
{
  int  fid;
  int  ch; 
  int  pos_x, pos_y; 
  VF_BITMAP  bm, page_bm;
  struct vf_s_bitmaplist  PageBuff;

  if (VF_Init(vflibcap, NULL) &#60; 0){
    printf("VFlib initialization error");
    switch (vf_error){
    case VF_ERR_INTERNAL:
      printf(" - Internal error.\n"); break;
    case VF_ERR_NO_MEMORY:
      printf(" - Server runs out of memory.\n"); break;
    case VF_ERR_NO_VFLIBCAP:
      printf(" -  No vflibcap.\n"); break;
    default: 
      printf(" -  Error code %d\n", vf_error); break;
    }
    fflush(stdout);
    exit(1);
  }

  if ((fid = VF_OpenFont1(fontname, -1, -1, -1, 1, 1)) &#60; 0)
    return;
    
  VF_BitmapListInit(&#38;PageBuff);

  pos_x = pos_y = 0; 
  while ((ch = getc(fp)) != EOF){
    if (!isprint(ch))
      ch = ' ';
    if ((bm = VF_GetBitmap1(fid, (long)ch, 1, 1)) == NULL)
      continue;
    VF_BitmapListPut(&#38;PageBuff, bm, pos_x, pos_y);
    pos_x = pos_x + bm-&#62;mv_x;
  }

  page_bm = VF_BitmapListCompose(&#38;PageBuff);
  VF_DumpBitmap(page_bm);
  VF_BitmapListFinish(&#38;PageBuff);
  VF_FreeBitmap(page_bm);

  VF_CloseFont(fid);
}

/*EOF*/
</PRE>

<P>
By the following commands is used to comple the program.



<PRE>
% gcc -c `VFlib3-config --cflags` vflbanner.c
% gcc -o vflbanner vflbanner.o `VFlib3-config --libs` 
</PRE>

<P>
<A NAME="IDX60"></A>
@command{VFlib3-config} is a program to print misc information on
configuration of VFlib. It prints C compiler option to specify
include directory (@option{--cflags}), dependent libraries (@option{--libs}),
for example.
Run @command{VFlib3-config} with @option{--help} option for detail.


<P>
 




<H1><A NAME="SEC47" HREF="VFlib-36_toc.html#TOC47">Writing a vflibcap</A></H1>



<H2><A NAME="SEC48" HREF="VFlib-36_toc.html#TOC48">Introduction to vflibcap</A></H2>

<P>
A vflibcap file is a database of font definitions for the VFlib library.  
A vflibcap font definition is described in a format
similar to termcap and printcap.  
Vflibcap provides logical font names and
logical font names may not corresponds to font files to be accessed.
In this document, we simply say "font" to denote logical fonts.


<P>
Each VFlib fonts have its own parameters listed below:



<UL>
<LI>Pixel size,

<LI>Point size, and

<LI>Resolution of target device.

</UL>

<P>
These parameters may not be available in font file.
For instance, these parameters are lacking in TrueType fonts.
Lacking information is given in vflibcap file, 
or it is given by a font driver as default values.


<P>
<B>Note:</B>
If you want to use VFlib for TeX DVI drivers, such as
previewers and pronter driver,
use @command{vflmkcaptex} program to generate vflibcap file
automatically.




<H2><A NAME="SEC49" HREF="VFlib-36_toc.html#TOC49">Syntax of vflibcap</A></H2>

<P>
The syntax of vflibcap file is lisp-like form. 
A semicolon <CODE>;</CODE> starts a comment and following 
text is ignored until the end of line.
A colon in a string which is enclosed by double colons is not 
considered as a comment character and forms a part of string.
In the following explanation, we ignore comments.


<P>
A vflibcap file is a sequence of expressions called s-expressions.
Basic data item of s-expression is string.
Unlike lisp, there is no "number" type.
A sequence of digits is parsed as a string.
To include a special characters in a string such as double quotation,
control code, and parenthesis, escape sequence can be used.
String is a sequence of characters of the following form:


<DL COMPACT>

<DT>String Form 1:
<DD>
   Sequence of characters enclosed by double quotations. 

   Examples: 

<PRE>
   "hello world"
   "a, b, c, d"
   "He said \"Thanks!\"."
   "a*(b+c)"
</PRE>

<DT>String Form 2:
<DD>
   Sequence of characters except space, tab, newline, and 
   closing parenthesis. A start character must not be a double quotation.

   Examples: 

<PRE>
   font-file
   hello\ world
   He\ said\ \"Thanks!\".
   a*\(b+c\)
</PRE>

</DL>

<P>
Unlink lisp, there is no distinction between string and symbol in
vflibcap; they are the same data type.
That is, <CODE>HELLO</CODE> and <CODE>"HELLO"</CODE> are the same.


<P>
Parentheses is used to form a "list" like in lisp.
For example, <CODE>(A B C)</CODE> is a list of three strings.
List can be nested any depth, e.g., 
<CODE>(A (B1 B2 B3) (C1 (C21 C22) C3))</CODE>.


<P>
A vflibcap must be a sequence of s-expression of the following forms:


<DL COMPACT>

<DT><CODE>(define-default <VAR>FONT-CLASS</VAR> <VAR>CAPABILITY-DEF</VAR> ... )</CODE>
<DD>
  This expression defines a default values for a font class.

<DT><CODE>(define-font <VAR>NAME</VAR> <VAR>CAPABILITY-DEF</VAR> ... )</CODE>
<DD>
  This expression defines a font.

<DT><CODE>(define-macro <VAR>NAME</VAR> <VAR>CAPABILITY-DEF</VAR> ... )</CODE>
<DD>
  This expression defines a macro <VAR>NAME</VAR>.
</DL>

<P>
<VAR>CAPABILITY-DEF</VAR> must be a list of form 
<CODE>(<VAR>CAPABILITY-NAME</VAR> <VAR>VALUE</VAR>)</CODE>, 
e.g., <CODE>(font-file "/usr/local/share/fonts/"</CODE>.
Each font class defines its own set of capabilities and
capability sets can be different by font classes.
 


<P>
This is an example of vflibcap file.



<PRE>
;; vflibcap
(define-default VFlib
  (extension-hints         (".bdf" bdf) (".pcf" pcf))
  (uncompression-programs  (".Z" "zcat") (".gz" "gzip -cd")
                           ("pk" ascii-jtex-kanji))
  (implicit-font-classes   bdf pcf hbf ascii-jtex-kanji)
  (variable-values     ("TeX_DPI" "300"))

(define-default bdf
  (filename-extensions ".bdf")
  (font-directories
     "/usr/X11R6/lib/X11/fonts//" "/usr/local/share/fonts/X11//")
  (compression-extensions ".gz" ".Z"))

(define-font timR24  ; times roman 24
  (font-class bdf)
  (font-file "timR24.bdf"))

(define-font timR18  ; times roman 18
  (font-class bdf)
  (font-file "timR18.bdf"))
</PRE>



<H2><A NAME="SEC50" HREF="VFlib-36_toc.html#TOC50">Macros in vflibcap</A></H2>

<P>
To avoid writing the same capabilities, macro feature is provided in vflib.
In case of <VAR>CAPABILITY-DEF</VAR> is a string,
it is treated as a macro and a macro definition for it is expanded.
For instance, 



<PRE>
(define-font timR18
  MACRO-NAME
  (font-file "timR18.bdf"))
</PRE>

<P>
is a font definition using a macro <CODE>MACRO-NAME</CODE>.
Suppose a macro <CODE>MACRO-NAME</CODE> is defined as follows.



<PRE>
(define-macro MACRO-NAME
  (font-class bdf)
  (dpi 300))
</PRE>

<P>
Then, the font definition for <CODE>timR24</CODE> is the same as follow.



<PRE>
(define-font timR18
  (font-class bdf)
  (dpi 300))
  (font-file "timR18.bdf"))
</PRE>

<P>
The rule of macr expand is as following procedure.



<OL>
<LI>

Looks for use of macros. 
From the first <VAR>CAPABILITY-DEF</VAR> to the last one,
it is checked if it is a string (thus a macro) or not in order.
If it is a macro, corresponding macro definition is substituted.
Then, next <VAR>CAPABILITY-DEF</VAR> is checked.

<LI>

Macro expand is done recursively.
Thus, a macro can be used in another macro. 

</OL>



<H2><A NAME="SEC51" HREF="VFlib-36_toc.html#TOC51">Searching font files</A></H2>

<P>
Some font classes (e.g., BDF, PCF) defines a <CODE>font-directories</CODE> 
capability in vflibcap file.
This capability specifies a list of font directories, for instance,
<CODE>(font-directories "/usr/local/fonts/" "/opt/fonts" "/usr/local/share/fonts//")</CODE>.
A font file can be searched recursively in a directory tree
if a font directory name ends by double slashes <CODE>//</CODE>.


<P>
Some font drivers support file search by kpathsea.
Typically, font files are located under <TT>`/usr/local/share/texmf'</TT>.
This directory is used to hold TeX-related files.
If a font driver supports searching by kpathsea,
a special name <CODE>TEXMF</CODE> can be given in a list of
<CODE>font-directories</CODE> capability. For instance, 
suppose that 
<CODE>(font-directories "/opt1/fonts//" "TEXMF" "/opt2/fonts//")</CODE>
is specified.   Then files are searched under <CODE>/opt1/fonts</CODE>, 
by kpathsea, and then <CODE>/opt2/fonts</CODE>, in this order.


<P>
Currently, pk, gf, tfm, vf, truetype, and type1 font classes suport 
searcing files by kpathsea.




<H2><A NAME="SEC52" HREF="VFlib-36_toc.html#TOC52">Fast font file search</A></H2>

<P>
<A NAME="IDX61"></A>
In case there are many font directories and sub-directory
which contains many font file, searching a font file take long time,
since font directories are traversed to find a requested font file.
For fast font file search,
font file hint database (FDB for short) can be used.
It is placed in a root of a font directory, and
it contains pairs of font file name and relative pathname of the font file
from the font directory.
The file name of FDB is <CODE>VFlib.fdb</CODE>.


<P>
The following is an example of FDB file.

<PRE>
times__m.pfb	type1/t/times__m.pfb
times__m.afm	type1/t/times__m.afm
zac_____.ttf	ttf/z/zac_____.ttf
zalescap.ttf	ttf/z/zalescap.ttf
</PRE>

<P>
Suppose that this FDB file is located in <TT>`/foo/bar/'</TT>, for instance.
The file tells us that there is a file <TT>`times__m.pfb'</TT> 
and absolute path name of the file is 
<TT>`/foo/bar/type1/t/times__m.pfb'</TT>.


<P>
If FDB file is found in a root directory of font directory,
the FDB file is opened to find a requested font file.
If a requested font file is not found, other font directory is searched,
i.e., the directory is not traversed at all.
In case FDB file is not found, a font directory is traversed to 
find a requested font file. 


<P>
It is important to remember that
you must not forget to update FDB file after you 
added new font files in a font directory.
If you forget, installed font files are not found evenif they are
in a font directory.
To update a FDB file, run the utility program <CODE>vflmkfdb</CODE>.
See section <A HREF="VFlib-36.html#SEC87">vflmkfdb</A>, for details of the program.


<P>
A FDB file must be located in a root of a font directory
and its name must be <TT>`VFlib.fdb'</TT>.
Even if there is a FDB file in a sub-directory of a font directory,
VFlib does not look for it. 




<H2><A NAME="SEC53" HREF="VFlib-36_toc.html#TOC53">Compressed font files</A></H2>

<P>
To reduce disk storage, compressed font files
and uncompression on the fly is supported by some font class.
Note that this feature is font class dependent and not all 
font class support this.


<P>
In a vflibcap file, a font file name need not have a compressed type
extension, such as <CODE>.gz</CODE>.
When VFlib searches a font file, it internally adds compressed 
type extension and finds a file.




<H2><A NAME="SEC54" HREF="VFlib-36_toc.html#TOC54">Explicit and implicit fonts</A></H2>
<P>
<A NAME="IDX62"></A>
<A NAME="IDX63"></A>


<P>
Fonts explicitly defined in a vflibcap file are called <EM>explicit fonts</EM>.
Fonts does not appear vflibcap file and searched by font drivers on
demand are called <EM>implicit fonts</EM>.




<H2><A NAME="SEC55" HREF="VFlib-36_toc.html#TOC55">Variables in vflibcap</A></H2>
<P>
<A NAME="IDX64"></A>


<P>
In a vflibcap file, variables can be used as capability values.
A capability value can be a value of a variable if a dollar sign 
(<CODE>$</CODE>) followed by a variable name is given.  


<P>
For instance, <CODE>(dpi $TeX_DPI)</CODE> can be used instead of <CODE>(dpi 300)</CODE>.
The value for a variable must be defined somewhere.
Default value can be given in <CODE>(define-default VFlib  ...)</CODE>, which 
will be explained later.


<P>
<A NAME="IDX65"></A>
Default values can be overridden on initialization function of 
VFlib <CODE>VF_Init()</CODE>, or Unix environment variables
<CODE>VFLIBCAP_PARAM_<VAR>var</VAR></CODE>. 
For example, <CODE>VFLIBCAP_PARAM_TeX_DPI</CODE> is defined, its value becomes the
value of the vflibcap variable <CODE>TeX_DPI</CODE>.


<P>
The value of an environment variable <CODE>VFLIBCAP_PARAM_<VAR>var</VAR></CODE>
is parsed as an S-expression, not as an string.
Thus, if you want to specify a string <CODE>ABC 123</CODE>, 
the value of an environment variablue must be <CODE>\"abc 123\"</CODE>.
(Without double quotation, it will be a sequence of two strings.
Only the first one is effective and the second one is ignored.)




<H2><A NAME="SEC56" HREF="VFlib-36_toc.html#TOC56">VFlib defaults</A></H2>

<P>
To specify global behavior of VFlib, (virtual) font class
<CODE>VFlib</CODE> is defined.


<P>
The following capability are defined.


<DL COMPACT>

<DT><CODE>implicit-font-classes</CODE> (optional)
<DD>
--- A list of implicit font classes. Font classes listed by
this capability is candidates for implicit font searching.

example: <CODE>(implicit-font-classes "bdf" "pcf" "gf")</CODE>

<DT><CODE>extension-hints</CODE> (optional)
<DD>
--- A list of paris of font name postfix and corresponding font class name.
This is hint information to find font class from a font name in case
of searching an implicit font.
If an implicit font name matches with a postfix given by this capability,
specified font class is invoked to search an implicit font.
This is effective to reduce time to search an implicit font.

example: <CODE>(extension-hints (".pcf" pcf) (".bdf" bdf) ("gf" gf))</CODE>

<DT><CODE>variable-values</CODE> (optional)
<DD>
--- A list of pairs of a name of vflibcap variable and its default value.

example: <CODE>(variable-values ("TeX_DPI" "300") ("TeX_KPATHSEA_MODE" "cx") (v ("p1" "v1")</CODE>

<DT><CODE>uncompression-programs</CODE> (optional)
<DD>
--- A list of pairs of file name extension and corresponding uncompression
program.  This is used for reading compressed font files.
An uncompression program must output uncompressed data 
to standard output.

This capability is just defines relations of 
an extension and an uncompression program.
A list of supported compressed types of a font class
is given in a font class default description of each font class.

example: <CODE>(uncompression-programs (".Z" "zcat") (".gz" "gzip -cd")</CODE>

<DT><CODE>code-conversion-files</CODE> (optional)
<DD>
--- A list of file names for encoding conversion. 
Currently, TrueType font class uses this. 
See section <A HREF="VFlib-36.html#SEC78">Code conversion system</A>.

example: <CODE>(code-conversion-files "iso8859-1_unicode.ccv".ccv")</CODE>

<DT><CODE>use-kpathsea</CODE> (optional)
<DD>
--- A flag whether kpathsea is used or not to search TeX font files.
Value of this capability must be one of <CODE>"Yes"</CODE> or <CODE>"No"</CODE>.

example: <CODE>(use-kpathsea "Yes")</CODE>

<DT><CODE>kpathsea-mode</CODE> (optional)
<DD>
--- A device mode name for kpathsea library.

example: <CODE>(kpathsea-mode "cx")</CODE>

<DT><CODE>kpathsea-dpi</CODE> (optional)
<DD>
--- Device resolution (in dpi) of a device mode for kpathsea library.

example: <CODE>(kpathsea-mode 300)</CODE>

<DT><CODE>kpathsea-program-name</CODE> (optional)
<DD>
--- An application program name for kpathsea library.

example: <CODE>(kpathsea-mode "xgdvi")</CODE>

</DL>



<H2><A NAME="SEC57" HREF="VFlib-36_toc.html#TOC57">BDF font class</A></H2>

<P>
The BDF format is a bitmap font format encoded in human-readable, platform
independent format for distributing X Window fonts.


<P>
This font class supports compressed font files and implicit fonts.
<BR>


<P>
<B>Font class name</B>: <CODE>bdf</CODE>
<A NAME="IDX66"></A>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
---  A list of font directories for searching font files.
Recursive searching of font files is support.

<DT><CODE>compression-extensions</CODE>  (optional)
<DD>
--- A list of supported compression type for this font class.
This font class supports only compression type given by this capability.
When a font is searched, a file followed by a compression extension
is searched if given font file is not found.
(Note that <CODE>uncompression-programs</CODE> capability of 
VFlib class default description gives a uncompression programs.)

example: <CODE>(compression-extensions ".gz" ".Z")</CODE>

<DT><CODE>dpi</CODE>  (optional)
<DD>
--- Defualt device resolution.  
Default horizontal and vertical resolutions will be the same value.
  
example: <CODE>(dpi 300)</CODE>

<DT><CODE>dpi-x</CODE> (optional)
<DD>
--- Default horizontal device resolution.  
  
example: <CODE>(dpi-x 300)</CODE>

<DT><CODE>dpi-y</CODE> (optional)
<DD>
--- Default vertical device resolution.  
  
example: <CODE>(dpi-y 300)</CODE>

<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
--- Aspect ratio of characters. 
If this value is 0.5 then width is half, and if 2 then width is doubled. 

example: <CODE>(aspect-ratio 0.8)</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
--- A list of pairs of a property name and its value. 
Property values given by this parameter is used by <CODE>VF_GetProp()</CODE>

example: <CODE>(properties ("PROP-1" "value-1") ("PROP-2" "value-2"))</CODE>

<DT><CODE>variable-values</CODE> (optional)
<DD>
--- A list of pairs of a vflibcap variable name and its default value. 

example: <CODE>(variable-values ("TeX_DPI" "300") ("TeX_KPATHSEA_MODE" "cx") ("TeX_KPATHSEA_PROGRAM" "/usr/X11R6/xldvi"))</CODE>

</DL>
<P>
<BR>


<P>
<B>Capabilities for font definition:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. This value must be <CODE>bdf</CODE>.

<DT><CODE>font-directories</CODE> (optional)
<DD>
---  A list of font directories for searching font files.
Recursive searching of font files is support.
A font file is searched in the directories given by this capability.

If this capability is not given, 
the font directory specified by the class default is used to search fonts.
If this capability is given, 
the font directory specified by the class default is not 
used to search fonts.

<DT><CODE>font-file</CODE> (optional)
<DD>
--- A font file name string. 
If this capability is not specified, the font name is used as 
the font file name.  
Multiple font file names can be listed in this capability.
The driver tries to open a font listed first.
If it is impossible to open, then  it tries to open the second font.
This is repeated until a font is successfully opened.
If all fonts are impossible to open, font open fails.

example: <CODE>(font-file "timI24.bdf" "timR24.bdf")</CODE>

<DT><CODE>point-size</CODE> (optional)
<DD>
--- font size in points.  If the size is different
from the size defined in the BDF font file, the bitmap is
enlarged or shrinked to yield the specified size.  
This capability has effect for the VFlib functions <CODE>VF_GetBitmap1()</CODE>
and <CODE>VF_GetMetric1()</CODE>.

example: <CODE>(point-size 24.0)</CODE>

<DT><CODE>pixel-size</CODE> (optional)
<DD>
--- font size in pixels. 
If the size is different from the size defined in the BDF font file, 
the bitmap is enlarged or shrinked to yield the specified size.  
This capability has effect for the VFlib functions <CODE>VF_GetBitmap2()</CODE>
and <CODE>VF_GetMetric2()</CODE>.

example: <CODE>(pixel-size 24)</CODE>

<DT><CODE>magnification</CODE> (optional)
<DD>
--- magnification factor.
The font is magnified by this factor.

example: <CODE>(magnification 1.20)</CODE>

<DT><CODE>character-set</CODE> (optional)
<DD>
--- This is used for code point conversion.
Value of this capability gives an external view of a character set of a font.
Code conversion (ccv) is determined by this value and
the following three capabilities.

<DT><CODE>encoding</CODE> (optional)
<DD>
--- This is used for code point conversion.
Value of this capability gives an external view of an encoding of a font.

<DT><CODE>font-character-set</CODE> (optional)
<DD>
--- This is used for code point conversion.
Value of this capability gives an internal view of a character set of a font.
Therefore, this value must match the character set of the font file
given by <CODE>font-file</CODE> capability.

<DT><CODE>font-encoding</CODE> (optional)
<DD>
--- This is used for code point conversion.
Value of this capability gives an internal view of an encoding of a font.
Therefore, this value must match the encoding of the font file
given by <CODE>font-file</CODE> capability.

The following example defines a font named <CODE>iso8859_5-font</CODE>
with ISO-8859-5 encoding by using a KOI8-R encoded font file.


<PRE>
(define-font iso8859_5-font
  (font-class pcf)
  (character-set "ISO8859-5")   (encoding "ISO")
  (font-character-set "KOI8-R") (font-encoding "KOI8-R")
  (font-file "koi8x13.pcf"))
</PRE>

Code conversion is done by a subsystem named CCV.
See section <A HREF="VFlib-36.html#SEC78">Code conversion system</A> for detail.

</DL>



<H2><A NAME="SEC58" HREF="VFlib-36_toc.html#TOC58">PCF font class</A></H2>
<P>
<A NAME="IDX67"></A>


<P>
<B>Font class name:</B> <CODE>pcf</CODE>
<BR>


<P>
Other specification is the same as BDF font class
except font class name is <CODE>pcf</CODE>.




<H2><A NAME="SEC59" HREF="VFlib-36_toc.html#TOC59">HBF font class</A></H2>
<P>
<A NAME="IDX68"></A>


<P>
<B>Font class name:</B> <CODE>hbf</CODE>
<BR>


<P>
Other specification is the same as BDF font class
except font class name is <CODE>hbf</CODE>.




<H2><A NAME="SEC60" HREF="VFlib-36_toc.html#TOC60">TrueType font class</A></H2>
<P>
<A NAME="IDX69"></A>


<P>
TrueType is a vector font font format.
This font class supports implicit fonts but does not support
compressed font files.
<A NAME="IDX70"></A>
TrueType font driver uses FreeType library version 1.2
developed by David Turner, Robert Wilhelm, and Werner Lemberg.
See <A HREF="http://www.freetype.org/">http://www.freetype.org/</A> for detail.
<BR>


<P>
<B>Font class name:</B> <CODE>truetype</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
--- A list of font directories.
This driver supports font file search by kpathsea.
To search a font file by kpathsea,
use <CODE>TEXMF</CODE> for a directory name.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>hinting</CODE> (optional)
<DD>
--- If the value of capability <CODE>on</CODE>, "hinting" information is
used to render characters. This is effective when small characters
are rendered. If the value is <CODE>off</CODE>, hinting is disabled.
Hinting information is used by default.

Note that enabling hinting has effect when obtaining bitmaps.
It has no effect when you obtain and rasterize 
outline data in VFlib format, 
since VFlib outline format does not supports hinting information.

<DT><CODE>platform-id</CODE> (optional)
<DD>
--- A TrueType font can have multiple character code - 
glyph mapping tables.
A mapping table is selected by specifying
a pair of platform ID (<CODE>Microsoft</CODE>, <CODE>Macintosh</CODE>, etc) 
and encoding ID (<CODE>Unicode</CODE>, <CODE>Shift-JIS</CODE>, etc).
This capability is used to specify platform ID of a mapping table 
to be selected.

Value of this capability is one of strings below:
<DL COMPACT>

<DT><CODE>apple</CODE>
<DD>
   Apple platform 
<DT><CODE>macintosh</CODE>, <CODE>mac</CODE>
<DD>
   Macintosh platform
<DT><CODE>ascii</CODE>, <CODE>iso</CODE>
<DD>
   ISO platform
<DT><CODE>microsoft</CODE>, <CODE>windows</CODE>, <CODE>ms</CODE>
<DD>
   Microsoft platform
<DT><CODE>any</CODE>, <CODE>?</CODE>, <CODE>*</CODE>
<DD>
   Any platform
</DL>

Default value for this capability is Microsoft platform.

example: <CODE>(platform-id "microsoft")</CODE>

<DT><CODE>encoding-id</CODE> (optional)
<DD>
--- Together with platform id, this capability is used to specify
a mapping table. 

When ISO platform is selected by the <CODE>encoding-id</CODE> 
capability, 
value of this <CODE>encoding-id</CODE> capability is one of strings below:
<BR>

<DL COMPACT>

<DT><CODE>ascii</CODE>
<DD>
   ASCII encoding.
<DT><CODE>iso10464</CODE>
<DD>
   ISO 10464 encoding.
<DT><CODE>iso8859-1</CODE>
<DD>
   ISO8859-1 encoding.
<DT><CODE>any</CODE>, <CODE>?</CODE>, <CODE>*</CODE>
<DD>
   Any encoding.
</DL>
<BR>

When Apple platform is selected by the <CODE>encoding-id</CODE> 
capability, 
value of this <CODE>encoding-id</CODE> capability is one of strings below:
<BR>

<DL COMPACT>

<DT><CODE>unicode1.1</CODE>
<DD>
   Unicode 1.1 encoding.
<DT><CODE>unicode2.0</CODE>
<DD>
   Unicode 2.0 encoding.
<DT><CODE>iso10464</CODE>
<DD>
   ISO 10464 encoding.
<DT><CODE>any</CODE>, <CODE>?</CODE>, <CODE>*</CODE>
<DD>
   Any encoding
</DL>
<BR>

When Microsoft platform is selected by the <CODE>encoding-id</CODE> 
capability, 
value of this <CODE>encoding-id</CODE> capability is one of strings below:
<BR>

<DL COMPACT>

<DT><CODE>symbol</CODE>
<DD>
<DT><CODE>unicode</CODE>
<DD>
  Unicode encoding.
<DT><CODE>shift-jis</CODE>, <CODE>sjis</CODE>, <CODE>ms-kanji</CODE>
<DD>
  Shift JIS encoding.
<DT><CODE>big5</CODE>
<DD>
  Big5 encoding.
<DT><CODE>rpc</CODE>
<DD>
<DT><CODE>wansung</CODE>
<DD>
<DT><CODE>johab</CODE>
<DD>
<DT><CODE>any</CODE>, <CODE>?</CODE>, <CODE>*</CODE>
<DD>
   Any encoding
</DL>
<BR>

When Macintosh platform is selected by the <CODE>encoding-id</CODE> 
capability, 
value of this <CODE>encoding-id</CODE> capability is one of strings below:

<DL COMPACT>

<DT><CODE>roman</CODE>
<DD>
<DT><CODE>japanese</CODE>
<DD>
<DT><CODE>traditional-chinese</CODE>
<DD>
<DT><CODE>korean</CODE>
<DD>
<DT><CODE>arabic</CODE>
<DD>
<DT><CODE>hebrew</CODE>
<DD>
<DT><CODE>greek</CODE>
<DD>
<DT><CODE>russian</CODE>
<DD>
<DT><CODE>any</CODE>, <CODE>?</CODE>, <CODE>*</CODE>
<DD>
   Any encoding
</DL>

example: <CODE>(encoding-id "any")</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>
<P>
<BR>


<P>
<B>Capabilities for font definition:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
This value must be "truetype".  

<DT><CODE>font-directories</CODE> (optional)
<DD>
---  A list of font directories for searching font files.
Recursive searching of font files is support.
A font file is searched in the directories by this capability.
If not found, then a font is searched in a directories 
given by the class default.

To search a font file by kpathsea,
use <CODE>TEXMF</CODE> for a directory name.

<DT><CODE>font-file</CODE> (optional)
<DD>
<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>hinting</CODE> (optional)
<DD>
<DT><CODE>font-number</CODE> (optional)
<DD>
<DT><CODE>encoding-force</CODE> (optional)
<DD>
--- In case encoding id data is broken in a TrueType font,
its value can be overridden by this capability.

example <CODE>(encoding-force "unicode")</CODE>

<DT><CODE>character-set</CODE> (optional)
<DD>
--- Together with <CODE>encoding</CODE> capability, this capability
is used to change "external view" of a font.
A font would be a font of a character set given by this capability
and encoding given by <CODE>encoding</CODE> capability.
Conversion of font internal character set and encoding to
an external view is determined by these capability.
Conversion is done by by code conversion system, called CCV.  
section <A HREF="VFlib-36.html#SEC78">Code conversion system</A>
Code conversion files are specified in 
<CODE>code-conversion-files</CODE> in <CODE>VFlib</CODE> font class default.
See section <A HREF="VFlib-36.html#SEC56">VFlib defaults</A>.

For example, a font of JIS X 0208 character set (a Japanese character set)
in Shift-JIS encoding fonts can be accessed as a JIS encoding font.

<DT><CODE>encoding</CODE> (optional)
<DD>
--- Together with <CODE>character-set</CODE> capability, 
this capability defines a external view of a font.   
section <A HREF="VFlib-36.html#SEC78">Code conversion system</A>

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>jisx0212-row47-empty-sjis</CODE> (optional)
<DD>
--- This capability is used for an ad-hoc solution to handle 
JIS X 0212 fonts with non-standard encoding such that 
row 47 is empty and followed rows are shifted by one.
(That is, Kanjis in row 48 of JIS X 0212 appeard in row 49 in such fonts.)
JIS X 0212 fonts of Ricoh TrueTypeWorld ValueFont DX are such fonts.
If <CODE>yes</CODE> is given to this capability,
buggy encoding is virtually fixed.

This capability can apply to other products of buggy encoded 
JIS X 0212 fonts whose internal encoding is Shift JIS.
(Use <CODE>ftdump</CODE> utility of FreeType package to check 
internal encoding scheme of fonts.)

</DL>



<H2><A NAME="SEC61" HREF="VFlib-36_toc.html#TOC61">Type1 font class</A></H2>
<P>
<A NAME="IDX71"></A>


<P>
Type1 is a vector font font format used by PostScript.
This font class supports implicit fonts but does not support
compressed font files.
<A NAME="IDX72"></A>
This Type1 font driver uses T1Lib library version 5.1 or later
developed by Rainer Menzner.
See 
<A HREF="http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html">http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html</A>
for detail.


<P>
Be careful, VFlib does not work with old T1Lib.
Obtain and install T1Lib 5.1 or later.


<P>
Currently, this font driver supports only 8-bit encoded fonts,
i.e., it does not support for fonts of Japanese Kanji characters.


<P>
The function <CODE>VF_GetOutline()</CODE> for Type1 font files is 
supported but the result is ugly.
Since T1Lib does not have a function to obtain outline data of a 
character in Type1 font, 
this font driver creates an outline data from a bitmap
(for compatibility). 
Thus, it is very ugly.
If your application software requires outline data, 
you are recommended to use the same font in other font format,
such as TrueType.
Thus, the outline obtained <CODE>VF_GetOutline()</CODE> function for Type1 font
should be used only when 
the same font in other font format is not available.
<BR>


<P>
<B>Font class name:</B> <CODE>type1</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
--- A list of directories of Type1 font files.
This driver supports font file search by kpathsea.
To search a font file by kpathsea,
use <CODE>TEXMF</CODE> for a directory name.

<DT><CODE>afm-directories</CODE> (optional)
<DD>
--- A list of directories of AFM files.
Each element of this capability should not be a directory for
recursive search (ending by <TT>//</TT>).
This is why AFM files are searched by inside of T1Lib,
although Type1 font files are searched by a file search subsystem of VFlib.

<DT><CODE>encoding-vector-directories</CODE> (optional)
<DD>
--- A list of directories of encoding files.
Each element of this capability should not be a directory for
recursive search (ending by <TT>//</TT>).
This is why encoding vector files are searched by inside of T1Lib.

By default, directories
<CODE>/usr/local/share/VFlib/<VAR>x.y.z</VAR>/t1lib/</CODE> and 
<CODE>/usr/local/share/VFlib/site/t1lib/</CODE> 
are registered.
Optional directories can be installed by this capability.

T1Lib adopts file format for encoding vector file.
When we want to use encoding vector files supplied by @command{dvips}, 
we must convert them into T1Lib format.
To automate this, you can use a Unix Shell script @command{mkt1enc.sh} 
which is in <CODE>/usr/local/share/VFlib/<VAR>x.y.z</VAR>/t1lib/</CODE> directory.
Encoding vector files for @command{dvips} are converted 
into T1Lib format and they are also installed in this directory.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>log-level</CODE> (optional)
<DD>
--- Select logfile output type of T1Lib.
The filename of a logfile is <TT>`t1lib.log'</TT>.
If this capability is not given, the logfile is not created.

<DL COMPACT>

<DT><CODE>error</CODE>
<DD>
  Only error messages are written to the logfile.
<DT><CODE>warning</CODE>
<DD>
  Warning messages and error messages are written to the logfile.
<DT><CODE>statistics</CODE>
<DD>
  Statistics messages and above written to the logfile.
<DT><CODE>debug</CODE>
<DD>
  Any messages useful for debugging and above are written to the logfile.
<DT><CODE>none</CODE>
<DD>
  Never use a logfile.
</DL>

See users manual of T1Lib for detail.

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>
<P>
<BR>


<P>
<B>Capabilities for font definition:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
This value must be "type1".  

<DT><CODE>font-file</CODE> (optional)
<DD>
A list of font file names.
Font file is searched in the listed order 
until existing font files is found.

example: <CODE>(font-file "AvantGarde-Book" "a0100131.pfb")</CODE>

By this example, <TT>`AvantGarde-Book'</TT> is seached first.
If it exists, it is opened.
Otherwise,  <TT>`a0100131.pfb'</TT> is seached next.
If it exists, it is opened.
If it does not exist either, font open fails.

<DT><CODE>encoding-vector</CODE> (optional)
<DD>
A file name for encoding vector.
This file must be reside in a directoy listed by
<CODE>encoding-vector-directories</CODE> capability for type1 font 
class default. 

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>slant-factor</CODE> (optional)
<DD>
--- Slant factor of a font.
This value is tan(<VAR>th</VAR>), where <VAR>th</VAR> is slant angle of a font.
Default value is 0, in case of <VAR>th</VAR> is 90 degree.

example: <CODE>(slant-factor 0.2)</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC62" HREF="VFlib-36_toc.html#TOC62">Zeit font class</A></H2>
<P>
<A NAME="IDX73"></A>


<P>
This font class supports <I>"Syotai Kurubu"</I> format;
it is a vector font format for Japanese Kanji characters. 


<P>
Several free Japanese fonts in this file format are available.



<UL>
<LI>

Umeda vector fonts

<UL>
<LI>

<A HREF="ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/umeda-vector/mincho.vf1.gz">ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/umeda-vector/mincho.vf1.gz</A>
<LI>

<A HREF="ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/umeda-vector/mincho.vf2.gz">ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/umeda-vector/mincho.vf2.gz</A>
<LI>

<A HREF="ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/umeda-vector-font/mincho.vf1.gz">ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/umeda-vector-font/mincho.vf1.gz</A>
<LI>

<A HREF="ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/umeda-vector-font/mincho.vf2.gz">ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/umeda-vector-font/mincho.vf2.gz</A>
</UL>

<BR>

<LI>

Watanabe vector fonts

<UL>
<LI>

<A HREF="ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/watanabe-vector/mincho.vf1.gz">ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/watanabe-vector/mincho.vf1.gz</A>
<LI>

<A HREF="ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/watanabe-vector/mincho.vf2.gz">ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/watanabe-vector/mincho.vf2.gz</A>
<LI>

<A HREF="ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/watanabe-vector-font/mincho.vf1.gz">ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/watanabe-vector-font/mincho.vf1.gz</A>
<LI>

<A HREF="ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/watanabe-vector-font/mincho.vf2.gz">ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/watanabe-vector-font/mincho.vf2.gz</A>
</UL>

<BR>

<LI>

Wadalab fonts

<UL>
<LI>

<A HREF="ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/wadalab-vector/">ftp://ftp.web.ad.jp/pub/TeX/akiu/fonts/wadalab-vector/</A>
<LI>

<A HREF="ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/wadalab-vector-font/">ftp://ftp.eos.hokudai.ac.jp/pub/TeX/fonts/wadalab-vector-font/</A>
<LI>

See also <A HREF="ftp://ftp.ipl.t.u-tokyo.ac.jp/Font/">ftp://ftp.ipl.t.u-tokyo.ac.jp/Font/</A> for Free Japanese Kanji
fonts in Type 1 formats.
</UL>

</UL>

<P>
This font class does not support compressed font files nor implicit fonts.
<BR>


<P>
<B>Font class name:</B> <CODE>zeit</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
<DT><CODE>filename-extensions</CODE> (optional)
<DD>
--- Two file files form a font for this font class, e.g., <CODE>mincho.vf1</CODE>
and <CODE>mincho.vf2</CODE>. Extension candidates without digit must be 
the value for this capability.  

example: <CODE>(filename-extensions ".vf" ".VF")</CODE>

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>writing-direction</CODE> (optional)
<DD>
--- Default writing direction. 
<CODE>Horizontal</CODE> or <CODE>vertical</CODE>; default is <CODE>Horizontal</CODE>. 
This is the same as 
<CODE>(vector-to-bbx-upper-left 0.0 0.86)</CODE>
and <CODE>(vector-to-next-ref-point 1.0 0.0)</CODE> if value of this
capability is "horizontal". 
Otherwise, it is the same as
<CODE>(vector-to-bbx-upper-left -0.5 0.0)</CODE>
and <CODE>(vector-to-next-ref-point 0.0 -1.0)</CODE>.

<DT><CODE>vector-to-bbx-upper-left</CODE> (optional)
<DD>
--- Default value of a vector from the reference point of a character to
upper-left bounding box. Right and up are positive directions.

example: <CODE>(vector-to-bbx-upper-left 0 0.86)</CODE>

<DT><CODE>vector-to-next-ref-point</CODE> (optional)
<DD>
--- Default value of a vector from the reference
point to next reference point. 

example: <CODE>(vector-to-next-ref-point 1.0 0.0)</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>
<P>
<BR>


<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 

<DT><CODE>font-name</CODE> (optional)
<DD>
--- Font file name without extensions.
Together with vale and extension given by default description,
font file names are formed.
For example, if <CODE>mincho</CODE> is given for the <CODE>font-name</CODE> capability and
<CODE>(".vf")</CODE> is given for the <CODE>filename-extensions</CODE> capability, then
font files <CODE>mincho.vf1</CODE> and <CODE>mincho.vf2</CODE> are used.

example: <CODE>(font-name "mincho")</CODE>

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>writing-direction</CODE> (optional)
<DD>
<DT><CODE>vector-to-bbx-upper-left</CODE> (optional)
<DD>
example: <CODE>(vector-to-bbx-upper-left 0 0.86)</CODE>

<DT><CODE>vector-to-next-ref-point</CODE> (optional)
<DD>
example: <CODE>(vector-to-next-ref-point 1.0 0.0)</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC63" HREF="VFlib-36_toc.html#TOC63">JG font class</A></H2>
<P>
<A NAME="IDX74"></A>


<P>
JG font format is a vector font format for Japanese character sets
JIS X 0208. JG font driver is based on the work by Hideo Morishita.
<BR>


<P>
<B>Font class name:</B> <CODE>jg</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>filename-extensions</CODE> (optional)
<DD>
--- Three files form a font for this font class, e.g., <CODE>mincho.fn0</CODE>,
<CODE>mincho.fn1</CODE>, and <CODE>mincho.fn2</CODE>. 
Extension candidates without digit must be 
the value for this capability.  

example: <CODE>(filename-extensions ".fn" ".FN")</CODE>
</DL>

<P>
(Other capabilities are the same as <CODE>zeit</CODE> font class.)


<P>
<B>Capability for font definition:</B>


<P>
Capabilities are the same as <CODE>zeit</CODE> font class.




<H2><A NAME="SEC64" HREF="VFlib-36_toc.html#TOC64">eKanji font class</A></H2>
<P>
<A NAME="IDX75"></A>


<P>
The eKanji font format is a bitmap font format for Kanji characters.
The first character in an eKanji font file has code point 1, and
the second character has code point 2.
That is, characters in an eKanji font are numbered sequentially 
starting from 1.
(This encoding scheme can be changed by setting some capabilities.)


<P>
eKanji font files are distributed at the following URL:
<A HREF="http://www.zinbun.kyoto-u.ac.jp/~ekanji/">http://www.zinbun.kyoto-u.ac.jp/~ekanji/</A>
The distribution package contains the following font files.



<UL>

<LI>Unicode (<TT>`ekan0010.d24'</TT>)

<A NAME="IDX76"></A>

<LI>Kyoto University KangXi (<TT>`ekan0020.d24'</TT>)

<A NAME="IDX77"></A>

<LI>Morohashi DaiKanwa (<TT>`ekan0030.d24'</TT>)

<A NAME="IDX78"></A>

<LI>JIS X 0208 (<TT>`jisx9052.d24'</TT>)

</UL>

<P>
<B>Font class name:</B> <CODE>ekanji</CODE>


<P>
<B>Capabilities for font class default:</B>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
<DT><CODE>font-dot-size</CODE> (optional)
<DD>
--- Dot size of characters in the font file.
Default value is 24.

example: <CODE>(font-dot-size 24)</CODE>

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>writing-direction</CODE> (optional)
<DD>
--- Default writing direction. 
<CODE>Horizontal</CODE> or <CODE>vertical</CODE>; default is <CODE>Horizontal</CODE>. 
This is the same as 
<CODE>(vector-to-bbx-upper-left 0.0 0.92)</CODE>
and <CODE>(vector-to-next-ref-point 1.0 0.0)</CODE> if value of this
capability is "Horizontal". 
Otherwise, it is the same as
<CODE>(vector-to-bbx-upper-left -0.5 0.0)</CODE>
and <CODE>(vector-to-next-ref-point 0.0 -1.0)</CODE>.

<DT><CODE>vector-to-bbx-upper-left</CODE> (optional)
<DD>
--- Default value of a vector from the reference point of a character to
upper-left bounding box. Right and up are positive directions.

example: <CODE>(vector-to-bbx-upper-left 0 0.90)</CODE>

<DT><CODE>vector-to-next-ref-point</CODE> (optional)
<DD>
--- Default value of a vector from the reference
point to next reference point. 

example: <CODE>(vector-to-next-ref-point 1.0 0.0)</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>
<P>
<BR>


<P>
<B>Capability for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 

<DT><CODE>font-name</CODE> (optional)
<DD>
--- Font file name with extension.

<DT><CODE>font-dot-size</CODE> (optional)
<DD>
--- Dot size of characters in the font file.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>dpi-x</CODE> (optional)
<DD>
<DT><CODE>dpi-y</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>character-set</CODE> (optional)
<DD>
<DT><CODE>encoding</CODE> (optional)
<DD>
<DT><CODE>font-character-set</CODE> (optional)
<DD>
<DT><CODE>font-encoding</CODE> (optional)
<DD>
--- Select code conversion.
If you want to access a eKanji font by ISO-2022 (JIS) encoding scheme, define 
<CODE>eKanji</CODE> for <CODE>character-set</CODE>, 
<CODE>ISO2022</CODE> for <CODE>encoding</CODE>,
<CODE>eKanji</CODE> for <CODE>font-character-set</CODE>, and
<CODE>SEQUENTIAL2-1</CODE> for <CODE>encoding</CODE>.
Then the first character in the eKanji font is accessed by code point 0x2121.

<DT><CODE>mock-font-encoding</CODE> (optional)
<DD>
--- By this capability, encoding of an eKanji font file is virtually changed.
This capability requires an argument and parameter.
There are three keywords for an argument:


<UL>

<LI><CODE>raw</CODE>

No effect, i.e., font encoding is not changed.

<LI><CODE>subblocks-94x94</CODE> <VAR>B</VAR>

An eKanji font file is virtually divided by 94x94 sub blocks 
(blocks of 94x94 = 8836 characters)
and selects <VAR>B</VAR>-th block for this font definition. 
This implies that an eKanji font file with this capability offers only
8836 (= 94x94) characters among all the characters of an eKanji font file.
The first sub block is numbered zero. 
(A font with <VAR>B</VAR> = 0 for this capability selects the first sub block.)

Characters with character code from <EM>8836*B+1</EM> to <EM>8836*B+8836</EM>
in an eKanji font file is accessed by character code 
from 0x2121 to 0x7e7e.

<LI><CODE>subblocks-94x60</CODE> <VAR>B</VAR>

This is similar to the case for <CODE>subblocks-94x60</CODE>.
An eKanji font file is virtually divided by 94x60 sub blocks 
(blocks of 94x60 = 5640 characters)
and selects <VAR>B</VAR>-th block for this font definition. 
The first sub block is numbered zero. 

Characters with character code from <EM>5640*B+1</EM> to <EM>5640*B+5640</EM>
in an eKanji font file is accessed by character code 
from 0x3021 to 0x4e7e (first 30 rows) and 
from 0x5021 to 0x6e7e (another 30 rows).
(This division scheme is the same as Mojikyo scheme.)

<LI><CODE>with-offset</CODE> <VAR>OFFS</VAR>

An offset value <VAR>OFFS</VAR> is added to obtain 
character code of a character in an eKanji font file.
When <VAR>OFFS</VAR> is <CODE>-0x4dff</CODE>, 
the first character in an eKanji font file is accessed by
code number 0x4e00, since <EM>0x4e00 + (-0x4dff) = 1</EM>.

</UL>

Theoretically, the same functionality shown above can be implemented within 
the CCV subsystem framework section <A HREF="VFlib-36.html#SEC78">Code conversion system</A>,
the eKanji font driver defines this capability, 
since the eKanji font file format adopts curious character encoding scheme
and it seems to be simpler and cleaner to define this capability.

<DT><CODE>writing-direction</CODE> (optional)
<DD>
<DT><CODE>vector-to-bbx-upper-left</CODE> (optional)
<DD>
example: <CODE>(vector-to-bbx-upper-left 0 0.86)</CODE>

<DT><CODE>vector-to-next-ref-point</CODE> (optional)
<DD>
example: <CODE>(vector-to-next-ref-point 1.0 0.0)</CODE>

<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC65" HREF="VFlib-36_toc.html#TOC65">TeX default and TeX font mapping font class</A></H2>
<P>
<A NAME="IDX79"></A>


<P>
This is a special font class to define common default values 
of TeX-related font classes.


<P>
This font class has a feature to map a requested font to another font. 
Thus, this class is also called 
<I>"TeX font mapping class"</I> or <I>"TeX font mapper"</I>.
TeX-related font classes include the followings:
GF, PK, TFM, VF, ASCII Japanese TeX.


<P>
This font class supports only implicit fonts and
explicit fonts is not supported. 
Therefore, the driver name of this font class must be given in 
<CODE>extension-hints</CODE> and/or <CODE>implicit-font-classes</CODE> capabilities
in the <CODE>VFlib</CODE> default description 
if you want to use the font mapping feature of this class.


<P>
Mapped font is recursively (recursively) requested to open and
any operations such as obtaining bitmaps on the requested font are
applied on the mapped font.
<BR>


<P>
<B>Font class name:</B> <CODE>TeX</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>dpi</CODE> (optional)
<DD>
--- Default device resolution for TeX-related fonts.

<DT><CODE>tfm-directories</CODE> (optional)
<DD>
--- A list of  directories of TFM files. 
Directories listed by this capability is used for searching TFM files.
If a directory name is <CODE>TEXMF</CODE>, kpathsea is invoked to
search a file.

example: <CODE>(tfm-directories "TEXMF" "/usr/local/share/font/tfm//")</CODE>

<DT><CODE>tfm-filename-extensions</CODE> (optional)
<DD>
--- A list of extensions of filenames for TFM files.
This is used to construct a TFM file name, e.g., "cmr10.tfm"
for a font "cmr10".

example: <CODE>(tfm-filename-extensions "tfm")</CODE>

<DT><CODE>font-mapping</CODE> (optional)
<DD>
--- Font mapping rules are described in this capability.
When a font is requested to open (as an implicit font),
the font name is mapped to another name and specified 
font driver is requested to open the mapped font.

Syntax of this capability is as follows:

<PRE>
(font-mapping
  ((<VAR>DRIVER-NAME</VAR> <VAR>MAPPING-FORMAT</VAR> <VAR>FONT-OPEN-OPTIONS</VAR>) ... 
   <VAR>FONT-NAME</VAR> <VAR>FONT-NAME</VAR> ...)
  ((<VAR>DRIVER-NAME</VAR> <VAR>MAPPING-FORMAT</VAR> <VAR>FONT-OPEN-OPTIONS</VAR>) ... 
   <VAR>FONT-NAME</VAR> <VAR>FONT-NAME</VAR> ...)
  ...) 
</PRE>

Thus, value for this capability is a sequence of items 
<CODE>((<VAR>DRIVER-NAME</VAR> <VAR>MAPPING-FORMAT</VAR> <VAR>FONT-OPEN-OPTIONS</VAR>) ... 
 <VAR>FONT-NAME</VAR> <VAR>FONT-NAME</VAR> ...)</CODE>, and this forms a mapping rule.
<VAR>FONT-NAME</VAR> is a font name and this rule applies if
requested font name matches <VAR>FONT-NAME</VAR>.
(<VAR>FONT-NAME</VAR> is a name without directory and extension parts.
A font name requested to open is compared with <VAR>FONT-NAME</VAR>
by deleting directory and extension parts.)
If <VAR>FONT-NAME</VAR> contains <CODE>*</CODE> character,
it matches to the rest of requested font name.
For example, <CODE>cm*</CODE> matches <CODE>cmr10</CODE> and <CODE>cmbx10</CODE>.
Thus, in case <VAR>FONT-NAME</VAR> is <CODE>*</CODE>, all fonts matches and thus all fonts
applies the rule.

The font name is mapped according to the format <VAR>MAPPING-FORMAT</VAR> and 
mapped name is opened by calling a font driver <VAR>DRIVER-NAME</VAR>.
<CODE>VF_OpenFont1()</CODE> and <CODE>VF_OpenFont2()</CODE> are not used.
(As a special case, when <VAR>DRIVER-NAME</VAR> is <CODE>*</CODE>,
<CODE>VF_OpenFont1()</CODE> or <CODE>VF_OpenFont2()</CODE> is used to open 
a mapped font.)

The syntax of <VAR>MAPPING-FORMAT</VAR> is similar to a format string of 
<CODE>printf()</CODE> function in C library, 
but conversion characters and semantics are different.
Conversion specification is introduced by <CODE>%</CODE> character.
Non-conversion characters are simply copied and 
conversion specifications are substituted for the following:

<DL COMPACT>

<DT><CODE>%%</CODE>
<DD>
 <CODE>%</CODE> character
<DT><CODE>%f</CODE>
<DD>
 the requested font name without extension and directory parts.
<DT><CODE>%d</CODE>
<DD>
 font file resolution part in the extension of the requested font name
<DT><CODE>%e</CODE>
<DD>
 file format part in the extension of the requested font name
</DL>
For instance, let <CODE>/foo/bar/qwe.300pk</CODE> is the requested font name.
Then <CODE>%f</CODE> is <CODE>qwe</CODE>, <CODE>%d</CODE> is <CODE>300</CODE>, 
and <CODE>%e</CODE> is <CODE>pk</CODE>.
A conversion specification will be null string if 
corresponding substring does not exist. 

In general, mapped fonts are opened with the same parameters 
(device resolution, magnification factors, point or pixel size)
of the requested font.
Such parameters can be changed by optional <VAR>FONT-OPEN-OPTIONS</VAR> part.
Following descriptions can be used for <VAR>FONT-OPEN-OPTIONS</VAR>:

We can specify multiple 
<CODE>(<VAR>DRIVER-NAME</VAR> <VAR>MAPPING-FORMAT</VAR> <VAR>FONT-OPEN-OPTIONS</VAR>)</CODE>
in a rule description.
This is useful if we need to write multiple mapping rules 
for the same set of fonts.

A font is opened by the following way.

<OL>
<LI>

For each rule (from the first one to the last one),
the requested font name is checked if the rule applies to the font.
If the rule does not apply, check next rule.

<LI>

For each (<VAR>DRIVER-NAME</VAR> <VAR>MAPPING-FORMAT</VAR> <VAR>FONT-OPEN-OPTIONS</VAR>)
in the rule, the requested font is mapped and font open is attempted.
If a mapped font is is successfully opened, it is used as a requested font.
Otherwise, next mapping 
(<VAR>DRIVER-NAME</VAR> <VAR>MAPPING-FORMAT</VAR> <VAR>FONT-OPEN-OPTIONS</VAR>)
is attempted.  This is repeated for a mapped font is opened.

<LI>

If mapped fonts are not opened, next rule is checked.
This is repeated for all rules until a mapped font is opened.

</OL>

example:

<PRE>
(font-mapping
 ((ascii-jtex-kanji "%f.jtex")  
  "min*" "goth*" "tmin*" "tgoth*")
 ((type1 "%f.pfb" point-size-from-tfm (magnification-adjustment 1.0)) 
  *)
 ((pk "%f.%dpk") (gf "%f.%dgf") (tfm "%f.tfm")
  *))
</PRE>

For this example, suppose that <CODE>min10.300pk</CODE> is requested to open.


<OL>

<LI>

The first rule applies to the requested font since <CODE>min*</CODE> is in the
font list.
The <CODE>ascii-jtex-kanji</CODE> driver is invoked to open a mapped name 
<CODE>min10.jtex</CODE>.  If it is opened, font open succeeds;
<CODE>min10.jtex</CODE> is used as <CODE>min10.300pk</CODE> and font open finishes.
If the font is not opened, continue to the next step.

<LI>

The second rule applies to the requested font since <CODE>*</CODE> is given in 
the font list.
The <CODE>type1</CODE> driver is invoked to open a mapped name <CODE>min10.pfb</CODE>.
If it is opened, <CODE>min10.jtex</CODE> is used as <CODE>min10.300pk</CODE> 
and font open finishes.
If the font is not opened, continue to the next step.

<LI>

The second rule applies to the reqiested font since <CODE>*</CODE> is given in 
the font list.

<OL>
<LI>

The <CODE>pk</CODE> driver is invoked to open a mapped name <CODE>min10.300pk</CODE>.
If it is not opened, next mapping is attempted.
<LI>

The <CODE>gf</CODE> driver is invoked to open a mapped name <CODE>min10.300gf</CODE>.
If it is not opened, next mapping is attempted.
<LI>

The <CODE>tfm</CODE> driver is invoked to open a mapped name <CODE>min10.tfm</CODE>.
</OL>

</OL>

If everything above fails, font open for <CODE>cmr10.300pk</CODE> fails.


<UL>
<LI><CODE>point-size-from-tfm</CODE> (optional)

--- When a mapped font is opened (in mode 1, high resolution oriented mode),
point size which is obtained from a TFM file is given.
This is necessary when we use TrueType and/or Type1 fonts for mapped fonts.
For example, "cmr10.ttf" and "cmr10.pfb" in the BaKoMa font set do not 
have point size information,
since TrueType and Type1 format fonts cannot have information on point size.

<LI><CODE>(magnification-adjustment <VAR>mag</VAR>)</CODE> (optional)

--- Mapped fonts are opened with magnification factors magnified 
by <VAR>mag</VAR>.  This can be used to adjust size of mapped fonts.
But most of the case, this is not necessary.

</UL>

As a restriction of fonts of this class,
each font must have a TFM file.

<DT><CODE>resolution-accuracy</CODE> (optional)
<DD>
<DT><CODE>resolution-corrections</CODE> (optional)
<DD>
--- According to arithmetic errors, DPI value for font files and
computed value (= device resolution times magnification value)
may be different. 
These two capabilities give correct resolution values for PK and GF fonts.

Syntax of these capabilities are as follows:

<PRE>
(resolution-accuracy <VAR>ACCURACY</VAR>)
(resolution-corrections
  (<VAR>DEVICE-RESOLUTION</VAR> <VAR>FONT-RESOLION</VAR> <VAR>FONT-RESOLION</VAR> ... )
  (<VAR>DEVICE-RESOLUTION</VAR> <VAR>FONT-RESOLION</VAR> <VAR>FONT-RESOLION</VAR> ... )
   ...)
</PRE>

<VAR>DEVICE-RESOLUTION</VAR> is the resolution of target device in DPI
and <VAR>FONT-RESOLUTION</VAR> is a font resolution value.

To find a font file, font resolution is computed by
device resolution times magnification factor.
Then, this driver finds a list 
<CODE>(<VAR>DEVICE-RESOLUTION</VAR> <VAR>FONT-RESOLUTION</VAR> 
<VAR>FONT-RESOLUTION</VAR> ... )</CODE>
such that <VAR>DEVICE-RESOLUTION</VAR> is the same as resolution of target device.
(If there is no such list is the capability value, 
font file resolution is not corrected and computed value is used.)

For each <VAR>FONT-RESOLUTION</VAR> in the list, the driver checks 
if the computed font file resolution is in the range
from <VAR>FONT-RESOLUTION</VAR> times (1-<VAR>ACCURACY</VAR>)
to   <VAR>FONT-RESOLUTION</VAR> times (1+<VAR>ACCURACY</VAR>).
If the computed resolution is in the range, 
font file resolution is changed to <VAR>FONT-RESOLUTION</VAR>.
Then, a font file is searched by the corrected font file resolution.

example:

<PRE>
(resolution-accuracy 0.02)
(resolution-corrections
 (300  ;; cx
  300  329  360  432  518  622  746  896 1075 1290  240 270)
 (600  ;; ljfour
  600  657  720  864 1037 1244 1493 1792 2150 2580  480 540))
</PRE>

Be careful not to map to the same name!
Otherwise, font open will be an infinite loop.
(VFlib restricts the depth of nested font open.
Even if the font name is mapped to the same name, 
VFlib will detects an error, anyway.)

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC66" HREF="VFlib-36_toc.html#TOC66">PK font class</A></H2>
<P>
<A NAME="IDX80"></A>


<P>
PK fonts are bitmap fonts used by TeX system.
PK font driver provides a logical view of PK fonts when a
font is requested to open as an implicit font;
if a given font filename is <CODE>cmr10.pk</CODE>,
requested device resolution is 300 and magnification is 1.2,
then PK font driver looks for a font file <CODE>cmr10.360pk</CODE>.
Thus, font names (for font open) should not be the same as 
font filenames on filesystems.


<P>
To search a font file, the kpathsea library can be used.
A special name <CODE>TEXMF</CODE> in a list of font directories 
(capability <CODE>font-directories</CODE>) is used to search 
a file by kpathsea.


<P>
To enable kpathsea, the value for <CODE>use-kpathsea</CODE> capability
in <CODE>VFlib</CODE> class default must be <CODE>"Yes"</CODE>.


<P>
This font class supports compressed font files and implicit fonts.
<BR>


<P>
<B>Font class name:</B> <CODE>pk</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
--- A list of directory names for font files.
This driver supports font file search by kpathsea.
To search a font file by kpathsea,
use <CODE>TEXMF</CODE> for a directory name.

<DT><CODE>filename-extensions</CODE> (optional)
<DD>
--- A list of extensions of filenames for PK fonts.
This is used to construct a font file name "cmr10.300pk"
from "cmr10.pk" for 300 dpi fonts.

example: <CODE>(filename-extensions "pk")</CODE>

<DT><CODE>make-missing-glyph</CODE> (optional)
<DD>
--- Generate a PK font file from Metafont source file by running METAFONT
    on the fly, if a requested PK font file does not exist.
example: <CODE>(make-missing-glyphs "yes")</CODE>

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>
<P>
<BR>


<P>
<B>Capabilities for font definition:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 

<DT><CODE>font-file</CODE> (optional)
<DD>
--- a font filename.  An extension (e.g., <CODE>.300pk</CODE>) can be omitted.
In case of this capability is not given, 
font name is used as this capability value.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC67" HREF="VFlib-36_toc.html#TOC67">GF font class</A></H2>
<P>
<A NAME="IDX81"></A>
<BR>


<P>
<B>Font class name:</B> <CODE>gf</CODE>
<BR>


<P>
Other capabilities are the same as ones for <CODE>pk</CODE> font class.




<H2><A NAME="SEC68" HREF="VFlib-36_toc.html#TOC68">TFM font class</A></H2>
<P>
<A NAME="IDX82"></A>


<P>
TFM files contains only metric information for typesetting TeX documents.
This font class provides fonts whose metrics are defined by TFM font files.
Since TFM files do not have glyph,
glyph of a font of this font class are (black or white) rectangles.
Fonts of this font class can be used as substitutes of PK, GF, or VF files
in case they are missing.


<P>
If the file is not found, it is searched by <CODE>font-directories</CODE>
capability given in <CODE>TFM</CODE> font class default description.
Note that the extension of font files (given by the 
<CODE>filename-extensions</CODE> capability) has no effect 
for searching by kpathsea library.
The extension of font files must be ".tfm". 
See kpathsea manual for detail.


<P>
This font class supports compressed font files and implicit fonts.
<BR>


<P>
<B>Font class name:</B> <CODE>tfm</CODE>
<BR>


<P>
<B>Capabilities for font class default:</B>
<BR>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
--- A list of directory names for font files.
This driver supports font file search by kpathsea.
To search a font file by kpathsea,
use <CODE>TEXMF</CODE> for a directory name.

<DT><CODE>filename-extensions</CODE> (optional)
<DD>
<DT><CODE>glyph-style</CODE> (optional)
<DD>
--- Defines default glyph style: <CODE>empty</CODE> or <CODE>fill</CODE>.
If <CODE>empty</CODE> is given, all glyph of a font are white rectangles.
If <CODE>fill</CODE> is given, all glyph of a font are black rectangles.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>

<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
 -- A font class name. 

<DT><CODE>font-file</CODE> (optional)
<DD>
<DT><CODE>glyph-style</CODE> (optional)
<DD>
--- Defines glyph style: <CODE>empty</CODE> or <CODE>fill</CODE>.
If <CODE>empty</CODE> is given, all glyph of a font are white rectangles.
If <CODE>fill</CODE> is given, all glyph of a font are black rectangles.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>aspect-ratio</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC69" HREF="VFlib-36_toc.html#TOC69">VF font class</A></H2>
<P>
<A NAME="IDX83"></A>


<P>
This font class handles <I>Virtual Font</I> files.
A virtual font consists of a font program and subfonts.
A font program in a vf file is similar to DVI file formats.
Glyph of a virtual font are constructed from a box instruction
in a font program and glyph taken from subfonts.
Therefore, this font class requires a font mapping rule to obtain
glyph from subfonts.
You can specify VFlib not to open subfonts of a virtual font
in case of subfonts are unavailable.


<P>
<B>Font class name:</B> <CODE>vf</CODE>


<P>
<B>Capabilities for font class default:</B>


<DL COMPACT>

<DT><CODE>font-directories</CODE> (optional)
<DD>
--- A list of directory names for font files.
This driver supports font file search by kpathsea library.
To search a font file by kpathsea library,
use <CODE>TEXMF</CODE> for a directory name.

<DT><CODE>filename-extensions</CODE> (optional)
<DD>
--- A extension string for virtual font files.

example: <CODE>(filename-extensions "vf")</CODE>

<DT><CODE>tfm-directories</CODE> (optional)
<DD>
<DT><CODE>tfm-filename-extensions</CODE> (optional)
<DD>
<DT><CODE>font-mapping</CODE> (optional)
<DD>
--- A set of rules for mapping for subfonts to open as an VFlib fonts. 
This is the same as TeX font mapper, i.e.,
<CODE>font-mapping</CODE> capability for <CODE>TeX</CODE> font class 
default description.

Be careful not to map to the same name!
Otherwise, font open will be an infinite loop.
(VFlib restricts the depth of nested font open.
Even if the font name is mapped to the same name, 
VFlib will detects an error, anyway.)

<DT><CODE>open-style</CODE> (optional)
<DD>
--- This capability specifies how subfonts are opened.
<DL COMPACT>

<DT><CODE>none</CODE>
<DD>
--- Boxes are used instead of glyph of subfonts.
Subfonts are not opened.
<DT><CODE>try</CODE>
<DD>
--- The virtual font driver tries to open each subfont.
If subfonts are opened, glyph are taken from opened subfonts.
If some subfonts are not opened, boxes are used instead of glyph of 
such subfonts.  
It is not an error even if all subfonts are not opened.
<DT><CODE>require</CODE>
<DD>
--- The virtual font driver tries to open each subfont.
It is an error if every subfont is not opened.

</DL>

<DT><CODE>glyph-style</CODE> (optional)
<DD>
--- In case boxes are used instead of glyph of subfonts,
this capability controls the looks of boxes.
<DL COMPACT>

<DT><CODE>empty</CODE>
<DD>
--- Boxes are white, i.e., all pixels are value 0.
<DT><CODE>fill</CODE>
<DD>
--- Boxes are black, i.e., all pixels are value 1.
</DL>

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variables</CODE> (optional)
<DD>
<DT><CODE>debug</CODE> (optional)
<DD>
</DL>

<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-file</CODE> (optional)
<DD>
--- File name of a virtual font.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC70" HREF="VFlib-36_toc.html#TOC70">ASCII Japanese TeX Kanji font class</A></H2>
<P>
<A NAME="IDX84"></A>


<P>
This is for <I>Kanji</I> fonts of Japanese TeX localized by ASCII Co.
This font driver provides <I>Kanji</I> fonts that can be accessed
as if they were PK fonts by using another VFlib font.
Font metrics of <I>Kanji</I> characters defined by ASCII jTeX 
may not match that of a <I>Kanji</I> font to be used.
This case happens when <CODE>jiskan24.pcf</CODE> font is used 
as a Japanese <I>Kanji</I> font for TeX.
This font driver works as a <EM>filter</EM> that 
modifies font metrics of another font.
Change of font metrics is defined by an external file
called <CODE>adjustment file</CODE>.
See sample distribution of adjustment files for their syntax.
(Not documented now...)


<P>
Font metrics of a font of this class is defined by a TFM font;
a vector to the next reference point is taken from a TFM file.
A vector to upper left corner of a bitmap is taken from subfont.
Then, font metrics is modified according to an adjustment file.


<P>
This driver supports vertical writing. 
In case fonts for vertical writing are not available,
the driver rotates glyph of some characters, e,g, parenthesis,
to yield (possible) correct glyph.


<P>
<B>Font class name:</B> <CODE>ascii-jtex</CODE>


<P>
<B>Capabilities for font class default:</B>


<DL COMPACT>

<DT><CODE>implicit-font-mapping-suffix</CODE> (optional)
<DD>
--- A suffix to map a font name for searching an implicit font.
Suppose a font is requested to open. 
Then, font name is mapped in such a way that 
extension is deleted and the suffix given by this 
capability is added. Then, an vflibcap entry of the mapped name
is searched. If such an entry exists, it is used for the implicit font
and the font is opened as if it were an explicit font.
(Note that a font of the mapped name must exist as an explicit font, 
not as an implicit font.)

Suppose <CODE>min10.400pk</CODE> is requested to open as an implicit font and
the value of this capability is <CODE>.jtex</CODE>.
Then mapped name is <CODE>min10.jtex</CODE> and it is opened by this font
driver internally. 

example: <CODE>(implicit-font-mapping-suffix ".jtex")</CODE>

<DT><CODE>tfm-directories</CODE> (optional)
<DD>
<DT><CODE>tfm-filename-extensions</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>

<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 

<DT><CODE>kanji-font</CODE> (optional)
<DD>
--- Font name for a subfont.

<DT><CODE>kanji-font-point-size</CODE> (optional)
<DD>
--- Default point size of subfont.
If point size is not explicitly given when a font is opened,
This value is used. 
  
<DT><CODE>kanji-font-pixel-size</CODE> (optional)
<DD>
--- Default pixel size of a subfont.
If pixel size is not explicitly given when a font is opened,
This value is used. 

<DT><CODE>kanji-font-magnification</CODE> (optional)
<DD>
--- magnification factor for subfont.

<DT><CODE>tfm-file</CODE> (optional)
<DD>
--- TFM file that defines font metrics of a font.

example: <CODE>(tfm-file "min10.tfm")</CODE>
 
<DT><CODE>metric-adjustment-file</CODE> (optional)
<DD>
--- a file name for font metric adjustment file.

<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC71" HREF="VFlib-36_toc.html#TOC71">Japanese comic font class</A></H2>
<P>
<A NAME="IDX85"></A>


<P>
This font driver composes two Japanese <I>Kanji</I> fonts.
According to code point (<I>Kana</I> or <I>kanji</I> character),
one of two font is selected to obtain a bitmap or metric.
This font class provides Japanese fonts
that composes <I>Kana</I> and <I>Kanji</I> font. 


<P>
<B>Font class name:</B> <CODE>japanese-comic</CODE>


<P>
<B>Capabilities for font class default:</B>


<DL COMPACT>

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>

<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 

<DT><CODE>kanji-font</CODE> (optional)
<DD>
--- A VFlib font name for Kanji characters.
For code points for Kanji characters,
this font is used to obtain bitmaps and metrics.

<DT><CODE>kana-font</CODE> (optional)
<DD>
--- A VFlib font name for Kana font
(code point: 0x2121 ... 0x287f).
For code points except Kanji characters,
this font is used to obtain bitmaps and metrics.

<DT><CODE>symbol-font</CODE> (optional)
<DD>
--- A VFlib font name for symbol characters
(code point: 0x2121 ... 0x227f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for symbol characters.

<DT><CODE>alpha-numeric-font</CODE> (optional)
<DD>
--- A VFlib font name for alphabet and numeric characters
(code point: 0x2321 ... 0x237f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for alphabet and numeric characters.

<DT><CODE>hirakana-font</CODE> (optional)
<DD>
--- A VFlib font name for Hirakana characters
(code point: 0x2421 ... 0x247f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for Hirakana characters.

<DT><CODE>katakana-font</CODE> (optional)
<DD>
--- A VFlib font name for Katakana characters
(code point: 0x2521 ... 0x257f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for Katakana characters.

<DT><CODE>greek-font</CODE> (optional)
<DD>
--- A VFlib font name for Greek characters
(code point: 0x2621 ... 0x267f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for Greek characters.

<DT><CODE>cyrillic-font</CODE> (optional)
<DD>
--- A VFlib font name for Cyrillic characters
(code point: 0x2721 ... 0x277f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for Cyrillic characters.

<DT><CODE>keisen-font</CODE> (optional)
<DD>
--- A VFlib font name for Keisen characters
(code point: 0x2821 ... 0x287f).
If this capability is not given, a font given by <CODE>kana-font</CODE> is used
for Keisen characters.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC72" HREF="VFlib-36_toc.html#TOC72">Try font class</A></H2>
<P>
<A NAME="IDX86"></A>


<P>
A font of this font class has a list of <EM>sub-fonts</EM>.
When a font of this class is requested open, 
the try font driver tries to open the sub-fonts one after another until
one of them is successfully opened.
If all sub-fonts in the list are not opened, the font is failed to be opened.
All font operation of the font is applied to an opened sub-font.


<P>
<B>Font class name:</B> <CODE>try</CODE>


<P>
<B>Capabilities for font class default:</B>


<DL COMPACT>

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>

<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 
This must be <CODE>try</CODE>.

<DT><CODE>font-list</CODE> (optional)
<DD>
--- A list of sub-fonts.  
These fonts are VFlib fonts, not a font file names.

<DT><CODE>point-size</CODE> (optional)
<DD>
<DT><CODE>pixel-size</CODE> (optional)
<DD>
<DT><CODE>dpi</CODE> (optional)
<DD>
<DT><CODE>magnification</CODE> (optional)
<DD>
<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC73" HREF="VFlib-36_toc.html#TOC73">Mojikyo font mapping class</A></H2>
<P>
<A NAME="IDX87"></A>


<P>
This font driver is specific to the Mojikyo font files, which 
is a huge collection (more than 80 thousand) of Kanji characters.
(Access <A HREF="http://www.mojikyo.gr.jp/">http://www.mojikyo.gr.jp/</A> for detail.)
The Mojikyo font is supplied by a set of font files,
since the number of characters is too huge to contain
in a single font file.


<P>
The Mojikyo font defines its own character encoding, staring from 1
and each character has its own character code.
(Character codes are not the codes in a font file.)
The Mojikyo font set is supplied by both TrueType and Type 1 formats.
A single character space of the Mojikyo is
divided into font file number and character code in a font file.
This means that we must compute font file among many font files
and code point in a font file to obtain a glyph of Mojikyo characters.
To avoid such complex procedure, this font driver provides
a virtual single font. 


<P>
Note that this font driver only delegates requested characters to
other font driver (TrueType or Type 1).
Therefore, TrueType and/or Type 1 font driver must be configured in VFlib
and they must be propopery set up in a vflibcap file.


<P>
<B>Font class name:</B> <CODE>mojikyo-mapper</CODE>


<P>
<B>Capabilities for font class default:</B>


<DL COMPACT>

<DT><CODE>properties</CODE> (optional)
<DD>
<DT><CODE>variable-values</CODE> (optional)
<DD>
</DL>

<P>
<B>Capabilities for font definition:</B>


<DL COMPACT>

<DT><CODE>font-class</CODE> (essential)
<DD>
--- A font class name. 
This must be <CODE>mojikyo-mapper</CODE>.

<DT><CODE>division-scheme</CODE> (optional)
<DD>
Mapping scheme from the Mojikyo character space to real font files
is different by real font file format (TrueType/Type1).
This capability defines which mapping scheme is used.

If <CODE>truetype</CODE> is given for this capability,
underlaying font files are in TrueType format.
If <CODE>type1</CODE> is given for this capability,
underlaying font files are in Type 1 format.
Default value for this capability is <CODE>truetype</CODE>.

Aliases of division scheme names are defined as follows:
<CODE>ttf</CODE> is an alias of <CODE>truetype</CODE>, and
<CODE>pfb</CODE> is an alias of <CODE>type1</CODE>.

<DT><CODE>subfont-name-format</CODE> (optional)
<DD>
This capability defines format of font file names.
If <CODE>truetype</CODE> is selected for <CODE>division-scheme</CODE> capability,
<CODE>Mojik%d.ttf</CODE> is assumed for this capability by default.
<CODE>%d</CODE> in <CODE>Mojik%d.ttf</CODE> is substituted by font number, 
starting from 101.
If <CODE>type1</CODE> is selected for <CODE>division-scheme</CODE> capability,
<CODE>mo%dm%02d.pfb</CODE> is assumed for this capability by default.
The first <CODE>%d</CODE> in <CODE>mo%dm%02d.pfb</CODE> is a major font number,
starting from 101. 
The second <CODE>%d</CODE> in <CODE>mo%dm%02d.pfb</CODE> is a minor font number,
starting from 6.

In case you want to use a font name format other than described above,
this capability should be defined.
Note that format sting should contain exactly one <CODE>%d</CODE> 
if you select <CODE>truetype</CODE> division scheme, 
and exactly two <CODE>%d</CODE>s if you select <CODE>type1</CODE> division scheme. 

<DT><CODE>truetype-subfont-encoding</CODE> (optional)
<DD>
This capability has effect only when <CODE>truetype</CODE> division scheme 
is selected.
This capability selects character encoding scheme of underlaying 
TrueType font files.
If <CODE>unicode</CODE> is given to this capability,
underlaying TrueType fonts are encoded in Unicode.
If <CODE>iso-2022</CODE> (as aliases, <CODE>iso2022</CODE> or <CODE>jis</CODE> can
be used) is given to this capability, underlaying TrueType fonts 
are encoded in ISO 2022 (JIS).

Default value is <CODE>unicode</CODE>, which is the same as the 
the Mojikyo font files in TrueType format.

<DT><CODE>properties</CODE> (optional)
<DD>
</DL>



<H2><A NAME="SEC74" HREF="VFlib-36_toc.html#TOC74">Example vflibcap 1</A></H2>

<P>
This example vflibcap is for general use.



<PRE>
;; -----------------------------------------------------------------
;;   VFlib Default
;; -----------------------------------------------------------------
(define-default  VFlib
  ;; hint to find font class from font name for fast font open
  (extension-hints  (".bdf" bdf) (".pcf" pcf) (".hbf" hbf)
                    (".ttf" truetype) (".ttc" truetype)
                    (".pfa" type1) (".pfb" type1)
                    ("pk" TeX) ("gf" gf) ("tfm" tfm))
  ;; implicit font classes
  (implicit-font-classes  pcf bdf hbf truetype type1 zeit jg gf tfm)

  ;; uncompression programs
  (uncompression-programs  (".Z" "zcat") (".gz" "gzip -cd"))

  ;; a list of default values of variables
  ;; *Note* "variable-values" must come before variable uses
  (variable-values  (TeX_DPI               "300")
                    (TeX_USE_KPATHSEA      "Yes")
                    (TeX_KPATHSEA_MODE     "cx") 
                    (TeX_KPATHSEA_PROGRAM  "/usr/local/bin/xldvi"))

  ;; kpathsea: enabled/disabled 
  (use-kpathsea           $TeX_USE_KPATHSEA)
  ;; kpathsea mode (e.g., "cx")
  (kpathsea-mode          $TeX_KPATHSEA_MODE)
  ;; kpathsea program name (e.g., "/usr/local/bin/xdvi")
  (kpathsea-program-name  $TeX_KPATHSEA_PROGRAM)

  ;; encoding/charset conversion files
  (code-conversion-files  
   "iso8859-1_unicode.ccv" "iso8859-2_unicode.ccv" "iso8859-3_unicode.ccv"
   "iso8859-4_unicode.ccv" "iso8859-5_unicode.ccv" "iso8859-6_unicode.ccv"
   "iso8859-7_unicode.ccv" "iso8859-8_unicode.ccv" "iso8859-9_unicode.ccv"
   "jisx0201_unicode.ccv" "jisx0208_unicode.ccv" "jisx0212_unicode.ccv"
   "ksc5601_unicode.ccv"
   "gb12345_unicode.ccv" "gb2312_unicode.ccv"
   "big5_unicode.ccv" "cns11643_unicode.ccv"
   "iso8859-5_koi8-r.ccv" "koi8-r_iso8859-5.ccv" "koi8-r_unicode.ccv"))

;; -----------------------------------------------------------------
;;   BDF Font Class Default
;; -----------------------------------------------------------------
(define-default  bdf
  ;; font directories
  (font-directories  "/usr/local/share/fonts/X11//")
  ;; extensions of compressed font files that this font class supports
  (compression-extensions ".gz" ".Z")
  ;; default values for fonts of this font class
  (variable-values    (VAR1 ("PROP1" "VAL1"))  ; just for debugging...
                      (VAR2 ("PROP2" "VAL2"))
                      (VARX ("PROPX" "VFlib-VALX")) )
  ;; properties for all fonts of this font class
  (properties ("FONT_CLASS" "BDF")) )

;; -----------------------------------------------------------------
;;   PCF Font Class Default
;; -----------------------------------------------------------------
(define-default  pcf
  ;; font directories
  (font-directories  "/usr/X11R6/lib/X11/fonts//"
                     "/usr/local/X11R6/lib/X11/fonts//"
                     "/usr/openwin/lib/X11/fonts//"
                     "/usr/X386/lib/X11/fonts//"
                     "/usr/XFree86/lib/X11/fonts//"
                     "/usr/X11/lib/X11/fonts//"
                     "/usr/local/lib/X11/fonts//"
                     "/usr/X11R5/lib/X11/fonts//"
                     "/usr/local/X11R5/lib/X11/fonts//"
                     "/usr/local/share/fonts/X11//")
  ;; extensions of compressed font files that this font class supports
  (compression-extensions ".gz" ".Z")
  ;; properties for all fonts of this font class
  (properties ("FONT_CLASS" "PCF"))  )

;; -----------------------------------------------------------------
;;   HBF Font Class Default
;; -----------------------------------------------------------------
(define-default  hbf
  ;; font directories
  (font-directories  "/usr/local/share/fonts/HBF//")
  ;; extensions of compressed font files that this font class supports
  (compression-extensions ".gz" ".Z")
  ;; properties for all fonts of this font class
  (properties ("FONT_CLASS" "HBF"))  )

;; -----------------------------------------------------------------
;; TrueType Font Class Default
;; -----------------------------------------------------------------
(define-default  truetype
  ;; font directories
  (font-directories  "TEXMF"  ; - a special name to search by `kpathsea'
                     "/usr/local/share/fonts/bakoma/ttf/"
                     "/usr/local/share/fonts/FontCity2//"
                     "/usr/local/share/fonts/DynaFont-Premium30/win95//"
                     "/usr/local/share/fonts/DynaFont-SpecialPack1/win95//"
                     "/usr/local/share/fonts/TrueTypeWorld-ValueFont141//"
                     "/usr/local/share/fonts/FontAsia//"
                     "/usr/local/share/fonts/FontGarden/ttf//"  )
  ;; debugging flags   ('*' selects all)
  (debug "")
  ;; properties for all fonts of this font class
  (properties ("FONT_CLASS" "TrueType"))  )
  
;; -----------------------------------------------------------------
;; Type1 Font Class Default
;; -----------------------------------------------------------------
(define-default type1
  ;; font (pfa, pfb) directories
  (font-directories "TEXMF"  ; - a special name to search by `kpathsea'
                    "/usr/local/share/fonts/bakoma/pfb/")
  ;; AFM directories
  (afm-directories "TEXMF"   ; - a special name to search by `kpathsea'
                   "/usr/local/share/fonts/bakoma/afm/")
  ;; T1Lib logfile output level: "none", "error", "warning", "stat", "debug"
  (log-level "none"))

;; -----------------------------------------------------------------
;;   Syotrai Club Font Class Default
;; -----------------------------------------------------------------
(define-default  zeit
  ;; filename extensions ("vf" for "mincho.vf{1,2}")
  (filename-extensions  ".vf")
  ;; font directories
  (font-directories   "/usr/local/share/fonts/Watanabe//"
                      "/usr/local/share/fonts/WadaLab//")
  ;; properties for all fonts of this font class
  (properties  ("FONT_CLASS" "ZEIT")
               ("CHARSET_REGISTRY" "jisx0208.1983")
               ("CHARSET_ENCODING" "0") ))

;; -----------------------------------------------------------------
;;   JG Font Class Default
;; -----------------------------------------------------------------
(define-default  jg
  ;; filename extensions ("fn" for "zkyo0by.fn{0,1,2}")
  (filename-extensions ".fn")
  ;; font directories
  (font-directories  "/usr/local/share/fonts/JG-Fonts//")
  ;; properties for all fonts of this font class
  (properties  ("FONT_CLASS" "JG")
               ("CHARSET_REGISTRY" "jisx0208.1983")
               ("CHARSET_ENCODING" "0")))

;; -----------------------------------------------------------------
;;   TeX-related Font Class Default and TeX Font Mapper
;; -----------------------------------------------------------------
(define-default  TeX
  ;; TFM file directories
  (tfm-directories  "TEXMF"
                    "/usr/local/share/fonts/bakoma/tfm/")
  ;; possible extensions of TFM files
  (tfm-filename-extensions  ".tfm")
  ;; font name mapping rules
  (font-mapping
   ((ascii-jtex-kanji "%f.jtex")  "min*" "goth*" "tmin*" "tgoth*")
   ((type1 "%f.pfb" point-size-from-tfm (magnification-adjustment 1.0)) 
     *)
   ((pk "%f.%dpk") (gf "%f.%dgf")  *)
   ((tfm "%f.%dtfm")  *))
  ;; accuracy of device resolutions, used with 'resolution-corrections'
  (resolution-accuracy 0.02)
  ;; font resolution values for each device resolutions.
  (resolution-corrections
   (240  ;; sparcptr
    240  263  288  312  346  415  498  597)
   (300  ;; cx
    300  329  360  432  518  622  746  896 1075 1290  240 270)
   (400  ;; sparcptr
    400  438  480  576  691  829  995 1194 1433 1720  320 360)
   (600  ;; ljfour
    600  657  720  864 1037 1244 1493 1792 2150 2580  480 540))
  ;; default device resolution
  (dpi $TeX_DPI))

;; -----------------------------------------------------------------
;;   TeX GF Font Class Default
;; -----------------------------------------------------------------
(define-default  gf
  ;; font directories
  (font-directories  "TEXMF" 
                     "/usr/local/TeX/gf//")
  ;; properties for all fonts of this font class
  (properties  ("FONT_CLASS" "GF")) )

;; -----------------------------------------------------------------
;;   TeX PK Font Class Default
;; -----------------------------------------------------------------
(define-default  pk
  ;; font directories
  (font-directories  "TEXMF"
                     "/usr/local/TeX/pk//")
  ;; properties for all fonts of this font class
  (properties  ("FONT_CLASS" "PK")) )

;; -----------------------------------------------------------------
;;   TeX TFM Font Class Default
;; -----------------------------------------------------------------
(define-default  tfm
  ;; font directories
  (font-directories  "TEXMF"
                     "/usr/local/TeX/tfm//")
  ;; glyph style: "fill" (all pixels black) or "empty" (all pixels white)
  (glyph-style  "fill")
  ;; properties for all fonts of this font class
  (properties  ("FONT_CLASS" "TFM")) )

;; -----------------------------------------------------------------
;;   ASCII-jTeX Kanji Font Class Default
;; -----------------------------------------------------------------
(define-default  ascii-jtex-kanji
  ;; TFM file directories
  (tfm-directories  "TEXMF")
  ;; possible extensions of TFM files
  (tfm-filename-extensions ".tfm")
  ;; Suffix for name mapping
  ;; (e.g., implicit font "min10.300pk" is mapped to "min10.jtex")
  (implicit-font-mapping-suffix ".jtex"))

;; -----------------------------------------------------------------
;;   Japanese Comic Font Class Default
;; -----------------------------------------------------------------
(define-default  japanese-comic
  ;; debugging flags   ('*' selects all)
  (debug "f")
  ;; properties for all fonts of this font class
  (properties  ("FONT_CLASS" "JAPANESE-COMIC")
               ("CHARSET_REGISTRY" "jisx0208.1983")
               ("CHARSET_ENCODING" "0")))

;; -----------------------------------------------------------------
;;  sample font definitions for Japanese TeX

(define-font jtex-min    (font-class pcf) (font-file "jiskan24.pcf"))
(define-font jtex-goth   (font-class pcf) (font-file "jiskan24.pcf"))
(define-font jtex-tmin   (font-class pcf) (font-file "jiskan24.pcf"))
(define-font jtex-tgoth  (font-class pcf) (font-file "jiskan24.pcf"))

;; Definitions for "min10" fonts. These fonts are used by
;; 'name mapping' feature of ascii-jtex-kanji driver.
;; (e.g., "min10.400pk" is mapped to "min10.jtex")
(define-macro min-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-min)
  (kanji-font-magnification 0.85) (metric-adjustment-file "jiskan24.adj"))
(define-macro goth-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-goth)
  (kanji-font-magnification 0.85) (metric-adjustment-file "jiskan24.adj"))
(define-macro tmin-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-tmin)  
  (kanji-font-magnification 0.85) 
  (metric-adjustment-file "jiskan24v.adj"))
(define-macro tgoth-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-tgoth)
  (kanji-font-magnification 0.85) 
  (metric-adjustment-file "jiskan24v.adj"))
(define-font min5.jtex     (kanji-font-point-size  5)  min-common)
(define-font min6.jtex     (kanji-font-point-size  6)  min-common)
(define-font min7.jtex     (kanji-font-point-size  7)  min-common)
(define-font min8.jtex     (kanji-font-point-size  8)  min-common)
(define-font min9.jtex     (kanji-font-point-size  9)  min-common)
(define-font min10.jtex    (kanji-font-point-size 10)  min-common)
(define-font goth5.jtex    (kanji-font-point-size  5)  goth-common)
(define-font goth6.jtex    (kanji-font-point-size  6)  goth-common)
(define-font goth7.jtex    (kanji-font-point-size  7)  goth-common)
(define-font goth8.jtex    (kanji-font-point-size  8)  goth-common)
(define-font goth9.jtex    (kanji-font-point-size  9)  goth-common)
(define-font goth10.jtex   (kanji-font-point-size 10)  goth-common)
(define-font tmin5.jtex    (kanji-font-point-size  5)  tmin-common)
(define-font tmin6.jtex    (kanji-font-point-size  6)  tmin-common)
(define-font tmin7.jtex    (kanji-font-point-size  7)  tmin-common)
(define-font tmin8.jtex    (kanji-font-point-size  8)  tmin-common)
(define-font tmin9.jtex    (kanji-font-point-size  9)  tmin-common)
(define-font tmin10.jtex   (kanji-font-point-size 10)  tmin-common)
(define-font tgoth5.jtex   (kanji-font-point-size  5)  tgoth-common)
(define-font tgoth6.jtex   (kanji-font-point-size  6)  tgoth-common)
(define-font tgoth7.jtex   (kanji-font-point-size  7)  tgoth-common)
(define-font tgoth8.jtex   (kanji-font-point-size  8)  tgoth-common)
(define-font tgoth9.jtex   (kanji-font-point-size  9)  tgoth-common)
(define-font tgoth10.jtex  (kanji-font-point-size 10)  tgoth-common)

;; -----------------------------------------------------------------
;; EOF
</PRE>



<H2><A NAME="SEC75" HREF="VFlib-36_toc.html#TOC75">Example vflibcap 2</A></H2>

<P>
This vflibcap file is an example for TeX DVI drivers.
This vflibcap file provides a set of fonts of the form
<CODE><VAR>NAME</VAR>.<VAR>DVI</VAR>pk</CODE> and <CODE><VAR>NAME</VAR>.pk</CODE>.
For example, <CODE>cmr10.300pk</CODE> and <CODE>cmr10.pk</CODE>.


<P>
For Japanese Kanji character fonts 
<CODE>min5</CODE> ... <CODE>min10</CODE>, <CODE>goth5</CODE> ... <CODE>goth10</CODE>, 
<CODE>tmin5</CODE> .. <CODE>tmin10</CODE>, <CODE>tgoth5</CODE> ... <CODE>tgoth10</CODE>, 
X Window PCF format font <CODE>jiskan24.pcf</CODE> is used via
<CODE>ascii-jtex-kanji</CODE> font driver.


<P>
Other fonts are solved in PK and GF format fonts.
If a font is not available in these formats, a TFM font
is used to produce a "black" box.
(TFM files are metrics files and do not conatin glyph. 
But TFM driver in VFlib produces a "box" glyph as it ware font files.)


<P>
Parameters of device resolution and magnification factor for
the function <CODE>VF_OpenFont1()</CODE> determines the font size 
and font metrics to be opened.


<P>
To use VFlib with this vflibcap file, 
I recommend to open font by
<CODE>VF_OpenFont1(<VAR>name</VAR>.pk, <VAR>dpi</VAR>, <VAR>dpi</VAR>, -1, <VAR>mag</VAR>, <VAR>mag</VAR>)</CODE>,
where 
<CODE><VAR>name</VAR>.pk</CODE> is a font name (e.g., <CODE>cmr10.pk</CODE>),
<VAR>dpi</VAR> is the device resolution in dpi (e.g., <CODE>300</CODE>), 
and <VAR>mag</VAR> is the magnification factor (e.g., <CODE>1.2</CODE> for
magstep 1 fonts).



<PRE>
;; -----------------------------------------------------------------
;;   VFlib Default
;; -----------------------------------------------------------------
(define-default VFlib
  (extension-hints  ("pk" TeX))
  (implicit-font-classes)
  (uncompression-programs  (".Z" "zcat") (".gz" "gzip -cd"))
  (variable-values  (TeX_USE_KPATHSEA      "Yes")
                    (TeX_DPI               "300")  ;; or "600"
                    (TeX_KPATHSEA_MODE     "cx")   ;; or "ljfour"
                    (TeX_KPATHSEA_PROGRAM  "/usr/local/bin/xldvi"))
  (use-kpathsea           $TeX_USE_KPATHSEA)
  (kpathsea-mode          $TeX_KPATHSEA_MODE)
  (kpathsea-program-name  $TeX_KPATHSEA_PROGRAM)
  (code-conversion-files  
   "iso8859-1_unicode.ccv" "iso8859-2_unicode.ccv" "iso8859-3_unicode.ccv"
   "iso8859-4_unicode.ccv" "iso8859-5_unicode.ccv" "iso8859-6_unicode.ccv"
   "iso8859-7_unicode.ccv" "iso8859-8_unicode.ccv" "iso8859-9_unicode.ccv"
   "jisx0201_unicode.ccv" "jisx0208_unicode.ccv" "jisx0212_unicode.ccv"
   "ksc5601_unicode.ccv"
   "gb12345_unicode.ccv" "gb2312_unicode.ccv"
   "big5_unicode.ccv" "cns11643_unicode.ccv"
   "iso8859-5_koi8-r.ccv" "koi8-r_iso8859-5.ccv" "koi8-r_unicode.ccv"))

;; -----------------------------------------------------------------
;;   TeX-related Font Class Default and TeX Font Mapper
;; -----------------------------------------------------------------
(define-default  TeX
  (tfm-directories  "TEXMF")
  (tfm-filename-extensions  ".tfm")
  (font-mapping
   ((ascii-jtex-kanji "%f.jtex")  "min*" "goth*" "tmin*" "tgoth*")
   ((pk "%f.%dpk") (gf "%f.%dgf")  *)
   ((tfm "%f.%dtfm") *))
  (resolution-accuracy 0.02)
  (resolution-corrections
   (240  ;; sparcptr
    240  263  288  312  346  415  498  597)
   (300  ;; cx
    300  329  360  432  518  622  746  896 1075 1290  240 270)
   (400  ;; sparcptr
    400  438  480  576  691  829  995 1194 1433 1720  320 360)
   (600  ;; ljfour
    600  657  720  864 1037 1244 1493 1792 2150 2580  480 540))
  (dpi $TeX_DPI))

;; -----------------------------------------------------------------
;;   GF Font Class Default
;; -----------------------------------------------------------------
(define-default gf
  (font-directories  "TEXMF"))

;; -----------------------------------------------------------------
;;   PK Font Class Default
;; -----------------------------------------------------------------
(define-default pk
  (font-directories  "TEXMF"))

;; -----------------------------------------------------------------
;;   VF Font Class Default
;; -----------------------------------------------------------------
(define-default vf
  (font-directories  "TEXMF")
  (font-mapping
   ((type1 "%f.pfb" point-size-from-tfm)  *) )
  (open-style "try")     ;; "none", "try", or "require"
  (glyph-style "fill"))  ;; "fill", or "empty"

;; -----------------------------------------------------------------
;;   TFM Font Class Default
;; -----------------------------------------------------------------
(define-default tfm
  (glyph-style  "fill"))

;; -----------------------------------------------------------------
;;   ASCII-JTeX Kanji fonts
;; -----------------------------------------------------------------
(define-default  ascii-jtex-kanji
  (tfm-directories  "TEXMF")
  (implicit-font-mapping-suffix ".jtex"))

;; -----------------------------------------------------------------
;; Type1 Font Class Default
;; -----------------------------------------------------------------
(define-default type1
  (font-directories  "TEXMF")
  (afm-directories   "TEXMF")
  (log-level "none")
  (dpi $TeX_DPI))

;; -----------------------------------------------------------------
;; TrueType Font Class Default
;; -----------------------------------------------------------------
(define-default truetype
  (font-directories  "TEXMF")
  (platform-id "microsoft")
  (dpi $TeX_DPI))
  
;; -----------------------------------------------------------------
;;   PCF Font Class Default
;; -----------------------------------------------------------------
(define-default  pcf
  (font-directories  "/usr/X11R6/lib/X11/fonts//"
                     "/usr/local/X11R6/lib/X11/fonts//"
                     "/usr/openwin/lib/X11/fonts//"
                     "/usr/X386/lib/X11/fonts//"
                     "/usr/XFree86/lib/X11/fonts//"
                     "/usr/X11/lib/X11/fonts//"
                     "/usr/local/lib/X11/fonts//"
                     "/usr/X11R5/lib/X11/fonts//"
                     "/usr/local/X11R5/lib/X11/fonts//"
                     "/usr/local/share/fonts/X11//")
  (compression-extensions ".gz" ".Z")
  (dpi $TeX_DPI))

;; -----------------------------------------------------------------
;;  Japanese Kanji fonts using standard X11 PCF fonts
(define-font jtex-min    (font-class pcf) (font-file "jiskan24.pcf"))
(define-font jtex-goth   (font-class pcf) (font-file "jiskan24.pcf"))
(define-font jtex-tmin   (font-class pcf) (font-file "jiskan24.pcf"))
(define-font jtex-tgoth  (font-class pcf) (font-file "jiskan24.pcf"))

(define-macro min-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-min)
  (kanji-font-magnification 0.85) (metric-adjustment-file "jiskan24.adj"))
(define-macro goth-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-goth)
  (kanji-font-magnification 0.85) (metric-adjustment-file "jiskan24.adj"))
(define-macro tmin-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-tmin)
  (kanji-font-magnification 0.85) (metric-adjustment-file "jiskan24v.adj"))
(define-macro tgoth-common
  (font-class ascii-jtex-kanji) (kanji-font jtex-tgoth)
  (kanji-font-magnification 0.85) (metric-adjustment-file "jiskan24v.adj"))

(define-font min5.jtex     (kanji-font-point-size  5)  min-common)
(define-font min6.jtex     (kanji-font-point-size  6)  min-common)
(define-font min7.jtex     (kanji-font-point-size  7)  min-common)
(define-font min8.jtex     (kanji-font-point-size  8)  min-common)
(define-font min9.jtex     (kanji-font-point-size  9)  min-common)
(define-font min10.jtex    (kanji-font-point-size 10)  min-common)
(define-font goth5.jtex    (kanji-font-point-size  5)  goth-common)
(define-font goth6.jtex    (kanji-font-point-size  6)  goth-common)
(define-font goth7.jtex    (kanji-font-point-size  7)  goth-common)
(define-font goth8.jtex    (kanji-font-point-size  8)  goth-common)
(define-font goth9.jtex    (kanji-font-point-size  9)  goth-common)
(define-font goth10.jtex   (kanji-font-point-size 10)  goth-common)
(define-font tmin5.jtex    (kanji-font-point-size  5)  tmin-common)
(define-font tmin6.jtex    (kanji-font-point-size  6)  tmin-common)
(define-font tmin7.jtex    (kanji-font-point-size  7)  tmin-common)
(define-font tmin8.jtex    (kanji-font-point-size  8)  tmin-common)
(define-font tmin9.jtex    (kanji-font-point-size  9)  tmin-common)
(define-font tmin10.jtex   (kanji-font-point-size 10)  tmin-common)
(define-font tgoth5.jtex   (kanji-font-point-size  5)  tgoth-common)
(define-font tgoth6.jtex   (kanji-font-point-size  6)  tgoth-common)
(define-font tgoth7.jtex   (kanji-font-point-size  7)  tgoth-common)
(define-font tgoth8.jtex   (kanji-font-point-size  8)  tgoth-common)
(define-font tgoth9.jtex   (kanji-font-point-size  9)  tgoth-common)
(define-font tgoth10.jtex  (kanji-font-point-size 10)  tgoth-common)
;; -----------------------------------------------------------------
;; EOF
</PRE>



<H2><A NAME="SEC76" HREF="VFlib-36_toc.html#TOC76">Example vflibcap 3</A></H2>

<P>
This is an example for TeX DVI drivers.
This vflibcap desgnates VFlib to use PK files.
For missing PK files, black "boxes" by TFM fonts are used 
as substitutes of glyphs of PK files



<PRE>
;; -----------------------------------------------------------------
;;   VFlib Default
;; -----------------------------------------------------------------
(define-default VFlib
  (extension-hints  ("pk" TeX) ("gf" TeX))
  (implicit-font-classes)
  (uncompression-programs  (".Z" "zcat") (".gz" "gzip -cd"))
  (variable-values  (TeX_USE_KPATHSEA      "Yes")
                    (TeX_DPI               "300")  ;; or "600"
                    (TeX_KPATHSEA_MODE     "cx")   ;; or "ljfour"
                    (TeX_KPATHSEA_PROGRAM  "/usr/local/bin/xldvi"))
  (use-kpathsea           $TeX_USE_KPATHSEA)
  (kpathsea-mode          $TeX_KPATHSEA_MODE)
  (kpathsea-program-name  $TeX_KPATHSEA_PROGRAM))

;; -----------------------------------------------------------------
;;   TeX-related Font Class Default and TeX Font Mapper
;; -----------------------------------------------------------------
(define-default  TeX
  (tfm-directories  "TEXMF"
                    "/usr/local/lib/jtex/fonts"
                    "/usr/local/lib/tex/fonts")
  (tfm-filename-extensions  ".tfm")
  (font-mapping
   ((pk "%f.%dpk") *)
   ((tfm "%f.%dtfm") *))
  (resolution-accuracy 0.02)
  (resolution-corrections
   (240  ;; sparcptr
    240  263  288  312  346  415  498  597)
   (300  ;; cx
    300  329  360  432  518  622  746  896 1075 1290  240 270)
   (400  ;; sparcptr
    400  438  480  576  691  829  995 1194 1433 1720  320 360)
   (600  ;; ljfour
    600  657  720  864 1037 1244 1493 1792 2150 2580  480 540))
  (dpi $TeX_DPI))

;; -----------------------------------------------------------------
;;   PK Font Class Default
;; -----------------------------------------------------------------
(define-default pk
  (font-directories "TEXMF"))

;; -----------------------------------------------------------------
;;   TFM Font Class Default
;; -----------------------------------------------------------------
(define-default tfm
  (glyph-style  "fill"))

;; -----------------------------------------------------------------
;EOF
</PRE>



<H1><A NAME="SEC77" HREF="VFlib-36_toc.html#TOC77">Debugging a vflibcap</A></H1>

<P>
There is no utility programs that checks syntax of a vflibcap file.
But VFlib checks syntax of vflibcap file when a font driver is
initialized or a font is opened.


<P>
VFlib prints a message to inform a user 
if syntax is illegal, undefined capability is used 
(this may be a typographical error),
essential capability is missing,
an undefined macro is used, or 
forms of capability values are illegal.


<P>
The following Unix environment variables are used
to print debugging messages.


<DL COMPACT>

<DT><CODE>VFLIB_DEBUG_FONT_OPEN</CODE>
<DD>
  -- If this environment variable is defined, 
  the processes of font opens are printed.

<DT><CODE>VFLIB_DEBUG_FONT_SEARCH</CODE>
<DD>
  -- If this variable is defined,
  the processes of font opens are printed

<DT><CODE>VFLIB_DEBUG_VFLIBCAP</CODE>
<DD>
  -- If this variable is defined,
  the process of reading of vflibcap file is printed.

<DT><CODE>VFLIB_DEBUG_PARAMETERS</CODE>
<DD>
  -- If this variable is defined,
  VFlib prints 
  how parameters (variables) in vflibcap file are substituted.

<DT><CODE>VFLIB_DEBUG_CCV</CODE>
<DD>
  -- If this variable is defined,
  the process of reading CCV files is printed.

<DT><CODE>VFLIB_DEBUG_CCV_MAPPING</CODE>
<DD>
  -- If this variable is defined,
  encoding conversions by CCV are printed.

</DL>



<H1><A NAME="SEC78" HREF="VFlib-36_toc.html#TOC78">Code conversion system</A></H1>

<P>
<A NAME="IDX88"></A>
<A NAME="IDX89"></A>
<A NAME="IDX90"></A>


<P>
Code conversion system (CCV) is used to convert 
from a character set and an encoding to another.
For example, a font of Unicode character set and Unicode encoding
can be accessed as ISO 8859-2 character set of ISO encoding
by encoding conversion.
TrueType font class makes use of this feature to hide 
invisible internal font encoding scheme and 
provides desired external view to users.


<P>
Conversion rule is given by one of the following two methods

<UL>
<LI>Internal functions in VFlib (written in C)

  These functions are hardcoded and new conversions rules cannot be 
  added without modifying source code.
<LI>External files, called CCV files.

  A list of CCV files to be used is specified in 
  <CODE>code-conversion-files</CODE> 
  capability of <CODE>VFlib</CODE> default.
</UL>



<H2><A NAME="SEC79" HREF="VFlib-36_toc.html#TOC79">How CCV works</A></H2>

<P>
Each conversion rule has the following information.



<UL>
<LI>EXTERNAL charset name

<LI>EXTERNAL encoding name

<LI>INTERNAL charset name

<LI>INTERNAL encoding name

<LI>other info such as format and size of conversion table...

</UL>

<P>
On invocation of VFlib, 
these information is read from each CCV files.
(CCV files are not fully loaded at initialization of VFlib;
VFlib just checks relation of conversion.
Conversion tables, which can be large, are loaded on demand.)
In addition, when VFlib is initialized, 
internal CCV functions are installed and 
these information is given for each conversion function.


<P>
"EXTERNAL" means external view (i.e., user side encoding) and 
"INTERNAL" means  internal view (i.e., font encoding).
Users can define arbitrary charset and encoding names, except
that some font driver may predefined names for internal use.
(TrueType font driver uses some predefined names, such as "unicode".)


<P>
CCV system has a conversion table searching mechanism.  
Table is searched by source charset/encoding names and destination 
charset/encoding names.  If there is a CCV file listed in 
<CODE>code_conversion_files</CODE> capability of <CODE>VFlib</CODE> defaults
entry in vflibcap that matches charset and encoding name, 
the CCV file is dynamically loaded and used for code conversion.


<P>
For example, a CCV file <TT>iso8859-1_unicode.ccv</TT> has the following
charset/encoding names:



<UL>
<LI>EXTERNAL charset name:      <TT>ISO8859-1</TT>

<LI>EXTERNAL charset encoding:  <TT>ISO</TT>

<LI>INTERNAL charset name:      <TT>UNICODE</TT>

<LI>INTERNAL charset encoding:  <TT>UNICODE</TT>

</UL>

<P>
By this CCV file, a unicode font can be viewed as a ISO
encoding of ISO 8859-1 charset. (It is very important to note
that names are just symbols and not have any meaning; 
in the above example, conversion to ISO encoding is implemented
by conversion table body in CCV file.)


<P>
In the current implementation, 
BDF, PCF, HBF, and TrueType font drivers use CCV system. 
In the following, how TrueType font driver uses CCV is described.


<P>
  Each TrueType font has information about charset name and encoding 
name of the font.  When a font entry is defined in vflibcap file
and <CODE>encoding</CODE> and <CODE>character-set</CODE> capability is defined,
say, <VAR>E</VAR> and <VAR>C</VAR> respectively. According to internal charset
and encoding information of TrueType font, the driver searches
a CCV table, when the VFlib font is opened, that matches  
the following conversion relation. 



<UL>
<LI>EXTERNAL charset name:      <VAR>E</VAR>

<LI>EXTERNAL charset encoding:  <VAR>C</VAR>

<LI>INTERNAL charset name:      possibly, <TT>UNICODE</TT> (from font file info)

<LI>INTERNAL charset encoding:  possibly, <TT>UNICODE</TT> (from font file info)

</UL>

<P>
If not found, conversion is impossible. If found, a CCV file found
is used.  After a font is opened, CCV table is used 
for converting code points for VFlib operation such as 
<CODE>VF_GetBitmap1()</CODE>.




<H2><A NAME="SEC80" HREF="VFlib-36_toc.html#TOC80">The internal (hardcoded) CCV functions</A></H2>
<P>
VFlib has several hardcoded CCV functions.
Followings CCV functions are implemented.



<UL>

<LI>from ISO-2022 (<CODE>ISO2022</CODE>) to Shift JIS (<CODE>SJIS</CODE>)

<LI>from Shift JIS (<CODE>SJIS</CODE>) to ISO 2022 (<CODE>ISO2022</CODE>)

<LI>from EUC (<CODE>EUC</CODE>) to ISO 2022 (<CODE>ISO2022</CODE>)

<LI>from Row-Cell (<CODE>Row-Cell</CODE>) to ISO 2022 (<CODE>ISO2022</CODE>)

<LI>from ISO-2022 (<CODE>ISO2022</CODE>) to Row-Cell (<CODE>Row-Cell</CODE>)

<LI>from ISO-2022 (<CODE>ISO2022</CODE>) to WanSung (<CODE>WanSung</CODE>)

<LI>from Row-Cell (<CODE>Row-Cell</CODE>) to WanSung (<CODE>WanSung</CODE>)

<LI>from ISO-2022 (<CODE>ISO2022</CODE>) to Sequential Numbering

(<CODE>Sequential2-0</CODE> and <CODE>Sequential2-1</CODE>)

By these encoding schemes, characters are numbered sequentially
starting from 0 (<CODE>Sequential2-0</CODE>) or 1 (<CODE>Sequential2-1</CODE>).
That is, <CODE>Sequential2-0</CODE> encoding is an encoding such that 
code of the first character is 0, 
code of the second is 1, ..., and 
code of the i-th character is (i-1). 
<CODE>Sequential2-1</CODE> encoding is an encoding such that 
code of the first character is 1, 
code of the second is 2, ..., and 
code of the i-th is (i).
External code point must be encoded two-byte, i.e., 0x2121...7e7e.
These values are converted to 0...8835 or 1...8836.

</UL>

<P>
Encoding name <CODE>JIS</CODE> is defined as an alias of <CODE>ISO2022</CODE>.
Encoding name <CODE>Ku-Ten</CODE> is defined as an alias of <CODE>Row-Cell</CODE>.
Note that these aliases are defined only for hardcorded CCV functions.


<P>
All of these are implemented simple arithmetic and 
large conversion tables are not necessary in memory.




<H2><A NAME="SEC81" HREF="VFlib-36_toc.html#TOC81">The syntax of CCV files</A></H2>

<P>
The syntax of CCV files is lisp-like notation, similar to vflibcap files.
The CCV file defines its own directive set, explained below.
A code conversion table is divided in several sub-tables to reduce
the file size (and memory size when the file is loaded into memory).
The sub-tables are called `blocks'.  


<DL COMPACT>

<DT><CODE>(charset-external-name <VAR>from-cs-name</VAR>)</CODE>
<DD>
<DT><CODE>(charset-external-encoding <VAR>from-cs-enc</VAR>)</CODE>
<DD>
<DT><CODE>(charset-internal-name <VAR>to-cs-name</VAR>)</CODE>
<DD>
<DT><CODE>(charset-internal-encoding <VAR>to-cs-enc</VAR>)</CODE>
<DD>
--- These four directives describes character set and encoding information 
of conversion.

<DT><CODE>(table-type <VAR>type</VAR>)</CODE>
<DD>
<VAR>type</VAR> must be one of the following:

<UL>
<LI><CODE>array</CODE>

<LI><CODE>random-arrays</CODE>

</UL>

<DT><CODE>(c1-min <VAR>c1min</VAR>)</CODE>
<DD>
<DT><CODE>(c1-max <VAR>c1max</VAR>)</CODE>
<DD>
<DT><CODE>(c2-min <VAR>c2min</VAR>)</CODE>
<DD>
<DT><CODE>(c2-max <VAR>c2max</VAR>)</CODE>
<DD>
<DT><CODE>(block-size <VAR>size</VAR>)</CODE>
<DD>
<DT><CODE>(nblocks <VAR>nblocks</VAR>)</CODE>
<DD>
<DT><CODE>(block <VAR>block</VAR> <VAR>code0</VAR> <VAR>code1</VAR> ...)</CODE>
<DD>
</DL>

<P>
Let <VAR>c</VAR> be a code point of a character to be converted 
by this CCV file.


<P>
It is converted as follows.
Let <VAR>c1</VAR> be <VAR>c</VAR>/<VAR>size</VAR> and <VAR>c2</VAR> be <VAR>c</VAR> modulo <VAR>size</VAR>.
The block number <VAR>b</VAR> that should be referred to is <VAR>c1</VAR>-<VAR>c1min</VAR>.
The position <VAR>i</VAR> in the block <VAR>b</VAR> is <VAR>c2</VAR>-<VAR>c2min</VAR>.
Thus, the value of <VAR>i</VAR>-th entry of a block numbered <VAR>b</VAR> is 
converted code point.


<P>
<VAR>c1max</VAR>, <VAR>c2max</VAR> and <VAR>nblocks</VAR> are used 
internally to determine the necessary memory area to load the table.


<P>
Theoretically, <CODE>array</CODE> is enough for the value for 
<CODE>table-type</CODE> directive.
But in case that there are many blocks that do not have conversion entries.
This is happen in the case of CNS11643 character set
(a Hanji character set in Taiwan).
To reduce the table size, some of blocks can be omitted by giving
<CODE>random-array</CODE> for <CODE>table-type</CODE> directive.


<P>
In case of <CODE>array</CODE>, lookup for code conversion is 
implemented by indexing an entire array, which is very fast. 
In case of <CODE>random-array</CODE>, lookup for code conversion 
takes time to find a corresponding sub-table (block), since
the table is not linear.




<H2><A NAME="SEC82" HREF="VFlib-36_toc.html#TOC82">Example of a CCV file 1</A></H2>

<P>
The following example is a CCV file that virtually provides 
a ISO 8859-1 character set font using a Unicode font.
That is, a Unicode font can be used as if it were a ISO 8859-1 font
by the CCV file.
This file is distributed with VFlib and installed
by the name <CODE>iso8859-1_unicode.ccv</CODE>.


<P>
This file is a table indexed by code points of ISO 8859-1; 
contents of table entries are Unicode code points. 



<PRE>
; Conversion table: ISO8859-1 ==&#62; UNICODE
(charset-external-name ISO8859-1)
(charset-external-encoding ISO)
(charset-internal-name UNICODE)
(charset-internal-encoding UNICODE)
(table-type array)
; Code point C is converted to C' by the following formula:
;   C' = Table[(c1 - c1min)*M + (c2 - c2min)],
;   where c1 = C/B and c2 = C%B, and M = c2max - c2min + 1.
;   B is a block size given by the 'block-size:' parameter.
(c1-min 0x0)
(c1-max 0x0)
(c2-min 0x20)
(c2-max 0xff)
(block-size 256)
(nblocks 1)
; 0x0020 ... 0x00ff
(block 0
    0x0020 0x0021 0x0022 0x0023 0x0024 0x0025 0x0026 0x0027 
    0x0028 0x0029 0x002a 0x002b 0x002c 0x002d 0x002e 0x002f 
    0x0030 0x0031 0x0032 0x0033 0x0034 0x0035 0x0036 0x0037 
    0x0038 0x0039 0x003a 0x003b 0x003c 0x003d 0x003e 0x003f 
    0x0040 0x0041 0x0042 0x0043 0x0044 0x0045 0x0046 0x0047 
    0x0048 0x0049 0x004a 0x004b 0x004c 0x004d 0x004e 0x004f 
    0x0050 0x0051 0x0052 0x0053 0x0054 0x0055 0x0056 0x0057 
    0x0058 0x0059 0x005a 0x005b 0x005c 0x005d 0x005e 0x005f 
    0x0060 0x0061 0x0062 0x0063 0x0064 0x0065 0x0066 0x0067 
    0x0068 0x0069 0x006a 0x006b 0x006c 0x006d 0x006e 0x006f 
    0x0070 0x0071 0x0072 0x0073 0x0074 0x0075 0x0076 0x0077 
    0x0078 0x0079 0x007a 0x007b 0x007c 0x007d 0x007e -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    0x00a0 0x00a1 0x00a2 0x00a3 0x00a4 0x00a5 0x00a6 0x00a7 
    0x00a8 0x00a9 0x00aa 0x00ab 0x00ac 0x00ad 0x00ae 0x00af 
    0x00b0 0x00b1 0x00b2 0x00b3 0x00b4 0x00b5 0x00b6 0x00b7 
    0x00b8 0x00b9 0x00ba 0x00bb 0x00bc 0x00bd 0x00be 0x00bf 
    0x00c0 0x00c1 0x00c2 0x00c3 0x00c4 0x00c5 0x00c6 0x00c7 
    0x00c8 0x00c9 0x00ca 0x00cb 0x00cc 0x00cd 0x00ce 0x00cf 
    0x00d0 0x00d1 0x00d2 0x00d3 0x00d4 0x00d5 0x00d6 0x00d7 
    0x00d8 0x00d9 0x00da 0x00db 0x00dc 0x00dd 0x00de 0x00df 
    0x00e0 0x00e1 0x00e2 0x00e3 0x00e4 0x00e5 0x00e6 0x00e7 
    0x00e8 0x00e9 0x00ea 0x00eb 0x00ec 0x00ed 0x00ee 0x00ef 
    0x00f0 0x00f1 0x00f2 0x00f3 0x00f4 0x00f5 0x00f6 0x00f7 
    0x00f8 0x00f9 0x00fa 0x00fb 0x00fc 0x00fd 0x00fe 0x00ff )
</PRE>



<H2><A NAME="SEC83" HREF="VFlib-36_toc.html#TOC83">Example of a CCV file 2</A></H2>

<P>
The following example is a CCV file that virtually provides 
a CNS 11643 Plane 1 character set font using a Unicode font.
This file is distributed with VFlib and installed
by the name <CODE>cns11643-1_unicode.ccv</CODE>.


<P>
This file is an example of CCV files
that have <CODE>random-arrays</CODE> for <CODE>table-type</CODE> directive.



<PRE>
; Conversion table: CNS11643-1 ==&#62; UNICODE
(charset-external-name CNS11643-1)
(charset-external-encoding ISO2022)
(charset-internal-name UNICODE)
(charset-internal-encoding UNICODE)
(table-type random-arrays)
; Code point C is converted to C' by the following formula:
;   C' = Table[(c1 - c1min)*M + (c2 - c2min)],
;   where c1 = C/B and c2 = C%B, and M = c2max - c2min + 1.
;   B is a block size given by the 'block-size:' parameter.
(c1-min 0x121)
(c1-max 0xe67)
(c2-min 0x21)
(c2-max 0x7e)
(block-size 256)
(nblocks 218)
; 0x12121 ... 0x1217e
(block 0
    0x3000 0xff0c 0x3001 0x3002 0xff0e 0x30fb 0xff1b 0xff1a 
    0xff1f 0xff01 0xfe30 0x2026 0x2025 0xfe50 0xfe51 0xfe52 
    0x00b7 0xfe54 0xfe55 0xfe56 0xfe57 0xfe31 0x2014 0xfe32 
    0x2013 -1     -1     -1     -1     0xff08 0xff09 0xfe35 
    0xfe36 0xff5b 0xff5d 0xfe37 0xfe38 0x3014 0x3015 0xfe39 
    0xfe3a 0x3010 0x3011 0xfe3b 0xfe3c 0x300a 0x300b 0xfe3d 
    0xfe3e 0x3008 0x3009 0xfe3f 0xfe40 0x300c 0x300d 0xfe41 
    0xfe42 0x300e 0x300f 0xfe43 0xfe44 0xfe59 0xfe5a 0xfe5b 
    0xfe5c 0xfe5d 0xfe5e 0x2018 0x2019 0x201c 0x201d 0x301d 
    0x301e 0x2032 0x2035 0xff03 0xff06 0xff0a 0x203b 0x00a7 
    0x3003 0x25cb 0x25cf 0x25b3 0x25b2 0x25ce 0x2606 0x2605 
    0x25c7 0x25c6 0x25a1 0x25a0 0x25bd 0x25bc )
; 0x12221 ... 0x1227e
(block 1
    0x32a3 0x2105 0x203e -1     0xff3f -1     0xfe49 0xfe4a 
    0xfe4d 0xfe4e 0xfe4b 0xfe4c 0xfe5f 0xfe60 0xfe61 0xff0b 
    0xff0d 0x00d7 0x00f7 0x00b1 0x221a 0xff1c 0xff1e 0xff1d 
    0x2266 0x2267 0x2260 0x221e 0x2252 0x2261 0xfe62 0xfe63 
    0xfe64 0xfe66 0xfe65 0x223c 0x2229 0x222a 0x22a5 0x2220 
    0x221f 0x22bf 0x33d2 0x33d1 0x222b 0x222e 0x2235 0x2234 
    0x2640 0x2642 0x2641 0x2609 0x2191 0x2193 0x2192 0x2190 
    0x2196 0x2197 0x2199 0x2198 0x2016 0xff5c 0xff0f 0xff3c 
    0x2215 0xfe68 0xff04 0xffe5 0x3012 0xffe0 0xffe1 0xff05 
    0xff20 0x2103 0x2109 0xfe69 0xfe6a 0xfe6b 0x33d5 0x339c 
    0x339d 0x339e 0x33ce 0x33a1 0x338e 0x338f 0x33c4 0x00b0 
    0x5159 0x515b 0x515e 0x515d 0x5161 0x5163 )
; 0x12321 ... 0x1237e
(block 2
    0x55e7 0x74e9 0x7cce 0x2581 0x2582 0x2583 0x2584 0x2585 
    0x2586 0x2587 0x2588 0x258f 0x258e 0x258d 0x258c 0x258b 
    0x258a 0x2589 0x253c 0x2534 0x252c 0x2524 0x251c 0x2594 
    0x2500 0x2502 0x2595 0x250c 0x2510 0x2514 0x2518 0x256d 
    0x256e 0x2570 0x256f 0x2550 0x255e 0x256a 0x2561 0x25e2 
    0x25e3 0x25e5 0x25e4 0x2571 0x2572 0x2573 -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     )

<VAR>... it's very long, snip, snip, snip ...</VAR>

; 0xe6621 ... 0xe667e
(block 3397
    0x7bd0 0x7c2f 0x7c32 0x7c42 0x7c4e 0x7c68 0x7ca9 0x7ced 
    0x7dd0 0x7e07 0x7dd3 0x7e64 0x7f40 -1     0x8041 0x8063 
    0x80bb 0x6711 0x6725 0x8248 0x8310 0x8362 0x8312 0x8421 
    0x841e 0x84e2 0x84de 0x84e1 0x8573 0x85d4 0x85f5 0x8637 
    0x8645 0x8672 0x874a 0x87a9 0x87a5 0x87f5 0x8834 0x8850 
    0x8887 0x8954 0x8984 0x8b03 0x8c52 0x8cd8 0x8d0c 0x8d18 
    0x8db0 0x8ebc 0x8ed5 0x8faa 0x909c -1     0x915c 0x922b 
    0x9221 0x9273 0x92f4 0x92f5 0x933f 0x9342 0x9386 0x93be 
    0x93bc 0x93bd 0x93f1 0x93f2 0x93ef 0x9422 0x9423 0x9424 
    0x9467 0x9466 0x9597 0x95ce 0x95e7 0x973b 0x974d 0x98e4 
    0x9942 0x9b1d 0x9b98 -1     0x9d49 0x6449 0x5e71 0x5e85 
    0x61d3 0x990e 0x8002 0x781e -1     -1     )
; 0xe6721 ... 0xe677e
(block 3398
    0x5528 0x5572 0x55ba 0x55f0 0x55ee 0x56b8 0x56b9 0x56c4 
    0x8053 0x92b0 -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     -1     -1     
    -1     -1     -1     -1     -1     -1     )
</PRE>



<H1><A NAME="SEC84" HREF="VFlib-36_toc.html#TOC84">Utility programs</A></H1>



<H2><A NAME="SEC85" HREF="VFlib-36_toc.html#TOC85">vflmkcaptex</A></H2>

<P>
<A NAME="IDX91"></A>


<P>
@command{vflmkcaptex} is a utility program 
to generate vflibcap file for TeX DVI driver software
automatically. 
With simple command line arugments,
a vflibcap that uses PK, GF, Virtual Font, Type 1
fonts with complex TeX font mapping rules.


<P>
<B>Usage:</B> <TT>vflmkcaptex</TT> [ <VAR>OPTIONS...</VAR> ] [ <VAR>CLASS...</VAR> ] 


<P>
<B>Usage:</B> <TT>vflmkcaptex</TT> [ <VAR>SHORTCUT</VAR> ] [ <VAR>OPTIONS...</VAR> ] 


<P>
@option{<VAR>CLASS...</VAR>} is a list of font class names 
to support by vflibcap file to be generated.
@option{<VAR>OPTIONS...</VAR>} is option list to customize default settings.
@option{<VAR>SHORTCUT</VAR>} is a shortcut name to typical options 
and class name list.


<P>
<B>Shortcut:</B>


<DL COMPACT>

<DT><TT>minimum</TT>
<DD>
This is the same as command line option <TT>pk</TT>.
Use PK fonts only. 

<DT><TT>simple</TT>
<DD>
This is the same as command line option <TT>-g pk tfm</TT>.
Use PK fonts. 
If PK font file is missing, it is generated on-the-fly.
If font cannot be created, black square is displayed
instead of character glyph (as long as corresponding TFM file exists).

<DT><TT>standard</TT>
<DD>
This is the same as command line option <TT>-t1 -g</TT>.
Use default class list <TT>type1 vf pk tfm</TT>.
Missing PK font is created on-the-fly.

<DT><TT>simple-ja</TT>
<DD>
This is the same as command line option <TT>-g pk tfm -jtex -jisx0212 -jpcf</TT>.
(Japanese support for <TT>simple</TT> shortcut.)

<DT><TT>standard-ja</TT>
<DD>
This is the same as command line option <TT>-t1 -g -jtex -jisx0212 -jpcf</TT>.
(Japanese support for <TT>standard</TT> shortcut.)

</DL>

<P>
<B>Font class list:</B>


<DL COMPACT>

<DT><TT>gf</TT>
<DD>
Enables to use GF font files.
For searching font files, kpathsea is used.
That is, font files are searched under TeX <TT>`texmf'</TT> directory
 (typically, <TT>`/usr/local/share/texmf'</TT>).

<DT><TT>pk</TT>
<DD>
Enables to use PK font files.
For searching font files, kpathsea is used.

<DT><TT>vf</TT>
<DD>
Enables to use Virtual Font files.
For searching font files, kpathsea is used.

<DT><TT>tfm</TT>
<DD>
Enables to use TFM files.
This option enables to display black square instead of glyph.
The size of square obeys font metric of each character.
This is useful when glyph file (e.g., PK, Type1) is missing.

<DT><TT>type1</TT>
<DD>
Enables to use Type 1 fonts.
(Currently, it supports Roman fonts. CJK fonts are not supported.)
For searching font files, kpathsea is used.

By this option, font definitions for PostScript fonts used in TeX 
DVI files are generated by reading <TT>`psfonts.map'</TT> of @command{dvips}.
Each PostScript font listed in <TT>`psfonts.map'</TT> is checked 
if it exists. 
(For PostScript fonts, this program automatically searchs 
Adobe Acrobat 3 and 4 font directories.)
If a PostScript font in question is not found, 
@command{Ghostscript} font definition file <TT>`Fontmap'</TT> 
is checked to substitute the font by a font in
@command{Ghostscript} font directory.

This feature is very useful for displaying and printing TeX 
DVI files with PostScript fonts. 
So, I recommned obtain Adobe Acrobat 3 and 4 for Type 1 PostScript fonts.
(Linux version are freely available.)

</DL>

<P>
When a font is requested to open,
the font is tried to open by font classes by the order 
in the command line.


<P>
So, by a <TT>`vflibcap'</TT> generated by the following example,
font in PK format is rearched first. 
If a font in PK format is not found, 
font in Type 1 format is searched next.

<PRE>
vflmkcaptex pk type1
</PRE>

<P>
Therefore, the order of font classes decides the priority of 
font file formats to search.


<P>
<B>Options:</B>


<DL COMPACT>

<DT><TT>--help</TT>
<DD>
Print a list of command line options and exit.

<DT><TT>--version</TT>
<DD>
Print version number of this program and exit.

<DT><TT>-p <VAR>PROG</VAR></TT>
<DD>
Application program name. This is used by kpathsea 
for font file search. Default is <TT>xgdvi</TT>, which is
a DVI previewer in the TeX-Guy package.

<DT><TT>-n <VAR>MODE</VAR></TT>
<DD>
Device mode name for font file search, used by kpathsea.
Default is <TT>cx</TT>
  
<DT><TT>-r <VAR>DPI</VAR></TT>
<DD>
Device resolution in DPI. Default is 300.

If this option is not given, @command{vflmkcaptex} reads <TT>`mode.mf'</TT>,
which is a device mode definition file for METAFONT,
and obtains revice resolution automatically.

<DT><TT>-g</TT>
<DD>
Configure <TT>`vflibcap'</TT> to generate non-existing PK files
on-the-fly.

<DT><TT>-pk</TT>
<DD>
When @option{<VAR>CLASS...</VAR>} is not given, 
default font class set is assumed by default.
For such case, generate a <TT>`vflibcap'</TT> to search PK font file
before searching Type 1 font by this option. 

<DT><TT>-t1</TT>
<DD>
When @option{<VAR>CLASS...</VAR>} is not given, 
generate a <TT>`vflibcap'</TT> to search Type 1 font file
before searching PK font file by this option. 

</DL>

<P>
<B>Options for Japanese TeX support:</B>


<DL COMPACT>

<DT><TT>-jtex</TT>
<DD>
Generate font definitions for JIS X0208 character set
used by Japanese TeX.
By default, a <TT>`vflibcap'</TT> to be generated uses
Japanese Kanji character in PCF format (in X11 font directory).
See also @option{-jpcf}, @option{-jekanji} and @option{-jttf} options.

<DT><TT>-jisx0212</TT>
<DD>
Generate font definitions for JIS X0208 character set
used by Japanese TeX. 
Note that generated font names are not standard.
It is used for private use of the author.

<DT><TT>-jpcf</TT>
<DD>
Switch to use PCF fonts for Japanese Kanji characters.
(This is the default.)

<DT><TT>-jekanji</TT>
<DD>
Switch to use eKanji fonts for Japanese Kanji characters.
See section <A HREF="VFlib-36.html#SEC64">eKanji font class</A> for detail about eKanji fonts.

<DT><TT>-jttf</TT>
<DD>
Switch to use TrueType fonts for Japanese Kanji characters.

<DT><TT>-jpfd <VAR>DIR</VAR></TT>
<DD>
Add a PCF font directory.
@command{vflmkcaptex} checks typical X11 PCF font directories 
and existing directories are added to PCF font directory list.
This option should be used when
you want to add optional (and not automatically detected) 
PCF font directory.
This option can be used multiple times.

<DT><TT>-jefd <VAR>DIR</VAR></TT>
<DD>
Add a eKanji font directory.
This option can be used multiple times.

<DT><TT>-jtfd <VAR>DIR</VAR></TT>
<DD>
Add a TrueType font directory.
This option can be used multiple times.

<DT><TT>-jtdb <VAR>FILE</VAR></TT>
<DD>
By this option, an external definition database file <VAR>FILE</VAR>
is read for generating definitions of non-standard TeX Japanese fonts
using Japanese TrueType font files.
Each line in <VAR>FILE</VAR> is a pair of 
(1) font name used in TeX and
(2) TrueType font file name.
Following is an example: 


<PRE>
dfailpaa dcail5.ttc
dfainpaa dcai5.ttc
dfaispaa dcais5.ttc
dfbrrsaa dfbrr7.ttc
dfbrrzaa dfbrrc.ttc
dfbrspaa dfbrs5.ttc
dfbrsvaa dfbrs9.ttc
dfbrszaa dfbrsc.ttc
</PRE>

See files in a directory <TT>`ascii-jtex/'</TT> for detail.

</DL>

<P>
@command{vflmkcaptex} is a Unix Shell script. 
It uses following programs to generate a <TT>`vflibcap'</TT> file.
Descriptions the followng programs are ommited since 
most of users never use them directly.
For details,
invoke each program with @option{--help} option to see how to use it.


<DL COMPACT>

<DT>@command{vflmkvfl}
<DD>
  A generator for VFlib defaults.
  (See section <A HREF="VFlib-36.html#SEC56">VFlib defaults</A>.)
<DT>@command{vflmktex}
<DD>
  A generator for TeX mapping class.
  (See section <A HREF="VFlib-36.html#SEC65">TeX default and TeX font mapping font class</A>.)
<DT>@command{vflmkpk}
<DD>
  A generator for PK class.
  (See section <A HREF="VFlib-36.html#SEC66">PK font class</A>.)
<DT>@command{vflmkgf}
<DD>
  A generator for GF class.
  (See section <A HREF="VFlib-36.html#SEC67">GF font class</A>.)
<DT>@command{vflmkvf}
<DD>
  A generator for Virtual Font class.
  (See section <A HREF="VFlib-36.html#SEC69">VF font class</A>.)
<DT>@command{vflmktfm}
<DD>
  A generator for TFM class.
  (See section <A HREF="VFlib-36.html#SEC68">TFM font class</A>.)
<DT>@command{vflmkt1}
<DD>
  A generator for Type 1 class.
  (See section <A HREF="VFlib-36.html#SEC61">Type1 font class</A>.)
<DT>@command{vflmkekan}
<DD>
  A generator for eKanji class.
  (See section <A HREF="VFlib-36.html#SEC64">eKanji font class</A>.)
<DT>@command{vflmkajt}
<DD>
  A generator for ASCII Japanese TeX class.
  (See section <A HREF="VFlib-36.html#SEC70">ASCII Japanese TeX Kanji font class</A>.)
</DL>



<H2><A NAME="SEC86" HREF="VFlib-36_toc.html#TOC86">vflpp</A></H2>
<P>
<A NAME="IDX92"></A>


<P>
@command{vflpp} prettyprints (i.e., grinds) a vflibcap file.
It eliminate all comment strings and unnecessary space and newline characters.


<P>
<B>Usage:</B> <TT>vflpp</TT> [ <VAR>vflibcap-file</VAR> ]


<P>
A program
@command{vflpp} prettyprints a file <VAR>vflibcap</VAR> to standard output.
If no argument is given, @command{vflpp} reads from standard input.




<H2><A NAME="SEC87" HREF="VFlib-36_toc.html#TOC87">vflmkfdb</A></H2>

<P>
<A NAME="IDX93"></A>


<P>
<B>Usage:</B> <TT>vflmkfdb</TT> <VAR>font-directory</VAR> [ ... ]


<P>
A program
@command{vflmkfdb} makes a font file hint database (FDB for short) 
in a font directories given in the command line argument.


<P>
It is used in a font file search module in VFlib.
In case there are many font files in many directories, search a font file
consumes much time to traverse directory hierarchy.
FDB file contains pairs of file name and path name to the file
in a single file. By reading FDB file, a font file can be found
without traversing directories.


<P>
<A NAME="IDX94"></A>
For each <VAR>font-directory</VAR>, a FDB file named <TT>`VFlib.fdb'</TT>
is created in the directory.




<H2><A NAME="SEC88" HREF="VFlib-36_toc.html#TOC88">vfldrvs</A></H2>

<P>
<A NAME="IDX95"></A>


<P>
<B>Usage:</B> <TT>vfldrvs</TT>


<P>
A program
@command{vfldrvs} prints a list of pre-installed 
font drivers in VFlib.




<H1><A NAME="SEC89" HREF="VFlib-36_toc.html#TOC89">Sample programs</A></H1>



<H2><A NAME="SEC90" HREF="VFlib-36_toc.html#TOC90">vflserver</A></H2>

<P>
<A NAME="IDX96"></A>
@command{vflserver} is a font server that provides 
the functionality of VFlib via network.


<P>
@command{vflserver} can be invokes from command line or via network.




<H3><A NAME="SEC91" HREF="VFlib-36_toc.html#TOC91">Using vflserver from command line</A></H3>

<P>
<B>Usage:</B> <TT>vflserver</TT> [<TT>-v</TT> <VAR>vflibcap</VAR>] [<TT>-s</TT> <VAR>shrink</VAR>] [<VAR>cmd-file ...</VAR>]


<P>
@command{vflserver} receives a command, executes it, and return a result.
This is repeated until connection is closed or quit command is executed.
@command{vflserver} reads a sequence of command from 
standard input if <VAR>cmd-file</VAR> option is not given.


<P>
Options:


<DL COMPACT>

<DT><TT>-v</TT> <VAR>vflibcap</VAR>
<DD>
A file name of vflibcap to be used. If this option is not given,
default vflibcap file is used. (Possibly, default vflibcap is
<TT>`/usr/local/share/VFlib/3.6.14/vflibcap'</TT>.)
  
<DT><TT>-s</TT> <VAR>shrink</VAR>
<DD>
@command{vflserver} has a feature to print obtained bitmaps in
ASCII-art style for debugging purpose. 
When this feature is enabled, bitmaps are shrinked by this factor.
This is effective when obtained bitmaps are huge.

<DT><VAR>cmd-file ...</VAR>
<DD>
A sequence of commands can be read from files.
Commands in files <VAR>cmd-file ...</VAR> are executed in given order.
After executing all files, @command{vflserver} reads a sequence of 
commands from standard input.
Thus, quit command may be explicitly given in <VAR>cmd-file</VAR>.
This option is effective in the process of font driver development 
to do the same commands many times.

</DL>



<H3><A NAME="SEC92" HREF="VFlib-36_toc.html#TOC92">Using vflserver via network</A></H3>

<P>
Before using @command{vflserver} via network, 
it must be installed to be invoked by @command{inetd}.
You must be a root to do the following procedures.


<P>
First, edit <TT>`/etc/services'</TT>:



<UL>
<LI>Network service name: vflserver

<LI>Well known port: 4681

<LI>Protocol: tcp

</UL>

<P>
Add the following line to <TT>`/etc/inetd.conf'</TT>. 



<PRE>
vflserver stream tcp nowait nobody /usr/local/bin/vflserver vflserver 
</PRE>

<P>
If you need to explicitly specify a vflibcap file to be used,
you must give @option{-v} option as follows:



<PRE>
vflserver stream tcp nowait nobady /usr/local/bin/vflserver vflserver -v /foo/vflibcap
</PRE>

<P>
To force inetd to re-read <TT>`inetd.conf'</TT>,
send a HUP signal to inetd.


<P>
We finished installing vflserver to use via network.
Now, use @command{telnet} to check if @command{vflserver} 
is correctly installed to network service.
The following an example interaction. 



<PRE>
% telnet localhost vflserver
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
; This is a font server VFLSERVER Version 2.0 Fri Mar 13 11:58:42 JST 1998
  ...

; Type `HELP' for description of the protocol.

(100 "vflserver ready.")

open1 timR14.pcf
(100 0 "timR14.pcf")
debug bitmap on
(100 "Ascii-art bitmap on.")
bitmap1 0 0x67
(100 8 13 0 9 9 0
 "3eccc4c4cc78407c7f83c1e27c"
"
 89012345678901
 +------------+
9|            |9
0| ..@@@@@.   |0
1| @@..@@..   |1
2| @@...@..   |2
3| @@...@..   |3
4| @@..@@..   |4
5| .@@@@...   |5
6| .@......   |6
7| .@@@@@..   |7
8| .@@@@@@@   |8
9| +.....@@ o |9
0| @@.....@   |0
1| @@@...@.   |1
2| .@@@@@..   |2
3|            |3
 +------------+
 89012345678901
")
quit
(100 "Happy Hacking")
Connection closed by foreign host.
</PRE>



<H3><A NAME="SEC93" HREF="VFlib-36_toc.html#TOC93">The protocol of vflserver</A></H3>



<H4><A NAME="SEC94" HREF="VFlib-36_toc.html#TOC94">Introduction</A></H4>
<P>
The VFLSERVER Protocol is a communication protocol between a 
server which offers font service and a client which uses
fonts. 


<P>
  The character set assumed by this protocol is ASCII character
set. A line is a sequence of character terminated by a newline
character and communication between a server and a client is
line-oriented.
     




<H4><A NAME="SEC95" HREF="VFlib-36_toc.html#TOC95">Reply Format of a Server</A></H4>

<P>
Each request to a server by a client takes a form of a line.
The following are examples of client's requests.



<PRE>
OPEN1 timR24.pcf
DEBUG BITMAP ON
BITMAP1 1 33
</PRE>

<P>
A reply by a server to a client is an S-expression, 
(lisp-like notation).
The following are examples of server's response.



<PRE>
(100 0 "timR14.pcf")
(100 "Ascii-art bitmap on.")
(100 8 13 0 9 9 0 "3eccc4c4cc78407c7f83c1e27c")
</PRE>

<P>
The first number of the response of each reply 
by a server are formed by decimal digits and these three digits
indicates the status of an execution of client's request.
Thus, this three digits is a status code.


<P>
The first digit is one of <SAMP>`1'</SAMP>, <SAMP>`2'</SAMP>, ...., <SAMP>`5'</SAMP>. 
If this digit is <SAMP>`1'</SAMP>, it there is no error at all. 
If it is <SAMP>`5'</SAMP>, there are some errors to achieve a request. 
According to the degree of fatalness, the digit is decided; 
It is <SAMP>`1'</SAMP> if no error is detected and is <SAMP>`5'</SAMP>
if some fatal errors are detected
and it is impossible to continue to execute a server.
If it is not <SAMP>`5'</SAMP>, a client can receive some result.




<H4><A NAME="SEC96" HREF="VFlib-36_toc.html#TOC96">The Protocol</A></H4>

<P>
The following defines commands and their arguments by a client, 
and corresponding responses by a server. Command name is 
case-insensitive, but arguments are case-sensitive.
In the description of command format, arguments enclosed by [ ]
can be omitted, while arguments that are not enclosed by [ ] are
essential arguments and cannot be omitted.


<DL COMPACT>

<DT><TT>OPEN1</TT> <VAR>font_name</VAR> [ <VAR>point_size</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> [ <VAR>dpi_x</VAR> <VAR>dpi_y</VAR> ]]]
<DD>
Open a font in mode 1 (high resolution device oriented mode).
This corresponds to <CODE>VF_OpenFont1()</CODE> function.
If it succeeds opening the font, a font identifier is returned.  
After a font is opened, any request for a font is specified by 
font identifier (not font name).

<B>Response:</B>
<DL COMPACT>

<DT>When the command is successful: <TT>( <VAR>status</VAR> <VAR>fontid</VAR> <VAR>message</VAR> )</TT>
<DD>
    <VAR>fontid</VAR> is a font id represented by non-negative integer in decimal. 
<DT>When the command failed: <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>
<DD>
     <VAR>status</VAR> indicates that an error occurred.
</DL>

<DT><TT>OPEN2</TT> <VAR>font_name</VAR> [ <VAR>pixel_size</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]]
<DD>
Open a font in mode 2 (low resolution device oriented mode).
This corresponds to <CODE>VF_OpenFont2()</CODE> function.
If it succeeds opening the font, a font identifier is returned.  
After a font is opened, any request for a font is specified by 
font identifier (not font name).

<B>Response:</B> Response is the same as one for @command{OPEN1} command.

<DT><TT>CLOSE</TT> <VAR>font_id</VAR>
<DD>
Closed a font.

<B>Response:</B> <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>

<DT><TT>BITMAP1</TT> <VAR>font_id</VAR> <VAR>code_point</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]
<DD>
Obtain a bitmap. 
<VAR>font_id</VAR> is a font id. 
This command corresponds to <CODE>VF_GetBitmap1()</CODE> function of VFlib.

<B>Response:</B>
<DL COMPACT>

<DT>When the command is successful: <TT>( <VAR>status</VAR> <VAR>width</VAR> <VAR>height</VAR> <VAR>offx</VAR> <VAR>offy</VAR> <VAR>mvx</VAR> <VAR>mvy</VAR> <VAR>bitmap</VAR> )</TT>
<DD>
<VAR>width</VAR> and <VAR>height</VAR> is a size of bitmap in pixels.
<VAR>bitmap</VAR> is encoded as a sequence of hexadecimal number. 
Eight pixels are encoded to two hexadecimal number and the 
weight of the i-th <EM>(0 &#60;= i &#60; 8)</EM> pixel from the leftmost 
pixel is <TT>0x80 &#62;&#62; i</TT>.
<VAR>bitmap</VAR> is a sequence of encoded of rasters; the first 
raster begins from the upper left corner to upper right corner.
Then, it is followed by next raster (one pixel down from the 
first raster). One raster is <EM>(width+7)/8</EM> bytes, and <VAR>bitmap</VAR> 
contains an encoded bitmap of <EM>((width+7)/8)*height</EM> bytes. 
Thus, the length of <VAR>bitmap</VAR> is <EM>2*((width+7)/8)*height</EM>.
<DT>When the command failed: <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>
<DD>
     <VAR>status</VAR> indicates that an error occurred.
</DL>

<DT><TT>BITMAP2</TT> <VAR>font_id</VAR> <VAR>code_point</VAR> [ <VAR>pixel_size</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]]
<DD>
Obtain a bitmap. This command corresponds to <CODE>VF_GetBitmap2()</CODE> function.
Response is the same as @command{BITMAP1} command.

<DT><TT>METRIC1</TT> <VAR>font_id</VAR> <VAR>code_point</VAR> [ <VAR>point_size</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]]
<DD>
Obtain a metric information of a font.
This command corresponds to <CODE>VF_GetMetric1()</CODE> function.

<B>Response:</B>
<DL COMPACT>

<DT>When the command is successful: <TT>( <VAR>status</VAR> <VAR>width</VAR> <VAR>height</VAR> <VAR>offx</VAR> <VAR>offy</VAR> <VAR>mvx</VAR> <VAR>mvy</VAR> )</TT>
<DD>
Each element of the response is the same as return 
values for @command{BITMAP1} command except for their units are points.
<DT>When the command failed: <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>
<DD>
     <VAR>status</VAR> indicates that an error occurred.
</DL>

<DT><TT>METRIC2</TT> <VAR>font_id</VAR> <VAR>code_point</VAR> [ <VAR>pixel_size</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]]
<DD>
Obtain a metric information of a font.
This command corresponds to <CODE>VF_GetMetric2()</CODE> function.

<B>Response:</B> Same as METRIC1 command except for units are points.

<DT><TT>FONTBBX1</TT> <VAR>font_id</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]
<DD>
Obtain font bounding information of a given font <VAR>font_id</VAR> opened
in mode 1. 
The argument <VAR>mag_x</VAR> <VAR>mag_y</VAR> are magnification factor
to be scaled.
This command corresponds to <CODE>VF_GetFontBoundingBox1()</CODE> function.

<B>Response:</B>
<DL COMPACT>

<DT>When the command is successful: <TT>( <VAR>status</VAR> <VAR>width</VAR> <VAR>height</VAR> <VAR>xoff</VAR> <VAR>yoff</VAR> )</TT>
<DD>
<VAR>width</VAR> and <VAR>height</VAR> are width and height
of bounding box, respectively.
<VAR>xoff</VAR> and <VAR>yoff</VAR> are the largest 
horizontal and vertical displacement of lower left corner of 
bounding box from reference points.
Note that these values does not guarantee the minimality;
they only guarantee that all characters can be contained in
a box described by them.
Units of return values are point.

<DT>When the command failed: <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>
<DD>
     <VAR>status</VAR> indicates that an error occurred.
</DL>

<DT><TT>FONTBBX2</TT> <VAR>font_id</VAR> [ <VAR>mag_x</VAR> <VAR>mag_y</VAR> ]
<DD>
Arguments and return values are the same except
<VAR>font_id</VAR> must be in mode 2 and
units of return values are pixel.

<DT><TT>PROPERTY</TT> <VAR>font_id</VAR> <VAR>property_name</VAR>
<DD>
Obtain a property named <VAR>property_name</VAR> of a font <VAR>font_id</VAR>.

<B>Response:</B>
<DL COMPACT>

<DT>When the command is successful: <TT>( <VAR>status</VAR> <VAR>value</VAR> )</TT>
<DD>
<DT>When the command failed: <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>
<DD>
     <VAR>status</VAR> indicates that an error occurred.
</DL>

<DT><TT>MINIMIZE-BBX</TT> [ <VAR>flag</VAR> ]
<DD>
Select a mode whether a bitmap sent from a server
should be minimized or not. If <VAR>flag</VAR> is <CODE>ON</CODE>, bounding boxes of
bitmaps sent from a server is minimized not to contain white 
pixels as possible. 
If <VAR>flag</VAR> is <CODE>OFF</CODE>, bitmaps sent from a 
server is not guaranteed to be minimized bounding boxes.
If <VAR>flag</VAR> is not given, current mode is returned. 
Initial mode is <CODE>OFF</CODE>.

<B>Response:</B> The current mode is returned even if the operation fails or succeeds.
<DL COMPACT>

<DT>When the command is successful: <TT>( <VAR>status-code</VAR> <VAR>mode</VAR> )</TT>
<DD>
      <VAR>Mode</VAR> is one of <CODE>ON</CODE> or <CODE>OFF</CODE>.
<DT>When the command failed: <TT>( <VAR>status-code</VAR> <VAR>mode</VAR> )</TT>
<DD>
      <VAR>Mode</VAR> is one of <CODE>ON</CODE> or <CODE>OFF</CODE>.
</DL>

<DT><TT>QUIT</TT>
<DD>
Finish interaction between a server and a client.
This operation always succeeds.

<B>Response:</B>   <TT>( <VAR>status</VAR> <VAR>message</VAR> )</TT>

</DL>



<H2><A NAME="SEC97" HREF="VFlib-36_toc.html#TOC97">vfltest</A></H2>

<P>
<A NAME="IDX97"></A>


<P>
@command{vfltest} displays glyph of a given font and characters
by ASCII-art form on a character terminal.
It does not requires X Window System, but the font of the terminal must be
a fixed-width font, since bitmaps are printed by ASCII-art form.


<P>
<B>Usage:</B> <TT>vfltest</TT> [ <VAR>OPTIONS...</VAR> ] <VAR>FONT_NAME</VAR> <VAR>CHAR_LIST</VAR>


<P>
<B>Options:</B>


<DL COMPACT>

<DT><TT>-mode1</TT>
<DD>
A font is opened in mode 1 (high resolution device oriented mode).

<DT><TT>-mode2</TT>
<DD>
A font is opened in mode 2 (low resolution device oriented mode).

<DT><TT>-ol</TT>
<DD>
Bitmaps are obtained by <CODE>VF_GetOutline()</CODE>
and then <CODE>VF_OutlineToBitmap()</CODE>.
This option is effective only when a font is opened in mode 1.

<DT><TT>-v</TT> <VAR>vflibcap</VAR>
<DD>
A file name of vflibcap to be used. If this option is not given,
default vflibcap file is used. (Possibly, default vflibcap is
<TT>`/usr/local/share/VFlib/3.6.14/vflibcap'</TT>.)
  
<DT><TT>-p</TT> <VAR>point</VAR> or <TT>-p</TT> <VAR>pixel</VAR>
<DD>
Specify point or pixel size of characters.
If this option is not given, size of characters
are original size of a font.

<DT><TT>-d</TT> <VAR>dpi</VAR>
<DD>
Give a device resolution in DPI. 
This option is effective only when a font is opened in mode 1.

<DT><TT>-m</TT> <VAR>mag</VAR>
<DD>
Specify vertical and horizontal magnification factor.
If this option is not given, magnification factor is 1.0.

<DT><TT>-mx</TT> <VAR>mag_h</VAR>
<DD>
Specify horizontal magnification factor.
If this option is not given, horizontal magnification factor is 1.0.

<DT><TT>-my</TT> <VAR>mag_v</VAR>
<DD>
Specify vertical magnification factor.
If this option is not given, vertical magnification factor is 1.0.

<DT><TT>--help</TT>
<DD>
Print command line arguments and key operations on a window.

</DL>

<P>
A list of character is a sequence of the following forms.


<DL COMPACT>

<DT><VAR>code</VAR>
<DD>
A character is given by character code.
Decimal (e.g., <SAMP>`34'</SAMP>) and  Hexa-decimal (e.g., <SAMP>`0x67'</SAMP>) 
numbers can be used.

<DT><VAR>from</VAR> <TT>-</TT> <VAR>to</VAR>
<DD>
This form specifies characters by a range of character code, 
from <VAR>from</VAR> to <VAR>to</VAR>  (e.g., <SAMP>`0x20 - 0x7e'</SAMP>).
Space characters are necessary before and after minus sign (<CODE>-</CODE>).

<DT><TT>=</TT><VAR>charlist</VAR>
<DD>
This form specifies characters by a list of 1-byte characters, 
e.g., <SAMP>`=abcdefg'</SAMP>.

</DL>



<H2><A NAME="SEC98" HREF="VFlib-36_toc.html#TOC98">vflx11</A></H2>

<P>
<A NAME="IDX98"></A>


<P>
@command{vflx11} displays glyph of a given font in a window.  
It requires X11R5 or X11R6. 


<P>
<B>Usage:</B> <TT>vflx11</TT> [ <VAR>OPTIONS...</VAR> ] <VAR>FONT_NAME</VAR>


<P>
<B>Options:</B>


<DL COMPACT>

<DT><TT>-mode1</TT>
<DD>
A font is opened in mode 1 (high resolution device oriented mode).

<DT><TT>-ol</TT>
<DD>
Bitmaps are obtained by <CODE>VF_GetOutline()</CODE>
 and then <CODE>VF_OutlineToBitmap()</CODE>.
This is effective when a font is opened in mode 1.

<DT><TT>-mode2</TT>
<DD>
A font is opened in mode 2 (low resolution device oriented mode).

<DT><TT>-v</TT> <VAR>vflibcap</VAR>
<DD>
A file name of vflibcap to be used. If this option is not given,
default vflibcap file is used. (Possibly, default vflibcap is
<TT>`/usr/local/share/VFlib/3.6.14/vflibcap'</TT>.)
  
<DT><TT>-p</TT> <VAR>point</VAR> or <TT>-p</TT> <VAR>pixel</VAR>
<DD>
Specify point or pixel size of characters.
If this option is not given, size of characters
are original size of a font.

<DT><TT>-m</TT> <VAR>mag</VAR>
<DD>
Specify vertical and horizontal magnification factor.
If this option is not given, magnification factor is 1.0.

<DT><TT>-mx</TT> <VAR>mag_h</VAR>
<DD>
Specify horizontal magnification factor.
If this option is not given, horizontal magnification factor is 1.0.

<DT><TT>-my</TT> <VAR>mag_v</VAR>
<DD>
Specify vertical magnification factor.
If this option is not given, vertical magnification factor is 1.0.

<DT><TT>--help</TT>
<DD>
Print command line arguments and key operations on a window.

</DL>

<P>
Following operations are defined on a @command{vflx11} window. 


<DL COMPACT>

<DT><KBD>q</KBD>
<DD>
Finish @command{vflx11}

<DT><KBD>b</KBD>
<DD>
Go to previous page.

<DT><KBD>SPC</KBD>
<DD>
Go to next page.

<DT><KBD>[</KBD>
<DD>
Go to previous 4 page.

<DT><KBD>]</KBD>
<DD>
Go to next 4 page.

<DT><KBD>{</KBD>
<DD>
Go to previous 16 page.

<DT><KBD>}</KBD>
<DD>
Go to next 16 page.

<DT><KBD>+</KBD>
<DD>
Enlarge the window.

<DT><KBD>-</KBD>
<DD>
Shrink the window.

<DT><KBD>&#60;</KBD>
<DD>
Go to the first page.

<DT><KBD>&#62;</KBD>
<DD>
Go to the last page.

<DT><KBD>m</KBD>
<DD>
Mark the current page.

<DT><KBD>g</KBD>
<DD>
Goto the marked page.

</DL>



<H2><A NAME="SEC99" HREF="VFlib-36_toc.html#TOC99">vfldisol</A></H2>

<P>
<A NAME="IDX99"></A>
@command{vfldisol} displays `disassembled lists' 
of vector data of a given font and code points.


<P>
<B>Usage:</B> <TT>vfldisol</TT> [ <VAR>OPTIONS...</VAR> ] <VAR>FONT_NAME</VAR> <VAR>CODE</VAR> ...


<P>
<B>Options:</B>


<DL COMPACT>

<DT><TT>-v <VAR>VFLIBCAP</VAR></TT>
<DD>
A file name of vflibcap to be used. If this option is not given,
default vflibcap file is used. (Possibly, default vflibcap is
<TT>`/usr/local/share/VFlib/3.6.14/vflibcap'</TT>.)

<DT><TT>-d <VAR>DPI</VAR></TT>
<DD>
Resolution of device in dpi.
If this option is not given, default resolution of a font is used.

<DT><TT>-p <VAR>POINT</VAR></TT>
<DD>
Point size of characters.
If this option is not given, default point size of a font is used.

<DT><TT>-x</TT>
<DD>
Print hexadecimal dump of outline data instead of disassembled list.

</DL>



<H2><A NAME="SEC100" HREF="VFlib-36_toc.html#TOC100">ctext2pgm</A></H2>

<P>
<A NAME="IDX100"></A>
<A NAME="IDX101"></A>
<A NAME="IDX102"></A>
@command{ctext2pgm} creates an image file in PGM or PBM format
from a multilingual text file encoded by compound text format.
It also supports various text encodings such as 
Chinese, Japanese, Korean EUCs and Shift-JIS.
PGM and PBM formats are portable formats, image files can be
easily converted to another image format such as GIF, TIFF.
<A NAME="IDX103"></A>
<A NAME="IDX104"></A>
<A NAME="IDX105"></A>
<A NAME="IDX106"></A>


<P>
It supports various character sets and left-to-right
and right-to-left directionalities.
<A NAME="IDX107"></A>
<A NAME="IDX108"></A>


<DL COMPACT>

<DT>ISO 8859-1,2,3,4,5,7,8,9
<DD>
<A NAME="IDX109"></A>
 <A NAME="IDX110"></A>
 <A NAME="IDX111"></A>
 
--- Latin character sets, 
including Hebrew which is written from right to left.

<A NAME="IDX112"></A>
<A NAME="IDX113"></A>
<DT>Mule Arabic
<DD>
--- An Arabic script, written from right to left. 
This character set is used by the multilingual editor Mule.

<A NAME="IDX114"></A>
<A NAME="IDX115"></A>
<A NAME="IDX116"></A>
<DT>JIS X 0201, JIS X 0208, JIS X 0212
<DD>
--- Japanese character sets.

<A NAME="IDX117"></A>
<DT>GB 2312
<DD>
--- A Chinese character set.

<A NAME="IDX118"></A>
<DT>CNS 11641-1, CNS 11641-2
<DD>
--- Chinese character sets.

<A NAME="IDX119"></A>
<DT>KSC 5601
<DD>
--- A Hangle character set.

</DL>



<H3><A NAME="SEC101" HREF="VFlib-36_toc.html#TOC101">Running ctext2pgm</A></H3>

<P>
<B>Usage:</B> <TT>ctext2pgm</TT> [ <VAR>OPTIONS...</VAR> ] [ <VAR>file</VAR> ]


<P>
--- @command{ctext2pgm} reads <VAR>file</VAR> (if not given, reads standard input)
and prints image file to standard output.


<P>
<B>Example:</B>

<PRE>
% ctext2pgm -pgm -ctext -16 -times DOC-10.txt  &#62; IMAGE.pgm
</PRE>

<P>
(Never forget to redirect the output.)


<P>
<B>Options for VFlib:</B>


<DL COMPACT>

<DT><TT>-v <VAR>f</VAR></TT>
<DD>
--- a vflibcap file to be used by @command{ctext2pgm}.
Default value is <TT>`vflibcap-ctext2pgm'</TT>.
</DL>

<P>
<B>Options for input encoding and script:</B>


<DL COMPACT>

<DT><TT>-ctext</TT>
<DD>
--- Assume that an encoding of input file. 
(This is the default input encoding.)
Default writing directionality is set to left-to-right.

By this encoding, multiple character set can be used in an input text
by escape sequences.
Mixture of scripts of left-to-right and right-to-left directionalities
is also supported.

<DT><TT>-iso-8859-1</TT> or <TT>-latin-1</TT>
<DD>
--- Assume that input file is encoded by iso-8859-1.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-iso-8859-2</TT> or <TT>-latin-2</TT>
<DD>
--- Assume that input file is encoded by iso-8859-2.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-iso-8859-3</TT> or <TT>-latin-3</TT>
<DD>
--- Assume that input file is encoded by iso-8859-3.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-iso-8859-4</TT> or <TT>-latin-4</TT>
<DD>
--- Assume that input file is encoded by iso-8859-4.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-iso-8859-5</TT>, <TT>-cyrillic</TT> or <TT>-russian</TT>
<DD>
--- Assume that input file is encoded by iso-8859-5.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-iso-8859-7</TT> or <TT>-greek</TT>
<DD>
--- Assume that input file is encoded by iso-8859-7.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-iso-8859-8</TT> or <TT>-hebrew</TT>
<DD>
--- Assume that input file is encoded by iso-8859-7.
Escape sequence is not allowed in input file.
Default writing directionality is set to right-to-left.

<DT><TT>-iso-8859-9</TT> or <TT>-latin-5</TT>
<DD>
--- Assume that input file is encoded by iso-8859-9.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

<DT><TT>-euc-jp</TT> or <TT>-euc-jp1</TT>
<DD>
--- Assume that input file is encoded by Japanese EUC.
Default writing directionality is set to left-to-right.

JIS X 0201 Roman character set is used for code set 0, 
JIS X 0208 is used for code set 1, 
JIS X 0201 Kana is used for code set 2, and
JIS X 0212 is used for code set 3.

<DT><TT>-euc-jp2</TT>
<DD>
--- Same as <TT>-euc-jp1</TT> except 
ASCII character set is used for code set 0.

<DT><TT>-euc-kr</TT>
<DD>
--- Assume that input file is encoded by Korean EUC.
Default writing directionality is set to left-to-right.

ASCII character set is used for code set 0 and
KSC 5601 is used for code set 1. 

<DT><TT>-euc-cn</TT> or <TT>-euc-gb</TT>
<DD>
--- Assume that input file is encoded by Chinese EUC by simplified Hanzi.
Default writing directionality is set to left-to-right.

ASCII character set is used for code set 0, and
GB 2312 is used for code set 1.

<DT><TT>-euc-cns</TT>
<DD>
--- Assume that input file is encoded by Chinese EUC by traditional Hanzi.
Default writing directionality is set to left-to-right.

ASCII character set is used for code set 0, 
CNS 11643-1 is used for code set 1, and
CNS 11643-2 is used for code set 3.

<A NAME="IDX120"></A>
<DT><TT>-sjis</TT>
<DD>
--- Assume that input file is encoded by Shift-JIS.
Escape sequence is not allowed in input file.
Default writing directionality is set to left-to-right.

ASCII character set is used for code set 0, 
JIS X 0208 is used for code set 1, and

</DL>

<P>
<B>Options for directionality:</B>


<DL COMPACT>

<DT><TT>-l2r</TT>
<DD>
--- Select left-to-right directionality for typesetting.
<DT><TT>-r2l</TT>
<DD>
--- Select right-to-left directionality for typesetting.
</DL>

<P>
<B>Options for font selection:</B>


<DL COMPACT>

<DT><TT>-fixed</TT>, <TT>-times</TT>, <TT>-helv</TT> or <TT>-cour</TT>
<DD>
--- Select a font family: Fixed, Times, Helvetia, or Courier, respectively.
Default font family is Times.

<DT><TT>-bold</TT> or <TT>-italic</TT>
<DD>
--- Select a font face: bold or italic (or oblique), respectively.
Default face is normal.

<DT><TT>-14</TT>, <TT>-16</TT>, <TT>-18</TT> or <TT>-24</TT>
<DD>
--- Select a font set of 14-, 16-, 18-, or 24-dot, respectively.
Default font size if 16.

<DT><TT>-scale <VAR>n</VAR></TT>
<DD>
--- Select a scalable font set and scales the font to <I>n</I> dot.

<DT><TT>-m <VAR>m</VAR></TT>
<DD>
--- Specify vertical and horizontal magnification factors.
Default value is 1.

<DT><TT>-mx <VAR>m</VAR></TT>
<DD>
--- Specify horizontal magnification factor.

<DT><TT>-my <VAR>m</VAR></TT>
<DD>
--- Specify vertical magnification factor.

<DT><TT>-font-list</TT>
<DD>
--- Print all installed character sets and font names. Then exit the program.

</DL>

<P>
<B>Options for typesetting:</B>


<DL COMPACT>

<DT><TT>-b <VAR>s</VAR></TT>
<DD>
--- Specify factor of baseline skip. 
Baseline of a text is moved this value times dot-size of a selected font set.
Default value is 1.2.

<DT><TT>-center-line</TT>
<DD>
--- Each line is centered.
Output image is vertically and horizontally centered.

<DT><TT>-flush-left</TT>
<DD>
--- Each line is flushed left.
This is default mode if writing directionality is left-to-right.
Output image is flushed left.

<DT><TT>-left-line</TT>
<DD>
--- Each line is flushed left, but image is not flushed left.

<DT><TT>-flush-right</TT>
<DD>
--- Each line is flushed to right.
This is the default mode if writing directionality is right-to-left.
(Note that options @option{-flush-right} and @option{-r2l} are different
--- consider an English text including Arabic words in the same line.)
Output image is flushed right.

<DT><TT>-right-line</TT>
<DD>
--- Each line is flushed right, but image is not flushed right.

</DL>

<P>
It is important to notice that the difference 
of @option{-flush-left} and @option{-left-line} options 
(and @option{-flush-right} and @option{-right-line} options).
By @option{-flush-left} option, input text is typeset to flush each line left
and typeset result is placed in the left of an output image.
By @option{-left-line} option, input text is typeset to flush each line left
and does not specify how to put the typeset result in an output image.
The difference appears when the horizontal size of output image is 
explicitly given by @option{-pw} option.


<P>
<B>Options for output:</B>


<DL COMPACT>

<DT><TT>-pgm</TT> or <TT>-pgm-raw</TT>
<DD>
--- Select binary PGM format for image output.

<DT><TT>-pgm-ascii</TT>
<DD>
--- Select ascii PGM format for image output.
This is the default output mode.

<DT><TT>-pbm</TT> or <TT>-pbm-ascii</TT>
<DD>
--- Select ascii PBM format for output an image.

<DT><TT>-ascii-art</TT> or <TT>-ascii-art-v</TT>
<DD>
--- An image is printed as an ASCII art. (Vertical mode)
Baseline is vertical; thus this mode is similar 
to the @command{banner} command
on Unix.

<DT><TT>-ascii-art-h</TT>
<DD>
--- An image is printed as an ASCII art. (Horizontal mode)
Baseline is horizontal.

<DT><TT>-eps</TT>
<DD>
--- Select EPS format for image output.
By default, 16-dot font is printed by 12-point in EPS file.
To change the point size, use the <TT>-eps-ptsize</TT> option described below.

<DT><TT>-eps-ptsize <VAR>pt</VAR></TT>
<DD>
--- Select point size of characters for EPS output.
If this option is given, point size of each character is 
scaled to <VAR>pt</VAR> point regardless dot size of fonts. 

<DT><TT>-none</TT>
<DD>
--- An image is not shipped out.

<DT><TT>-r</TT>
<DD>
--- Reverse the black and white of output image.
(This option does not have effect when EPS is selected
for image output format.)

<DT><TT>-s <VAR>n</VAR></TT>
<DD>
--- Shrink factor for anti-aliased output.
<VAR>n</VAR> by <VAR>n</VAR> pixels are shrinked together and forms one pixel 
in an output image. 
This option has effect when output format is PGM and EPS.
Default value is 1.

<DT><TT>-pw <VAR>w</VAR></TT>
<DD>
--- Specify width of output image (in pixels).
If this option is not given, the width of output image is the 
smallest width to contain the glyph of all characters.

<DT><TT>-ph</TT>
<DD>
--- Specify height of output image (in pixels).
If this option is not given, the height of output image is the 
smallest height to contain the glyph of all characters.

<DT><TT>-g</TT>
<DD>
--- Specify horizontal and vertical margins of output image (in pixels).
Default margin is zero pixel.

<DT><TT>-gx</TT>
<DD>
--- Specify horizontal margin of output image (in pixels).
Default margin is zero pixel.

<DT><TT>-gy</TT>
<DD>
--- Specify vertical margin of output image (in pixels).
Default margin is zero pixel.

<DT><TT>-center-image</TT>
<DD>
--- An image of typeset text is horizontaly and vertically centered.

<DT><TT>-h-center-image</TT>
<DD>
--- An image of typeset text is horizontaly centered.

<DT><TT>-v-center-image</TT>
<DD>
--- An image of typeset text is vertically centered.

<DT><TT>-left-image</TT>
<DD>
--- An image of typeset text is flushed left.

<DT><TT>-right-image</TT>
<DD>
--- An image of typeset text is flushed right.

<DT><TT>-top-image</TT>
<DD>
--- An image of typeset text is flushed top.

<DT><TT>-bottom-image</TT>
<DD>
--- An image of typeset text is flushed bottom.

</DL>



<H3><A NAME="SEC102" HREF="VFlib-36_toc.html#TOC102">Making input files for ctext2pgm</A></H3>

<P>
Any text editor can be used to prepare input files for @command{ctext2pgm}.
Input files are plain texts. 
If you want to create an image containing multiple character sets,
save the files by <EM>compound text</EM> encoding.
<A NAME="IDX121"></A>
If you want to make images of Arabic text, use the @command{Mule} editor.
(@command{Mule} is an extension of @command{GNU Emacs} 
for multilingual text processing.)
For making images of Arabic script, @command{ctext2pgm} only supports 
a text created by Mule, ISO-8859-6 is not supported.
<A NAME="IDX122"></A>
<A NAME="IDX123"></A>
<A NAME="IDX124"></A>


<P>
Unlike TeX and HTML, 
newlines of input files are <EM>not</EM> ignored and 
a newline character in input text breaks line.
Thus, input text is typeset like  `verbatim' environment of LaTeX or
`&#60;PRE&#62; ... &#60;/PRE&#62;' tag of HTML.




<H3><A NAME="SEC103" HREF="VFlib-36_toc.html#TOC103">Commands in input text</A></H3>

<P>
Several commands can be embedded in text files such as font switch.
Command sequence starts by a backslash (<CODE>\</CODE>) followed by one character
which represents command name.
If you want to display a backslash character itself, use 
double backslashes <CODE>\\</CODE>. 


<P>
Following commands are defined:


<DL COMPACT>

<DT><CODE>\f</CODE>, <CODE>\t</CODE>, <CODE>\h</CODE>, <CODE>\c</CODE>
<DD>
--- Change of font families. 
Current font family is changed to 
fixed, times, Helvetia, courier, respectively.

<DT><CODE>\d</CODE>
<DD>
--- Current font family is changed to the default font family.
The default font family can be specified by a command line option.

<DT><CODE>\N</CODE>, <CODE>\B</CODE>, <CODE>\I</CODE>
<DD>
--- Change of font faces. 
Current font face is changed to normal, bold, italic, respectively.

<DT><CODE>\D</CODE>
<DD>
--- Current font face is changed to the default font face.
The default font face can be specified by a command line option.

<DT><CODE>\.</CODE>
<DD>
--- Same as <CODE>\d</CODE> followed by <CODE>\D</CODE>.

<DT><CODE>\(</CODE>
<DD>
--- Black and white of glyph of following characters are reversed.
This command is recommended <EM>only</EM> for fixed-width fonts.
(For the reason of current implementation,
 resulting bitmap is ugly for proportional fonts and you cannot 
 read the text in an image.)

Nesting of <CODE>\(</CODE> has no effect.

<DT><CODE>\)</CODE>
<DD>
--- End of reversing black and white.

<DT><CODE>\\</CODE>
<DD>
--- Print backslash itself.

</DL>



<H3><A NAME="SEC104" HREF="VFlib-36_toc.html#TOC104">Trouble shooting</A></H3>

<P>
In case you failed to obtain a desired image output, 
the following command line options for debugging may be useful.
(Debugging messages are printed to standard output.
The @option{-none} option is useful to suppress printing binary image
to your terminal. Otherwise, debugging message and image file
are printed together on your terminal!)


<DL COMPACT>

<DT><TT>-ds</TT>
<DD>
--- Print the state transition of the parser for compound text.
<DT><TT>-dr2l</TT>
<DD>
--- Print the state transition of bi-directionality handling.
<DT><TT>-df</TT>
<DD>
--- Print font name to be opened.
<DT><TT>-dbc</TT>
<DD>
--- Print each character glyph in ascii-art form.
<DT><TT>-dbl</TT>
<DD>
--- Print each line image by in ascii-art form.
<DT><TT>-dbp</TT>
<DD>
--- Print entire page image in ascii-art form.
<DT><TT>-dall</TT>
<DD>
--- Selects all debugging options above.
</DL>



<H1><A NAME="SEC105" HREF="VFlib-36_toc.html#TOC105">Difference between VFlib version 3.6 and 2</A></H1>

<P>
VFlib version 3.6 and version 2 are quite different and 
you should forget about VFlib version 2.


<DL COMPACT>

<DT>VFlib 2 was designed only for Japanese Kanji fonts
<DD>
   VFlib 3.6 can handle fonts for multilingual text printing.

<DT>Font metric is introduced in VFlib 3.6
<DD>
   VFlib 2 does not concepts on font metrics since it assumes
   all characters are the same metrics.
   Font metrics is introduced in VFlib 3.6 and proportional fonts
   can be used.

<DT>Syntax of vflibcap file
<DD>
   Syntax of vflibcap file is quite different.
   VFlib 2 adopted termcap-like notation, but now
   VFlib 3.6 adopts lisp-like notation.

<DT>Arguments and return values of function are changed
<DD>
   In VFlib 2, bitmaps of characters are written in a frame buffer
   which is given by argument.
   But in VFlib 3.6, a bitmap object is returned.

</DL>



<H1><A NAME="SEC106" HREF="VFlib-36_toc.html#TOC106">Acknowledgments</A></H1>

<P>
Since I released VFlib version 1, so many people helped me 
to improve VFlib.
I am grateful for all of them.
Special gratitude is due to Satoru Tomura, Ken'ichi Handa,
Werner Lemberg, and Ichiro Matsuda.




<H1><A NAME="SEC107" HREF="VFlib-36_toc.html#TOC107">Concept index</A></H1>

<P>
Jump to:
<A HREF="#cindex_a">a</A>
-
<A HREF="#cindex_b">b</A>
-
<A HREF="#cindex_c">c</A>
-
<A HREF="#cindex_e">e</A>
-
<A HREF="#cindex_f">f</A>
-
<A HREF="#cindex_g">g</A>
-
<A HREF="#cindex_h">h</A>
-
<A HREF="#cindex_i">i</A>
-
<A HREF="#cindex_j">j</A>
-
<A HREF="#cindex_k">k</A>
-
<A HREF="#cindex_l">l</A>
-
<A HREF="#cindex_m">m</A>
-
<A HREF="#cindex_p">p</A>
-
<A HREF="#cindex_r">r</A>
-
<A HREF="#cindex_s">s</A>
-
<A HREF="#cindex_t">t</A>
-
<A HREF="#cindex_u">u</A>
-
<A HREF="#cindex_v">v</A>
-
<A HREF="#cindex_w">w</A>
-
<A HREF="#cindex_z">z</A>
<P>
<H2><A NAME="cindex_a">a</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX112">Arabic</A>
<LI><A HREF="VFlib-36.html#IDX84">ASCII Japanese TeX Kanji font class</A>
</DIR>
<H2><A NAME="cindex_b">b</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX66">BDF font class</A>
</DIR>
<H2><A NAME="cindex_c">c</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX88">CCV</A>
<LI><A HREF="VFlib-36.html#IDX106">Chinese EUC</A>
<LI><A HREF="VFlib-36.html#IDX118">CNS 11641</A>
<LI><A HREF="VFlib-36.html#IDX89">code conversion system</A>
<LI><A HREF="VFlib-36.html#IDX90">code-conversion-files</A>
<LI><A HREF="VFlib-36.html#IDX121">compound text</A>
<LI><A HREF="VFlib-36.html#IDX1">Copyright</A>
<LI><A HREF="VFlib-36.html#IDX111">Cyrillic</A>
</DIR>
<H2><A NAME="cindex_e">e</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX75">eKanji font class</A>
<LI><A HREF="VFlib-36.html#IDX124">Emacs</A>
<LI><A HREF="VFlib-36.html#IDX103">EUC</A>
<LI><A HREF="VFlib-36.html#IDX62">explicit fonts</A>
</DIR>
<H2><A NAME="cindex_f">f</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX7">font class</A>
<LI><A HREF="VFlib-36.html#IDX8">font driver</A>
<LI><A HREF="VFlib-36.html#IDX13">FreeType</A>, <A HREF="VFlib-36.html#IDX70">FreeType</A>
</DIR>
<H2><A NAME="cindex_g">g</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX117">GB 2312</A>
<LI><A HREF="VFlib-36.html#IDX81">GF font class</A>
<LI><A HREF="VFlib-36.html#IDX123">GNU Emacs</A>
<LI><A HREF="VFlib-36.html#IDX3">GNU Library General Public License</A>
</DIR>
<H2><A NAME="cindex_h">h</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX68">HBF font class</A>
<LI><A HREF="VFlib-36.html#IDX110">Hebrew</A>
<LI><A HREF="VFlib-36.html#IDX10">High resolution oriented mode</A>
</DIR>
<H2><A NAME="cindex_i">i</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX63">implicit fonts</A>
<LI><A HREF="VFlib-36.html#IDX12">Installing VFlib</A>
<LI><A HREF="VFlib-36.html#IDX109">ISO 8859</A>
</DIR>
<H2><A NAME="cindex_j">j</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX85">Japanese comic font class</A>
<LI><A HREF="VFlib-36.html#IDX104">Japanese EUC</A>
<LI><A HREF="VFlib-36.html#IDX74">JG font class</A>
<LI><A HREF="VFlib-36.html#IDX114">JIS X 0201</A>
<LI><A HREF="VFlib-36.html#IDX115">JIS X 0208</A>
<LI><A HREF="VFlib-36.html#IDX116">JIS X 0212</A>
</DIR>
<H2><A NAME="cindex_k">k</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX77">KangXi</A>
<LI><A HREF="VFlib-36.html#IDX105">Korean EUC</A>
<LI><A HREF="VFlib-36.html#IDX15">kpathsea</A>
<LI><A HREF="VFlib-36.html#IDX119">KSC 5601</A>
</DIR>
<H2><A NAME="cindex_l">l</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX108">left-to-right directionality</A>
<LI><A HREF="VFlib-36.html#IDX2">LGPL</A>
<LI><A HREF="VFlib-36.html#IDX4">libVFlib.a</A>, <A HREF="VFlib-36.html#IDX17">libVFlib.a</A>
<LI><A HREF="VFlib-36.html#IDX5">libVFlib.so</A>, <A HREF="VFlib-36.html#IDX18">libVFlib.so</A>
<LI><A HREF="VFlib-36.html#IDX11">Low resolution oriented mode</A>
</DIR>
<H2><A NAME="cindex_m">m</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX87">Mojikyo font mapping class</A>
<LI><A HREF="VFlib-36.html#IDX78">Morohashi DaiKanwa</A>
<LI><A HREF="VFlib-36.html#IDX113">Mule</A>, <A HREF="VFlib-36.html#IDX122">Mule</A>
</DIR>
<H2><A NAME="cindex_p">p</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX102">PBM</A>
<LI><A HREF="VFlib-36.html#IDX67">PCF font class</A>
<LI><A HREF="VFlib-36.html#IDX101">PGM</A>
<LI><A HREF="VFlib-36.html#IDX80">PK font class</A>
</DIR>
<H2><A NAME="cindex_r">r</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX107">right-to-left directionality</A>
</DIR>
<H2><A NAME="cindex_s">s</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX120">Shift JIS</A>
</DIR>
<H2><A NAME="cindex_t">t</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX14">T1Lib</A>, <A HREF="VFlib-36.html#IDX72">T1Lib</A>
<LI><A HREF="VFlib-36.html#IDX79">TeX default and TeX font mapping font class</A>
<LI><A HREF="VFlib-36.html#IDX82">TFM font class</A>
<LI><A HREF="VFlib-36.html#IDX69">TrueType font class</A>
<LI><A HREF="VFlib-36.html#IDX86">Try font class</A>
<LI><A HREF="VFlib-36.html#IDX71">Type1 font class</A>
</DIR>
<H2><A NAME="cindex_u">u</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX76">Unicode</A>
</DIR>
<H2><A NAME="cindex_v">v</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX64">variables</A>
<LI><A HREF="VFlib-36.html#IDX83">VF font class</A>
<LI><A HREF="VFlib-36.html#IDX58">VFlib-3\_6.h</A>
<LI><A HREF="VFlib-36.html#IDX61">VFlib.fdb</A>, <A HREF="VFlib-36.html#IDX94">VFlib.fdb</A>
<LI><A HREF="VFlib-36.html#IDX6">vflibcap</A>, <A HREF="VFlib-36.html#IDX19">vflibcap</A>
<LI><A HREF="VFlib-36.html#IDX65">VFLIBCAP_PARAM_var</A>
<LI><A HREF="VFlib-36.html#IDX9">Virtual Font library</A>
</DIR>
<H2><A NAME="cindex_w">w</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX16">web2c</A>
</DIR>
<H2><A NAME="cindex_z">z</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX73">Zeit font class</A>
</DIR>




<H1><A NAME="SEC108" HREF="VFlib-36_toc.html#TOC108">Data type index</A></H1>

<P>
Jump to:
<A HREF="#tindex_s">s</A>
-
<A HREF="#tindex_v">v</A>
<P>
<H2><A NAME="tindex_s">s</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX20">struct vf_s_bitmap</A>
<LI><A HREF="VFlib-36.html#IDX22">struct vf_s_metric1</A>
<LI><A HREF="VFlib-36.html#IDX24">struct vf_s_metric2</A>
</DIR>
<H2><A NAME="tindex_v">v</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX21">VF_BITMAP</A>
<LI><A HREF="VFlib-36.html#IDX23">VF_METRIC1</A>
<LI><A HREF="VFlib-36.html#IDX25">VF_METRIC2</A>
<LI><A HREF="VFlib-36.html#IDX27">VF_OUTLINE</A>
<LI><A HREF="VFlib-36.html#IDX26">VF_OUTLINE_ELEM</A>
</DIR>




<H1><A NAME="SEC109" HREF="VFlib-36_toc.html#TOC109">Function index</A></H1>

<P>
Jump to:
<A HREF="#findex_v">v</A>
<P>
<H2><A NAME="findex_v">v</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX30">VF_ClearError</A>
<LI><A HREF="VFlib-36.html#IDX33">VF_CloseFont</A>
<LI><A HREF="VFlib-36.html#IDX43">VF_CopyBitmap</A>
<LI><A HREF="VFlib-36.html#IDX47">VF_DumpBitmap</A>
<LI><A HREF="VFlib-36.html#IDX29">vf_error</A>
<LI><A HREF="VFlib-36.html#IDX54">VF_FreeBitmap</A>
<LI><A HREF="VFlib-36.html#IDX55">VF_FreeMetric1</A>
<LI><A HREF="VFlib-36.html#IDX56">VF_FreeMetric2</A>
<LI><A HREF="VFlib-36.html#IDX34">VF_GetBitmap1</A>
<LI><A HREF="VFlib-36.html#IDX35">VF_GetBitmap2</A>
<LI><A HREF="VFlib-36.html#IDX40">VF_GetFontBoundingBox1</A>
<LI><A HREF="VFlib-36.html#IDX41">VF_GetFontBoundingBox2</A>
<LI><A HREF="VFlib-36.html#IDX36">VF_GetMetric1</A>
<LI><A HREF="VFlib-36.html#IDX37">VF_GetMetric2</A>
<LI><A HREF="VFlib-36.html#IDX38">VF_GetOutline</A>
<LI><A HREF="VFlib-36.html#IDX42">VF_GetProp</A>
<LI><A HREF="VFlib-36.html#IDX52">VF_ImageOut_ASCIIArt</A>
<LI><A HREF="VFlib-36.html#IDX53">VF_ImageOut_ASCIIArtV</A>
<LI><A HREF="VFlib-36.html#IDX51">VF_ImageOut_EPS</A>
<LI><A HREF="VFlib-36.html#IDX48">VF_ImageOut_PBMAscii</A>
<LI><A HREF="VFlib-36.html#IDX49">VF_ImageOut_PGMAscii</A>
<LI><A HREF="VFlib-36.html#IDX50">VF_ImageOut_PGMRaw</A>
<LI><A HREF="VFlib-36.html#IDX28">VF_Init</A>
<LI><A HREF="VFlib-36.html#IDX57">VF_InstallFontDriver</A>
<LI><A HREF="VFlib-36.html#IDX44">VF_MakeScaledBitmap</A>
<LI><A HREF="VFlib-36.html#IDX31">VF_OpenFont1</A>
<LI><A HREF="VFlib-36.html#IDX32">VF_OpenFont2</A>
<LI><A HREF="VFlib-36.html#IDX39">VF_OutlineToBitmap</A>
<LI><A HREF="VFlib-36.html#IDX45">VF_ReflectedBitmap</A>
<LI><A HREF="VFlib-36.html#IDX46">VF_RotatedBitmap</A>
</DIR>




<H1><A NAME="SEC110" HREF="VFlib-36_toc.html#TOC110">Program index</A></H1>
<P>
Jump to:
<A HREF="#pindex_c">c</A>
-
<A HREF="#pindex_v">v</A>
<P>
<H2><A NAME="pindex_c">c</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX100">ctext2pgm</A>
</DIR>
<H2><A NAME="pindex_v">v</A></H2>
<DIR>
<LI><A HREF="VFlib-36.html#IDX59">vflbanner</A>
<LI><A HREF="VFlib-36.html#IDX99">vfldisol</A>
<LI><A HREF="VFlib-36.html#IDX95">vfldrvs</A>
<LI><A HREF="VFlib-36.html#IDX60">VFlib3-config</A>
<LI><A HREF="VFlib-36.html#IDX91">vflmkcaptex</A>
<LI><A HREF="VFlib-36.html#IDX93">vflmkfdb</A>
<LI><A HREF="VFlib-36.html#IDX92">vflpp</A>
<LI><A HREF="VFlib-36.html#IDX96">vflserver</A>
<LI><A HREF="VFlib-36.html#IDX97">vfltest</A>
<LI><A HREF="VFlib-36.html#IDX98">vflx11</A>
</DIR>


<P><HR><P>
This document was generated on 27 February 2006 using
<A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.
</BODY>
</HTML>