projects / sdlgit/SDL-Site.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | history | HEAD
added docs for SDL::TTF::Font
[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
3ad5a97a 191 my $font = SDL::TTF::open_font('arial.ttf', 24);
55bbf7a2 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>
148a0b32 352<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 353
354</div>
355<h4 id="set_font_kerning">set_font_kerning</h4>
356<div id="set_font_kerning_CONTENT">
357<pre> SDL::TTF::set_font_kerning($font, $kerning_enabled);
358
359</pre>
360<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
361characters, 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
362overlapping glyphs or abnormal spacing within words.</p>
363<p>Pass <code>0</code> to disable kerning, 1 to enable.</p>
364<p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
365
366</div>
367<h3 id="Font_metrics">Font metrics</h3>
368<div id="Font_metrics_CONTENT">
369
370</div>
371<h4 id="font_height">font_height</h4>
372<div id="font_height_CONTENT">
373<pre> my $font_height = SDL::TTF::font_height($font);
374
375</pre>
b2c46b06 376<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
377possible, 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
378printing, 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 379
380</div>
381<h4 id="font_ascent">font_ascent</h4>
382<div id="font_ascent_CONTENT">
383<pre> my $font_ascent = SDL::TTF::font_ascent($font);
b2c46b06 384
385</pre>
386<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
387baseline.
388It 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
389of the rectangle used when blitting the glyph on the screen.</p>
390<p>Example:</p>
c5291845 391<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
b2c46b06 392
393 $rect-&gt;y( $top + SDL::TTF::font_ascent($font) - $maxy );
55bbf7a2 394
395</pre>
396
397</div>
398<h4 id="font_descent">font_descent</h4>
399<div id="font_descent_CONTENT">
400<pre> my $font_descent = SDL::TTF::font_descent($font);
b2c46b06 401
402</pre>
403<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
404the font.
405It 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
406of the rectangle used when blitting the glyph on the screen.</p>
407<p>Example:</p>
c5291845 408<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
b2c46b06 409
410 $rect-&gt;y( $bottom - SDL::TTF::font_descent($font) - $maxy );
55bbf7a2 411
412</pre>
413
414</div>
415<h4 id="font_line_skip">font_line_skip</h4>
416<div id="font_line_skip_CONTENT">
417<pre> my $font_line_skip = SDL::TTF::font_line_skip($font);
55bbf7a2 418
419</pre>
b2c46b06 420<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
421font.</p>
55bbf7a2 422
423</div>
424<h3 id="Face_attributes">Face attributes</h3>
425<div id="Face_attributes_CONTENT">
426
427</div>
428<h4 id="font_faces">font_faces</h4>
429<div id="font_faces_CONTENT">
b0e2356c 430<pre> my $font_faces = SDL::TTF::font_faces($font);
431
432</pre>
433<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
434and other typographical features perhaps) contained in the font itself.</p>
55bbf7a2 435
436</div>
437<h4 id="font_face_is_fixed_width">font_face_is_fixed_width</h4>
438<div id="font_face_is_fixed_width_CONTENT">
b0e2356c 439<pre> my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font);
440
441</pre>
442<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
443in 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>
444<p>Returns: <code>&gt;0</code> if font is a fixed width font. <code>0</code> if not a fixed width font. </p>
55bbf7a2 445
446</div>
447<h4 id="font_face_family_name">font_face_family_name</h4>
448<div id="font_face_family_name_CONTENT">
b0e2356c 449<pre> my $font_face_family_name = SDL::TTF::font_face_family_name($font);
450
451</pre>
452<p>Get the current font face family name from the loaded font. This information is not for every font available.</p>
453<p>Example:</p>
454<pre> my $font = SDL::TTF::open_font('arialuni.ttf', 8);
455
456 printf(&quot;%s\n&quot;, SDL::TTF::font_face_family_name($font)); # will print &quot;Arial Unicode MS&quot;
457
458</pre>
55bbf7a2 459
460</div>
461<h4 id="font_face_style_name">font_face_style_name</h4>
462<div id="font_face_style_name_CONTENT">
b0e2356c 463<pre> my $font_face_style_name = SDL::TTF::font_face_style_name($font);
464
465</pre>
466<p>Get the current font face style name from the loaded font. This information is not for every font available. </p>
467<p>Example:</p>
468<pre> my $font = SDL::TTF::open_font('arialuni.ttf', 8);
469
470 printf(&quot;%s\n&quot;, SDL::TTF::font_face_style_name($font)); # will print &quot;Regular&quot;
471
472</pre>
55bbf7a2 473
474</div>
475<h3 id="Glyphs">Glyphs</h3>
476<div id="Glyphs_CONTENT">
477
478</div>
479<h4 id="glyph_is_provided">glyph_is_provided</h4>
480<div id="glyph_is_provided_CONTENT">
c5291845 481<pre> my $glyph_is_provided = SDL::TTF::glyph_is_provided($font, $unicode_char);
482
483</pre>
484<p>Get the status of the availability of the glyph from the loaded font.</p>
485<p>Returns: the index of the glyph in font, or 0 for an undefined character code.</p>
486<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>
487<p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
488<p>Example:</p>
489<pre> print(&quot;We have this char!\n&quot;) if SDL::TTF::glyph_is_provided($font, &quot;\0M&quot;);
490
491</pre>
55bbf7a2 492
493</div>
494<h4 id="glyph_metrics">glyph_metrics</h4>
495<div id="glyph_metrics_CONTENT">
c5291845 496<pre> my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, $unicode_char) };
497
498</pre>
499<p>Get desired glyph metrics of the UNICODE char from the loaded font.</p>
500<p>See also: <a href="http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html">The FreeType2 Documentation Tutorial</a></p>
501<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>
502<p>Example:</p>
503<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
55bbf7a2 504
505</pre>
506
507</div>
508<h3 id="Text_metrics">Text metrics</h3>
509<div id="Text_metrics_CONTENT">
510
511</div>
512<h4 id="size_text">size_text</h4>
513<div id="size_text_CONTENT">
499f3731 514<pre> my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
55bbf7a2 515
516</pre>
499f3731 517<p>Calculate the resulting surface size of the LATIN1 encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning
518is 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 519
520</div>
521<h4 id="size_utf8">size_utf8</h4>
522<div id="size_utf8_CONTENT">
499f3731 523<pre> my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) };
524
525</pre>
526<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
527done 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>
528<p>Note that the first example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.</p>
529<p>Examples:</p>
530<pre> ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') }; # plain text, if your script is in utf8 or ansi-format
531
532 # or
533
534 ($width, $height) = @{ SDL::TTF::size_utf8($font, &quot;\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF&quot;) }; # utf8 hex-data
535
536 # or
537
538 use Unicode::String;
539 my $unicode = utf8($data_from_somwhere);
540 ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode-&gt;utf8) }; # utf8 via Unicode::String
55bbf7a2 541
542</pre>
543
544</div>
545<h4 id="size_unicode">size_unicode</h4>
546<div id="size_unicode_CONTENT">
499f3731 547<pre> my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) };
548
549</pre>
550<p>Calculate the resulting surface size of the UNICODE encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning
551is 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>
552<p><code>$text</code> has to be:</p>
553<dl>
554 <dt>UTF16BE without BOM</dt>
555 <dd>
556 <p>&quot;hallo&quot; will look like &quot;\0h\0a\0l\0l\0o&quot;</p>
557 </dd>
558 <dt>UTF16BE with BOM</dt>
559 <dd>
560 <p>&quot;hallo&quot; will look like &quot;\xFE\xFF\0h\0a\0l\0l\0o&quot;</p>
561 </dd>
562 <dt>UTF16LE with BOM</dt>
563 <dd>
564 <p>&quot;hallo&quot; will look like &quot;\xFF\xFEh\0a\0l\0l\0o\0&quot;</p>
565 </dd>
566</dl>
567<p>You may use Unicode::String for this.</p>
55bbf7a2 568
569</div>
570<h2 id="Font_Rendering">Font Rendering</h2>
571<div id="Font_Rendering_CONTENT">
572
573</div>
c5f5ab4d 574<h3 id="Solid">Solid</h3>
575<div id="Solid_CONTENT">
576
577</div>
578<h4 id="render_glyph_solid">render_glyph_solid</h4>
55bbf7a2 579<div id="render_glyph_solid_CONTENT">
c5f5ab4d 580<pre> my $surface = SDL::TTF::render_glyph_solid($font, $char, $color);
581
582</pre>
583<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>
584<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>
585<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 586
587</div>
c5f5ab4d 588<h4 id="render_text_solid">render_text_solid</h4>
589<div id="render_text_solid_CONTENT">
590<pre> my $surface = SDL::TTF::render_text_solid($font, $text, $color);
591
592</pre>
593<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>
594<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
595version 2.3.5</p>
596<p>Example:</p>
597<pre> use SDL;
598 use SDL::Video;
599 use SDL::Color;
600 use SDL::TTF;
601 use SDL::TTF::Font;
602
603 SDL::init(SDL_INIT_VIDEO);
604
605 my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
606 my $font = SDL::TTF::open_font('arial.ttf', '24);
607 my $surface = SDL::TTF::render_text_solid($font, 'Hallo!', SDL::Color-&gt;new(0xFF,0xFF,0xFF));
608
609 SDL::Video::blit_surface($surface, SDL::Rect-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;new(10, 10, 640, 480));
610 SDL::Video::update_rect($display, 0, 0, 0, 0);
611
612 SDL::delay(5000);
613
614</pre>
55bbf7a2 615
616</div>
c5f5ab4d 617<h4 id="render_utf8_solid">render_utf8_solid</h4>
618<div id="render_utf8_solid_CONTENT">
619<pre> my $surface = SDL::TTF::render_utf8_solid($font, $text, $color);
620
621</pre>
622<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>
623<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
624version 2.3.5</p>
55bbf7a2 625
626</div>
c5f5ab4d 627<h4 id="render_unicode_solid">render_unicode_solid</h4>
628<div id="render_unicode_solid_CONTENT">
629<pre> my $surface = SDL::TTF::render_unicode_solid($font, $text, $color);
630
631</pre>
632<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>
633<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>
634<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
635version 2.3.5</p>
55bbf7a2 636
637</div>
c5f5ab4d 638<h3 id="Shaded">Shaded</h3>
639<div id="Shaded_CONTENT">
55bbf7a2 640
641</div>
c5f5ab4d 642<h4 id="render_glyph_shaded">render_glyph_shaded</h4>
643<div id="render_glyph_shaded_CONTENT">
644<pre> my $surface = SDL::TTF::render_glyph_shaded($font, $char, $color, $background_color);
645
646</pre>
647<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
648your display-surface.</p>
649<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 650
651</div>
c5f5ab4d 652<h4 id="render_text_shaded">render_text_shaded</h4>
653<div id="render_text_shaded_CONTENT">
654<pre> my $surface = SDL::TTF::render_text_shaded($font, $text, $color, $background_color);
655
656</pre>
657<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
658your display-surface.</p>
659<p>Example:</p>
660<pre> use SDL;
661 use SDL::Video;
662 use SDL::Color;
663 use SDL::TTF;
664 use SDL::TTF::Font;
665
666 SDL::init(SDL_INIT_VIDEO);
667
668 my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
669 my $font = SDL::TTF::open_font('arial.ttf', '24);
670 my $white = SDL::Color-&gt;new(0xFF, 0xFF, 0xFF);
671 my $black = SDL::Color-&gt;new(0x00, 0x00, 0x00);
672 my $surface = SDL::TTF::render_text_solid($font, 'Hallo!', $white, $black);
673
674 SDL::Video::blit_surface($surface, SDL::Rect-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;new(10, 10, 640, 480));
675 SDL::Video::update_rect($display, 0, 0, 0, 0);
676
677 SDL::delay(5000);
678
679</pre>
55bbf7a2 680
681</div>
c5f5ab4d 682<h4 id="render_utf8_shaded">render_utf8_shaded</h4>
55bbf7a2 683<div id="render_utf8_shaded_CONTENT">
c5f5ab4d 684<pre> my $surface = SDL::TTF::render_utf8_shaded($font, $text, $color, $background_color);
685
686</pre>
687<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
688your display-surface.</p>
55bbf7a2 689
690</div>
c5f5ab4d 691<h4 id="render_unicode_shaded">render_unicode_shaded</h4>
692<div id="render_unicode_shaded_CONTENT">
693<pre> my $surface = SDL::TTF::render_unicode_shaded($font, $text, $color, $background_color);
694
695</pre>
696<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
697your display-surface.</p>
698<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 699
700</div>
c5f5ab4d 701<h3 id="Blended">Blended</h3>
702<div id="Blended_CONTENT">
55bbf7a2 703
704</div>
c5f5ab4d 705<h4 id="render_glyph_blended">render_glyph_blended</h4>
706<div id="render_glyph_blended_CONTENT">
707<pre> my $surface = SDL::TTF::render_glyph_blended($font, $char, $color);
708
709</pre>
710<p>Render the unicode encoded char onto a new surface. After that you can blit this surface to your display-surface.</p>
711<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 712
713</div>
c5f5ab4d 714<h4 id="render_text_blended">render_text_blended</h4>
715<div id="render_text_blended_CONTENT">
716<pre> my $surface = SDL::TTF::render_text_blended($font, $text, $color);
717
718</pre>
719<p>Render the LATIN1 encoded text onto a new surface. After that you can blit this surface to your display-surface.</p>
720<p>Example:</p>
721<pre> use SDL;
722 use SDL::Video;
723 use SDL::Color;
724 use SDL::TTF;
725 use SDL::TTF::Font;
726
727 SDL::init(SDL_INIT_VIDEO);
728
729 my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
730 my $font = SDL::TTF::open_font('arial.ttf', '24);
731 my $surface = SDL::TTF::render_text_blended($font, 'Hallo!', SDL::Color-&gt;new(0xFF,0xFF,0xFF));
732
733 SDL::Video::blit_surface($surface, SDL::Rect-&gt;new(0, 0, 640, 480), $display, SDL::Rect-&gt;new(10, 10, 640, 480));
734 SDL::Video::update_rect($display, 0, 0, 0, 0);
735
736 SDL::delay(5000);
737
738</pre>
739
740</div>
741<h4 id="render_utf8_blended">render_utf8_blended</h4>
742<div id="render_utf8_blended_CONTENT">
743<pre> my $surface = SDL::TTF::render_utf8_blended($font, $text, $color);
744
745</pre>
746<p>Render the UTF8 encoded text onto a new surface. After that you can blit this surface to your display-surface.</p>
747
748</div>
749<h4 id="render_unicode_blended">render_unicode_blended</h4>
55bbf7a2 750<div id="render_unicode_blended_CONTENT">
c5f5ab4d 751<pre> my $surface = SDL::TTF::render_unicode_blended($font, $text, $color);
752
753</pre>
754<p>Render the unicode encoded text onto a new surface. After that you can blit this surface to your display-surface.</p>
755<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 756
757</div>
758<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
759<div id="AUTHOR_CONTENT">
760<p>Tobias Leich [FROGGS]</p>
90d38009 761
55bbf7a2 762</div>
763<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
764<div id="SEE_ALSO_CONTENT">
765<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 766
55bbf7a2 767</div>
90d38009 768</div>
Unnamed repository; edit this file to name it for gitweb.