HBF File Format

An HBF file is a US-ASCII-encoded, human-readable file describing a bitmap font in which all characters have identical dimensions and offsets. The character bitmaps are stored in separate binary files.

The HBF file format is based on X11 BDF [2]. An HBF file consists of a series of variable-length lines (terminated by carriage-return and linefeed or just linefeed) each beginning with a keyword consisting of uppercase letters, digits and underscores. Many of these are borrowed from BDF 2.1, and have the same meaning as there. They are described here for completeness. Additional keywords consist of "HBF_" followed by one or more English words separated by underscores. In either case, tokens on each input line are separated by one or more spaces.

Some definitions:

Lines beginning with the keyword "COMMENT" may appear anywhere in the file, and are ignored.

Other lines appear in the following order:

  1. HBF_START_FONT formatVersion

    formatVersion: a token specifying the version of the HBF file format the file conforms to, so that backward compatibility can be supported even if a later version of this specification defines an altered format. The version described in this specification is 1.1.

    Note that the X11 BDF file keyword "STARTFONT" is not used.

  2. HBF_CODE_SCHEME hanziCodeSchemeName

    hanziCodeSchemeName: one or more tokens representing the character code scheme used to index this font. See Code Schemes for possible values.

  3. FONT fontName

    fontName: one or more tokens naming the font. Case distinctions should be ignored in font name matching. E.g. the following all refer to the same font, a 24x24 bitmap Kai style font from the ETen system: eb5-24k, Eb5-24K, EB5-24K.

    For full X compatability, the font name may conform to the X11R6 XLFD standard [1], as in the example full HBF file included as an appendix.

  4. SIZE ptsize xres yres

    A BDF entry giving the point size of the font and the x- and y-resolutions of the device for which it was designed. These values will be unused unless BDF compatability is required.


    w, h: width and height of the bounding-box of the glyph bitmap.

    xd, yd: the x- and y-displacement of the lower left corner of the glyph bitmap bounding-box from its origin.

    The HBF_BITMAP_BOUNDING_BOX value corresponds to the BDF 2.1 property "BBX" for each individual glyph in a font. Since HBF is tailored to fonts in which all glyphs have the same size, this information need only be specified once.

  6. FONTBOUNDINGBOX w h xd yd

    w, h: width and height of the font bounding-box inside which the glyph bitmap of this HBF will be placed.

    xd, yd: the x- and y-displacement of the lower left corner of the font bounding-box from its origin.

    The relationship between HBF_BITMAP_BOUNDING_BOX and FONTBOUNDINGBOX is explained under Bounding Boxes.


    p: an unsigned integer, indicating the number of font properties that follow this line. (Note: in BDF 2.1, this whole properties section is optional.)

    There follow p lines, each comprising a property name and a value, which is either an integer or a quoted string. A quoted string is surrounded by double quotes ("), with any internal double quote represented by a pair of double quotes. These properties are defined in the XLFD standard [1]. Those particularly relevant to HBF are:

    An example full HBF file using more XLFD properties is included as an appendix.

    This line indicates the end of the STARTPROPERTIES section.

  9. CHARS n

    n: an unsigned integer specifying the total number of the glyphs in this font. This BDF 2.1 property is optional in HBF, as this number is determined by the byte-2 and code range properties. (This property was mandatory in HBF 1.0.)


    r: an unsigned integer showing how many valid sub-ranges are represented by the byte 2 of the character codes. This section is present if the character code comprises 2 or more bytes.

  11. HBF_BYTE_2_RANGE rangeStart-rangeEnd

    rangeStart, rangeEnd: unsigned integers showing the start and the end value of a valid sub-range represented by the byte 2 of the character codes.

    It is required that: 0 <= rangeStart <= rangeEnd <= 0xFF. The sub-ranges must be given in increasing order, and must not overlap. E.g., there are two valid sub-ranges of byte 2 values for the Big5 code:

            HBF_BYTE_2_RANGE 0x40-0x7E
            HBF_BYTE_2_RANGE 0xA1-0xFE

    This line indicates the end of the HBF_START_BYTE_2_RANGES section.

    The meaning and usage of "HBF_START_BYTE_3_RANGES", "HBF_BYTE_3_RANGE" and "HBF_END_BYTE_3_RANGES" are similar to those for "byte 2".


    r: an unsigned integer showing how many code-ranges of character code are valid in the whole coding space of the font.

  14. HBF_CODE_RANGE firstCode-lastCode bitmapFileName offset

    firstCode, lastCode: unsigned integers showing the first and the last character code of a valid code range of the coding space of the HBF. For a 2-byte character code, it is required that: 0 <= firstCode <= lastCode <= 0xFFFF. The code ranges must be given in increasing order, and must not overlap.

    bitmapFileName: an unquoted string of the name of the bitmap file containing the bitmaps for the characters in the code range. The form of the file name will depend on the native operating system, as will its interpretation. However, in most implementations the bitmap file name will be interpreted as if the current directory were the one containing the HBF file.

    offset: an unsigned integer (at least 32-bits) representing the file offset of the bitmap of the character code firstCode in the bitmap file.

    See Bitmap File Format for more details on how byte-2 ranges and code ranges describe the structure of the bitmap files.


    This line indicates the end of the HBF_START_CODE_RANGES section.


    This line marks the end of the HBF file. Note that the X11 BDF file keyword "ENDFONT" is not used.

Part of Hanzi Bitmap Font (HBF) File Format version 1.1.