There are two ways to obtain a subsetted font from an existing file. The user can (1) do it step by step which requires reading, decrypting, reorganizing and encrypting of the font file, and (2) use a high level function to do it without having to know anything about the details. For font subsetting, t1lib provides the function
char *T1_SubsetFont( int FontID, char *mask, unsigned int flags, int linewidth, unsigned long maxblocksize, unsigned long *bufsize)
FontID
as usual is used to tell
t1lib which file or font is to be used for the operation.
mask
points to an array of characters which has to be setup by the
user. This array must comprise exactly 256 characters and for the index of
each non-zero entry the charstring resulting from the current encoding is
preserved in the subsetted font. To give an instance, if the subset should
consist in the character 'A' only and we assume the current font specifies
StandardEncoding
, then the mask
-array should be initialized to
zeroes and mask['A']=1
or some other non-zero value.
The flags
parameter allows to control the subsetting operation. It
usually should be set to T1_SUBSET_DEFAULT
. In this case, the subset is
ASCII-hex encrypted, that is, as in a .pfa
-file. It is thus well-suited
for the verbatim insertion into a Postscript file. If the source font file in
question defines the encoding to be StandardEncoding
, the encoding is
not adjusted to the subset specified by mask
. By contrast, if the font
defines a FontSpecific
encoding, this encoding will be adjusted
according to the subset. This default behavior--which mimics what
e.g. dvips
seems to do--may be overwritten by OR'ing flags
with
T1_SUBSET_FORCE_REENCODE
, which leads to adjusting the encoding vector
in any case. Conversely, reencoding can be suppressed unconditionally by OR'ing
flags
with T1_SUBSET_SKIP_REENCODE
. If flags
is OR'ed
with T1_SUBSET_ENCRYPT_BINARY
, a buffer of mixed ASCII, binary and EOF
segment types is created and encryption is performed in binary mode. The
buffer's contents in this case represents a valid compact binary format file
(.pfb
). It is considerably smaller than a comparable .pfa
-file
but it is not suitable to be inserted into Postscript files.
The parameter linewidth
is used to specify the line length if ASCII-hex
encryption is used. Since--according to the Adobe speification--the first 8
encrypted bytes have to be stored one after the other without interspersed
white space, the allowed range of linwidth
is limited to 8 at the lower
bound. It is also limited at the upper bound by 1024, because writing that
long lines does not preserve the readability of the produced file.
The parameter maxblocksize
is important if binary encryption is
used. Then, this value specifies the maximum allowed segment size. For similar
reasons as discussed above, this value must be equal to or larger
than 4. There is no limit at the upper bound, because the maximum segment size
can be derived automatically follows from the target font file.
bufsize
must be a valid pointer to an unsigned long int
in the
context of the calling function. The size of the memory area to which the
function returns a pointer, is written to bufsize
. The calling function
needs this number to process to buffers contents, e.g., to write it to a file.
If errors occur in this function, NULL
is returned and T1_errno
is set to an appropriate value. If the font corresponding to FontID
is
not loaded, T1_errno
is set to T1ERR_INVALID_FONTID
.
T1ERR_INVALID_PARAMETER
is used to indicate that one of the further
arguments is out of range. T1ERR_ALLOC_MEM
and
T1ERR_FILE_OPEN_ERR
may also be set in this function. Finally,
T1ERR_UNSPECIFIED
may also be set if the charstring definition for
.notdef
could not be located. This is considered to be a fatal error.
An example of how to use the function described above is given in the file
subset.c
in the examples/
subdirectory of the distribution.