pages/SDL-TTF.html-inc

   1 <div class="pod">
   2 <!-- INDEX START -->
   3 <h3 id="TOP">Index</h3>
   4
   5 <ul><li><a href="#NAME">NAME</a></li>
   6 <li><a href="#CATEGORY">CATEGORY</a></li>
   7 <li><a href="#CONSTANTS">CONSTANTS</a></li>
   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>
  32 <li><a href="#get_font_outline">get_font_outline</a></li>
  33 <li><a href="#set_font_outline">set_font_outline</a></li>
  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>
  71 <ul><li><a href="#Solid">Solid</a>
  72 <ul><li><a href="#render_glyph_solid">render_glyph_solid</a></li>
  73 <li><a href="#render_text_solid">render_text_solid</a></li>
  74 <li><a href="#render_utf8_solid">render_utf8_solid</a></li>
  75 <li><a href="#render_unicode_solid">render_unicode_solid</a></li>
  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>
  82 <li><a href="#render_unicode_shaded">render_unicode_shaded</a></li>
  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>
  89 <li><a href="#render_unicode_blended">render_unicode_blended</a></li>
  90 </ul>
  91 </li>
  92 </ul>
  93 </li>
  94 </ul>
  95 </li>
  96 <li><a href="#AUTHORS">AUTHORS</a></li>
  97 <li><a href="#SEE_ALSO">SEE ALSO</a>
  98 </li>
  99 </ul><hr />
 100 <!-- INDEX END -->
 101
 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">
 109 <p>TTF</p>
 110
 111 </div>
 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 exported by default. You can avoid this by doing:</p>
 115 <pre> use SDL::TTF ();
 116
 117 </pre>
 118 <p>and access them directly:</p>
 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>
 141 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 142 <div id="METHODS_CONTENT">
 143
 144 </div>
 145 <h2 id="General_methods">General methods</h2>
 146 <div id="General_methods_CONTENT">
 147
 148 </div>
 149 <h3 id="linked_version">linked_version</h3>
 150 <div id="linked_version_CONTENT">
 151 <pre> my $version = SDL::TTF::linked_version();
 152
 153 </pre>
 154 <p>This gives you the SDL::Version object which SDL_ttf lib is used on the system.
 155 No prior initialization needs to be done before these function is called. </p>
 156 <p>Example:</p>
 157 <pre> use SDL::TTF;
 158  use SDL::Version;
 159
 160  my $version = SDL::TTF::linked_version();
 161
 162  printf(&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.
 181 This 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>.
 182 SDL does not have to be initialized before this call.</p>
 183 <p>Returns: <code>0</code> on success, <code>-1</code> on any error.</p>
 184
 185 </div>
 186 <h3 id="was_init">was_init</h3>
 187 <div id="was_init_CONTENT">
 188 <pre> my $was_init = SDL::TTF::was_init();
 189
 190 </pre>
 191 <p>Query the initilization status of the truetype font API.
 192 You 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
 193 <a href="/SDL-TTF.html#quit">SDL::TTF::quit</a>.</p>
 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.
 202 After 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
 203 use the functionality again</p>
 204
 205 </div>
 206 <h2 id="Management_functions">Management functions</h2>
 207 <div id="Management_functions_CONTENT">
 208
 209 </div>
 210 <h3 id="open_font">open_font</h3>
 211 <div id="open_font_CONTENT">
 212 <pre> my $font = SDL::TTF::open_font($font_file, $point_size);
 213
 214 </pre>
 215 <p>Load file for use as a font, at the given size. This is actually <code>SDL::TTF::open_font_index(..., ..., $index = 0)</code>. This can load TTF and FON files.</p>
 216 <p>Returns: a <a href="SDL-TTF-Font.html">SDL::TTF::Font</a> object. <code>undef</code> is returned on errors.</p>
 217 <p>Example:</p>
 218 <pre> use SDL::TTF;
 219  use SDL::TTF::Font;
 220
 221  my $font = SDL::TTF::open_font('arial.ttf', 24);
 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>
 231 <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.
 232 This can load TTF and FON files. </p>
 233
 234 </div>
 235 <h3 id="open_font_RW">open_font_RW</h3>
 236 <div id="open_font_RW_CONTENT">
 237 <pre> my $font = SDL::TTF::open_font_RW($rwops_object, $free, $point_size);
 238
 239 </pre>
 240 <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
 241 will be freed by SDL_ttf library. Don't do this, perl will free this object for you.</p>
 242 <p>Example:</p>
 243 <pre> my $font = SDL::TTF::open_font_RW(SDL::RWOps-&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>
 253 <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
 254 <a href="SDL-RWOps.html">SDL::RWOps</a>-object will be freed by SDL_ttf library. Don't do this, perl will free this object for you.</p>
 255
 256 </div>
 257 <h2 id="Attributes">Attributes</h2>
 258 <div id="Attributes_CONTENT">
 259
 260 </div>
 261 <h3 id="Global_attributes">Global attributes</h3>
 262 <div id="Global_attributes_CONTENT">
 263
 264 </div>
 265 <h4 id="byte_swapped_unicode">byte_swapped_unicode</h4>
 266 <div id="byte_swapped_unicode_CONTENT">
 267 <pre> SDL::TTF::byte_swapped_unicode( $bool );
 268
 269 </pre>
 270 <p>This function tells SDL_ttf whether UNICODE (2 bytes per character) text is generally byteswapped. A <code>UNICODE_BOM_NATIVE</code> or
 271 <code>UNICODE_BOM_SWAPPED</code> character in a string will temporarily override this setting for the remainder of that string, however this setting
 272 will be restored for the next one. The default mode is non-swapped, native endianness of the CPU.</p>
 273
 274 </div>
 275 <h3 id="Font_style">Font style</h3>
 276 <div id="Font_style_CONTENT">
 277
 278 </div>
 279 <h4 id="get_font_style">get_font_style</h4>
 280 <div id="get_font_style_CONTENT">
 281 <pre> SDL::TTF::get_font_style($font);
 282
 283 </pre>
 284 <p>Returns: The style as a bitmask composed of the following masks:</p>
 285 <ul>
 286                 <li>TTF_STYLE_NORMAL    </li>
 287                 <li>TTF_STYLE_BOLD      </li>
 288                 <li>TTF_STYLE_ITALIC    </li>
 289                 <li>TTF_STYLE_UNDERLINE </li>
 290                 <li>TTF_STYLE_STRIKETHROUGH (since SDL_ttf 2.0.10)</li>
 291 </ul>
 292
 293 <p>Example:</p>
 294 <pre> my $style = SDL::TTF::get_font_style($font);
 295
 296  print(&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,
 312 to encompass the underline if the original glyph metrics didn't allow for the underline to be drawn below. This does not change the math used
 313 to place a glyph using glyph metrics.
 314 On the other hand <code>TTF_STYLE_STRIKETHROUGH</code> doesn't extend the glyph, since this would invalidate the metrics used to position the glyph when
 315 blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter
 316 about glyph blitting math than they are currently designed for.
 317 Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In
 318 this case, you should probably turn off these styles and draw your own strikethroughs and underlines. </p>
 319
 320 </div>
 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>
 339 <h3 id="Font_settings">Font settings</h3>
 340 <div id="Font_settings_CONTENT">
 341
 342 </div>
 343 <h4 id="get_font_hinting">get_font_hinting</h4>
 344 <div id="get_font_hinting_CONTENT">
 345 <pre> my $hinting = SDL::TTF::get_font_hinting($font);
 346
 347 </pre>
 348 <p>Get the current hinting setting of the loaded font.</p>
 349 <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
 350 <p>Returns the hinting type matching one of the following defined values:</p>
 351 <ul>
 352                 <li>TTF_HINTING_NORMAL  </li>
 353                 <li>TTF_HINTING_LIGHT   </li>
 354                 <li>TTF_HINTING_MONO    </li>
 355                 <li>TTF_HINTING_NONE</li>
 356 </ul>
 357
 358
 359 </div>
 360 <h4 id="set_font_hinting">set_font_hinting</h4>
 361 <div id="set_font_hinting_CONTENT">
 362 <pre> SDL::TTF::set_font_hinting($font, $hinting);
 363
 364 </pre>
 365 <p>Set the hinting of the loaded font. You should experiment with this setting if you know which font you are using beforehand, especially when
 366 using smaller sized fonts. If the user is selecting a font, you may wish to let them select the hinting mode for that font as well.</p>
 367 <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
 368 <p>Example:</p>
 369 <pre> SDL::TTF::set_font_hinting($font, TTF_HINTING_LIGHT);
 370
 371 </pre>
 372
 373 </div>
 374 <h4 id="get_font_kerning">get_font_kerning</h4>
 375 <div id="get_font_kerning_CONTENT">
 376 <pre> my $kerning_enabled = SDL::TTF::get_font_kerning($font);
 377
 378 </pre>
 379 <p>Get the current kerning setting of the loaded font.</p>
 380 <p>Returns: <code>0</code>(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(<code>1</code>). </p>
 381 <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
 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>
 383
 384 </div>
 385 <h4 id="set_font_kerning">set_font_kerning</h4>
 386 <div id="set_font_kerning_CONTENT">
 387 <pre> SDL::TTF::set_font_kerning($font, $kerning_enabled);
 388
 389 </pre>
 390 <p>Set whether to use kerning when rendering the loaded font. This has no effect on individual glyphs, but rather when rendering whole strings of
 391 characters, at least a word at a time. Perhaps the only time to disable this is when kerning is not working for a specific font, resulting in
 392 overlapping glyphs or abnormal spacing within words.</p>
 393 <p>Pass <code>0</code> to disable kerning, 1 to enable.</p>
 394 <p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
 395
 396 </div>
 397 <h3 id="Font_metrics">Font metrics</h3>
 398 <div id="Font_metrics_CONTENT">
 399
 400 </div>
 401 <h4 id="font_height">font_height</h4>
 402 <div id="font_height_CONTENT">
 403 <pre> my $font_height = SDL::TTF::font_height($font);
 404
 405 </pre>
 406 <p>Get the maximum pixel height of all glyphs of the loaded font. You may use this height for rendering text as close together vertically as
 407 possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_ttf doesn't handle multiline
 408 printing, 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>
 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);
 414
 415 </pre>
 416 <p>Get the maximum pixel ascent of all glyphs of the loaded font. This can also be interpreted as the distance from the top of the font to the
 417 baseline.
 418 It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's <code>maxy</code> metric to resolve the top
 419 of the rectangle used when blitting the glyph on the screen.</p>
 420 <p>Example:</p>
 421 <pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
 422
 423  $rect-&gt;y( $top + SDL::TTF::font_ascent($font) - $maxy );
 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);
 431
 432 </pre>
 433 <p>Get the maximum pixel descent of all glyphs of the loaded font. This can also be interpreted as the distance from the baseline to the bottom of
 434 the font.
 435 It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's <code>maxy</code> metric to resolve the top
 436 of the rectangle used when blitting the glyph on the screen.</p>
 437 <p>Example:</p>
 438 <pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
 439
 440  $rect-&gt;y( $bottom - SDL::TTF::font_descent($font) - $maxy );
 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);
 448
 449 </pre>
 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.html#font_height">SDL::TTF::font_height</a> of the
 451 font.</p>
 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">
 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
 464 and other typographical features perhaps) contained in the font itself.</p>
 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">
 469 <pre> my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font);
 470
 471 </pre>
 472 <p>Test if the current font face of the loaded font is a fixed width font. Fixed width fonts are monospace, meaning every character that exists
 473 in the font is the same width, thus you can assume that a rendered string's width is going to be the result of <code>glyph_width * string_length</code>.</p>
 474 <p>Returns: <code>&gt;0</code> if font is a fixed width font. <code>0</code> if not a fixed width font. </p>
 475
 476 </div>
 477 <h4 id="font_face_family_name">font_face_family_name</h4>
 478 <div id="font_face_family_name_CONTENT">
 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>
 489
 490 </div>
 491 <h4 id="font_face_style_name">font_face_style_name</h4>
 492 <div id="font_face_style_name_CONTENT">
 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>
 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">
 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>
 522
 523 </div>
 524 <h4 id="glyph_metrics">glyph_metrics</h4>
 525 <div id="glyph_metrics_CONTENT">
 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;) };
 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">
 544 <pre> my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
 545
 546 </pre>
 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
 548 is 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>
 549
 550 </div>
 551 <h4 id="size_utf8">size_utf8</h4>
 552 <div id="size_utf8_CONTENT">
 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
 557 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>
 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
 571
 572 </pre>
 573
 574 </div>
 575 <h4 id="size_unicode">size_unicode</h4>
 576 <div id="size_unicode_CONTENT">
 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
 581 is done to get the actual width. The height returned in h is the same as you can get using <a href="/SDL-TTF.html#font_height">SDL::TTF::font_height</a>.</p>
 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>
 598
 599 </div>
 600 <h2 id="Font_Rendering">Font Rendering</h2>
 601 <div id="Font_Rendering_CONTENT">
 602
 603 </div>
 604 <h3 id="Solid">Solid</h3>
 605 <div id="Solid_CONTENT">
 606
 607 </div>
 608 <h4 id="render_glyph_solid">render_glyph_solid</h4>
 609 <div id="render_glyph_solid_CONTENT">
 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>
 614 <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>
 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>
 616
 617 </div>
 618 <h4 id="render_text_solid">render_text_solid</h4>
 619 <div id="render_text_solid_CONTENT">
 620 <pre> my $surface = SDL::TTF::render_text_solid($font, $text, $color);
 621
 622 </pre>
 623 <p>Render the LATIN1 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.</p>
 624 <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least
 625 version 2.3.5</p>
 626 <p>Example:</p>
 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;
 633
 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);
 643
 644 </pre>
 645
 646 </div>
 647 <h4 id="render_utf8_solid">render_utf8_solid</h4>
 648 <div id="render_utf8_solid_CONTENT">
 649 <pre> my $surface = SDL::TTF::render_utf8_solid($font, $text, $color);
 650
 651 </pre>
 652 <p>Render the UTF8 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.</p>
 653 <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least
 654 version 2.3.5</p>
 655
 656 </div>
 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>
 663 <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>
 664 <p><strong>Note</strong>: <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062">See space-character bug</a>. You have to upgrade libfreetype2 to at least
 665 version 2.3.5</p>
 666
 667 </div>
 668 <h3 id="Shaded">Shaded</h3>
 669 <div id="Shaded_CONTENT">
 670
 671 </div>
 672 <h4 id="render_glyph_shaded">render_glyph_shaded</h4>
 673 <div id="render_glyph_shaded_CONTENT">
 674 <pre> my $surface = SDL::TTF::render_glyph_shaded($font, $char, $color, $background_color);
 675
 676 </pre>
 677 <p>Render the unicode encoded char onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to
 678 your display-surface.</p>
 679 <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>
 680
 681 </div>
 682 <h4 id="render_text_shaded">render_text_shaded</h4>
 683 <div id="render_text_shaded_CONTENT">
 684 <pre> my $surface = SDL::TTF::render_text_shaded($font, $text, $color, $background_color);
 685
 686 </pre>
 687 <p>Render the LATIN1 encoded text onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to
 688 your display-surface.</p>
 689 <p>Example:</p>
 690 <pre> use SDL;
 691  use SDL::Video;
 692  use SDL::Color;
 693  use SDL::TTF;
 694  use SDL::TTF::Font;
 695
 696  SDL::init(SDL_INIT_VIDEO);
 697
 698  SDL::TTF::init();
 699
 700  my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
 701  my $font    = SDL::TTF::open_font('arial.ttf', '24');
 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>
 712
 713 </div>
 714 <h4 id="render_utf8_shaded">render_utf8_shaded</h4>
 715 <div id="render_utf8_shaded_CONTENT">
 716 <pre> my $surface = SDL::TTF::render_utf8_shaded($font, $text, $color, $background_color);
 717
 718 </pre>
 719 <p>Render the UTF8 encoded text onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to
 720 your display-surface.</p>
 721
 722 </div>
 723 <h4 id="render_unicode_shaded">render_unicode_shaded</h4>
 724 <div id="render_unicode_shaded_CONTENT">
 725 <pre> my $surface = SDL::TTF::render_unicode_shaded($font, $text, $color, $background_color);
 726
 727 </pre>
 728 <p>Render the unicode encoded text onto a new surface. The surface is filled with <code>$background_color</code>. After that you can blit this surface to
 729 your display-surface.</p>
 730 <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>
 731
 732 </div>
 733 <h3 id="Blended">Blended</h3>
 734 <div id="Blended_CONTENT">
 735
 736 </div>
 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>
 743 <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>
 744
 745 </div>
 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
 761  SDL::TTF::init();
 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>
 784 <div id="render_unicode_blended_CONTENT">
 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>
 790
 791 </div>
 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>
 795
 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>
 800
 801 </div>
 802 </div>