Info file: VFlib-36.info,    -*-Text-*-
produced by `texinfo-format-buffer'
from file `VFlib-36.texi'
using `texinfmt.el' version 2.38 of 3 July 1998.





 




File: VFlib-36.info, Node: Top, Up: (dir)

This is a TeXinfo version of 

     VVVVV    VVVV FFFFFFFFF  ll   ii   bb      
      VVV      VV   FF    FF lll   ii  bbb      
       VV      V    FF     F  ll        bb      
       VVV     V    FF        ll        bb      
        VV    VV    FF        ll   ii   bb bbb  
        VV    V     FF    F   ll  iii   bbb bbb 
        VVV   V     FFFFFFF   ll   ii   bb   bb    33     66     1    4
         VV  VV     FF    F   ll   ii   bb   bb   3  3   6      11   44
         VVV V      FF        ll   ii   bb   bb      3   6       1  4 4
          VV V      FF        ll   ii   bb   bb     33   666     1 4  4
          VVVV      FF        ll   ii   bb   bb      3   6  6    1 44444
           VV       FF        ll   ii   bb  bb    3  3   6  6    1    4
           VV      FFFF      llll iiii  b bbb      33  *  66  * 111   4

                                   User's Manual by Hirotsugu Kakugawa
                                           Final Revision: 26 Feb 2006




* Menu:

* Copyright::
* Copying::
* Introduction::
* Installing VFlib::
* Programming with VFlib::
* Writing a vflibcap::
* Debugging a vflibcap::
* Code conversion system::
* Utility programs::
* Sample programs::
* Difference between VFlib version 3.6 and 2::
* Concept index::
* Data type index::
* Function index::
* Program index::
* Acknowledgments::



File: VFlib-36.info, Node: Copyright, Next: Copying, Up: Top

Copyright
*********


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

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.





File: VFlib-36.info, Node: Copying, Next: Introduction, Prev: Copyright, Up: Top

Copying
*******

                  GNU LIBRARY GENERAL PUBLIC LICENSE
                         Version 2, June 1991

     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.]


Preamble
========

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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


GNU LIBRARY GENERAL PUBLIC LICENSE
==================================
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. 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.
  
  2. 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.

  3. 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:

       a.     The modified work must itself be a software library.

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

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

       d.     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.)

     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.

  4. 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.

  5. 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.

  6. 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.

  7. 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:

       a.     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.)

       b.     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.

       c.     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.

       d.     Verify that the user has already received a copy of
          these materials or that you have already sent this user a
          copy.

       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.

  8. 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:

       1.     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.

       2.     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.

  9.  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.

 10. 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.

 11.  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.

 12. 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.

 13. 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.

 14. 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.

 15. 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.

                                NO WARRANTY

 16. 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.

 17.  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.


                     END OF TERMS AND CONDITIONS


Appendix: How to Apply These Terms to Your New Libraries
========================================================

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).

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.

     ONE LINE TO GIVE THE LIBRARY'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) YEAR  NAME OF AUTHOR

     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.

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

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:

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

       SIGNATURE OF TY COON, 1 April 1990
       Ty Coon, President of Vice

That's all there is to it!




File: VFlib-36.info, Node: Introduction, Next: Installing VFlib, Prev: Copying, Up: Top

Introduction
************

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.

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.

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

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).

The VFlib system consists of two parts:

A library (`libVFlib.a' and/or `libVFlib.so')

     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.

A font database file (`vflibcap')

     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.


Basic concept of VFlib


Font Classes and Font Drivers

     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 *font driver*.  Service units provided by a
     font driver is called *font class*.  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 View of VFlib Font From The End-User

     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
     `vflibcap' 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.

Font Names and Font Searching Mechanism

     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 *explicit fonts*
     and fonts that are searched for by the font search feature are
     called *implicit fonts*.  Support for explicit and implicit fonts
     depends on font driver.


Obtaining Bitmaps (Glyph)

     Two interfaces are provided to obtain glyph (bitmaps) of a font.

     High resolution device oriented glyph

          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.

     Low resolution device oriented glyph

          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.








File: VFlib-36.info, Node: Installing VFlib, Next: Programming with VFlib, Prev: Introduction, Up: Top

Installing VFlib
****************

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

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:


   * FreeType VFlib is tested with FreeType 1.3.  (FreeType 1.0 does
     not work with current VFlib3.)
        - `http://www.freetype.org/'
        - `ftp://ftp.freetype.org/pub/freetype/freetype-1.3.tar.gz'

   * T1Lib VFlib is tested with T1Lib 5.1.
        - `ftp://sunsite.unc.edu/pub/Linux/libs/graphics/'
        - `http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html'
        - `ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/'

   * kpathsea VFlib is tested with kpathsea 3.2 in web2c-7.2b.
        - `ftp://ftp.ctan.org/tex-archive/system/web2c/'


 
  1.   VFlib is tested on the following platforms:
        * FreeBSD 2.2.2 and 3.2 on IBM PC-clones
        * Solaris 2.5.1 on Sun SPARC Stations

     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.

  2.  Go into the directory `VFlib3-3.6.14'.

  3.  Run the `configure' script.

          % ./configure  [RET]

     By default, VFlib does *not* 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 `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.

          % ./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]

     *Note:* See the `configure-site' script; it invokes the
     `configure' script with typical settings shown above.


     Options for configure script is as follows:


     --enable-shared
             Enable to build a shared library version of VFlib.  By
          default, shared library version is created, if the target
          system supports shared library.

     --disable-shared
             Disable to build a shared library version of VFlib.

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

     --enable-static
             Enable to build a shared library version of VFlib.

     --disable-bdf
             VFlib is built without the BDF font driver.

     --disable-pcf
             VFlib is built without the PCF font driver.

     --disable-hbf
             VFlib is built without the HBF font driver.

     --disable-gf
             VFlib is built without the TeX GF font driver.

     --disable-pk
             VFlib is built without the TeX PK font driver.

     --disable-tfm
             VFlib is built without the TeX TFM font driver.

     --disable-jtex
             VFlib is built without the Japanese TeX Kanji font
          driver.

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

     --disable-zeit
             VFlib is built without the Zeit (Syotai Kurabu) font
          driver.

     --disable-jg
             VFlib is built without the JG font driver.

     --disable-ekanji
             VFlib is built without the eKanji font driver.

     --disable-comic
             VFlib is built without the Japanese comic font driver.

     --disable-try
             VFlib is built without the Try font driver.

     --disable-mojikmap
             VFlib is built without the Mojikyo font mapping driver.

     --with-freetype[=LIB]
             FreeType library file is LIB.  Default value is `ttf'.
          (Application programs must be linked against `libLIB.a' or
          `libLIB.so'.)

     --with-freetype-includedir=DIR
             FreeType include files are in DIR.

     --with-freetype-libdir=DIR
             FreeType library files are in DIR.

     --with-t1lib[=LIB]
             T1Lib library file is LIB.  Default value is `t1'.
          (Application programs must be linked against `libLIB.a' or
          `libLIB.so'.)

     --with-t1lib-includedir=DIR
             T1Lib include files are in DIR.

     --with-t1lib-libdir=DIR
             T1lib library files are in DIR.

     --with-kpathsea=LIB
             Kpathsea library file is LIB.  Default value is
          `kpathsea'.  (Application programs must be linked against
          `libLIB.a' or `libLIB.so'.)

     --with-kpathsea-includedir=DIR
             Kpathsea include files are in DIR.

     --with-kpathsea-libdir=DIR
             Kpathsea library files are in DIR.


  4.  Run `make' to compile VFlib.

          % make  [RET]

  5. Become a super user (root) and run `make' with `install' option
     to install.  (Run `make' with `uninstall' option to uninstall.)

          # make  install [RET]

  6. If installation is successful, the following has been created:

     `libVFlib.a' and/or `libVFlib.so'
          These are the library files and linked with application
          programs.

     `vflserver', `vflmkcaptex', `vflx11', `vfltest', etc.
           -- A VFlib server and test programs on X11

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

          `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.

          `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.

          `vfltest' is a test program that displays characters on
          terminal by ascii-art form.


Installation directories are as follows:


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

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

     Under this directory, there are following subdirectories:

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

     `t1lib'
          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 `mkt1enc.sh'
          program in this directory.  By default, this directory
          contains files converted from encoding vector files in the
          `dvips' distribution.

     `ascii-jtex'
          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
          `VFLIB_ASCII_JTEX_DIRECTORY'.  If this variable is set,
          default runtime directory and the value by
          `VFLIB_RUNTIME_DIRECTORY' variable are ignored.

     `doc'
          This directory contains several papers on VFlib, written by
          Hirotsugu Kakugawa.

`/usr/local/share/VFlib/site/'
     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 (`/usr/local/share/VFlib/X.Y.Z/') 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
     `/usr/local/share/VFlib/site/', which is called "site directory".

     Before searching in `/usr/local/share/VFlib/X.Y.Z/', 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 `VFLIB_RUNTIME_SITE_DIRECTORY'.

`/usr/local/bin/'
     Binary programs such as `vflserver', `vflx11', etc are installed
     here.

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

`/usr/local/lib/'
     VFlib library files such as `libVFlib.a', `libVFlib.so' are
     installed here.


Install directories can be changed when you run `configure' script by
the `--prefix=' option, for example.  Invoke `configure' with `--help'
option for details.




File: VFlib-36.info, Node: Programming with VFlib, Next: Writing a vflibcap, Prev: Installing VFlib, Up: Top

Programming with VFlib
**********************


* Menu:

* Data types::
* Functions and variables::
* Building an application software with VFlib::
* A simple example::




File: VFlib-36.info, Node: Data types, Next: Functions and variables, Up: Programming with VFlib

Data types
==========

* Menu:

* bitmap type::
* metric1 type::
* metric2 type::
* outline type::




File: VFlib-36.info, Node: bitmap type, Next: metric1 type, Up: Data types

bitmap type
-----------

A bitmap object is a structure of the following:

     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;

`bbx_width' and `bbx_height' are the bitmap width and height.  A pair
of `off_x' and `off_y') forms a vector to the left-upper corner of the
bitmap from the reference point.  A pair of `mv_x' and `mv_y' 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.)

The unit of `bbx_width', `bbx_height', `off_x', `off_y', `mv_x', and
`mv_y' is pixels.  `bitmap' is a pointer to the bitmap data; one pixel
corresponds to one bit.

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.  `bitmap' 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 `raster'.  Although the
raster line length of a bitmap is (`bbx_width'+7)/8, it is not
guaranteed that this value is the same as `raster'.  The type of
`bitmap' is a pointer to `unsigned char' data object, and each
`unsigned char' data object contains eight pixels.  Let `P[0]' be the
start address of a raster line.  The `x'-th pixel counted from the
leftmost pixel (which is pixel 0) is 1 if and only if `P[x/8] &
(0x80>>(x%8))' is non-zero.

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




File: VFlib-36.info, Node: metric1 type, Next: metric2 type, Prev: bitmap type, Up: Data types

metric1 type
------------

A metric1 object is a structure of the following:

     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;


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




File: VFlib-36.info, Node: metric2 type, Next: outline type, Prev: metric1 type, Up: Data types

metric2 type
------------

A metric2 object is a structure of the following:

     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;

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




File: VFlib-36.info, Node: outline type, Prev: metric2 type, Up: Data types

outline type
------------

VFlib defines its private outline data formats for presenting vector
data of characters.  This data format is used by VFlib API functions
`VF_GetOutline()' and `VF_OutlineToBitmap()'.

Each font driver returns a outline data of a character of a font if a
font driver of that font supports `VF_GetOutline()' 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
`VF_GetOutline()' function and it constructs and return an outline
data which is a set of square; each square corresponds to a pixel of a
bitmap.

Note that not all font drivers support `VF_GetOutline()' 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.)

Outline data is defined as follows:

     /* Outline data */
     typedef long              VF_OUTLINE_ELEM;
     typedef VF_OUTLINE_ELEM   *VF_OUTLINE;

According to CPU architecture, `VF_OUTLINE_ELEM' is defined as `int'
if size of `long' is 8.

     typedef long              VF_OUTLINE_ELEM;

Outline data is an array of VF_OUTLINE_ELEM type (`long' or `int'
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.

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




