
Format of PCF font files
========================

Header format
-------------

The file begins with a header with the following format (all fields are
32-bit little endian):

	version		0x70636601 (i.e. "pcf\1" in little-endian)
	count		Number of tables in the file.

This is followed by "count" table index records, each of which contains
four fields (all fields are 32-bit little endian):

	type		Type of table.
	format		Format of the table.
	size		Size of the table, in bytes.
	offset		Offset to the table, from the beginning of the file.

Type values:

	#define PCF_PROPERTIES              (1<<0)
	#define PCF_ACCELERATORS            (1<<1)
	#define PCF_METRICS                 (1<<2)
	#define PCF_BITMAPS                 (1<<3)
	#define PCF_INK_METRICS             (1<<4)
	#define PCF_BDF_ENCODINGS           (1<<5)
	#define PCF_SWIDTHS                 (1<<6)
	#define PCF_GLYPH_NAMES             (1<<7)
	#define PCF_BDF_ACCELERATORS        (1<<8)

Format flags:

	0x00000003		glyph padding size mask
	0x00000000		glyph padding is 1 byte in size
	0x00000001		glyph padding is 2 bytes in size
	0x00000002		glyph padding is 4 bytes in size
	0x00000004		set if byte order is MSBFirst
	0x00000008		set if bit order is MSBFirst
	0x00000030		scan index size mask
	0x00000000		scan index is 1 byte in size
	0x00000010		scan index is 2 bytes in size
	0x00000020		scan index is 4 bytes in size

	#define PCF_FORMAT_MASK         0xffffff00

	#define PCF_DEFAULT_FORMAT      0x00000000
	#define PCF_INKBOUNDS           0x00000200
	#define PCF_ACCEL_W_INKBOUNDS   0x00000100
	#define PCF_COMPRESSED_METRICS  0x00000100

Each table's section begins with a 32-bit little-endian value indicating
its format (duplicating the value in the table index record).  After
that, the endian-ness of values is defined by the format flags.

Metric values
-------------

Metric values can be stored in either "full" or "compressed" form.  The
"full" form is as follows:

	leftSideBearing		16-bit
	rightSideBearing	16-bit
	characterWidth		16-bit
	ascent				16-bit
	descent				16-bit
	attributes			16-bit

The "compressed" form is as follows:

	leftSideBearing		8-bit, 128-adjusted
	rightSideBearing	8-bit, 128-adjusted
	characterWidth		8-bit, 128-adjusted
	ascent				8-bit, 128-adjusted
	descent				8-bit, 128-adjusted

"128-adjusted" means that 128 is added to the value before it is encoded.
i.e. -1 becomes 127, 0 becomes 128, and 1 becomes 129.

The "PCF_COMPRESSED_METRICS" format flag will be present on tables that
contain compressed metrics.

PCF_PROPERTIES table
--------------------

The properties table starts with a 32-bit value indicating the number
of properties, followed by the property index records.  Each property
index record consists of the following fields:

	name		32-bit index into the atom table for the property's name.
	isString	8-bit flag that indicates if the property is string or int.
	value		32-bit property value (index into atom table if a string).

The index record table is padded to a 4-byte boundary and then is followed
by a 32-bit value indicating the size of the atom table.  The null-terminated
strings for the atom names follow this size value.

Atom name indexes are interpreted relative to the start of the first
null-terminated atom name.

PCF_ACCELERATORS and PCF_BDF_ACCELERATORS tables
------------------------------------------------

The accelerators table contains information about the whole font,
for accelerated access to certain properties:

	noOverlap			8-bit
	constantMetrics		8-bit
	terminalFont		8-bit
	constantWidth		8-bit
	inkInside			8-bit
	inkMetrics			8-bit
	drawDirection		8-bit
	pad					8-bit, set to zero
	fontAscent			32-bit
	fontDescent			32-bit
	maxOverlap			32-bit
	minbounds			full metric value
	maxbounds			full metric value
	ink_minbounds		full metric value, optional
	ink_maxbounds		full metric value, optional

The last two fields will only be present if "PCF_ACCEL_W_INKBOUNDS" is
present in the format flags for the table.  If it isn't present, the
minimum and maximum ink boundaries will need to be determined from the
metrics for the individual gluphs.

If both "PCF_ACCELERATORS" and "PCF_BDF_ACCELERATORS" are present, then
the latter table should be preferred.

PCF_METRICS and PCF_INK_METRICS tables
--------------------------------------

Metrics tables may be either "full" or "compressed".  Compressed tables
are indicated by the presence of the "PCF_COMPRESSED_METRICS" value in the
table's format flags.

A full metrics table contains a 32-bit count for the number of characters,
followed by that many full metric values.

A compressed metrics table contains a 16-bit count for the number of
characters, followed by that many compressed metric values.

PCF_BITMAPS table
-----------------

The bitmaps table begins with a 32-bit value indicating the number of
characters.  This is followed by a glyph offset table, consisting of
32-bit values.  The offsets are relative to the start of the bitmap
data area.

Following the glyph offset table are four 32-bit values indicating the
size of the bitmap data area for each glyph padding size.  The only one that
is really relevant is the one indicated by the table's format.

The remainder of the bitmaps table is the bitmap data area.

PCF_BDF_ENCODINGS table
-----------------------

The encodings table contains some information about the whole font:

	min_char_or_byte2		16-bit
	max_char_or_byte2		16-bit
	min_byte1				16-bit
	max_byte1				16-bit
	default_char			16-bit

This header is followed by a table of 16-bit values, which maps encoding
values (e.g. Latin1/Unicode) into actual glyph indices.  A glyph index of
0xFFFF indicates that there is no glyph in that position and the default
character should be used instead.

PCF_SWIDTHS and PCF_GLYPH_NAMES tables
--------------------------------------

These tables are not relevant to simple bitmap font renderers, and so we
don't document them at this time.
