Commit | Line | Data |
90d38009 |
1 | <div class="pod"> |
2 | <!-- INDEX START --> |
3 | <h3 id="TOP">Index</h3> |
55bbf7a2 |
4 | |
5 | <ul><li><a href="#NAME">NAME</a></li> |
6 | <li><a href="#CATEGORY">CATEGORY</a></li> |
25fbbc5b |
7 | <li><a href="#CONSTANTS">CONSTANTS</a></li> |
55bbf7a2 |
8 | <li><a href="#METHODS">METHODS</a> |
9 | <ul><li><a href="#General_methods">General methods</a> |
10 | <ul><li><a href="#linked_version">linked_version</a></li> |
11 | <li><a href="#compile_time_version">compile_time_version</a></li> |
12 | <li><a href="#init">init</a></li> |
13 | <li><a href="#was_init">was_init</a></li> |
14 | <li><a href="#quit">quit</a></li> |
15 | </ul> |
16 | </li> |
17 | <li><a href="#Management_functions">Management functions</a> |
18 | <ul><li><a href="#open_font">open_font</a></li> |
19 | <li><a href="#open_font_index">open_font_index</a></li> |
20 | <li><a href="#open_font_RW">open_font_RW</a></li> |
21 | <li><a href="#open_font_index_RW">open_font_index_RW</a></li> |
22 | </ul> |
23 | </li> |
24 | <li><a href="#Attributes">Attributes</a> |
25 | <ul><li><a href="#Global_attributes">Global attributes</a> |
26 | <ul><li><a href="#byte_swapped_unicode">byte_swapped_unicode</a></li> |
27 | </ul> |
28 | </li> |
29 | <li><a href="#Font_style">Font style</a> |
30 | <ul><li><a href="#get_font_style">get_font_style</a></li> |
31 | <li><a href="#set_font_style">set_font_style</a></li> |
b2c46b06 |
32 | <li><a href="#get_font_outline">get_font_outline</a></li> |
33 | <li><a href="#set_font_outline">set_font_outline</a></li> |
55bbf7a2 |
34 | </ul> |
35 | </li> |
36 | <li><a href="#Font_settings">Font settings</a> |
37 | <ul><li><a href="#get_font_hinting">get_font_hinting</a></li> |
38 | <li><a href="#set_font_hinting">set_font_hinting</a></li> |
39 | <li><a href="#get_font_kerning">get_font_kerning</a></li> |
40 | <li><a href="#set_font_kerning">set_font_kerning</a></li> |
41 | </ul> |
42 | </li> |
43 | <li><a href="#Font_metrics">Font metrics</a> |
44 | <ul><li><a href="#font_height">font_height</a></li> |
45 | <li><a href="#font_ascent">font_ascent</a></li> |
46 | <li><a href="#font_descent">font_descent</a></li> |
47 | <li><a href="#font_line_skip">font_line_skip</a></li> |
48 | </ul> |
49 | </li> |
50 | <li><a href="#Face_attributes">Face attributes</a> |
51 | <ul><li><a href="#font_faces">font_faces</a></li> |
52 | <li><a href="#font_face_is_fixed_width">font_face_is_fixed_width</a></li> |
53 | <li><a href="#font_face_family_name">font_face_family_name</a></li> |
54 | <li><a href="#font_face_style_name">font_face_style_name</a></li> |
55 | </ul> |
56 | </li> |
57 | <li><a href="#Glyphs">Glyphs</a> |
58 | <ul><li><a href="#glyph_is_provided">glyph_is_provided</a></li> |
59 | <li><a href="#glyph_metrics">glyph_metrics</a></li> |
60 | </ul> |
61 | </li> |
62 | <li><a href="#Text_metrics">Text metrics</a> |
63 | <ul><li><a href="#size_text">size_text</a></li> |
64 | <li><a href="#size_utf8">size_utf8</a></li> |
65 | <li><a href="#size_unicode">size_unicode</a></li> |
66 | </ul> |
67 | </li> |
68 | </ul> |
69 | </li> |
70 | <li><a href="#Font_Rendering">Font Rendering</a> |
c5f5ab4d |
71 | <ul><li><a href="#Solid">Solid</a> |
55bbf7a2 |
72 | <ul><li><a href="#render_glyph_solid">render_glyph_solid</a></li> |
55bbf7a2 |
73 | <li><a href="#render_text_solid">render_text_solid</a></li> |
55bbf7a2 |
74 | <li><a href="#render_utf8_solid">render_utf8_solid</a></li> |
55bbf7a2 |
75 | <li><a href="#render_unicode_solid">render_unicode_solid</a></li> |
c5f5ab4d |
76 | </ul> |
77 | </li> |
78 | <li><a href="#Shaded">Shaded</a> |
79 | <ul><li><a href="#render_glyph_shaded">render_glyph_shaded</a></li> |
80 | <li><a href="#render_text_shaded">render_text_shaded</a></li> |
81 | <li><a href="#render_utf8_shaded">render_utf8_shaded</a></li> |
55bbf7a2 |
82 | <li><a href="#render_unicode_shaded">render_unicode_shaded</a></li> |
c5f5ab4d |
83 | </ul> |
84 | </li> |
85 | <li><a href="#Blended">Blended</a> |
86 | <ul><li><a href="#render_glyph_blended">render_glyph_blended</a></li> |
87 | <li><a href="#render_text_blended">render_text_blended</a></li> |
88 | <li><a href="#render_utf8_blended">render_utf8_blended</a></li> |
55bbf7a2 |
89 | <li><a href="#render_unicode_blended">render_unicode_blended</a></li> |
90 | </ul> |
91 | </li> |
92 | </ul> |
93 | </li> |
c5f5ab4d |
94 | </ul> |
95 | </li> |
c7e8d3c6 |
96 | <li><a href="#AUTHORS">AUTHORS</a></li> |
55bbf7a2 |
97 | <li><a href="#SEE_ALSO">SEE ALSO</a> |
98 | </li> |
99 | </ul><hr /> |
90d38009 |
100 | <!-- INDEX END --> |
101 | |
55bbf7a2 |
102 | <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p> |
103 | <div id="NAME_CONTENT"> |
104 | <p>SDL::TTF - True Type Font functions (libfreetype)</p> |
105 | |
106 | </div> |
107 | <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p> |
108 | <div id="CATEGORY_CONTENT"> |
c5f5ab4d |
109 | <p>TTF</p> |
55bbf7a2 |
110 | |
111 | </div> |
25fbbc5b |
112 | <h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
113 | <div id="CONSTANTS_CONTENT"> |
3549ee6a |
114 | <p>The constants are exported by default. You can avoid this by doing:</p> |
115 | <pre> use SDL::TTF (); |
116 | |
36bc5147 |
117 | </pre> |
3549ee6a |
118 | <p>and access them directly:</p> |
25fbbc5b |
119 | <pre> SDL::TTF::TTF_HINTING_NORMAL; |
120 | |
121 | </pre> |
122 | <p>Available constants for "hinting":</p> |
123 | <ul> |
124 | <li>TTF_HINTING_NORMAL </li> |
125 | <li>TTF_HINTING_LIGHT </li> |
126 | <li>TTF_HINTING_MONO </li> |
127 | <li>TTF_HINTING_NONE</li> |
128 | </ul> |
129 | |
130 | <p>Available constants for "style":</p> |
131 | <ul> |
132 | <li>TTF_STYLE_NORMAL </li> |
133 | <li>TTF_STYLE_BOLD </li> |
134 | <li>TTF_STYLE_ITALIC </li> |
135 | <li>TTF_STYLE_UNDERLINE </li> |
136 | <li>TTF_STYLE_STRIKETHROUGH</li> |
137 | </ul> |
138 | |
139 | |
140 | </div> |
55bbf7a2 |
141 | <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
142 | <div id="METHODS_CONTENT"> |
143 | |
144 | </div> |
145 | <h2 id="General_methods">General methods</h2> |
146 | <div id="General_methods_CONTENT"> |
147 | |
148 | </div> |
149 | <h3 id="linked_version">linked_version</h3> |
150 | <div id="linked_version_CONTENT"> |
151 | <pre> my $version = SDL::TTF::linked_version(); |
152 | |
153 | </pre> |
154 | <p>This gives you the SDL::Version object which SDL_ttf lib is used on the system. |
155 | No prior initialization needs to be done before these function is called. </p> |
156 | <p>Example:</p> |
157 | <pre> use SDL::TTF; |
158 | use SDL::Version; |
159 | |
160 | my $version = SDL::TTF::linked_version(); |
161 | |
162 | printf("got version: %d.%d.%d\n", $version->major, $version->minor, $version->patch); |
163 | |
164 | </pre> |
165 | |
166 | </div> |
167 | <h3 id="compile_time_version">compile_time_version</h3> |
168 | <div id="compile_time_version_CONTENT"> |
169 | <pre> my $version = SDL::TTF::compile_time_version(); |
170 | |
171 | </pre> |
172 | <p>This gives you the SDL::Version object which SDL_ttf was present at compile time.</p> |
173 | |
174 | </div> |
175 | <h3 id="init">init</h3> |
176 | <div id="init_CONTENT"> |
177 | <pre> my $success = SDL::TTF::init(); |
178 | |
179 | </pre> |
180 | <p>Initialize the truetype font API. |
0b221bb4 |
181 | This must be called before using other functions in this library, except <a href="SDL-TTF::was_init.html">SDL::TTF::was_init</a> and <a href="SDL-TTF::linked_version.html">SDL::TTF::linked_version</a>. |
55bbf7a2 |
182 | SDL does not have to be initialized before this call.</p> |
183 | <p>Returns: <code>0</code> on success, <code>-1</code> on any error.</p> |
184 | |
185 | </div> |
186 | <h3 id="was_init">was_init</h3> |
187 | <div id="was_init_CONTENT"> |
188 | <pre> my $was_init = SDL::TTF::was_init(); |
189 | |
190 | </pre> |
191 | <p>Query the initilization status of the truetype font API. |
0b221bb4 |
192 | You may, of course, use this before <a href="SDL-TTF::init.html">SDL::TTF::init</a> to avoid initializing twice in a row. Or use this to determine if you need to call |
193 | <a href="SDL-TTF::quit.html">SDL::TTF::quit</a>.</p> |
55bbf7a2 |
194 | |
195 | </div> |
196 | <h3 id="quit">quit</h3> |
197 | <div id="quit_CONTENT"> |
198 | <pre> SDL::TTF::quit(); |
199 | |
200 | </pre> |
201 | <p>Shutdown and cleanup the truetype font API. |
0b221bb4 |
202 | After calling this the SDL::TTF functions should not be used, excepting <a href="SDL-TTF::was_init.html">SDL::TTF::was_init</a>. You may, of course, use <a href="SDL-TTF::init.html">SDL::TTF::init</a> to |
55bbf7a2 |
203 | use the functionality again</p> |
204 | |
205 | </div> |
206 | <h2 id="Management_functions">Management functions</h2> |
207 | <div id="Management_functions_CONTENT"> |
208 | |
209 | </div> |
210 | <h3 id="open_font">open_font</h3> |
211 | <div id="open_font_CONTENT"> |
212 | <pre> my $font = SDL::TTF::open_font($font_file, $point_size); |
213 | |
214 | </pre> |
215 | <p>Load file for use as a font, at the given size. This is actually <code>SDL::TTF::open_font_index(..., ..., $index = 0)</code>. This can load TTF and FON files.</p> |
216 | <p>Returns: a <a href="SDL-TTF-Font.html">SDL::TTF::Font</a> object. <code>undef</code> is returned on errors.</p> |
217 | <p>Example:</p> |
218 | <pre> use SDL::TTF; |
219 | use SDL::TTF::Font; |
220 | |
3ad5a97a |
221 | my $font = SDL::TTF::open_font('arial.ttf', 24); |
55bbf7a2 |
222 | |
223 | </pre> |
224 | |
225 | </div> |
226 | <h3 id="open_font_index">open_font_index</h3> |
227 | <div id="open_font_index_CONTENT"> |
228 | <pre> my $font = SDL::TTF::open_font($font_file, $point_size, $face_index); |
229 | |
230 | </pre> |
0b221bb4 |
231 | <p>This is the same as <a href="SDL-TTF::open_font.html">SDL::TTF::open_font</a>, except you can specify the face index of a font file containing multiple faces. |
55bbf7a2 |
232 | This can load TTF and FON files. </p> |
233 | |
234 | </div> |
235 | <h3 id="open_font_RW">open_font_RW</h3> |
236 | <div id="open_font_RW_CONTENT"> |
237 | <pre> my $font = SDL::TTF::open_font_RW($rwops_object, $free, $point_size); |
238 | |
239 | </pre> |
0b221bb4 |
240 | <p>This is the same as <a href="SDL-TTF::open_font.html">SDL::TTF::open_font</a>, except you can pass an <a href="SDL-RWOps.html">SDL::RWOps</a>-object. If you pass true as <code>$free</code>, the <a href="SDL-RWOps.html">SDL::RWOps</a>-object |
55bbf7a2 |
241 | will be freed by SDL_ttf library. Don't do this, perl will free this object for you.</p> |
242 | <p>Example:</p> |
243 | <pre> my $font = SDL::TTF::open_font_RW(SDL::RWOps->new_file($font_file, 'r'), 0, 24); |
244 | |
245 | </pre> |
246 | |
247 | </div> |
248 | <h3 id="open_font_index_RW">open_font_index_RW</h3> |
249 | <div id="open_font_index_RW_CONTENT"> |
250 | <pre> my $font = SDL::TTF::open_font_index_RW($rwops_object, $free, $point_size, $face_index); |
251 | |
252 | </pre> |
0b221bb4 |
253 | <p>This is the same as <a href="SDL-TTF::open_font_index.html">SDL::TTF::open_font_index</a>, except you can pass an <a href="SDL-RWOps.html">SDL::RWOps</a>-object. If you pass true as <code>$free</code>, the |
55bbf7a2 |
254 | <a href="SDL-RWOps.html">SDL::RWOps</a>-object will be freed by SDL_ttf library. Don't do this, perl will free this object for you.</p> |
255 | |
256 | </div> |
257 | <h2 id="Attributes">Attributes</h2> |
258 | <div id="Attributes_CONTENT"> |
259 | |
260 | </div> |
261 | <h3 id="Global_attributes">Global attributes</h3> |
262 | <div id="Global_attributes_CONTENT"> |
263 | |
264 | </div> |
265 | <h4 id="byte_swapped_unicode">byte_swapped_unicode</h4> |
266 | <div id="byte_swapped_unicode_CONTENT"> |
267 | <pre> SDL::TTF::byte_swapped_unicode( $bool ); |
268 | |
269 | </pre> |
270 | <p>This function tells SDL_ttf whether UNICODE (2 bytes per character) text is generally byteswapped. A <code>UNICODE_BOM_NATIVE</code> or |
271 | <code>UNICODE_BOM_SWAPPED</code> character in a string will temporarily override this setting for the remainder of that string, however this setting |
272 | will be restored for the next one. The default mode is non-swapped, native endianness of the CPU.</p> |
273 | |
274 | </div> |
275 | <h3 id="Font_style">Font style</h3> |
276 | <div id="Font_style_CONTENT"> |
277 | |
278 | </div> |
279 | <h4 id="get_font_style">get_font_style</h4> |
280 | <div id="get_font_style_CONTENT"> |
281 | <pre> SDL::TTF::get_font_style($font); |
282 | |
283 | </pre> |
284 | <p>Returns: The style as a bitmask composed of the following masks:</p> |
285 | <ul> |
286 | <li>TTF_STYLE_NORMAL </li> |
287 | <li>TTF_STYLE_BOLD </li> |
288 | <li>TTF_STYLE_ITALIC </li> |
289 | <li>TTF_STYLE_UNDERLINE </li> |
290 | <li>TTF_STYLE_STRIKETHROUGH (since SDL_ttf 2.0.10)</li> |
291 | </ul> |
292 | |
293 | <p>Example:</p> |
294 | <pre> my $style = SDL::TTF::get_font_style($font); |
295 | |
296 | print("normal\n") if $style == TTF_STYLE_NORMAL; |
297 | print("bold\n") if $style & TTF_STYLE_BOLD; |
298 | print("italic\n") if $style & TTF_STYLE_ITALIC; |
299 | print("underline\n") if $style & TTF_STYLE_UNDERLINE; |
300 | print("strikethrough\n") if $style & TTF_STYLE_STRIKETHROUGH; |
301 | |
302 | </pre> |
303 | |
304 | </div> |
305 | <h4 id="set_font_style">set_font_style</h4> |
306 | <div id="set_font_style_CONTENT"> |
307 | <pre> SDL::TTF::set_font_style($font, $style); |
308 | |
309 | </pre> |
310 | <p>Set the rendering style of the loaded font.</p> |
311 | <p><strong>Note</strong>: <code>TTF_STYLE_UNDERLINE</code> may cause surfaces created by <code>SDL::TTF::render_glyph_*</code> functions to be extended vertically, downward only, |
312 | to encompass the underline if the original glyph metrics didn't allow for the underline to be drawn below. This does not change the math used |
313 | to place a glyph using glyph metrics. |
314 | On the other hand <code>TTF_STYLE_STRIKETHROUGH</code> doesn't extend the glyph, since this would invalidate the metrics used to position the glyph when |
315 | blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter |
316 | about glyph blitting math than they are currently designed for. |
317 | Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In |
318 | this case, you should probably turn off these styles and draw your own strikethroughs and underlines. </p> |
319 | |
320 | </div> |
b2c46b06 |
321 | <h4 id="get_font_outline">get_font_outline</h4> |
322 | <div id="get_font_outline_CONTENT"> |
323 | <pre> my $outline = SDL::TTF::get_font_outline($font); |
324 | |
325 | </pre> |
326 | <p>Get the current outline width of the font, in pixels.</p> |
327 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
328 | |
329 | </div> |
330 | <h4 id="set_font_outline">set_font_outline</h4> |
331 | <div id="set_font_outline_CONTENT"> |
332 | <pre> SDL::TTF::get_font_outline($font, $outline); |
333 | |
334 | </pre> |
335 | <p>Set the outline pixel width of the loaded font. Use <code>0</code>(zero) to turn off outlining.</p> |
336 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
337 | |
338 | </div> |
55bbf7a2 |
339 | <h3 id="Font_settings">Font settings</h3> |
340 | <div id="Font_settings_CONTENT"> |
341 | |
342 | </div> |
343 | <h4 id="get_font_hinting">get_font_hinting</h4> |
344 | <div id="get_font_hinting_CONTENT"> |
345 | <pre> my $hinting = SDL::TTF::get_font_hinting($font); |
346 | |
347 | </pre> |
348 | <p>Get the current hinting setting of the loaded font.</p> |
349 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
350 | <p>Returns the hinting type matching one of the following defined values:</p> |
351 | <ul> |
352 | <li>TTF_HINTING_NORMAL </li> |
353 | <li>TTF_HINTING_LIGHT </li> |
354 | <li>TTF_HINTING_MONO </li> |
355 | <li>TTF_HINTING_NONE</li> |
356 | </ul> |
357 | |
358 | |
359 | </div> |
360 | <h4 id="set_font_hinting">set_font_hinting</h4> |
361 | <div id="set_font_hinting_CONTENT"> |
362 | <pre> SDL::TTF::set_font_hinting($font, $hinting); |
363 | |
364 | </pre> |
365 | <p>Set the hinting of the loaded font. You should experiment with this setting if you know which font you are using beforehand, especially when |
366 | using smaller sized fonts. If the user is selecting a font, you may wish to let them select the hinting mode for that font as well.</p> |
367 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
368 | <p>Example:</p> |
369 | <pre> SDL::TTF::set_font_hinting($font, TTF_HINTING_LIGHT); |
370 | |
371 | </pre> |
372 | |
373 | </div> |
374 | <h4 id="get_font_kerning">get_font_kerning</h4> |
375 | <div id="get_font_kerning_CONTENT"> |
376 | <pre> my $kerning_enabled = SDL::TTF::get_font_kerning($font); |
377 | |
378 | </pre> |
379 | <p>Get the current kerning setting of the loaded font.</p> |
380 | <p>Returns: <code>0</code>(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(<code>1</code>). </p> |
381 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
148a0b32 |
382 | <p><strong>Note</strong>: This function returns wrong values: See <a href="http://bugzilla.libsdl.org/show_bug.cgi?id=973">http://bugzilla.libsdl.org/show_bug.cgi?id=973</a></p> |
55bbf7a2 |
383 | |
384 | </div> |
385 | <h4 id="set_font_kerning">set_font_kerning</h4> |
386 | <div id="set_font_kerning_CONTENT"> |
387 | <pre> SDL::TTF::set_font_kerning($font, $kerning_enabled); |
388 | |
389 | </pre> |
390 | <p>Set whether to use kerning when rendering the loaded font. This has no effect on individual glyphs, but rather when rendering whole strings of |
391 | characters, at least a word at a time. Perhaps the only time to disable this is when kerning is not working for a specific font, resulting in |
392 | overlapping glyphs or abnormal spacing within words.</p> |
393 | <p>Pass <code>0</code> to disable kerning, 1 to enable.</p> |
394 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
395 | |
396 | </div> |
397 | <h3 id="Font_metrics">Font metrics</h3> |
398 | <div id="Font_metrics_CONTENT"> |
399 | |
400 | </div> |
401 | <h4 id="font_height">font_height</h4> |
402 | <div id="font_height_CONTENT"> |
403 | <pre> my $font_height = SDL::TTF::font_height($font); |
404 | |
405 | </pre> |
b2c46b06 |
406 | <p>Get the maximum pixel height of all glyphs of the loaded font. You may use this height for rendering text as close together vertically as |
407 | possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_ttf doesn't handle multiline |
0b221bb4 |
408 | printing, so you are responsible for line spacing, see the <a href="SDL-TTF::font_line_skip.html">SDL::TTF::font_line_skip</a> as well.</p> |
55bbf7a2 |
409 | |
410 | </div> |
411 | <h4 id="font_ascent">font_ascent</h4> |
412 | <div id="font_ascent_CONTENT"> |
413 | <pre> my $font_ascent = SDL::TTF::font_ascent($font); |
b2c46b06 |
414 | |
415 | </pre> |
416 | <p>Get the maximum pixel ascent of all glyphs of the loaded font. This can also be interpreted as the distance from the top of the font to the |
417 | baseline. |
418 | It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's <code>maxy</code> metric to resolve the top |
419 | of the rectangle used when blitting the glyph on the screen.</p> |
420 | <p>Example:</p> |
c5291845 |
421 | <pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") }; |
b2c46b06 |
422 | |
423 | $rect->y( $top + SDL::TTF::font_ascent($font) - $maxy ); |
55bbf7a2 |
424 | |
425 | </pre> |
426 | |
427 | </div> |
428 | <h4 id="font_descent">font_descent</h4> |
429 | <div id="font_descent_CONTENT"> |
430 | <pre> my $font_descent = SDL::TTF::font_descent($font); |
b2c46b06 |
431 | |
432 | </pre> |
433 | <p>Get the maximum pixel descent of all glyphs of the loaded font. This can also be interpreted as the distance from the baseline to the bottom of |
434 | the font. |
435 | It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's <code>maxy</code> metric to resolve the top |
436 | of the rectangle used when blitting the glyph on the screen.</p> |
437 | <p>Example:</p> |
c5291845 |
438 | <pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") }; |
b2c46b06 |
439 | |
440 | $rect->y( $bottom - SDL::TTF::font_descent($font) - $maxy ); |
55bbf7a2 |
441 | |
442 | </pre> |
443 | |
444 | </div> |
445 | <h4 id="font_line_skip">font_line_skip</h4> |
446 | <div id="font_line_skip_CONTENT"> |
447 | <pre> my $font_line_skip = SDL::TTF::font_line_skip($font); |
55bbf7a2 |
448 | |
449 | </pre> |
0b221bb4 |
450 | <p>Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the <a href="SDL-TTF::font_height.html">SDL::TTF::font_height</a> of the |
b2c46b06 |
451 | font.</p> |
55bbf7a2 |
452 | |
453 | </div> |
454 | <h3 id="Face_attributes">Face attributes</h3> |
455 | <div id="Face_attributes_CONTENT"> |
456 | |
457 | </div> |
458 | <h4 id="font_faces">font_faces</h4> |
459 | <div id="font_faces_CONTENT"> |
b0e2356c |
460 | <pre> my $font_faces = SDL::TTF::font_faces($font); |
461 | |
462 | </pre> |
463 | <p>Get the number of faces ("sub-fonts") available in the loaded font. This is a count of the number of specific fonts (based on size and style |
464 | and other typographical features perhaps) contained in the font itself.</p> |
55bbf7a2 |
465 | |
466 | </div> |
467 | <h4 id="font_face_is_fixed_width">font_face_is_fixed_width</h4> |
468 | <div id="font_face_is_fixed_width_CONTENT"> |
b0e2356c |
469 | <pre> my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font); |
470 | |
471 | </pre> |
472 | <p>Test if the current font face of the loaded font is a fixed width font. Fixed width fonts are monospace, meaning every character that exists |
473 | in the font is the same width, thus you can assume that a rendered string's width is going to be the result of <code>glyph_width * string_length</code>.</p> |
474 | <p>Returns: <code>>0</code> if font is a fixed width font. <code>0</code> if not a fixed width font. </p> |
55bbf7a2 |
475 | |
476 | </div> |
477 | <h4 id="font_face_family_name">font_face_family_name</h4> |
478 | <div id="font_face_family_name_CONTENT"> |
b0e2356c |
479 | <pre> my $font_face_family_name = SDL::TTF::font_face_family_name($font); |
480 | |
481 | </pre> |
482 | <p>Get the current font face family name from the loaded font. This information is not for every font available.</p> |
483 | <p>Example:</p> |
484 | <pre> my $font = SDL::TTF::open_font('arialuni.ttf', 8); |
485 | |
486 | printf("%s\n", SDL::TTF::font_face_family_name($font)); # will print "Arial Unicode MS" |
487 | |
488 | </pre> |
55bbf7a2 |
489 | |
490 | </div> |
491 | <h4 id="font_face_style_name">font_face_style_name</h4> |
492 | <div id="font_face_style_name_CONTENT"> |
b0e2356c |
493 | <pre> my $font_face_style_name = SDL::TTF::font_face_style_name($font); |
494 | |
495 | </pre> |
496 | <p>Get the current font face style name from the loaded font. This information is not for every font available. </p> |
497 | <p>Example:</p> |
498 | <pre> my $font = SDL::TTF::open_font('arialuni.ttf', 8); |
499 | |
500 | printf("%s\n", SDL::TTF::font_face_style_name($font)); # will print "Regular" |
501 | |
502 | </pre> |
55bbf7a2 |
503 | |
504 | </div> |
505 | <h3 id="Glyphs">Glyphs</h3> |
506 | <div id="Glyphs_CONTENT"> |
507 | |
508 | </div> |
509 | <h4 id="glyph_is_provided">glyph_is_provided</h4> |
510 | <div id="glyph_is_provided_CONTENT"> |
c5291845 |
511 | <pre> my $glyph_is_provided = SDL::TTF::glyph_is_provided($font, $unicode_char); |
512 | |
513 | </pre> |
514 | <p>Get the status of the availability of the glyph from the loaded font.</p> |
515 | <p>Returns: the index of the glyph in font, or 0 for an undefined character code.</p> |
516 | <p><strong>Note</strong>: You have to pass this unicode character either as UTF16/UCS-2 big endian without BOM, or with BOM as UTF16/UCS-2 big/little endian.</p> |
517 | <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p> |
518 | <p>Example:</p> |
519 | <pre> print("We have this char!\n") if SDL::TTF::glyph_is_provided($font, "\0M"); |
520 | |
521 | </pre> |
55bbf7a2 |
522 | |
523 | </div> |
524 | <h4 id="glyph_metrics">glyph_metrics</h4> |
525 | <div id="glyph_metrics_CONTENT"> |
c5291845 |
526 | <pre> my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, $unicode_char) }; |
527 | |
528 | </pre> |
529 | <p>Get desired glyph metrics of the UNICODE char from the loaded font.</p> |
530 | <p>See also: <a href="http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html">The FreeType2 Documentation Tutorial</a></p> |
531 | <p><strong>Note</strong>: You have to pass this unicode character either as UTF16/UCS-2 big endian without BOM, or with BOM as UTF16/UCS-2 big/little endian.</p> |
532 | <p>Example:</p> |
533 | <pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") }; |
55bbf7a2 |
534 | |
535 | </pre> |
536 | |
537 | </div> |
538 | <h3 id="Text_metrics">Text metrics</h3> |
539 | <div id="Text_metrics_CONTENT"> |
540 | |
541 | </div> |
542 | <h4 id="size_text">size_text</h4> |
543 | <div id="size_text_CONTENT"> |
499f3731 |
544 | <pre> my ($width, $height) = @{ SDL::TTF::size_text($font, $text) }; |
55bbf7a2 |
545 | |
546 | </pre> |
499f3731 |
547 | <p>Calculate the resulting surface size of the LATIN1 encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning |
0b221bb4 |
548 | is done to get the actual width. The height returned is the same as you can get using <a href="SDL-TTF::font_height.html">SDL::TTF::font_height</a>.</p> |
55bbf7a2 |
549 | |
550 | </div> |
551 | <h4 id="size_utf8">size_utf8</h4> |
552 | <div id="size_utf8_CONTENT"> |
499f3731 |
553 | <pre> my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) }; |
554 | |
555 | </pre> |
556 | <p>Calculate the resulting surface size of the UTF8 encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning is |
0b221bb4 |
557 | done to get the actual width. The height returned in h is the same as you can get using <a href="SDL-TTF::font_height.html">SDL::TTF::font_height</a>.</p> |
499f3731 |
558 | <p>Note that the first example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.</p> |
559 | <p>Examples:</p> |
560 | <pre> ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') }; # plain text, if your script is in utf8 or ansi-format |
561 | |
562 | # or |
563 | |
564 | ($width, $height) = @{ SDL::TTF::size_utf8($font, "\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF") }; # utf8 hex-data |
565 | |
566 | # or |
567 | |
568 | use Unicode::String; |
569 | my $unicode = utf8($data_from_somwhere); |
570 | ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode->utf8) }; # utf8 via Unicode::String |
55bbf7a2 |
571 | |
572 | </pre> |
573 | |
574 | </div> |
575 | <h4 id="size_unicode">size_unicode</h4> |
576 | <div id="size_unicode_CONTENT"> |
499f3731 |
577 | <pre> my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) }; |
578 | |
579 | </pre> |
580 | <p>Calculate the resulting surface size of the UNICODE encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning |
0b221bb4 |
581 | is done to get the actual width. The height returned in h is the same as you can get using <a href="SDL-TTF::font_height.html">SDL::TTF::font_height</a>.</p> |
499f3731 |
582 | <p><code>$text</code> has to be:</p> |
583 | <dl> |
584 | <dt>UTF16BE without BOM</dt> |
585 | <dd> |
586 | <p>"hallo" will look like "\0h\0a\0l\0l\0o"</p> |
587 | </dd> |
588 | <dt>UTF16BE with BOM</dt> |
589 | <dd> |
590 | <p>"hallo" will look like "\xFE\xFF\0h\0a\0l\0l\0o"</p> |
591 | </dd> |
592 | <dt>UTF16LE with BOM</dt> |
593 | <dd> |
594 | <p>"hallo" will look like "\xFF\xFEh\0a\0l\0l\0o\0"</p> |
595 | </dd> |
596 | </dl> |
597 | <p>You may use Unicode::String for this.</p> |
55bbf7a2 |
598 | |
599 | </div> |
600 | <h2 id="Font_Rendering">Font Rendering</h2> |
601 | <div id="Font_Rendering_CONTENT"> |
602 | |
603 | </div> |
c5f5ab4d |
604 | <h3 id="Solid">Solid</h3> |
605 | <div id="Solid_CONTENT"> |
606 | |
607 | </div> |
608 | <h4 id="render_glyph_solid">render_glyph_solid</h4> |
55bbf7a2 |
609 | <div id="render_glyph_solid_CONTENT"> |
c5f5ab4d |
610 | <pre> my $surface = SDL::TTF::render_glyph_solid($font, $char, $color); |
611 | |
612 | </pre> |
613 | <p>Render the unicode encoded char onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.</p> |
0b221bb4 |
614 | <p><strong>Note</strong>: The unicode char has to be passed exactly like for <a href="SDL-TTF::size_unicode.html">SDL::TTF::size_unicode</a>.</p> |
c5f5ab4d |
615 | <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least version 2.3.5</p> |
55bbf7a2 |
616 | |
617 | </div> |
c5f5ab4d |
618 | <h4 id="render_text_solid">render_text_solid</h4> |
619 | <div id="render_text_solid_CONTENT"> |
620 | <pre> my $surface = SDL::TTF::render_text_solid($font, $text, $color); |
621 | |
622 | </pre> |
623 | <p>Render the LATIN1 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.</p> |
624 | <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least |
625 | version 2.3.5</p> |
626 | <p>Example:</p> |
c7e8d3c6 |
627 | <pre> use SDL; |
628 | use SDL::Rect; |
629 | use SDL::Video; |
630 | use SDL::Color; |
631 | use SDL::TTF; |
632 | use SDL::TTF::Font; |
25fbbc5b |
633 | |
c7e8d3c6 |
634 | SDL::init(SDL_INIT_VIDEO); |
635 | SDL::TTF::init(); |
636 | my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE); |
637 | my $font = SDL::TTF::open_font('test/data/aircut3.ttf', '24'); |
638 | die 'Coudnt make font '. SDL::get_error if !$font; |
639 | my $surface = SDL::TTF::render_text_solid($font, 'Hallo!', SDL::Color->new(0xFF,0xFF,0xFF)); |
640 | SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480)); |
641 | SDL::Video::update_rect($display, 0, 0, 0, 0); |
642 | SDL::delay(5000); |
c5f5ab4d |
643 | |
644 | </pre> |
55bbf7a2 |
645 | |
646 | </div> |
c5f5ab4d |
647 | <h4 id="render_utf8_solid">render_utf8_solid</h4> |
648 | <div id="render_utf8_solid_CONTENT"> |
649 | <pre> my $surface = SDL::TTF::render_utf8_solid($font, $text, $color); |
650 | |
651 | </pre> |
652 | <p>Render the UTF8 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.</p> |
653 | <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least |
654 | version 2.3.5</p> |
55bbf7a2 |
655 | |
656 | </div> |
c5f5ab4d |
657 | <h4 id="render_unicode_solid">render_unicode_solid</h4> |
658 | <div id="render_unicode_solid_CONTENT"> |
659 | <pre> my $surface = SDL::TTF::render_unicode_solid($font, $text, $color); |
660 | |
661 | </pre> |
662 | <p>Render the unicode encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.</p> |
0b221bb4 |
663 | <p><strong>Note</strong>: The unicode test has to be passed exactly like for <a href="SDL-TTF::size_unicode.html">SDL::TTF::size_unicode</a>.</p> |
c5f5ab4d |
664 | <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least |
665 | version 2.3.5</p> |
55bbf7a2 |
666 | |
667 | </div> |
c5f5ab4d |
668 | <h3 id="Shaded">Shaded</h3> |
669 | <div id="Shaded_CONTENT"> |
55bbf7a2 |
670 | |
671 | </div> |
c5f5ab4d |
672 | <h4 id="render_glyph_shaded">render_glyph_shaded</h4> |
673 | <div id="render_glyph_shaded_CONTENT"> |
674 | <pre> my $surface = SDL::TTF::render_glyph_shaded($font, $char, $color, $background_color); |
675 | |
676 | </pre> |
677 | <p>Render the unicode encoded char onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to |
678 | your display-surface.</p> |
0b221bb4 |
679 | <p><strong>Note</strong>: The unicode char has to be passed exactly like for <a href="SDL-TTF::size_unicode.html">SDL::TTF::size_unicode</a>.</p> |
55bbf7a2 |
680 | |
681 | </div> |
c5f5ab4d |
682 | <h4 id="render_text_shaded">render_text_shaded</h4> |
683 | <div id="render_text_shaded_CONTENT"> |
684 | <pre> my $surface = SDL::TTF::render_text_shaded($font, $text, $color, $background_color); |
685 | |
686 | </pre> |
687 | <p>Render the LATIN1 encoded text onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to |
688 | your display-surface.</p> |
689 | <p>Example:</p> |
690 | <pre> use SDL; |
691 | use SDL::Video; |
692 | use SDL::Color; |
693 | use SDL::TTF; |
694 | use SDL::TTF::Font; |
695 | |
696 | SDL::init(SDL_INIT_VIDEO); |
697 | |
505f308d |
698 | SDL::TTF::init(); |
699 | |
c5f5ab4d |
700 | my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE); |
505f308d |
701 | my $font = SDL::TTF::open_font('arial.ttf', '24'); |
c5f5ab4d |
702 | my $white = SDL::Color->new(0xFF, 0xFF, 0xFF); |
703 | my $black = SDL::Color->new(0x00, 0x00, 0x00); |
704 | my $surface = SDL::TTF::render_text_solid($font, 'Hallo!', $white, $black); |
705 | |
706 | SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480)); |
707 | SDL::Video::update_rect($display, 0, 0, 0, 0); |
708 | |
709 | SDL::delay(5000); |
710 | |
711 | </pre> |
55bbf7a2 |
712 | |
713 | </div> |
c5f5ab4d |
714 | <h4 id="render_utf8_shaded">render_utf8_shaded</h4> |
55bbf7a2 |
715 | <div id="render_utf8_shaded_CONTENT"> |
c5f5ab4d |
716 | <pre> my $surface = SDL::TTF::render_utf8_shaded($font, $text, $color, $background_color); |
717 | |
718 | </pre> |
719 | <p>Render the UTF8 encoded text onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to |
720 | your display-surface.</p> |
55bbf7a2 |
721 | |
722 | </div> |
c5f5ab4d |
723 | <h4 id="render_unicode_shaded">render_unicode_shaded</h4> |
724 | <div id="render_unicode_shaded_CONTENT"> |
725 | <pre> my $surface = SDL::TTF::render_unicode_shaded($font, $text, $color, $background_color); |
726 | |
727 | </pre> |
728 | <p>Render the unicode encoded text onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to |
729 | your display-surface.</p> |
0b221bb4 |
730 | <p><strong>Note</strong>: The unicode text has to be passed exactly like for <a href="SDL-TTF::size_unicode.html">SDL::TTF::size_unicode</a>.</p> |
55bbf7a2 |
731 | |
732 | </div> |
c5f5ab4d |
733 | <h3 id="Blended">Blended</h3> |
734 | <div id="Blended_CONTENT"> |
55bbf7a2 |
735 | |
736 | </div> |
c5f5ab4d |
737 | <h4 id="render_glyph_blended">render_glyph_blended</h4> |
738 | <div id="render_glyph_blended_CONTENT"> |
739 | <pre> my $surface = SDL::TTF::render_glyph_blended($font, $char, $color); |
740 | |
741 | </pre> |
742 | <p>Render the unicode encoded char onto a new surface. After that you can blit this surface to your display-surface.</p> |
0b221bb4 |
743 | <p><strong>Note</strong>: The unicode char has to be passed exactly like for <a href="SDL-TTF::size_unicode.html">SDL::TTF::size_unicode</a>.</p> |
55bbf7a2 |
744 | |
745 | </div> |
c5f5ab4d |
746 | <h4 id="render_text_blended">render_text_blended</h4> |
747 | <div id="render_text_blended_CONTENT"> |
748 | <pre> my $surface = SDL::TTF::render_text_blended($font, $text, $color); |
749 | |
750 | </pre> |
751 | <p>Render the LATIN1 encoded text onto a new surface. After that you can blit this surface to your display-surface.</p> |
752 | <p>Example:</p> |
753 | <pre> use SDL; |
754 | use SDL::Video; |
755 | use SDL::Color; |
756 | use SDL::TTF; |
757 | use SDL::TTF::Font; |
758 | |
759 | SDL::init(SDL_INIT_VIDEO); |
760 | |
505f308d |
761 | SDL::TTF::init(); |
762 | |
c5f5ab4d |
763 | my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE); |
505f308d |
764 | my $font = SDL::TTF::open_font('arial.ttf', '24'); |
c5f5ab4d |
765 | my $surface = SDL::TTF::render_text_blended($font, 'Hallo!', SDL::Color->new(0xFF,0xFF,0xFF)); |
766 | |
767 | SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480)); |
768 | SDL::Video::update_rect($display, 0, 0, 0, 0); |
769 | |
770 | SDL::delay(5000); |
771 | |
772 | </pre> |
773 | |
774 | </div> |
775 | <h4 id="render_utf8_blended">render_utf8_blended</h4> |
776 | <div id="render_utf8_blended_CONTENT"> |
777 | <pre> my $surface = SDL::TTF::render_utf8_blended($font, $text, $color); |
778 | |
779 | </pre> |
780 | <p>Render the UTF8 encoded text onto a new surface. After that you can blit this surface to your display-surface.</p> |
781 | |
782 | </div> |
783 | <h4 id="render_unicode_blended">render_unicode_blended</h4> |
55bbf7a2 |
784 | <div id="render_unicode_blended_CONTENT"> |
c5f5ab4d |
785 | <pre> my $surface = SDL::TTF::render_unicode_blended($font, $text, $color); |
786 | |
787 | </pre> |
788 | <p>Render the unicode encoded text onto a new surface. After that you can blit this surface to your display-surface.</p> |
0b221bb4 |
789 | <p><strong>Note</strong>: The unicode char has to be passed exactly like for <a href="SDL-TTF::size_unicode.html">SDL::TTF::size_unicode</a>.</p> |
55bbf7a2 |
790 | |
791 | </div> |
c7e8d3c6 |
792 | <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
793 | <div id="AUTHORS_CONTENT"> |
794 | <p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p> |
90d38009 |
795 | |
55bbf7a2 |
796 | </div> |
797 | <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p> |
798 | <div id="SEE_ALSO_CONTENT"> |
799 | <p><a href="SDL-TTF-Font.html">SDL::TTF::Font</a>, <a href="http://search.cpan.org/perldoc?Unicode::String">Unicode::String</a>, <a href="SDL-Video.html">SDL::Video</a>, <a href="SDL-Surface.html">SDL::Surface</a></p> |
90d38009 |
800 | |
55bbf7a2 |
801 | </div> |
90d38009 |
802 | </div> |