projects / sdlgit/SDL-Site.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | history | HEAD
update for SDL::Event
[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>
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 &quot;hinting&quot;:</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 &quot;style&quot;:</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.
155No 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(&quot;got version: %d.%d.%d\n&quot;, $version-&gt;major, $version-&gt;minor, $version-&gt;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 181This 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 182SDL 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 192You 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 202After 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 203use 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 232This 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 241will 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-&gt;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
272will 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(&quot;normal\n&quot;) if $style == TTF_STYLE_NORMAL;
297 print(&quot;bold\n&quot;) if $style &amp; TTF_STYLE_BOLD;
298 print(&quot;italic\n&quot;) if $style &amp; TTF_STYLE_ITALIC;
299 print(&quot;underline\n&quot;) if $style &amp; TTF_STYLE_UNDERLINE;
300 print(&quot;strikethrough\n&quot;) if $style &amp; 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,
312to 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
313to place a glyph using glyph metrics.
314On 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
315blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter
316about glyph blitting math than they are currently designed for.
317Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In
318this 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
366using 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
391characters, 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
392overlapping 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
407possible, 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 408printing, 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
417baseline.
418It 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
419of 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, &quot;\0M&quot;) };
b2c46b06 422
423 $rect-&gt;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
434the font.
435It 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
436of 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, &quot;\0M&quot;) };
b2c46b06 439
440 $rect-&gt;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 451font.</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 (&quot;sub-fonts&quot;) available in the loaded font. This is a count of the number of specific fonts (based on size and style
464and 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
473in 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>&gt;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(&quot;%s\n&quot;, SDL::TTF::font_face_family_name($font)); # will print &quot;Arial Unicode MS&quot;
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(&quot;%s\n&quot;, SDL::TTF::font_face_style_name($font)); # will print &quot;Regular&quot;
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(&quot;We have this char!\n&quot;) if SDL::TTF::glyph_is_provided($font, &quot;\0M&quot;);
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, &quot;\0M&quot;) };
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 548is 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 557done 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, &quot;\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF&quot;) }; # 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-&gt;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 581is 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>&quot;hallo&quot; will look like &quot;\0h\0a\0l\0l\0o&quot;</p>
587 </dd>
588 <dt>UTF16BE with BOM</dt>
589 <dd>
590 <p>&quot;hallo&quot; will look like &quot;\xFE\xFF\0h\0a\0l\0l\0o&quot;</p>
591 </dd>
592 <dt>UTF16LE with BOM</dt>
593 <dd>
594 <p>&quot;hallo&quot; will look like &quot;\xFF\xFEh\0a\0l\0l\0o\0&quot;</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
625version 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-&gt;new(0xFF,0xFF,0xFF));
640 SDL::Video::blit_surface($surface, SDL::Rect-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;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
654version 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
665version 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
678your 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
688your 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-&gt;new(0xFF, 0xFF, 0xFF);
703 my $black = SDL::Color-&gt;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-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;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
720your 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
729your 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-&gt;new(0xFF,0xFF,0xFF));
766
767 SDL::Video::blit_surface($surface, SDL::Rect-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;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>
Unnamed repository; edit this file to name it for gitweb.