SDL::TTF(3pm)

1SDL::TTF(3)           User Contributed Perl Documentation          SDL::TTF(3)
2
3
4

NAME

6       SDL::TTF - True Type Font functions (libfreetype)
7

CONSTANTS

12       The constants are exported by default. You can avoid this by doing:
13
14        use SDL::TTF ();
15
16       and access them directly:
17
18        SDL::TTF::TTF_HINTING_NORMAL;
19
20       Available constants for "hinting":
21
22       •   TTF_HINTING_NORMAL
23
24       •   TTF_HINTING_LIGHT
25
26       •   TTF_HINTING_MONO
27
28       •   TTF_HINTING_NONE
29
30       Available constants for "style":
31
32       •   TTF_STYLE_NORMAL
33
34       •   TTF_STYLE_BOLD
35
36       •   TTF_STYLE_ITALIC
37
38       •   TTF_STYLE_UNDERLINE
39
40       •   TTF_STYLE_STRIKETHROUGH
41

METHODS

43   General methods
44       linked_version
45
46        my $version = SDL::TTF::linked_version();
47
48       This gives you the SDL::Version object which SDL_ttf lib is used on the
49       system.  No prior initialization needs to be done before these function
50       is called.
51
52       Example:
53
54        use SDL::TTF;
55        use SDL::Version;
56
57        my $version = SDL::TTF::linked_version();
58
59        printf("got version: %d.%d.%d\n", $version->major, $version->minor, $version->patch);
60
61       compile_time_version
62
63        my $version = SDL::TTF::compile_time_version();
64
65       This gives you the SDL::Version object which SDL_ttf was present at
66       compile time.
67
68       init
69
70        my $success = SDL::TTF::init();
71
72       Initialize the truetype font API.  This must be called before using
73       other functions in this library, except SDL::TTF::was_init and
74       SDL::TTF::linked_version.  SDL does not have to be initialized before
75       this call.
76
77       Returns: 0 on success, "-1" on any error.
78
79       was_init
80
81        my $was_init = SDL::TTF::was_init();
82
83       Query the initialization status of the truetype font API.  You may, of
84       course, use this before SDL::TTF::init to avoid initializing twice in a
85       row. Or use this to determine if you need to call SDL::TTF::quit.
86
87       quit
88
89        SDL::TTF::quit();
90
91       Shutdown and cleanup the truetype font API.  After calling this the
92       SDL::TTF functions should not be used, excepting SDL::TTF::was_init.
93       You may, of course, use SDL::TTF::init to use the functionality again
94
95   Management functions
96       open_font
97
98        my $font = SDL::TTF::open_font($font_file, $point_size);
99
100       Load file for use as a font, at the given size. This is actually
101       "SDL::TTF::open_font_index(..., ..., $index = 0)". This can load TTF,
102       OTF and FON files.
103
104       Returns: a SDL::TTF::Font object. "undef" is returned on errors.
105
106       Example:
107
108        use SDL::TTF;
109        use SDL::TTF::Font;
110
111        my $font = SDL::TTF::open_font('arial.ttf', 24);
112
113       open_font_index
114
115        my $font = SDL::TTF::open_font($font_file, $point_size, $face_index);
116
117       This is the same as SDL::TTF::open_font, except you can specify the
118       face index of a font file containing multiple faces.  This can load TTF
119       and FON files.
120
121       open_font_RW
122
123        my $font = SDL::TTF::open_font_RW($rwops_object, $free, $point_size);
124
125       This is the same as SDL::TTF::open_font, except you can pass an
126       SDL::RWOps-object. If you pass true as $free, the SDL::RWOps-object
127       will be freed by SDL_ttf library. Don't do this, perl will free this
128       object for you.
129
130       Example:
131
132        my $font = SDL::TTF::open_font_RW(SDL::RWOps->new_file($font_file, 'r'), 0, 24);
133
134       open_font_index_RW
135
136        my $font = SDL::TTF::open_font_index_RW($rwops_object, $free, $point_size, $face_index);
137
138       This is the same as SDL::TTF::open_font_index, except you can pass an
139       SDL::RWOps-object. If you pass true as $free, the SDL::RWOps-object
140       will be freed by SDL_ttf library. Don't do this, perl will free this
141       object for you.
142
143   Attributes
144       Global attributes
145
146       byte_swapped_unicode
147
148        SDL::TTF::byte_swapped_unicode( $bool );
149
150       This function tells SDL_ttf whether UNICODE (2 bytes per character)
151       text is generally byteswapped. A "UNICODE_BOM_NATIVE" or
152       "UNICODE_BOM_SWAPPED" character in a string will temporarily override
153       this setting for the remainder of that string, however this setting
154       will be restored for the next one. The default mode is non-swapped,
155       native endianness of the CPU.
156
157       Font style
158
159       get_font_style
160
161        SDL::TTF::get_font_style($font);
162
163       Returns: The style as a bitmask composed of the following masks:
164
165       •   TTF_STYLE_NORMAL
166
167       •   TTF_STYLE_BOLD
168
169       •   TTF_STYLE_ITALIC
170
171       •   TTF_STYLE_UNDERLINE
172
173       •   TTF_STYLE_STRIKETHROUGH (since SDL_ttf 2.0.10)
174
175       Example:
176
177        my $style = SDL::TTF::get_font_style($font);
178
179        print("normal\n")        if $style == TTF_STYLE_NORMAL;
180        print("bold\n")          if $style  & TTF_STYLE_BOLD;
181        print("italic\n")        if $style  & TTF_STYLE_ITALIC;
182        print("underline\n")     if $style  & TTF_STYLE_UNDERLINE;
183        print("strikethrough\n") if $style  & TTF_STYLE_STRIKETHROUGH;
184
185       set_font_style
186
187        SDL::TTF::set_font_style($font, $style);
188
189       Set the rendering style of the loaded font.
190
191       Note: "TTF_STYLE_UNDERLINE" may cause surfaces created by
192       "SDL::TTF::render_glyph_*" functions to be extended vertically,
193       downward only, to encompass the underline if the original glyph metrics
194       didn't allow for the underline to be drawn below. This does not change
195       the math used to place a glyph using glyph metrics.  On the other hand
196       "TTF_STYLE_STRIKETHROUGH" doesn't extend the glyph, since this would
197       invalidate the metrics used to position the glyph when blitting,
198       because they would likely be extended vertically upward. There is
199       perhaps a workaround, but it would require programs to be smarter about
200       glyph blitting math than they are currently designed for.  Still,
201       sometimes the underline or strikethrough may be outside of the
202       generated surface, and thus not visible when blitted to the screen. In
203       this case, you should probably turn off these styles and draw your own
204       strikethroughs and underlines.
205
206       get_font_outline
207
208        my $outline = SDL::TTF::get_font_outline($font);
209
210       Get the current outline width of the font, in pixels.
211
212       Note: at least SDL_ttf 2.0.10 needed
213
214       set_font_outline
215
216        SDL::TTF::set_font_outline($font, $outline);
217
218       Set the outline pixel width of the loaded font. Use 0(zero) to turn off
219       outlining.
220
221       Note: at least SDL_ttf 2.0.10 needed
222
223       Font settings
224
225       get_font_hinting
226
227        my $hinting = SDL::TTF::get_font_hinting($font);
228
229       Get the current hinting setting of the loaded font.
230
231       Note: at least SDL_ttf 2.0.10 needed
232
233       Returns the hinting type matching one of the following defined values:
234
235       •   TTF_HINTING_NORMAL
236
237       •   TTF_HINTING_LIGHT
238
239       •   TTF_HINTING_MONO
240
241       •   TTF_HINTING_NONE
242
243       set_font_hinting
244
245        SDL::TTF::set_font_hinting($font, $hinting);
246
247       Set the hinting of the loaded font. You should experiment with this
248       setting if you know which font you are using beforehand, especially
249       when using smaller sized fonts. If the user is selecting a font, you
250       may wish to let them select the hinting mode for that font as well.
251
252       Note: at least SDL_ttf 2.0.10 needed
253
254       Example:
255
256        SDL::TTF::set_font_hinting($font, TTF_HINTING_LIGHT);
257
258       get_font_kerning
259
260        my $kerning_enabled = SDL::TTF::get_font_kerning($font);
261
262       Get the current kerning setting of the loaded font.
263
264       Returns: 0(zero) if kerning is disabled. A non-zero value is returned
265       when enabled. The default for a newly loaded font is enabled(1).
266
267       Note: at least SDL_ttf 2.0.10 needed
268
269       Note: This function returns wrong values: See
270       <http://bugzilla.libsdl.org/show_bug.cgi?id=973>
271
272       set_font_kerning
273
274        SDL::TTF::set_font_kerning($font, $kerning_enabled);
275
276       Set whether to use kerning when rendering the loaded font. This has no
277       effect on individual glyphs, but rather when rendering whole strings of
278       characters, at least a word at a time. Perhaps the only time to disable
279       this is when kerning is not working for a specific font, resulting in
280       overlapping glyphs or abnormal spacing within words.
281
282       Pass 0 to disable kerning, 1 to enable.
283
284       Note: at least SDL_ttf 2.0.10 needed
285
286       Font metrics
287
288       font_height
289
290        my $font_height = SDL::TTF::font_height($font);
291
292       Get the maximum pixel height of all glyphs of the loaded font. You may
293       use this height for rendering text as close together vertically as
294       possible, though adding at least one pixel height to it will space it
295       so they can't touch. Remember that SDL_ttf doesn't handle multiline
296       printing, so you are responsible for line spacing, see the
297       SDL::TTF::font_line_skip as well.
298
299       font_ascent
300
301        my $font_ascent = SDL::TTF::font_ascent($font);
302
303       Get the maximum pixel ascent of all glyphs of the loaded font. This can
304       also be interpreted as the distance from the top of the font to the
305       baseline.  It could be used when drawing an individual glyph relative
306       to a top point, by combining it with the glyph's "maxy" metric to
307       resolve the top of the rectangle used when blitting the glyph on the
308       screen.
309
310       Example:
311
312        my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
313
314        $rect->y( $top + SDL::TTF::font_ascent($font) - $maxy );
315
316       font_descent
317
318        my $font_descent = SDL::TTF::font_descent($font);
319
320       Get the maximum pixel descent of all glyphs of the loaded font. This
321       can also be interpreted as the distance from the baseline to the bottom
322       of the font.  It could be used when drawing an individual glyph
323       relative to a bottom point, by combining it with the glyph's "maxy"
324       metric to resolve the top of the rectangle used when blitting the glyph
325       on the screen.
326
327       Example:
328
329        my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
330
331        $rect->y( $bottom - SDL::TTF::font_descent($font) - $maxy );
332
333       font_line_skip
334
335        my $font_line_skip = SDL::TTF::font_line_skip($font);
336
337       Get the recommended pixel height of a rendered line of text of the
338       loaded font. This is usually larger than the SDL::TTF::font_height of
339       the font.
340
341       Face attributes
342
343       font_faces
344
345        my $font_faces = SDL::TTF::font_faces($font);
346
347       Get the number of faces ("sub-fonts") available in the loaded font.
348       This is a count of the number of specific fonts (based on size and
349       style and other typographical features perhaps) contained in the font
350       itself.
351
352       font_face_is_fixed_width
353
354        my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font);
355
356       Test if the current font face of the loaded font is a fixed width font.
357       Fixed width fonts are monospace, meaning every character that exists in
358       the font is the same width, thus you can assume that a rendered
359       string's width is going to be the result of "glyph_width *
360       string_length".
361
362       Returns: ">0" if font is a fixed width font. 0 if not a fixed width
363       font.
364
365       font_face_family_name
366
367        my $font_face_family_name = SDL::TTF::font_face_family_name($font);
368
369       Get the current font face family name from the loaded font. This
370       information is not for every font available.
371
372       Example:
373
374        my $font = SDL::TTF::open_font('arialuni.ttf', 8);
375
376        printf("%s\n", SDL::TTF::font_face_family_name($font)); # will print "Arial Unicode MS"
377
378       font_face_style_name
379
380        my $font_face_style_name = SDL::TTF::font_face_style_name($font);
381
382       Get the current font face style name from the loaded font. This
383       information is not for every font available.
384
385       Example:
386
387        my $font = SDL::TTF::open_font('arialuni.ttf', 8);
388
389        printf("%s\n", SDL::TTF::font_face_style_name($font)); # will print "Regular"
390
391       Glyphs
392
393       glyph_is_provided
394
395        my $glyph_is_provided = SDL::TTF::glyph_is_provided($font, $unicode_char);
396
397       Get the status of the availability of the glyph from the loaded font.
398
399       Returns: the index of the glyph in font, or 0 for an undefined
400       character code.
401
402       Note: You have to pass this unicode character either as UTF16/UCS-2 big
403       endian without BOM, or with BOM as UTF16/UCS-2 big/little endian.
404
405       Note: at least SDL_ttf 2.0.10 needed
406
407       Example:
408
409        print("We have this char!\n") if SDL::TTF::glyph_is_provided($font, "\0M");
410
411       glyph_metrics
412
413        my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, $unicode_char) };
414
415       Get desired glyph metrics of the UNICODE char from the loaded font.
416
417       See also: The FreeType2 Documentation Tutorial
418       <http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html>
419
420       Note: You have to pass this unicode character either as UTF16/UCS-2 big
421       endian without BOM, or with BOM as UTF16/UCS-2 big/little endian.
422
423       Example:
424
425        my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
426
427       Text metrics
428
429       size_text
430
431        my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
432
433       Calculate the resulting surface size of the LATIN1 encoded text
434       rendered using $font. No actual rendering is done, however correct
435       kerning is done to get the actual width. The height returned is the
436       same as you can get using SDL::TTF::font_height.
437
438       size_utf8
439
440        my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) };
441
442       Calculate the resulting surface size of the UTF8 encoded text rendered
443       using $font. No actual rendering is done, however correct kerning is
444       done to get the actual width. The height returned in h is the same as
445       you can get using SDL::TTF::font_height.
446
447       Note that the first example uses the same text as in the LATIN1
448       example, that is because plain ASCII is UTF8 compatible.
449
450       Examples:
451
452        ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hello World!') }; # plain text, if your script is in utf8 or ansi-format
453
454        # or
455
456        ($width, $height) = @{ SDL::TTF::size_utf8($font, "\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF") }; # utf8 hex-data
457
458        # or
459
460        use Unicode::String;
461        my $unicode       = utf8($data_from_somewhere);
462        ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode->utf8) }; # utf8 via Unicode::String
463
464       size_unicode
465
466        my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) };
467
468       Calculate the resulting surface size of the UNICODE encoded text
469       rendered using $font. No actual rendering is done, however correct
470       kerning is done to get the actual width. The height returned in h is
471       the same as you can get using SDL::TTF::font_height.
472
473       $text has to be:
474
475       UTF16BE without BOM
476           "hello" will look like "\0h\0e\0l\0l\0o"
477
478       UTF16BE with BOM
479           "hello" will look like "\xFE\xFF\0h\0e\0l\0l\0o"
480
481       UTF16LE with BOM
482           "hello" will look like "\xFF\xFEh\0e\0l\0l\0o\0"
483
484       You may use Unicode::String for this.
485
486   Font Rendering
487       Solid
488
489       render_glyph_solid
490
491        my $surface = SDL::TTF::render_glyph_solid($font, $char, $color);
492
493       Render the unicode encoded char onto a new surface, using the Solid
494       mode. After that you can blit this surface to your display-surface.
495
496       Note: The unicode char has to be passed exactly like for
497       SDL::TTF::size_unicode.
498
499       Note: See space-character bug <http://bugs.debian.org/cgi-
500       bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at
501       least version 2.3.5
502
503       render_text_solid
504
505        my $surface = SDL::TTF::render_text_solid($font, $text, $color);
506
507       Render the LATIN1 encoded text onto a new surface, using the Solid
508       mode. After that you can blit this surface to your display-surface.
509
510       Note: See space-character bug <http://bugs.debian.org/cgi-
511       bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at
512       least version 2.3.5
513
514       Example:
515
516        use SDL;
517        use SDL::Rect;
518        use SDL::Video;
519        use SDL::Color;
520        use SDL::TTF;
521        use SDL::TTF::Font;
522
523        SDL::init(SDL_INIT_VIDEO);
524        SDL::TTF::init();
525        my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
526        my $font    = SDL::TTF::open_font('somefont.ttf', '24');
527        die 'Coudnt make font '. SDL::get_error if !$font;
528        my $surface = SDL::TTF::render_text_solid($font, 'Hello!', SDL::Color->new(0xFF,0xFF,0xFF));
529        SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
530        SDL::Video::update_rect($display, 0, 0, 0, 0);
531        SDL::delay(5000);
532
533       render_utf8_solid
534
535        my $surface = SDL::TTF::render_utf8_solid($font, $text, $color);
536
537       Render the UTF8 encoded text onto a new surface, using the Solid mode.
538       After that you can blit this surface to your display-surface.
539
540       Note: See space-character bug <http://bugs.debian.org/cgi-
541       bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at
542       least version 2.3.5
543
544       render_unicode_solid
545
546        my $surface = SDL::TTF::render_unicode_solid($font, $text, $color);
547
548       Render the unicode encoded text onto a new surface, using the Solid
549       mode. After that you can blit this surface to your display-surface.
550
551       Note: The unicode test has to be passed exactly like for
552       SDL::TTF::size_unicode.
553
554       Note: See space-character bug <http://bugs.debian.org/cgi-
555       bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at
556       least version 2.3.5
557
558       Shaded
559
560       render_glyph_shaded
561
562        my $surface = SDL::TTF::render_glyph_shaded($font, $char, $color, $background_color);
563
564       Render the unicode encoded char onto a new surface. The surface is
565       filled with $background_color. After that you can blit this surface to
566       your display-surface.
567
568       Note: The unicode char has to be passed exactly like for
569       SDL::TTF::size_unicode.
570
571       render_text_shaded
572
573        my $surface = SDL::TTF::render_text_shaded($font, $text, $color, $background_color);
574
575       Render the LATIN1 encoded text onto a new surface. The surface is
576       filled with $background_color. After that you can blit this surface to
577       your display-surface.
578
579       Example:
580
581        use SDL;
582        use SDL::Video;
583        use SDL::Color;
584        use SDL::TTF;
585        use SDL::TTF::Font;
586
587        SDL::init(SDL_INIT_VIDEO);
588
589        SDL::TTF::init();
590
591        my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
592        my $font    = SDL::TTF::open_font('arial.ttf', '24');
593        my $white   = SDL::Color->new(0xFF, 0xFF, 0xFF);
594        my $black   = SDL::Color->new(0x00, 0x00, 0x00);
595        my $surface = SDL::TTF::render_text_solid($font, 'Hello!', $white, $black);
596
597        SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
598        SDL::Video::update_rect($display, 0, 0, 0, 0);
599
600        SDL::delay(5000);
601
602       render_utf8_shaded
603
604        my $surface = SDL::TTF::render_utf8_shaded($font, $text, $color, $background_color);
605
606       Render the UTF8 encoded text onto a new surface. The surface is filled
607       with $background_color. After that you can blit this surface to your
608       display-surface.
609
610       render_unicode_shaded
611
612        my $surface = SDL::TTF::render_unicode_shaded($font, $text, $color, $background_color);
613
614       Render the unicode encoded text onto a new surface. The surface is
615       filled with $background_color. After that you can blit this surface to
616       your display-surface.
617
618       Note: The unicode text has to be passed exactly like for
619       SDL::TTF::size_unicode.
620
621       Blended
622
623       render_glyph_blended
624
625        my $surface = SDL::TTF::render_glyph_blended($font, $char, $color);
626
627       Render the unicode encoded char onto a new surface. After that you can
628       blit this surface to your display-surface.
629
630       Note: The unicode char has to be passed exactly like for
631       SDL::TTF::size_unicode.
632
633       render_text_blended
634
635        my $surface = SDL::TTF::render_text_blended($font, $text, $color);
636
637       Render the LATIN1 encoded text onto a new surface. After that you can
638       blit this surface to your display-surface.
639
640       Example:
641
642        use SDL;
643        use SDL::Video;
644        use SDL::Color;
645        use SDL::TTF;
646        use SDL::TTF::Font;
647
648        SDL::init(SDL_INIT_VIDEO);
649
650        SDL::TTF::init();
651
652        my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
653        my $font    = SDL::TTF::open_font('arial.ttf', '24');
654        my $surface = SDL::TTF::render_text_blended($font, 'Hello!', SDL::Color->new(0xFF,0xFF,0xFF));
655
656        SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
657        SDL::Video::update_rect($display, 0, 0, 0, 0);
658
659        SDL::delay(5000);
660
661       render_utf8_blended
662
663        my $surface = SDL::TTF::render_utf8_blended($font, $text, $color);
664
665       Render the UTF8 encoded text onto a new surface. After that you can
666       blit this surface to your display-surface.
667
668       render_unicode_blended
669
670        my $surface = SDL::TTF::render_unicode_blended($font, $text, $color);
671
672       Render the unicode encoded text onto a new surface. After that you can
673       blit this surface to your display-surface.
674
675       Note: The unicode char has to be passed exactly like for
676       SDL::TTF::size_unicode.
677

AUTHORS

679       See "AUTHORS" in SDL.
680

NAME

CATEGORY

CONSTANTS

METHODS

AUTHORS

SEE ALSO