Home Explore Help
Sign In
cpp
/
oxygine-framework
mirror of https://github.com/oxygine/oxygine-framework
2
0
Fork 0
Files Issues 0 Wiki
Branch: http-shared-ptr
Branches Tags
oxygine-framewo...
/
3rdPartyTools
/
BMFont
/
doc
/
file_format.html

file_format.html 11 KB
Permalink History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206 
  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>Bitmap Font Generator - Documentation</title>
    4. 

  4. </head>
    5. 

  5. <body>
    6. 

  6. 

  7. <h1>Bitmap Font Generator - Documentation</h1>
    8. 

  8. 

  9. <p><a href="../documentation.html">Back to main page</a></p>
    10. 

  10. 

  11. <h2>File format</h2>
    12. 

  12. 

  13. <li><a href="#tags">File tags</a>
    14. 

  14. <li><a href="#bin">Binary file layout</a>
    15. 

  15. 

  16. <a name="tags"></a>
    17. 

  17. <h2>File tags</h2>
    18. 

  18. 

  19. <h3>info</h3>
    20. 

  20. 

  21. <p>This tag holds information on how the font was generated.</p>
    22. 

  22. 

  23. <table>
    24. 

  24. <tr><td width=100>face</td><td>This is the name of the true type font.</td></tr>
    25. 

  25. <tr><td>size</td><td>The size of the true type font.</td></tr>
    26. 

  26. <tr><td>bold</td><td>The font is bold.</td></tr>
    27. 

  27. <tr><td>italic</td><td>The font is italic.</td></tr>
    28. 

  28. <tr><td>charset</td><td>The name of the OEM charset used (when not unicode).</td></tr>
    29. 

  29. <tr><td>unicode</td><td>Set to 1 if it is the unicode charset.</td></tr>
    30. 

  30. <tr><td>stretchH</td><td>The font height stretch in percentage. 100% means no stretch.</td></tr>
    31. 

  31. <tr><td>smooth</td><td>Set to 1 if smoothing was turned on.</td></tr>
    32. 

  32. <tr><td>aa</td><td>The supersampling level used. 1 means no supersampling was used.</td></tr>
    33. 

  33. <tr><td>padding</td><td>The padding for each character (up, right, down, left).</td></tr>
    34. 

  34. <tr><td>spacing</td><td>The spacing for each character (horizontal, vertical).</td></tr>
    35. 

  35. <tr><td>outline</td><td>The outline thickness for the characters.</td></tr>
    36. 

  36. </table>
    37. 

  37. 

  38. <h3>common</h3>
    39. 

  39. 

  40. <p>This tag holds information common to all characters.</p>
    41. 

  41. 

  42. <table>
    43. 

  43. <tr><td width=100>lineHeight</td><td>This is the distance in pixels between each line of text.</td></tr>
    44. 

  44. <tr><td>base</td><td>The number of pixels from the absolute top of the line to the base of the characters.</td></tr>
    45. 

  45. <tr><td>scaleW</td><td>The width of the texture, normally used to scale the x pos of the character image.</td></tr>
    46. 

  46. <tr><td>scaleH</td><td>The height of the texture, normally used to scale the y pos of the character image.</td></tr>
    47. 

  47. <tr><td>pages</td><td>The number of texture pages included in the font.</td></tr>
    48. 

  48. <tr><td>packed</td><td>Set to 1 if the monochrome characters have been packed into each of the texture channels. In this case alphaChnl describes what is stored in each channel.</td></tr>
    49. 

  49. <tr><td>alphaChnl</td><td>Set to 0 if the channel holds the glyph data, 1 if it holds the outline, 2 if it holds the glyph and the outline, 3 if its set to zero, and 4 if its set to one.</td></tr>
    50. 

  50. <tr><td>redChnl</td><td>Set to 0 if the channel holds the glyph data, 1 if it holds the outline, 2 if it holds the glyph and the outline, 3 if its set to zero, and 4 if its set to one.</td></tr>
    51. 

  51. <tr><td>greenChnl</td><td>Set to 0 if the channel holds the glyph data, 1 if it holds the outline, 2 if it holds the glyph and the outline, 3 if its set to zero, and 4 if its set to one.</td></tr>
    52. 

  52. <tr><td>blueChnl</td><td>Set to 0 if the channel holds the glyph data, 1 if it holds the outline, 2 if it holds the glyph and the outline, 3 if its set to zero, and 4 if its set to one.</td></tr>
    53. 

  53. </table>
    54. 

  54. 

  55. <h3>page</h3>
    56. 

  56. 

  57. <p>This tag gives the name of a texture file. There is one for each page in the font.</p>
    58. 

  58. 

  59. <table>
    60. 

  60. <tr><td width=100>id</td><td>The page id.</td></tr>
    61. 

  61. <tr><td>file</td><td>The texture file name.</td></tr>
    62. 

  62. </table>
    63. 

  63. 

  64. <h3>char</h3>
    65. 

  65. 

  66. <p>This tag describes on character in the font. There is one for each included character in the font.</p>
    67. 

  67. 

  68. <table>
    69. 

  69. <tr><td width=100>id</td><td>The character id.</td></tr>
    70. 

  70. <tr><td>x</td><td>The left position of the character image in the texture.</td></tr>
    71. 

  71. <tr><td>y</td><td>The top position of the character image in the texture.</td></tr>
    72. 

  72. <tr><td>width</td><td>The width of the character image in the texture.</td></tr>
    73. 

  73. <tr><td>height</td><td>The height of the character image in the texture.</td></tr>
    74. 

  74. <tr><td>xoffset</td><td>How much the current position should be offset when copying the image from the texture to 
    75. 

  75. the screen.</td></tr>
    76. 

  76. <tr><td>yoffset</td><td>How much the current position should be offset when copying the image from the texture to 
    77. 

  77. the screen.</td></tr>
    78. 

  78. <tr><td>xadvance</td><td>How much the current position should be advanced after drawing the character.</td></tr>
    79. 

  79. <tr><td>page</td><td>The texture page where the character image is found.</td></tr>
    80. 

  80. <tr><td>chnl</td><td>The texture channel where the character image is found 
    81. 

  81. (1 = blue, 2 = green, 4 = red, 8 = alpha, 15 = all channels).</td></tr>
    82. 

  82. </table>
    83. 

  83. 

  84. <h3>kerning</h3>
    85. 

  85. 

  86. <p>The kerning information is used to adjust the distance between certain characters, e.g. some characters should 
    87. 

  87. be placed closer to each other than others.</p>
    88. 

  88. 

  89. <table>
    90. 

  90. <tr><td width=100>first</td><td>The first character id.</td></tr>
    91. 

  91. <tr><td>second</td><td>The second character id.</td></tr>
    92. 

  92. <tr><td>amount</td><td>How much the x position should be adjusted when drawing the second character immediately 
    93. 

  93. following the first.</td></tr>
    94. 

  94. </table>
    95. 

  95. 

  96. 

  97. <a name="bin"></A>
    98. 

  98. <h2>Binary file layout</h2>
    99. 

  99. 

  100. <p>This section describes the layout of the tags in the binary file format. To understand what each tag means refer 
    101. 

  101. to the <a href="#tags">file tags</A> section.</p>
    102. 

  102. 

  103. <p>The first three bytes are the file identifier and must always be 66, 77, 70, or "BMF". The fourth byte gives 
    104. 

  104. the format version, currently it must be 3.</p>
    105. 

  105. 

  106. <ul>
    107. 

  107. <li>Version 1 (introduced with application version 1.8).
    108. 

  108. <li>Version 2 (introduced with application version 1.9) added the outline field in the infoBlock and the encoded 
    109. 

  109.     field in the commonBlock.
    110. 

  110. <li>Version 3 (introduced with application version 1.10) removed the encoded field in the commonBlock, and 
    111. 

  111.     added the alphaChnl, redChnl, greenChnl, blueChnl instead. The size of each block is now stored without 
    112. 

  112.     accounting for the size field itself. The character id in the charsBlock and the kerningPairsBlock was increased 
    113. 

  113.     to 4 bytes to support the full unicode range. 
    114. 

  114. </ul>
    115. 

  115. 

  116. <p>Following the first four bytes is a series of blocks with information. Each block starts with a one byte block 
    117. 

  117. type identifier, followed by a 4 byte integer that gives the size of the block, not including the block type identifier 
    118. 

  118. and the size value.</p>
    119. 

  119. 

  120. <h3>Block type 1: info</h3>
    121. 

  121. 

  122. <table>
    123. 

  123. <tr><td width=100><b>field</b></td><td width=30><b>size</b></td><td width=40><b>type</b></td><td width=30><b>pos</b></td><td><b>comment</b></td></tr>
    124. 

  124. <tr><td>fontSize</td>    <td>2</td>         <td>int</td>     <td>0</td> <td></td></tr>
    125. 

  125. <tr><td>bitField</td>    <td>1</td>         <td>bits</td>    <td>2</td> <td>bit 0: smooth, bit 1: unicode, bit 2: italic, bit 3: bold, bit 4: fixedHeigth, bits 5-7: reserved</td></tr>
    126. 

  126. <tr><td>charSet</td>     <td>1</td>         <td>uint</td>    <td>3</td> <td></td></tr>
    127. 

  127. <tr><td>stretchH</td>    <td>2</td>         <td>uint</td>    <td>4</td> <td></td></tr>
    128. 

  128. <tr><td>aa</td>          <td>1</td>         <td>uint</td>    <td>6</td> <td></td></tr>
    129. 

  129. <tr><td>paddingUp</td>   <td>1</td>         <td>uint</td>    <td>7</td> <td></td></tr>
    130. 

  130. <tr><td>paddingRight</td><td>1</td>         <td>uint</td>    <td>8</td> <td></td></tr>
    131. 

  131. <tr><td>paddingDown</td> <td>1</td>         <td>uint</td>    <td>9</td> <td></td></tr>
    132. 

  132. <tr><td>paddingLeft</td> <td>1</td>         <td>uint</td>    <td>10</td><td></td></tr>
    133. 

  133. <tr><td>spacingHoriz</td><td>1</td>         <td>uint</td>    <td>11</td><td></td></tr>
    134. 

  134. <tr><td>spacingVert</td> <td>1</td>         <td>uint</td>    <td>12</td><td></td></tr>
    135. 

  135. <tr><td>outline</td>     <td>1</td>         <td>uint</td>    <td>13</td><td>added with version 2</td></tr>
    136. 

  136. <tr><td>fontName</td>    <td><i>n</i>+1</td><td>string</td>  <td>14</td><td>null terminated string with length <i>n</i></td></tr>
    137. 

  137. </table>
    138. 

  138. 

  139. <p>This structure gives the layout of the fields. Remember that there should be no 
    140. 

  140. padding between members. Allocate the size of the block using the blockSize, as 
    141. 

  141. following the block comes the font name, including the terminating null char. 
    142. 

  142. Most of the time this block can simply be ignored.</p>
    143. 

  143. 

  144. <h3>Block type 2: common</h3>
    145. 

  145. 

  146. <table>
    147. 

  147. <tr><td width=100><b>field</b></td><td width=30><b>size</b></td><td width=40><b>type</b></td><td width=30><b>pos</b></td><td><b>comment</b></td></tr>
    148. 

  148. <tr><td>lineHeight</td>    <td>2</td>     <td>uint</td>    <td>0</td>  <td></td></tr>
    149. 

  149. <tr><td>base</td>          <td>2</td>     <td>uint</td>    <td>2</td>  <td></td></tr>
    150. 

  150. <tr><td>scaleW</td>        <td>2</td>     <td>uint</td>    <td>4</td>  <td></td></tr>
    151. 

  151. <tr><td>scaleH</td>        <td>2</td>     <td>uint</td>    <td>6</td>  <td></td></tr>
    152. 

  152. <tr><td>pages</td>         <td>2</td>     <td>uint</td>    <td>8</td>  <td></td></tr>
    153. 

  153. <tr><td>bitField</td>      <td>1</td>     <td>bits</td>    <td>10</td> <td>bits 0-6: reserved, bit 7: packed</td></tr>
    154. 

  154. <tr><td>alphaChnl</td>     <td>1</td>     <td>uint</td>    <td>11</td> <td></td></tr>
    155. 

  155. <tr><td>redChnl</td>       <td>1</td>     <td>uint</td>    <td>12</td> <td></td></tr>
    156. 

  156. <tr><td>greenChnl</td>     <td>1</td>     <td>uint</td>    <td>13</td> <td></td></tr>
    157. 

  157. <tr><td>blueChnl</td>      <td>1</td>     <td>uint</td>    <td>14</td> <td></td></tr>
    158. 

  158. </table>
    159. 

  159. 

  160. <h3>Block type 3: pages</h3>
    161. 

  161. 

  162. <table>
    163. 

  163. <tr><td width=100><b>field</b></td><td width=70><b>size</b></td><td width=40><b>type</b></td><td width=30><b>pos</b></td><td><b>comment</b></td></tr>
    164. 

  164. <tr><td>pageNames</td>    <td><i>p</i>*(<i>n</i>+1)</td>     <td>strings</td>    <td>0</td>  <td><i>p</i> null terminated strings, each with length <i>n</i></td></tr>
    165. 

  165. </table>
    166. 

  166. 

  167. <p>This block gives the name of each texture file with the image data for the characters. 
    168. 

  168. The string pageNames holds the names separated and terminated by null chars. Each filename 
    169. 

  169. has the same length, so once you know the size of the first name, you can easily determine 
    170. 

  170. the position of each of the names. The id of each page is the zero-based index of the string name.</p>
    171. 

  171. 

  172. <h3>Block type 4: chars</h3>
    173. 

  173. 

  174. <table>
    175. 

  175. <tr><td width=100><b>field</b></td><td width=30><b>size</b></td><td width=40><b>type</b></td><td width=70><b>pos</b></td><td><b>comment</b></td></tr>
    176. 

  176. <tr><td>id</td>       <td>4</td>     <td>uint</td>    <td>0+<i>c</i>*20</td>   <td>These fields are repeated until all characters have been described</td></tr>
    177. 

  177. <tr><td>x</td>        <td>2</td>     <td>uint</td>    <td>4+<i>c</i>*20</td>   <td></td></tr>
    178. 

  178. <tr><td>y</td>        <td>2</td>     <td>uint</td>    <td>6+<i>c</i>*20</td>   <td></td></tr>
    179. 

  179. <tr><td>width</td>    <td>2</td>     <td>uint</td>    <td>8+<i>c</i>*20</td>   <td></td></tr>
    180. 

  180. <tr><td>height</td>   <td>2</td>     <td>uint</td>    <td>10+<i>c</i>*20</td>   <td></td></tr>
    181. 

  181. <tr><td>xoffset</td>  <td>2</td>     <td>int</td>     <td>12+<i>c</i>*20</td>  <td></td></tr>
    182. 

  182. <tr><td>yoffset</td>  <td>2</td>     <td>int</td>     <td>14+<i>c</i>*20</td>  <td></td></tr>
    183. 

  183. <tr><td>xadvance</td> <td>2</td>     <td>int</td>     <td>16+<i>c</i>*20</td>  <td></td></tr>
    184. 

  184. <tr><td>page</td>     <td>1</td>     <td>uint</td>    <td>18+<i>c</i>*20</td>  <td></td></tr>
    185. 

  185. <tr><td>chnl</td>     <td>1</td>     <td>uint</td>    <td>19+<i>c</i>*20</td>  <td></td></tr>
    186. 

  186. </table>
    187. 

  187. 

  188. <p>The number of characters in the file can be computed by taking the size of the block 
    189. 

  189. and dividing with the size of the charInfo structure, i.e.: numChars = charsBlock.blockSize/20.</p>
    190. 

  190. 

  191. <h3>Block type 5: kerning pairs</h3>
    192. 

  192. 

  193. <table>
    194. 

  194. <tr><td width=100><b>field</b></td><td width=30><b>size</b></td><td width=40><b>type</b></td><td width=60><b>pos</b></td><td><b>comment</b></td></tr>
    195. 

  195. <tr><td>first</td>     <td>4</td>    <td>uint</td>     <td>0+<i>c</i>*10</td>  <td>These fields are repeated until all kerning pairs have been described</td></tr>
    196. 

  196. <tr><td>second</td>    <td>4</td>    <td>uint</td>     <td>4+<i>c</i>*10</td>  <td></td></tr>
    197. 

  197. <tr><td>amount</td>    <td>2</td>    <td>int</td>      <td>8+<i>c</i>*6</td>  <td></td></tr>
    198. 

  198. </table>
    199. 

  199. 

  200. 

  201. <p>This block is only in the file if there are any kerning pairs with amount differing from 0.</p>
    202. 

  202. 

  203. 

  204. 

  205. </body>
    206. 

  206. </html>
    207.