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.
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.]
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.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
NO WARRANTY
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!
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:
Basic concept of 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:
% ./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 @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.
% ./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 @command{configure-site} script;
it invokes the @command{configure} script with typical settings shown above.
Options for configure script is as follows:
ttf.
(Application programs must be linked against
`libLIB.a' or `libLIB.so'.)
t1.
(Application programs must be linked against
`libLIB.a' or `libLIB.so'.)
kpathsea.
(Application programs must be linked against
`libLIB.a' or `libLIB.so'.)
% make [RET]
# make install [RET]
Installation directories are as follows:
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:
VFLIB_CCV_DIRECTORY.
If this variable is set, default runtime directory and
the value by VFLIB_RUNTIME_DIRECTORY variable are ignored.
VFLIB_ASCII_JTEX_DIRECTORY.
If this variable is set, default runtime directory and
the value by VFLIB_RUNTIME_DIRECTORY variable are ignored.
VFLIB_RUNTIME_SITE_DIRECTORY.
Install directories can be changed when you run configure
script by the @option{--prefix=} option, for example.
Invoke @command{configure} with @option{--help} option for details.
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.
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.
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.
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.
VF_Init()int VF_Init(char* vflibcap, char* variable_list)
/usr/local/lib/VFlib/3.6.14/vflibcap).
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., /usr/local/lib/VFlib/3.6.14/).
For example, vflibcap-tex is given, VFlib first look for
vflibcap-tex in current directory, and then, it looks for
the file under runtime directory.
Default runtime directory can be changed by an environment variable
VFLIB_RUNTIME_DIRECTORY on runtime.
If an environment variable VFLIB_VFLIBCAP_PATH is set,
the first argument of this function is ignored and
its value is used.
If an environment variable VFLIB_VFLIBCAP_DIRECTORY is set,
a vflibcap file is searched under a directory sepecified by this
environment variable.
variable_list 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
Variable=Value, separated by a comma ,.
For example, DPI=400, LEVEL=1, FOO=bar.
vf_errorint vf_error
VF_ClearError()void VF_ClearError(void)
VF_OpenFont1()
int VF_OpenFont1(char* font_name,
double dpi_x, double dpi_y, double point_size,
double mag_x, double mag_y)
VF_OpenFont1()
fails, a negative integer is returned.
VF_OpenFont2()
int VF_OpenFont2(char* font_name,
int pixel_size, double mag_x, double mag_y)
VF_OpenFont2()
fails, a negative integer is returned.
VF_CloseFont()int VF_CloseFont(int font_id)
VF_GetBitmap1()
VF_BITMAP VF_GetBitmap1(int font_id, long code_point,
double mag_x, double mag_y)
VF_OpenFont1().
Size of bitmap to be obtained can be specified by
mag_x and mag_y arguments.
VF_FreeBitmap().
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.
VF_GetBitmap2()
VF_BITMAP VF_GetBitmap2(int font_id, long code_point,
double mag_x, double mag_y)
VF_OpenFont2().
Size of bitmap to be obtained can be specified by pixel_size,
mag_x and mag_y arguments.
VF_FreeBitmap().
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.
VF_GetMetric1()
VF_METRIC1 VF_GetMetric1(int font_id, long code_point,
VF_METRIC1 metric1,
double mag_x, double mag_y)
VF_GetBitmap1().
VF_GetBitmap1()
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 VF_FreeMetric1().
VF_GetMetric2()
VF_METRIC2 VF_GetMetric2(int font_id, long code_point,
VF_METRIC2 metric2,
double mag_x, double mag_y)
VF_GetBitmap2().
VF_GetBitmap2()
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 VF_FreeMetric2().
VF_GetOutline()
VF_OUTLINE VF_GetOutline(int font_id, long code_point,
double mag_x, double mag_y)
VF_GetBitmap1().
VF_Outline2Bitmap(). (Default point size and device
resolution is also kept in the outline data.)
VF_OutlineToBitmap()
VF_OUTLINE VF_OutlineToBitmap(VF_OUTLINE outline,
double dpi_x, double dpi_y,
double point_size,
double mag_x, double mag_y)
VF_GetBitmap1(). The outline data
contains information on device resolution and point size
specified by VF_GetOutline(). (If not specified, default
values are used. Thus, bitmaps with a default size can be
obtained by giving -1 for the arguments).
VF_FreeBitmap().
VF_GetFontBoundingBox1()
int VF_GetFontBoundingBox1(int font_id,
double mag_x, double mag_y,
double* w, double* h,
double* xoff, double* yoff)
VF_GetFontBoundingBox2()
int VF_GetFontBoundingBox2(int font_id,
double mag_x, double mag_y,
int* w, int* h,
int* xoff, int* yoff)
Same as VF_GetFontBoundingBox1() except units of
font bounding box parameters are pixel.
VF_GetProp()char* VF_GetProp(int font_id, char* prop_name)
VF_CopyBitmap()VF_BITMAP VF_CopyBitmap(VF_BITMAP bm)
VF_FreeBitmap() if it is no longer needed.
VF_MakeScaledBitmap()
VF_BITMAP VF_MakeScaledBitmap(VF_BITMAP bm,
double mag_x, double mag_y)
VF_FreeBitmap() if the returned bitmap object
is no longer necessary.
VF_ReflectedBitmap()
VF_BITMAP VF_ReflectedBitmap(VF_BITMAP bm,
int refl_x, double refl_y)
VF_CopyBitmap().
VF_FreeBitmap() if the returned bitmap object
is no longer necessary.
VF_RotatedBitmap()VF_BITMAP VF_RotatedBitmap(VF_BITMAP bm, int angle)
VF_BM_ROTATE_0
VF_CopyBitmap().
VF_BM_ROTATE_90
VF_BM_ROTATE_180
VF_BM_ROTATE_270
VF_FreeBitmap() 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
VF_RotatedBitmap(bm, VF_BM_ROTATE_180)
and that of
VF_ReflectedBitmap(bm, 1, 1)
are different.
VF_DumpBitmap()void VF_DumpBitmap(VF_BITMAP bm)
VF_ImageOut_PBMAscii()
int VF_ImageOut_PBMAscii(VF_BITMAP bm, FILE *fp,
int image_width, int image_height,
int position_x, int position_y,
int margin_l, int margin_r,
int margin_t, int margin_b,
int reverse, int shrink,
char *prog, char *title)
VF_IMAGEOUT_POSITION_NONE
VF_IMAGEOUT_POSITION_LEFT.
VF_IMAGEOUT_POSITION_CENTER
VF_IMAGEOUT_POSITION_LEFT
VF_IMAGEOUT_POSITION_RIGHT
VF_IMAGEOUT_POSITION_NONE
VF_IMAGEOUT_POSITION_TOP.
VF_IMAGEOUT_POSITION_CENTER
VF_IMAGEOUT_POSITION_TOP
VF_IMAGEOUT_POSITION_BOTTOM
VF_ImageOut_PGMAscii()
int VF_ImageOut_PGMAscii(VF_BITMAP bm, FILE *fp,
int image_width, int image_height,
int position_x, int position_y,
int margin_l, int margin_r,
int margin_t, int margin_b,
int reverse, int shrink,
char *prog, char *title)
VF_ImageOut_PGMAscii().
If shrink is greater than 1, output image is anti-aliased (gray-scaled).
VF_ImageOut_PGMRaw()
int VF_ImageOut_PGMRaw(VF_BITMAP bm, FILE *fp,
int image_width, int image_height,
int position_x, int position_y,
int margin_l, int margin_r,
int margin_t, int margin_b,
int reverse, int shrink,
char *prog, char *title)
VF_ImageOut_PGMAscii().
If shrink is greater than 1, output image is anti-aliased (gray-scaled).
VF_ImageOut_EPS()
int VF_ImageOut_EPS(VF_BITMAP bm, FILE *fp,
int image_width, int image_height,
int position_x, int position_y,
int margin_l, int margin_r,
int margin_t, int margin_b,
int reverse, int shrink,
char *prog, char *title,
double ptsize, int pixsize)
VF_ImageOut_PGMAscii().
If shrink is greater than 1, output image is anti-aliased (gray-scaled).
Arguments ptsize and pixsize specify size of EPS bounding box;
pixsize pixels occupy ptsize points in physical paper.
VF_ImageOut_ASCIIArt()
int VF_ImageOut_ASCIIArt(VF_BITMAP bm, FILE *fp,
int image_width, int image_height,
int position_x, int position_y,
int margin_l, int margin_r,
int margin_t, int margin_b,
int reverse, int shrink)
VF_ImageOut_PGMAscii().
VF_ImageOut_ASCIIArtV()
int VF_ImageOut_ASCIIArtV(VF_BITMAP bm, FILE *fp,
int image_width, int image_height,
int position_x, int position_y,
int margin_l, int margin_r,
int margin_t, int margin_b,
int reverse, int shrink)
VF_ImageOut_PGMAscii().
VF_FreeBitmap()void VF_FreeBitmap(VF_BITMAP bm)
VF_FreeMetric1()void VF_FreeMetric1(VF_METRIC1 metric)
VF_FreeMetric2()void VF_FreeMetric2(VF_METRIC2 metric)
VF_InstallFontDriver()
int VF_InstallFontDriver(char* class_name,
int(*driver)(VF_FONT font,
char* class_name,
char* font_name,
int implicit_flag));
VF_OpenFont1() and VF_OpenFont2().
The function driver is called with parameters of the font
to be opened: font is a data object for font management
defined by VFlib internally. class_name is the font
class name. font_name is the name of the font to be
opened. This argument is the same as the argument of
VF_OpenFont1() and VF_OpenFont2().
implicit_font 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).
An application software that use VFlib must include a header file `VFlib-3_6.h'. Typically, this file is installed `/usr/local/include/' directory.
Never forget, that application software that uses VFlib must be linked against FreeType 1.2 or later (`libttf.a' or `libttf.so'), T1Lib 5.1 or later (`libt1.a' or `libt1.so'), and kpathsea 3.2 (`libkpathsea.a' or `libkpathsea.so'), if you configure VFlib to use them. (If VFlib is configured not to use them, they are not necessary.)
I recommend shared library versions for these optional libraries if you built a shared library version of VFlib.
#include <VFlib-3_6.h>
VFlib must be initialized before it is used.
char* vflibcap = "vflibcap";
char* params = "TeX_DPI=300, KPATHSEA_MODE=cx";
if (VF_Init(vflibcap, params) < 0){
fprintf(stderr, "Initializing VFlib: failed\n");
exit(1);
}
Following program fragment opens a font, obtains a bitmap, and print obtained bitmap.
int fid;
VF_BITMAP bm;
if ((fid = VF_OpenFont2("timR24.pcf", -1, 1.0, 1.0)) < 0){
fprintf(stderr, "Opening font: failed\n");
exit(1);
}
bm = VF_GetBitmap2(fid, 0x67, 1.0, 1.0);
VF_DumpBitmap(bm);
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.
/*
* 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 <stdio.h>
#include <stdlib.h>
#include <ctype.h>
#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 > 0){
if ((argc >= 1)
&& ((strcmp(argv[0], "-h") == 0) || (strcmp(argv[0], "--help") == 0))){
usage();
exit(0);
} else if ((argc >= 2) && (strcmp(argv[0], "-v") == 0)){
--argc; argv++;
vflibcap = argv[0];
--argc; argv++;
} else if ((argc >= 2) && (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) < 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)) < 0)
return;
VF_BitmapListInit(&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(&PageBuff, bm, pos_x, pos_y);
pos_x = pos_x + bm->mv_x;
}
page_bm = VF_BitmapListCompose(&PageBuff);
VF_DumpBitmap(page_bm);
VF_BitmapListFinish(&PageBuff);
VF_FreeBitmap(page_bm);
VF_CloseFont(fid);
}
/*EOF*/
By the following commands is used to comple the program.
% gcc -c `VFlib3-config --cflags` vflbanner.c % gcc -o vflbanner vflbanner.o `VFlib3-config --libs`
@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.
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.
Each VFlib fonts have its own parameters listed below:
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.
Note: 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.
The syntax of vflibcap file is lisp-like form.
A semicolon ; 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.
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:
"hello world" "a, b, c, d" "He said \"Thanks!\"." "a*(b+c)"
font-file hello\ world He\ said\ \"Thanks!\". a*\(b+c\)
Unlink lisp, there is no distinction between string and symbol in
vflibcap; they are the same data type.
That is, HELLO and "HELLO" are the same.
Parentheses is used to form a "list" like in lisp.
For example, (A B C) is a list of three strings.
List can be nested any depth, e.g.,
(A (B1 B2 B3) (C1 (C21 C22) C3)).
A vflibcap must be a sequence of s-expression of the following forms:
(define-default FONT-CLASS CAPABILITY-DEF ... )
(define-font NAME CAPABILITY-DEF ... )
(define-macro NAME CAPABILITY-DEF ... )
CAPABILITY-DEF must be a list of form
(CAPABILITY-NAME VALUE),
e.g., (font-file "/usr/local/share/fonts/".
Each font class defines its own set of capabilities and
capability sets can be different by font classes.
This is an example of vflibcap file.
;; 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"))
To avoid writing the same capabilities, macro feature is provided in vflib. In case of CAPABILITY-DEF is a string, it is treated as a macro and a macro definition for it is expanded. For instance,
(define-font timR18 MACRO-NAME (font-file "timR18.bdf"))
is a font definition using a macro MACRO-NAME.
Suppose a macro MACRO-NAME is defined as follows.
(define-macro MACRO-NAME (font-class bdf) (dpi 300))
Then, the font definition for timR24 is the same as follow.
(define-font timR18 (font-class bdf) (dpi 300)) (font-file "timR18.bdf"))
The rule of macr expand is as following procedure.
Some font classes (e.g., BDF, PCF) defines a font-directories
capability in vflibcap file.
This capability specifies a list of font directories, for instance,
(font-directories "/usr/local/fonts/" "/opt/fonts" "/usr/local/share/fonts//").
A font file can be searched recursively in a directory tree
if a font directory name ends by double slashes //.
Some font drivers support file search by kpathsea.
Typically, font files are located under `/usr/local/share/texmf'.
This directory is used to hold TeX-related files.
If a font driver supports searching by kpathsea,
a special name TEXMF can be given in a list of
font-directories capability. For instance,
suppose that
(font-directories "/opt1/fonts//" "TEXMF" "/opt2/fonts//")
is specified. Then files are searched under /opt1/fonts,
by kpathsea, and then /opt2/fonts, in this order.
Currently, pk, gf, tfm, vf, truetype, and type1 font classes suport searcing files by kpathsea.
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 VFlib.fdb.
The following is an example of FDB file.
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
Suppose that this FDB file is located in `/foo/bar/', for instance. The file tells us that there is a file `times__m.pfb' and absolute path name of the file is `/foo/bar/type1/t/times__m.pfb'.
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.
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 vflmkfdb.
See section vflmkfdb, for details of the program.
A FDB file must be located in a root of a font directory and its name must be `VFlib.fdb'. Even if there is a FDB file in a sub-directory of a font directory, VFlib does not look for it.
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.
In a vflibcap file, a font file name need not have a compressed type
extension, such as .gz.
When VFlib searches a font file, it internally adds compressed
type extension and finds a file.
Fonts explicitly defined in a vflibcap file are called explicit fonts. Fonts does not appear vflibcap file and searched by font drivers on demand are called implicit fonts.
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
($) followed by a variable name is given.
For instance, (dpi $TeX_DPI) can be used instead of (dpi 300).
The value for a variable must be defined somewhere.
Default value can be given in (define-default VFlib ...), which
will be explained later.
Default values can be overridden on initialization function of
VFlib VF_Init(), or Unix environment variables
VFLIBCAP_PARAM_var.
For example, VFLIBCAP_PARAM_TeX_DPI is defined, its value becomes the
value of the vflibcap variable TeX_DPI.
The value of an environment variable VFLIBCAP_PARAM_var
is parsed as an S-expression, not as an string.
Thus, if you want to specify a string ABC 123,
the value of an environment variablue must be \"abc 123\".
(Without double quotation, it will be a sequence of two strings.
Only the first one is effective and the second one is ignored.)
To specify global behavior of VFlib, (virtual) font class
VFlib is defined.
The following capability are defined.
implicit-font-classes (optional)
(implicit-font-classes "bdf" "pcf" "gf")
extension-hints (optional)
(extension-hints (".pcf" pcf) (".bdf" bdf) ("gf" gf))
variable-values (optional)
(variable-values ("TeX_DPI" "300") ("TeX_KPATHSEA_MODE" "cx") (v ("p1" "v1")
uncompression-programs (optional)
(uncompression-programs (".Z" "zcat") (".gz" "gzip -cd")
code-conversion-files (optional)
(code-conversion-files "iso8859-1_unicode.ccv".ccv")
use-kpathsea (optional)
"Yes" or "No".
example: (use-kpathsea "Yes")
kpathsea-mode (optional)
(kpathsea-mode "cx")
kpathsea-dpi (optional)
(kpathsea-mode 300)
kpathsea-program-name (optional)
(kpathsea-mode "xgdvi")
The BDF format is a bitmap font format encoded in human-readable, platform independent format for distributing X Window fonts.
This font class supports compressed font files and implicit fonts.
Capabilities for font class default:
font-directories (optional)
compression-extensions (optional)
uncompression-programs capability of
VFlib class default description gives a uncompression programs.)
example: (compression-extensions ".gz" ".Z")
dpi (optional)
(dpi 300)
dpi-x (optional)
(dpi-x 300)
dpi-y (optional)
(dpi-y 300)
aspect-ratio (optional)
(aspect-ratio 0.8)
properties (optional)
VF_GetProp()
example: (properties ("PROP-1" "value-1") ("PROP-2" "value-2"))
variable-values (optional)
(variable-values ("TeX_DPI" "300") ("TeX_KPATHSEA_MODE" "cx") ("TeX_KPATHSEA_PROGRAM" "/usr/X11R6/xldvi"))
Capabilities for font definition:
font-class (essential)
bdf.
font-directories (optional)
font-file (optional)
(font-file "timI24.bdf" "timR24.bdf")
point-size (optional)
VF_GetBitmap1()
and VF_GetMetric1().
example: (point-size 24.0)
pixel-size (optional)
VF_GetBitmap2()
and VF_GetMetric2().
example: (pixel-size 24)
magnification (optional)
(magnification 1.20)
character-set (optional)
encoding (optional)
font-character-set (optional)
font-file capability.
font-encoding (optional)
font-file capability.
The following example defines a font named iso8859_5-font
with ISO-8859-5 encoding by using a KOI8-R encoded font file.
(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"))Code conversion is done by a subsystem named CCV. See section Code conversion system for detail.
Font class name: pcf
Other specification is the same as BDF font class
except font class name is pcf.
Font class name: hbf
Other specification is the same as BDF font class
except font class name is hbf.
TrueType is a vector font font format.
This font class supports implicit fonts but does not support
compressed font files.
TrueType font driver uses FreeType library version 1.2
developed by David Turner, Robert Wilhelm, and Werner Lemberg.
See http://www.freetype.org/ for detail.
Font class name: truetype
Capabilities for font class default:
font-directories (optional)
TEXMF for a directory name.
point-size (optional)
pixel-size (optional)
dpi (optional)
dpi-x (optional)
dpi-y (optional)
aspect-ratio (optional)
hinting (optional)
on, "hinting" information is
used to render characters. This is effective when small characters
are rendered. If the value is off, 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.
platform-id (optional)
Microsoft, Macintosh, etc)
and encoding ID (Unicode, Shift-JIS, 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:
apple
macintosh, mac
ascii, iso
microsoft, windows, ms
any, ?, *
(platform-id "microsoft")
encoding-id (optional)
encoding-id
capability,
value of this encoding-id capability is one of strings below:
ascii
iso10464
iso8859-1
any, ?, *
encoding-id
capability,
value of this encoding-id capability is one of strings below:
unicode1.1
unicode2.0
iso10464
any, ?, *
encoding-id
capability,
value of this encoding-id capability is one of strings below:
symbol
unicode
shift-jis, sjis, ms-kanji
big5
rpc
wansung
johab
any, ?, *
encoding-id
capability,
value of this encoding-id capability is one of strings below:
roman
japanese
traditional-chinese
korean
arabic
hebrew
greek
russian
any, ?, *
(encoding-id "any")
properties (optional)
variable-values (optional)
Capabilities for font definition:
font-class (essential)
font-directories (optional)
TEXMF for a directory name.
font-file (optional)
point-size (optional)
pixel-size (optional)
dpi (optional)
dpi-x (optional)
dpi-y (optional)
magnification (optional)
aspect-ratio (optional)
hinting (optional)
font-number (optional)
encoding-force (optional)
(encoding-force "unicode")
character-set (optional)
encoding 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 encoding 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 Code conversion system
Code conversion files are specified in
code-conversion-files in VFlib font class default.
See section VFlib defaults.
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.
encoding (optional)
character-set capability,
this capability defines a external view of a font.
section Code conversion system
properties (optional)
jisx0212-row47-empty-sjis (optional)
yes 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 ftdump utility of FreeType package to check
internal encoding scheme of fonts.)
Type1 is a vector font font format used by PostScript. This font class supports implicit fonts but does not support compressed font files. This Type1 font driver uses T1Lib library version 5.1 or later developed by Rainer Menzner. See http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html for detail.
Be careful, VFlib does not work with old T1Lib. Obtain and install T1Lib 5.1 or later.
Currently, this font driver supports only 8-bit encoded fonts, i.e., it does not support for fonts of Japanese Kanji characters.
The function VF_GetOutline() 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 applica