| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Font Resources</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<h3>Resource options</h3> |
| 8 |
|
| 9 |
<p>Each font <i>can</i> have the following properties:</p> |
| 10 |
|
| 11 |
<pre> |
| 12 |
<font |
| 13 |
name="my_font" |
| 14 |
width_offset="offset" |
| 15 |
height_offset="offset" |
| 16 |
delims="delimiters"> |
| 17 |
|
| 18 |
<system |
| 19 |
font_name="facename" |
| 20 |
height="height_in_pixels" |
| 21 |
width="width_in_pixels" |
| 22 |
bold="[0,1]" |
| 23 |
italic="[0,1]" |
| 24 |
underline="[0,1]" |
| 25 |
strikeout="[0,1]" |
| 26 |
letters="abcdefghijkl..." /> |
| 27 |
|
| 28 |
<bitmap |
| 29 |
glyphs="sprite_resource_id" |
| 30 |
letters="abcdefghijkl..." |
| 31 |
spacelen="pixel_width_of_space" |
| 32 |
monospace="[0,1]" /> |
| 33 |
|
| 34 |
</font> |
| 35 |
</pre> |
| 36 |
|
| 37 |
<p>To setup a font resource, it is required to specify the <i>name</i> |
| 38 |
attribute of <font> and at least the required attributes for either a |
| 39 |
<system> font or a <bitmap> font. The required attributes for |
| 40 |
the system fonts are <i>font_name</i> and <i>height</i>. |
| 41 |
Required attributes for bitmap fonts are <i>glyphs</i>, <i>letters</i> and |
| 42 |
<i>spacelen</i>.</p> |
| 43 |
|
| 44 |
<h3>Using <system> fonts</h3> |
| 45 |
|
| 46 |
<p>System fonts are generated by the local font system, typically Windows or |
| 47 |
X11. For performance reasons, the system font is converted into a bitmap |
| 48 |
font internally in ClanLib, which means it can save texture memory if it is |
| 49 |
specified more exactly what letters will be used in the font. Aside from |
| 50 |
that the only limitations are that the font specified by the |
| 51 |
<i>font_name</i> attribute must be available on the system. If it is not |
| 52 |
the underlying window system will pick another font, based on criterias that |
| 53 |
are platform specific.</p> |
| 54 |
|
| 55 |
<p>For system fonts only the <i>font_name</i> and <i>height</i> (specified |
| 56 |
in pixels) needs to be specified. The remaining flag attributes are |
| 57 |
optional. If the <i>letters</i> attribute, which specifies characters |
| 58 |
should be included when creating the bitmap glyphs, is not specified then it |
| 59 |
will include the default characters in the range 32-128. It is highly |
| 60 |
adviced to specify the letters as this can save a lot of memory the bigger |
| 61 |
the font is.</p> |
| 62 |
|
| 63 |
<h3>Using <bitmap> fonts</h3> |
| 64 |
|
| 65 |
<p>Bitmap fonts are built using a sprite resource. The attributes in the |
| 66 |
<bitmap> element specify what sprite resource contains the glyphs |
| 67 |
(a glyph is the image of a character) to be used in the font. The sprite |
| 68 |
resource is then used together with the <i>letters</i> attribute to link |
| 69 |
each frame from the sprite resource to the corresponding glyph character in |
| 70 |
the font.</p> |
| 71 |
|
| 72 |
<p>To illustrate this, imagine a sprite that contain 10 frames, containing |
| 73 |
the letters A, B, C, D, E, 4, 3, 2, 1, 0 in that order. The <i>letters</i> |
| 74 |
attribute should then contain the string "ABCDE43210".</p> |
| 75 |
|
| 76 |
<p>Any character printed not present in the font will be replaced by the space |
| 77 |
character. The space character gets the width specified by the |
| 78 |
<i>spacelen</i> attribute.</p> |
| 79 |
|
| 80 |
<p><i>monospace</i> is an optional attribute that, if set to "1", will cause |
| 81 |
all characters to use the <i>spacelen</i> as the width of the character |
| 82 |
(instead of using the glyph's bitmap width).</p> |
| 83 |
|
| 84 |
<h3>Font resource options reference</h3> |
| 85 |
|
| 86 |
<p><b><font></b></p> |
| 87 |
|
| 88 |
<ul> |
| 89 |
<li>Attribute <b>name</b>: Name of resource. |
| 90 |
<p> |
| 91 |
<i>Valid values</i>:<br> |
| 92 |
<i>Default value</i>: None, MUST BE PRESENT. |
| 93 |
</p> |
| 94 |
</li> |
| 95 |
<li>Attribute <b>width_offset</b>: Width offset of the font. |
| 96 |
<p> |
| 97 |
<i>Valid values</i>:<br> |
| 98 |
<i>Default value</i>: "0" |
| 99 |
</p> |
| 100 |
</li> |
| 101 |
<li>Attribute <b>height_offset</b>: Height offset of the font. |
| 102 |
<p> |
| 103 |
<i>Valid values</i>:<br> |
| 104 |
<i>Default value</i>: "0" |
| 105 |
</p> |
| 106 |
</li> |
| 107 |
<li>Attribute <b>delims</b>: Delimiter characters. |
| 108 |
<p> |
| 109 |
<i>Valid values</i>:<br> |
| 110 |
<i>Default value</i>: " " (space) |
| 111 |
</p> |
| 112 |
</li> |
| 113 |
</ul> |
| 114 |
|
| 115 |
<p><b><system></b></p> |
| 116 |
|
| 117 |
<ul> |
| 118 |
<li>Attribute <b>font_name</b>: Font face name. |
| 119 |
<p> |
| 120 |
<i>Valid values</i>:<br> |
| 121 |
<i>Default value</i>: None, MUST BE PRESENT. |
| 122 |
</p> |
| 123 |
</li> |
| 124 |
<li>Attribute <b>height</b>: Font height in pixels. |
| 125 |
<p> |
| 126 |
<i>Valid values</i>:<br> |
| 127 |
<i>Default value</i>: None, MUST BE PRESENT. |
| 128 |
</p> |
| 129 |
</li> |
| 130 |
<li>Attribute <b>width</b>: Font width in pixels. |
| 131 |
<p> |
| 132 |
<i>Valid values</i>:<br> |
| 133 |
<i>Default value</i>: "0" |
| 134 |
</p> |
| 135 |
</li> |
| 136 |
<li>Attribute <b>bold</b>: Bold flag. |
| 137 |
<p> |
| 138 |
<i>Valid values</i>: "0", "1"<br> |
| 139 |
<i>Default value</i>: "0" |
| 140 |
</p> |
| 141 |
</li> |
| 142 |
<li>Attribute <b>italic</b>: Italic flag. |
| 143 |
<p> |
| 144 |
<i>Valid values</i>: "0", "1"<br> |
| 145 |
<i>Default value</i>: "0" |
| 146 |
</p> |
| 147 |
</li> |
| 148 |
<li>Attribute <b>underline</b>: Underline flag. |
| 149 |
<p> |
| 150 |
<i>Valid values</i>: "0", "1"<br> |
| 151 |
<i>Default value</i>: "0" |
| 152 |
</p> |
| 153 |
</li> |
| 154 |
<li>Attribute <b>strikeout</b>: Strikeout flag. |
| 155 |
<p> |
| 156 |
<i>Valid values</i>: "0", "1"<br> |
| 157 |
<i>Default value</i>: "0" |
| 158 |
</p> |
| 159 |
</li> |
| 160 |
<li>Attribute <b>letters</b>: Characters to include in font. |
| 161 |
<p> |
| 162 |
<i>Valid values</i>: <br> |
| 163 |
<i>Default value</i>: "abcdefghijklmnopqrstuvwxyz0123456789.." - (generally all chars from 32 to 128) |
| 164 |
</p> |
| 165 |
</li> |
| 166 |
</ul> |
| 167 |
|
| 168 |
<p><b><bitmap></b></p> |
| 169 |
|
| 170 |
<ul> |
| 171 |
<li>Attribute <b>glyphs</b>: Sprite resource containing the glyphs (font characters). |
| 172 |
<p> |
| 173 |
<i>Valid values</i>: Any sprite resource<br> |
| 174 |
<i>Default value</i>: None, MUST BE PRESENT. |
| 175 |
</p> |
| 176 |
</li> |
| 177 |
<li>Attribute <b>letters</b>: Characters to be linked with each sprite frame. |
| 178 |
<p> |
| 179 |
<i>Valid values</i>: "abcdefghi.."<br> |
| 180 |
<i>Default value</i>: None, MUST BE PRESENT. |
| 181 |
</p> |
| 182 |
</li> |
| 183 |
<li>Attribute <b>spacelen</b>: Width of the space character. |
| 184 |
<p> |
| 185 |
<i>Valid values</i>:<br> |
| 186 |
<i>Default value</i>: None, MUST BE PRESENT. |
| 187 |
</p> |
| 188 |
</li> |
| 189 |
<li>Attribute <b>monospace</b>: Monospace flag. |
| 190 |
<p> |
| 191 |
<i>Valid values</i>: "0", "1"<br> |
| 192 |
<i>Default value</i>: "0" |
| 193 |
</p> |
| 194 |
</li> |
| 195 |
</ul> |
| 196 |
|
| 197 |
</body> |
| 198 |
</xml> |