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