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