From mcpong@cs.ust.hk Fri Jun 4 05:26:56 1993 Return-Path: Date: Fri, 4 Jun 93 18:23:56 HKT From: mcpong@cs.ust.hk (Dr. Man-Chi PONG) To: xiaofei@ifcss.org Subject: updated HBF Standard v1.0 Hanzi Bitmap Font (HBF) File Format Standard Version 1.0 -------------------------------------------------------- Written by: Man-Chi Pong Department of Computer Science The Hong Kong University of Science and Technology Clear Water Bay Kowloon Hong Kong mcpong@cs.ust.hk With contributions from many -- please see the Acknowledgement section. Draft v0.1 -- released for comment on 1993/02/17. Draft v0.2 -- released for comment on 1993/02/28. changes from v0.1: -- All property keywords related to HBF starts with "HBF_". -- "_" is used to separate the English words in the HBF keywords to make them more readable. -- "ENCODING" is renamed as "HBF_CODE_SCHEME" because "ENCODING" in X BDF means the hanzi code value of a glyph. -- "SEGMENT" is renamed as "HBF_CODE_RANGE"; more suggestive. Draft v0.3 -- released for comment on 1993/03/15. changes from v0.2: -- uniform naming of keywords: HBF_xxx_yyy. -- cut the details of X11R5 XLDF and BDF properties. -- simplify API. Draft v0.4 -- released for comment on 1993/04/30. changes from v0.3: -- found in BDF [2] that " can be used in a string (use ""). -- FONTBOUNDINGBOX & HBF_BITMAP_BOUNDING_BOX can have -ve xd yd; BNF in Appendix 1 updated. -- changes in API HBF_OpenFont() HBF_GetBitmap() and API routines return 0 if OK, non-zero if not OK. Draft v0.5 -- officially announced 1993/05/28 -- adopted as Hanzi Bitmap Font (HBF) File Format Standard Version 1.0 changes from v0.4: -- mention that HBF file name convention is not part of this standard. -- some minor presentation changes. Table of Content ---------------- 0. Acknowledgement 1. Introduction 2. Definition of terms 2.1 bitmap file 2.2 HBF file 3. Simple HBF file 4. Full HBF file Appendix 1: Formal Syntax of simple HBF file Appendix 2: Implementation -- Application Programming Interface (API) routines 0. Acknowledgement This document is the result of discussion via e-mail among a group of Chinese software developers who would like to see a standard way to access hanzi (Chinese character) bitmap files. The following is a list, in alphabetic order of the surnames, of the contributors to the discussion. CAI@neurophys.wisc.edu (CAI, Yidao) jiang@ifcss.org (JIANG, Yuan) lee@umunhum.stanford.edu (LEE, Fung Fung) A7621GAC@AWIUNI11.EDVZ.UniVie.AC.AT (LEMBERG, Werner) 87P0786@csdvax.csd.unsw.edu.au (NI, Hongbo) mcpong@cs.ust.hk (PONG, Man-Chi) simpson@math.psu.edu (SIMPSON, Stephen G.) tee@ecf.toronto.edu (TEE, Luns) yawei@bronze.ucs.indiana.edu (WEI, Ya-Gui) eric@coeus.ucsd.edu (YANG, Bo) Ricky.Yeung@eng.sun.cOM (YEUNG, Ricky) FARZ%NMUMUS.bitnet@vmd.cso.uiuc.edu (ZHANG, Roxin) ygz@cs.purdue.edu (ZHANG, Yongguang) All previous mail exchanges, related programs, the names in the mailing list (soft.list), etc., are ftp'able from ifcss.org:/software/fonts/d/. Also thanks to xiaofei@ifcss.org (WANG XiaoFei) who maintains the mailing list "soft-authors@ifcss.org" for the discussion. 1. Introduction The aim of the standard is to allow different software to access some canonical representation of "hanzi bitmap font" (HBF). This is achieved by using a separate "HBF file" to specify the HBF properties and to record the index (or file offset) information to access the separately existing "bitmap file(s)" of the HBF. The "bitmap file" exists independently of the "HBF file". The implementation of the standard will alleviate the problem that a certain software is usually distributed with its own hanzi bitmap file(s). This reduces the need to keep different formats of the same hanzi bitmap fonts, thus reducing the disk space requirement. It also provides an easy way to access existing commonly available bitmap files, such as those distributed with a commercial Chinese system running in PC. The purpose of this document is to describe the features and the formal syntax (using Extended Backus-Naur Form) of an "HBF file", based on the discussion in the mailing list "soft-authors@ifcss.org". The format of a "HBF file" is essentially based on that described in X11R5 X Logical Font Description (XLFD) Conventions version 1.4 [1] and X11R5 Bitmap Distribution Format (BDF) version 2.1 [2]. A "simple HBF file" contains the minimum number of properties relevant to a fixed-width HBF. A "full HBF file" can have all the properties of an X11R5 font file on top of the properties of a "simple HBF file". An "HBF file" for an HBF can have any number of properties between that of the "simple HBF file" and that of the "full HBF file" of the HBF. An "HBF file" can be converted easily to an X11R5 BDF file. The details of the X11R5 font properties specified in the "full HBF file" format can be found in References [1] and [2]. This document will concentrate on "simple HBF file". Software running in non-X window system can simply use the "simple HBF file" format, and ignore any optional X11R5 font properties. The HBF file naming convention is not part of this standard. However, to be consistent with most systems, it is highly recommended that an HBF file name has ".hbf" as the file name extension part. It is up to the applications to define the HBF file basenames. Some conventions should be useful, e.g., an HBF file specifying a "Big5-code" "Kai-style" "24x24-bitmap" font from the foundry "ETen-system" may be named as "b5k-24.hbf" or "b5k-24et.hbf", where in this case two characters are used to specify one attribute and the attributes are arranged in the above order according to the importance deemed by the author. (Note that this is only an example, not part of this standard.) The rest of this document is organized as follows. In section 2, some special terms used are defined. In section 3, the "simple HBF file" is described. In section 4, an example "full HBF file" is given. If the reader is not interested in X11R5 font properties, section 4 can be skipped. Appendix 1 gives the formal syntax of the "simple HBF file" format. For the sake of brevity, the syntax of the properties of the "full HBF file" is not described, and the details can be found in References [1] and [2]. Appendix 2 gives the application programming interface (API) routines to access an HBF file. The references are: [1] X Logical Font Description Conventions version 1.4, MIT X Consortium Standard, X11R5 (1991), by Jim Flowers of Digital Equipment Corporation. (available in X11R5 distribution mit/{hardcopy,doc}/XLFD/.) [2] Bitmap Distribution Format version 2.1, MIT X Consortium Standard, X11R5 (1991), by Adobe Systems, Inc. (available in X11R5 distribution mit/{hardcopy,doc}/BDF/.) 2. Definition of terms Each hanzi is represented by a two-byte "hanzi code" in a computer system, no matter which "hanzi code scheme" is used. The most significant byte of a hanzi code is also called "byte 1" (or "first byte") and the least significant byte "byte 2" (or "second byte") of the hanzi code. Every "Hanzi Bitmap Font" (HBF) consists of a "HBF file" and a set of one or more "bitmap file(s)". A "HBF file" is an ASCII text file which describes: (1) the properties of the font, and (2) for different ranges of valid hanzi code, the index (or file offset) information to the bitmap file(s). A "bitmap file" is a binary file of hanzi bitmaps indexed by the corresponding "HBF file". This "HBF File Format Standard v1.0" only takes care of uncompressed bitmap file which stores the "full bitmaps" of each hanzi. (Compressed bitmap files may be considered in future versions.) Common hanzi code schemes are: GB2312-80 Big5 Unicode Note that different vendors' bitmap files for Big5 may have different hanzi codes added for some uncommonly used hanzi. It is more precise to say that a certain Big5 hanzi code scheme corresponds to the scheme of "Big5 Vendor-or-System-Name version". Thus, we have "Big5 ETen v1.0" "Big5 ETen v2.0" which have different numbers of hanzi codes in the respective "bitmap files". 2.1 bitmap file A "bitmap file" is a file of binary data where the bitmaps of individual hanzi "glyphs" are linearized into the byte sequence in the file. (A glyph is a technical term in typography. It means a symbol that conveys information nonverbally. In this document, it refers to a hanzi symbol.) The bitmap of a glyph shows the shape of the hanzi, with bits '0' represent the background and bits '1' represent the shape of the hanzi in the upright position, as usually seen as black hanzi on white background. A bitmap of size "Width x Height" bits is stored as a sequence of Height*((Width+7)/8) bytes, where integer division with truncation of decimal places is used in the calculation. The bits are stored row-wise, with each row stored in ((Width+7)/8) bytes. The most significant bit of the first byte is the upper-left bit of the glyph image. The values of the unfilled bits of the last byte for a row of bits are immaterial. The bytes of the bitmaps follows each other consecutively. E.g., a 16x16 bitmap occupies 16*((16+7)/8) = 32 bytes a 15x16 bitmap occupies 16*((15+7)/8) = 32 bytes a 16x15 bitmap occupies 15*((16+7)/8) = 30 bytes a 64x64 bitmap occupies 64*((64+7)/8) = 512 bytes (Note that the most significant bit of a byte is precisely defined, independent of whether the machine is a little or a big endian machine.) 2.2 HBF file An "HBF file" is an ASCII text file following the X11R5 BDF format, but with modification to tailor for the characteristics of hanzi font, which is always a fixed pitch font (consisting of fixed width glyphs). The information in an HBF file is used to access bitmap file(s) and is also for human to read in order to get information on the relevant font. No binary data is allowed in an HBF file. An HBF file contains the font name and other properties of the font, followed by index (or file offset) information to the bitmap file(s). Each property of HBF is described in one line terminated with the system-specific end-of-line character. Each property is introduced by a keyword spelled as a string of upper case letters and the underscore characters. The keywords of X11R5 BDF are used, except when they are inappropriate. New keywords introduced for HBF properties are prefixed with "HBF_". If an HBF keyword is made up from more than one English word, the words are separated by "_" for better readability. Note that "_" is used as word separator in some X11R5 BDF keywords but not in others, whereas "_" is used consistently in HBF keywords. The property value is usually either a string or an integer-string. The term "integer-string" is used in Reference [1]. It actually means an "integer" in textual form. An unsigned integer can be given in either the decimal, hexadecimal, or octal format. An octal integer is introduced by the prefix '0'. A hexadecimal integer is introduced by the prefix "0x", as in the programming language C. For readability purpose, either a decimal or hexadecimal format is recommended, depending on which property is being specified. An unquoted string is not enclosed by a pair of double quotes '"'. A quoted string is enclosed by a pair of double quotes '"'. The letters in a string, either quoted or unquoted, are case insensitive, i.e. a lower case letter is equivalent to the corresponding upper case letter. The quote character '"' inside a string is represented as '""'. (This follows the convention used in X11R5 BDF files [2].) 3. Simple HBF file The following is an example simple HBF file which uses the bitmap files supplied in the ETen system Version 2.00.03. The keywords specific to HBF are preceded by "HBF_". Other keywords have the same meaning of the X11R5 BDF convention [2]. HBF_START_FONT 1.0 HBF_CODE_SCHEME Big5 ETen v2.00.03 FONT ETenKai24 HBF_BITMAP_BOUNDING_BOX 24 24 0 -2 FONTBOUNDINGBOX 24 24 0 -2 COMMENT Begin Logical Font Description -- 5 special properties for this FONT STARTPROPERTIES 5 FAMILY_NAME "kai" ADD_STYLE_NAME "fanti" DEFAULT_CHAR 0xA140 COPYRIGHT "public domain simple HBF file (1993)" NOTICE "The bitmap files are that of ETen system v2.00.03 or the equivalent." ENDPROPERTIES COMMENT Users should observe the copyright of the individual font bitmap files. CHARS 13867 HBF_START_BYTE_2_RANGES 2 HBF_BYTE_2_RANGE 0x40-0x7E HBF_BYTE_2_RANGE 0xA1-0xFE HBF_END_BYTE_2_RANGES COMMENT HBF_START_CODE_RANGES 4 HBF_CODE_RANGE 0xA140-0xA3BF SPCFONT.24 0 HBF_CODE_RANGE 0xA440-0xC67E STDFONT.24K 0 HBF_CODE_RANGE 0xC6A1-0xC8D3 SPCFSUPP.24 0 HBF_CODE_RANGE 0xC940-0xF9FE STDFONT.24K 388872 HBF_END_CODE_RANGES COMMENT COMMENT Non-hanzi symbol (408 chars) bitmaps in file "SPCFONT.24". COMMENT Vendor-specific symbols (365 chars) bitmaps in file "SPCFSUPP.24K". COMMENT Frequently-used hanzi (5401 chars) bitmaps followed by COMMENT less-frequently-used hanzi (7693 chars) bitmaps in file "STDFONT.24K". COMMENT COMMENT For the fourth HBF_CODE_RANGE of less-frequently-used hanzi, COMMENT the range is smaller in standard Big5: 0xC940-0xF9D5 (7652 chars); COMMENT and the offset 388872 bytes from the start of the file "STDFONT.24K" COMMENT is based on the information supplied by COMMENT simpson@math.psu.edu (Stephen G. Simpson) COMMENT -- these may vary depending on the version of the ETen system. HBF_END_FONT The following explains the properties which are relevant to this simple HBF file. (0) COMMENT string string: an optional comment. The COMMENT line can appear anywhere in the HBF file. (1) HBF_START_FONT formatVersion formatVersion: an unquoted string specifying which version of HBF file format standard this file is conformed to, so that backward compatibility can be supported even if there is a change in the format definition in later version. E.g. HBF_START_FONT 1.0 This serves to identify that it is an HBF Standard version 1.0 file. Note that the X11 BDF file keyword "STARTFONT" is not used. (2) HBF_CODE_SCHEME hanziCodeSchemeName bitmapSourceName bitmapSourceVersion hanziCodeSchemeName: an unquoted string representing the hanzi code scheme. bitmapSourceName, bitmapSourceVersion: optional unquoted strings (appeared together) representing the name of the source of the bitmap files and the version, respectively. Usually, the vendor or the system providing the bitmap files is the source of the bitmap files. This property HBF_CODE_SCHEME is similar to the X11R5 X Logical Font Description (XLFD) property CHARSET_REGISTRY. With this extra HBF_CODE_SCHEME property, one can easily see what hanzi code scheme the HBF file supports. Like CHARSET_REGISTRY, a clearing house is required to register the hanziCodeSchemeName and bitmapSourceName and bitmapSourceVersion. The "clearing house" effect is currently achieved by common consensus through discussion in the mailing list "soft-authors@ifcss.org". Accepted values for HBF_CODE_SCHEME in this Standard v1.0 are: GB2312-80 -- not simply "GB"; there are many GuoBiao's for hanzi. Big5 -- any so-called "Big5" bitmap file(s) can be used, but such bitmap file(s) must conform to the Big5 hanzi code standard without vendor-added hanzi code. The Big5 hanzi code scheme has the following valid code ranges for hanzi: 0xA440-0xC67E for frequently-used hanzi (5401 chars) 0xC940-0xF9D5 for less-frequently-used hanzi (7652 chars) Big5 ETen v2.00.03 -- not simply "Big5"; use specifically the bitmap files in the ETen system v2.00.03 which contains vendor-specific hanzi code. (Other bitmapSourceName and bitmapSourceVersion values are acceptable.) Unicode vendor v1.1 -- not simply "Unicode"; use the specific version "v1.1" supplied by "vendor". Unicode is still evolving and thus different versions exist. If an application wants to find a font conforming to a certain code scheme, it can match the hanziCodeSchemeName value of an HBF file. Further matches of bitmapSourceName and bitmapSourceVersion will give more precise conformance. These two values are not so important in most cases, and thus they are optional values. (3) FONT fontName fontName: either a simple case insensitive string with alphanumeric characters ('a'-'z', 'A'-'Z', '0'-'9') or a font name conforming to the X11R5 XLFD standard [1]. The later case is illustrated in the example full HBF file given in next section. Uninterested reader can ignore X11R5 XLFD related detail. The font name should be suggestive. E.g., the following refers to the same font, a 24x24 bitmap Kai style font from the ETen system: etenkai24 ETenKai24 ETENKAI24 (4) HBF_BITMAP_BOUNDING_BOX w h xd yd 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 the origin of the glyph bounding-box. Bounding-box values (w h xd yd) are the same for each glyph in a hanzi font which has fixed pitch. The values are in pixels of the output device. A bounding-box is shown below. |<--- width --->| = w - ----------------- - ^ | | | ^ | | | | | ascent | | | | | | | | | | height = h | | | | | baseline ---> - |---O-----------| | point "O" = Origin | | | | | descent = yd | | | | | v | | | v - ----------------- - |<--| xd The bitmap bounding-box bounds the bitmap of a glyph; thus its width and height are equal to the width and height of the bitmap. However, in an application, a line of text may contain glyphs from more than one font. The glyphs must be aligned along the horizontal "baseline" of the line of text. The baseline contains the "origins" of the glyph bounding-boxes. The origin of a bounding-box may not be at the lower left corner of the bounding-box because for some letters in an ASCII font, like 'g', 'j', 'Q', etc., they have "descents" extending below the baseline. The xd and yd values of a bounding-box specifies the offset of the origin from the lower left corner of the bounding-box. The HBF_BITMAP_BOUNDING_BOX value is actually the X11R5 BDF property "BBX" for individual glyph in a font. For a hanzi font, since all glyphs have equal bounding-box, we only specify the glyph bounding-box once as the HBF_BITMAP_BOUNDING_BOX property. Another related property FONTBOUNDINGBOX is described next. Some examples are then given to show the interaction of FONTBOUNDINGBOX and HBF_BITMAP_BOUNDING_BOX. (5) FONTBOUNDINGBOX wFont hFont xdFont ydFont 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 the origin of the font bounding-box. FONTBOUNDINGBOX is an X11R5 BDF property. The interpretation in HBF is the same as in X11R5 BDF. A glyph of a font, no matter it is variable width or fixed width, is usually shown within the extent of the font bounding-box for the glyph. A hanzi glyph bitmap (i.e. its bounding-box) may be placed anywhere inside the font bounding-box, Thus it is required that: w of font bounding-box >= w of bitmap bounding-box h of font bounding-box >= h of bitmap bounding-box The FONTBOUNDINGBOX allows for the specification of inter-glyph and inter-line-of-text spacing. Note that in most cases, the sizes of HBF_BITMAP_BOUNDING_BOX and FONTBOUNDINGBOX are the same; and the application need not concern with FONTBOUNDINGBOX if the application does not work with mixed fonts. In such case, the yd value of FONTBOUNDINGBOX (and HBF_BITMAP_BOUNDING_BOX) may still be non-zero due to the need to align nicely with an ASCII font along a line of text. E.g., use FONTBOUNDINGBOX 24 24 0 -2 instead of FONTBOUNDINGBOX 24 24 0 0 to align nicely with an ASCII font with "FONTBOUNDINGBOX 12 24 0 -2" which contains letters with descent "-2", such as 'g', 'j', 'Q', etc. The following shows an example of unequal bitmap and font bounding-boxes: Let --- be the boundary of the FONTBOUNDINGBOX 16 18 0 -2. ... be the top and bottom boundaries of the HBF_BITMAP_BOUNDING_BOX of a font consisting of 16x15 bitmap: HBF_BITMAP_BOUNDING_BOX 16 15 0 -1. |<--- width --->| = 16 ----------------- - a blank row--> | | ^ a blank row--> | | | |...............| - | |///////////////| ^ | |///////////////| | | |// 16x15 /////| | | |// bitmap /////| |15 |18 = FONTBOUNDINGBOX height. |///////////////| | | |///////////////| | | baseline ----> O---------------- | | point "O" = Origin (0,0) |///////////////| v | -1|...............| - | -1 = yd of HBF_BITMAP_BOUNDING_BOX. a blank row--> | | v -2----------------- - -2 = yd of FONTBOUNDINGBOX. The following are some more examples to illustrate the relationships between FONTBOUNDINGBOX and HBF_BITMAP_BOUNDING_BOX. Suppose we have five HBF files: HBF1, HBF2, HBF3, HBF4, HBF5. 16x16 bitmap HBFs: ------------------ HBF1: (HBF_BITMAP_BOUNDING_BOX and FONTBOUNDINGBOX are the same.) HBF_BITMAP_BOUNDING_BOX 16 16 0 -2 FONTBOUNDINGBOX 16 16 0 -2 HBF2: (to allow for inter-line-of-text spacing of 2 pixels with the glyph bitmap aligned at the bottom of the FONTBOUNDINGBOX) HBF_BITMAP_BOUNDING_BOX 16 16 0 -2 FONTBOUNDINGBOX 16 18 0 -2 16x15 bitmap HBFs: ------------------ HBF3: (to be aligned at the top of HBF1 glyph bitmap when shown with HBF1) HBF_BITMAP_BOUNDING_BOX 16 15 0 -1 FONTBOUNDINGBOX 16 16 0 -2 HBF4: (to be aligned at the bottom of HBF1 glyph bitmap when shown with HBF1) HBF_BITMAP_BOUNDING_BOX 16 15 0 -2 FONTBOUNDINGBOX 16 16 0 -2 HBF5: (to be aligned at the top of HBF2 glyph bitmap when shown with HBF2 and using the same FONTBOUNDINGBOX as HBF2) HBF_BITMAP_BOUNDING_BOX 16 15 0 -1 FONTBOUNDINGBOX 16 18 0 -2 (6) STARTPROPERTIES p p: an unsigned integer. (not optional.) (Note: in X11R5 BDF, this unsigned integer is optional.) It indicates the number of font properties that follow this line. The property names are those defined in the XLFD standard [1]. (7) FAMILY_NAME fontFamilyName fontFamilyName: a quoted string that identifies the "family" of typeface designs that are all variations of one basic typographic style. E.g., "kai-ti" (meaning "kai style") is a common hanzi font style: FAMILY_NAME "kai" (8) ADD_STYLE_NAME styleInfoString styleInfoString: a quoted string that identifies additional typographic style information that is not captured by other fields but is needed to identify the particular font. It is not a typeface classification field and is only used for uniqueness. E.g., ETenKai24 is a font of "fanti" glyphs (i.e., containig glyphs of "traditional hanzi") and we need to document this fact: ADD_STYLE_NAME "fanti" (9) DEFAULT_CHAR defaultCharCode defaultCharCode: an unsigned integer specifying the hanzi code to be used when an attempt is made to display an undefined or non-existent glyph in the font. E.g., 0xa140 is the blank character in the ETen system fonts: DEFAULT_CHAR 0xa140 An HBF file must specify this property to facilitate processing. (Note: in X11R5 BDF, this property is optional.) (10) COPYRIGHT string string: a human-understandable quoted string that gives the copyright information of the legal owner of the HBF file. E.g., an HBF file should not be copyrighted by anybody, thus: COPYRIGHT "public domain simple HBF file (1993)" (11) NOTICE string string: a human-understandable quoted string that gives the copyright information of the legal owner of the font design of the bitmap file(s). E.g., NOTICE "The bitmap files are that of ETen system v2.00.03 or the equivalent." (12) ENDPROPERTIES This line indicates the end of the STARTPROPERTIES section. (13) CHARS totalNumberOfGlyphsInFont totalNumberOfGlyphsInFont: an unsigned integer specifying the total number of the glyphs in this HBF. E.g., CHARS 13867 There are 13867 glyphs in the bitmap files of the ETen system v2.00.03 as illustrated in the HBF_START_CODE_RANGES section below. (14) HBF_START_BYTE_2_RANGES r r: an unsigned integer showing how many valid sub-ranges are represented by the byte 2 of the hanzi codes. E.g., there are two valid sub-ranges of byte 2 values for ETen Big5 code: START_BYTE_2_RANGES 2 (15) 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 hanzi codes. It is required that: 0 <= rangeStart <= rangeEnd <= 0xFF The sub-ranges must be given in increasing order. E.g., there are two valid sub-ranges of byte 2 values for ETen Big5 code: HBF_BYTE_2_RANGE 0x40-0x7E HBF_BYTE_2_RANGE 0xA1-0xFE (16) HBF_END_BYTE_2_RANGES This line indicates the end of the HBF_START_BYTE_2_RANGES section. (17) HBF_START_CODE_RANGES r r: an unsigned integer showing how many code-ranges of hanzi code are valid in the whole coding space of the HBF. E.g., there are four valid code-ranges in the ETen Big5 coding space: HBF_START_CODE_RANGES 4 (18) HBF_CODE_RANGE firstCode-lastCode bitmapFileName offset firstCode, lastCode: unsigned integers showing the first and the last hanzi code of a valid code-range of the coding space of the HBF. For 2-byte hanzi code, it is required that: 0 <= firstCode <= lastCode <= 0xFFFF No two HBF_CODE_RANGE lines should have overlapping code-ranges. The code-ranges must be given in increasing order of firstCode. bitmapFileName: an unquoted string of the name of the bitmap file containing the bitmaps for the glyphs in the code-range. offset: an unsigned integer (at least 32-bits) representing the file offset of the bitmap of the hanzi code firstCode in the bitmap file. Other bitmaps of the hanzi code in the same CODE_RANGE follows in the bitmap file. E.g., there are four valid code-ranges for the font ETenKai24 using ETen v2.00.03 bitmap files. The bitmaps are stored in three different files, with the frequently-used and less-frequently-used hanzi bitmaps stored in the same file "STDFONT.24K": HBF_CODE_RANGE 0xA140-0xA3BF SPCFONT.24 0 HBF_CODE_RANGE 0xA440-0xC67E STDFONT.24K 0 HBF_CODE_RANGE 0xC6A1-0xC8D3 SPCFSUPP.24 0 HBF_CODE_RANGE 0xC940-0xF9FE STDFONT.24K 388872 (19) HBF_END_CODE_RANGES This line indicates the end of the HBF_START_CODE_RANGES section. (20) HBF_END_FONT This line marks the end of the HBF file. Note that the X11 BDF file keyword "ENDFONT" is not used. 4. Full HBF file The following is an example full HBF file which is equivalent to the simple HBF file described in section 3, but with additional X11R5 font properties. The additional X11R5 XLFD and BDF font properties are assigned default values, possibly calculated from the property values in the simple HBF file. They have exactly the same meanings as described in References [1] and [2]. Please refer to them for detail. For those readers who are not interested in X11R5 related font properties, they can skip this section. HBF_START_FONT 1.0 HBF_CODE_SCHEME Big5 ETen v2.00.03 FONT ETenKai24 COMMENT COMMENT An equivalent full X11R5 XLFD conforming font name is COMMENT -eten-kai-medium-r-normal-fanti-24-240-80-80-c-240-big5.eten.v2.00.03-0 COMMENT which is formed from the first 14 properties listed in COMMENT the STARTPROPERTIES section below. COMMENT Any of these properties is optional, as in the simple HBF file. COMMENT SIZE 24 75 75 HBF_BITMAP_BOUNDING_BOX 24 24 0 -2 FONTBOUNDINGBOX 24 24 0 -2 COMMENT COMMENT Begin Logical Font Description -- 20 special properties for this FONT COMMENT STARTPROPERTIES 20 FOUNDRY "eten" FAMILY_NAME "kai" WEIGHT_NAME "medium" SLANT "r" SETWIDTH_NAME "normal" ADD_STYLE_NAME "fanti" PIXEL_SIZE 24 POINT_SIZE 240 RESOLUTION_X 80 RESOLUTION_Y 80 SPACING "c" AVERAGE_WIDTH 240 COMMENT '-' can't be used in full XLFD name, thus use '.' in CHARSET_REGISTRY CHARSET_REGISTRY "big5.eten.v2.00.03" CHARSET_ENCODING "0" FONTNAME_REGISTRY "" FONT_DESCENT 2 FONT_ASCENT 22 COMMENT COMMENT All the above properties are discussed in X11R5 XLFD Conventions [1]. COMMENT COMMENT The rest is the same as the simple HBF file in section 3. COMMENT DEFAULT_CHAR 0xA140 COPYRIGHT "public domain simple HBF file (1993)" NOTICE "The bitmap files are that of ETen system v2.00.03 or the equivalent." ENDPROPERTIES COMMENT Users should observe the copyright of the individual bitmap font files. CHARS 13867 HBF_START_BYTE_2_RANGES 2 HBF_BYTE_2_RANGE 0x40-0x7E HBF_BYTE_2_RANGE 0xA1-0xFE HBF_END_BYTE_2_RANGES COMMENT HBF_START_CODE_RANGES 4 HBF_CODE_RANGE 0xA140-0xA3BF SPCFONT.24 0 HBF_CODE_RANGE 0xA440-0xC67E STDFONT.24K 0 HBF_CODE_RANGE 0xC6A1-0xC8D3 SPCFSUPP.24 0 HBF_CODE_RANGE 0xC940-0xF9FE STDFONT.24K 388872 HBF_END_CODE_RANGES COMMENT COMMENT Non-hanzi symbol (408 chars) bitmaps in file "SPCFONT.24". COMMENT Vendor-specific symbols (365 chars) bitmaps in file "SPCFSUPP.24K". COMMENT Frequently-used hanzi (5401 chars) bitmaps followed by COMMENT less-frequently-used hanzi (7693 chars) bitmaps in file "STDFONT.24K". COMMENT COMMENT For the fourth HBF_CODE_RANGE of less-frequently-used hanzi, COMMENT the range is smaller in standard Big5: 0xC940-0xF9D5 (7652 chars); COMMENT and the offset 388872 bytes from the start of the file "STDFONT.24K" COMMENT is based on the information supplied by COMMENT simpson@math.psu.edu (Stephen G. Simpson) COMMENT -- these may vary depending on the version of the ETen system. HBF_END_FONT Appendix 1: Formal Syntax of simple HBF file. The following uses the formal notation Extended Backus-Naur Form (EBNF) to describe a simple HBF file. The syntax of full HBF file is similar, and the extra X11R5 properties are defined as in the documents [1] and [2]. A production rule has the following format: Non-terminal symbol ::= a combination of non-terminal symbols, terminal tokens, and meta-symbols. The left-hand-side can generate "items" on the right-hand side of each "production rule". The following is a list of meta-symbols: "." terminates a rule. "( items )" means a sequence of items. "{ item }" means item will be repeat for 0 or more times. "[ item ]" means item will be repeat for 0 or one times. "item1 | item2" means either item1 or item2 is valid. 'literal' is the literal string that should appear as it is (without the single-quote) in the rule. The terminal tokens (i.e. literals, keywords, identifiers, numbers or strings) can be separated by one or more blank or tab characters. The property keywords are spelled in upper case letters. Other terminal tokens (literals and identifiers) are case insensitive; i.e. lower case letter is equivalent to upper case letter. This ensures backward compatibility in MS-DOS environment. Comment lines can appear anywhere, which have the form: 'COMMENT' string EOLN EOLN stands for system-specific end-of-line character(s). unquotedString ::= char { char } . quotedString ::= '"' char { char } '"' . /* char can be any printable ASCII character. */ /* The character '"' is represented as '""' in a quotedString. */ unsignedInteger ::= digit { digit } . /* unsigned integer in C language */ /* short integer is not used */ /* digit can be any one of the ASCII characters '0' to '9'. */ /* unsignedInteger can be read in by C scanf functions using %i format */ signedInteger ::= [ '+' | '-' ] unsignedInteger . /* signed integer in C language */ /* short integer is not used */ /* signedInteger can be read in by C scanf functions using %i format */ unsignedInteger32 ::= digit { digit } . /* 32-bit unsigned integer */ /* unsignedInteger32 can be read in by C scanf functions using %l format */ HBFHeaderFile ::= 'HBF_START_FONT' formatVersion EOLN 'HBF_CODE_SCHEME' hanziCodeSchemeName [ bitmapSourceName bitmapSourceVersion ] EOLN 'FONT' fontName EOLN 'HBF_BITMAP_BOUNDING_BOX' w h xd yd EOLN 'FONTBOUNDINGBOX' wFont hFont xdFont ydFont EOLN X11R5FontPropertySection 'CHARS' totalNumberOfGlyphsInFont EOLN HBFByte2RangeSection HBFCodeRangeSection 'HBF_END_FONT' EOLN . formatVersion ::= unquotedString . hanziCodeSchemeName ::= unquotedString . bitmapSourceName ::= unquotedString . bitmapSourceVersion ::= unquotedString . fontName ::= unquotedString . w ::= unsignedInteger . /* usually in decimal format */ h ::= unsignedInteger . /* usually in decimal format */ xd ::= signedInteger . /* usually in decimal format */ yd ::= signedInteger . /* usually in decimal format */ wFont ::= unsignedInteger . /* usually in decimal format */ hFont ::= unsignedInteger . /* usually in decimal format */ xdFont ::= signedInteger . /* usually in decimal format */ ydFont ::= signedInteger . /* usually in decimal format */ totalNumberOfGlyphsInFont ::= unsignedInteger . /* usually in decimal format */ X11R5FontPropertySection ::= 'STARTPROPERTIES' numberOfX11R5FontProperties EOLN X11R5FontProperty { X11R5FontProperty } 'ENDPROPERTIES' EOLN . numberOfX11R5FontProperties ::= unsignedInteger . /* usually in decimal format */ X11R5FontProperty ::= 'FAMILY_NAME' fontFamilyName EOLN | 'ADD_STYLE_NAME' styleInfoString EOLN | 'DEFAULT_CHAR' defaultCharCode EOLN | 'COPYRIGHT' quotedString EOLN | 'NOTICE' quotedString EOLN . /* Only the X11R5FontProperty for simple HBF file is shown here. */ /* An X11R5FontProperty should appear once only. */ fontFamilyName ::= quotedString . styleInfoString ::= quotedString . defaultCharCode ::= unsignedInteger . /* usually in hexadecimal format */ HBFByte2RangeSection ::= 'HBF_START_BYTE_2_RANGES' numberOfByte2Ranges EOLN HBFByte2Range { HBFByte2Range } 'HBF_END_BYTE_2_RANGES' EOLN . numberOfByte2Ranges ::= unsignedInteger . /* usually in decimal format */ HBFByte2Range ::= 'HBF_BYTE_2_RANGE' rangeStart '-' rangeEnd EOLN . rangeStart ::= unsignedInteger . /* usually in hexadecimal format */ rangeEnd ::= unsignedInteger . /* usually in hexadecimal format */ HBFCodeRangeSection ::= 'HBF_START_CODE_RANGES' numberOfCodeRanges EOLN HBFCodeRange { HBFCodeRange } 'HBF_END_CODE_RANGES' EOLN . numberOfCodeRanges ::= unsignedInteger . /* usually in decimal format */ HBFCodeRange ::= 'HBF_CODE_RANGE' firstCode '-' lastCode bitmapFileName offset EOLN . firstCode ::= unsignedInteger . /* usually in hexadecimal format */ lastCode ::= unsignedInteger . /* usually in hexadecimal format */ bitmapFileName ::= unquotedString . offset ::= unsignedInteger32 . /* usually in decimal format */ /* offset to (large) bitmap file, thus need 32-bit unsigned integer value */ Appendix 2: Implementation -- Application Programming Interface (API) routines The following (abstract) data types are used: HBF_Handle /* a handle to access an HBF */ HBF_HandlePtr /* a pointer to an HBF_handle */ HBF_Byte /* an 8-bit byte */ HBF_BytePtr /* pointer to HBF_Byte sequence (a bitmap) */ HBF_HzCode /* 16-bit hanzi code represented as an unsigned integer */ String /* a pointer to a string of character */ A sample implementation in C can be: typedef unsigned char HBF_Byte ; typedef HBF_Byte * HBF_BytePtr ; typedef FILE * HBF_Handle ; typedef HBF_Handle * HBF_HandlePtr ; typedef char * String ; The following is a list of library routines for using an HBF file. The exact values of non-zero error codes are left undefined in this Standard v1.0. (They should be defined in future versions, after gaining experience from the actual implementation(s).) int HBF_OpenFont( IN char * hbfFileName, INOUT HBF_HandlePtr ptrHandleStorage ); /* Open and initialize an HBF file. * * The INOUT parameter "ptrHandleStorage" points to a storage * large enough to store the opened font handle. * This routine will assign the value of the opened handle * to this storage. * * RETURN 0 if the font given by the hbfFileName is opened successfully; * or non-zero if error. */ /************************************************************/ int HBF_CloseFont( IN HBF_Handle handle ); /* Close an HBF file. * * RETURN 0 if OK; * or non-zero if error. */ /************************************************************/ char * HBF_GetProperty( IN HBF_Handle handle, IN char * propertyName ); /* Get the property of the given propertyName. * * RETURN the character string as if appeared after the keyword of * the property in the property line in the HBF file, * starting with a non-blank character, with only one blank * character separating each pair of tokens in the string, * and with no trailing blanks; * or NULL if invalid HBF handle or invalid propertyName. * * The calling routine should NOT change the returned string. */ /************************************************************/ /* FONTBOUNDINGBOX information is expected to be frequently used, * thus a separate API routine to get this property. */ int HBF_GetFontBoundingBox( IN HBF_Handle handle, OUT unsigned int *width, OUT unsigned int *height, OUT int *xDisplacement, OUT int *yDisplacement ); /* Get the font bounding-box information for a given HBF. * * RETURN 0 if OK, and the font bounding-box information * is returned in OUT parameters; * or non-zero if invalid HBF handle. */ /************************************************************/ /* HBF_BITMAP_BOUNDING_BOX information is expected to be frequently used, * thus a separate API routine to get this property. */ int HBF_GetBitmapBoundingBox( IN HBF_Handle handle, OUT unsigned int *width, OUT unsigned int *height, OUT int *xDisplacement, OUT int *yDisplacement ); /* Get the glyph bitmap bounding-box information for a given HBF. * * RETURN 0 if OK, and the glyph bitmap bounding-box information * is returned in OUT parameters; * or non-zero if invalid HBF handle. */ /************************************************************/ int HBF_GetBitmap( IN HBF_Handle handle, IN HBF_HzCode hanziCode, INOUT HBF_BytePtr ptrBitmapBuffer ); /* Get the bitmap for the given hanzi code. * * The INOUT parameter "ptrBitmapBuffer" points to a buffer * large enough to store the byte sequence of the bitmap of * the hanzi. This routine will copy the bitmap sequence * into the buffer. * * RETURN 0 if the bitmap is found; * or non-zero if invalid HBF handle or invalid hanzi code, * and the BitmapBuffer's content is undefined. */ /* N.B.: * It is up to the application to show the bitmap properly within * the FONTBOUNDINGBOX, if different from HBF_BITMAP_BOUNDING_BOX. */ /************************************************************/ ######## End of HBF Standard v1.0 ########