Debian Codegraph @

Documentation/Overview/font_resources.xml

raw
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 &lt;font
13 name="my_font"
14 width_offset="offset"
15 height_offset="offset"
16 delims="delimiters"&gt;
17
18 &lt;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..." /&gt;
27
28 &lt;bitmap
29 glyphs="sprite_resource_id"
30 letters="abcdefghijkl..."
31 spacelen="pixel_width_of_space"
32 monospace="[0,1]" /&gt;
33
34 &lt;/font&gt;
35 </pre>
36
37 <p>To setup a font resource, it is required to specify the <i>name</i>
38 attribute of &lt;font&gt; and at least the required attributes for either a
39 &lt;system&gt; font or a &lt;bitmap&gt; 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 &lt;system&gt; 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 &lt;bitmap&gt; fonts</h3>
64
65 <p>Bitmap fonts are built using a sprite resource. The attributes in the
66 &lt;bitmap&gt; 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>&lt;font&gt;</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>&lt;system&gt;</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>&lt;bitmap&gt;</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>