next up previous contents index
Next: Further Functions for Subsetting Up: Font Subsetting Previous: Font File Organization and   Contents   Index


Functions for Subsetting

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)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} It returns a pointer to a memory block containing the subset data. The memory is allocated in the function and it is the responsability of the user to free this memory. The parameter 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.


next up previous contents index
Next: Further Functions for Subsetting Up: Font Subsetting Previous: Font File Organization and   Contents   Index
2004-10-04