Commit | Line | Data |
896b04ee |
1 | =head1 NAME |
2 | |
3 | SDL::TTFont - a SDL perl extension |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | $font = SDL::TTFont->new( -name => "Utopia.ttf", -size => 18 ); |
8 | |
9 | =head1 DESCRIPTION |
10 | |
11 | L<< SDL::TTFont >> is a module for applying true type fonts to L<< SDL::Surface >>. |
12 | |
13 | =head1 METHODS |
14 | |
15 | =head2 new |
16 | |
17 | Instanciates a new font surface. It accepts the following parameters: |
18 | |
19 | =head3 -name |
20 | |
21 | =head3 -n |
22 | |
23 | The font filename (possibly with proper path) to be used. B<< This options is mandatory >>. |
24 | |
25 | =head3 -size |
26 | |
27 | =head3 -s |
28 | |
29 | The font size (height, in pixels) to be used. B<< This option is mandatory >>. |
30 | |
31 | =head3 -foreground |
32 | |
33 | =head3 -fg |
34 | |
35 | Foreground color for the font surface (i.e. the actual font color). It expects a |
36 | SDL::Color value. If omitted, black is used as font color. |
37 | |
38 | =head3 -background |
39 | |
40 | =head3 -bg |
41 | |
42 | Background color for the font surface (i.e. the font background color). It expects |
43 | a SDL::Color value. If omitted , white is used for the background. |
44 | |
45 | =head3 -mode |
46 | |
47 | =head3 -m |
48 | |
49 | Font mode. If omitted, SDL::TEXT_SHADED is used. Note that this class provides |
50 | human friendly accessors for setting different modes, so you should probably use |
51 | them instead. See below for further details. |
52 | |
53 | =head2 Text Modes |
54 | |
55 | The SDL::TTFont accepts three different types (shaded, solid, blended) for |
56 | three different encodings (text, utf8, unicode). |
57 | |
58 | $font->text_shaded; # sets mode to SDL::TEXT_SHADED |
59 | $font->text_solid; # sets mode to SDL::TEXT_SOLID |
60 | $font->text_blended; # sets mode to SDL::TEXT_BLENDED |
61 | |
62 | $font->utf8_shaded; # sets mode to SDL::UTF8_SHADED |
63 | $font->utf8_solid; # sets mode to SDL::UTF8_SOLID |
64 | $font->utf8_blended; # sets mode to SDL::UTF8_BLENDED |
65 | |
66 | $font->unicode_shaded; # sets mode to SDL::UNICODE_SHADED |
67 | $font->unicode_solid; # sets mode to SDL::UNICODE_SOLID |
68 | $font->unicode_blended; # sets mode to SDL::UNICODE_BLENDED |
69 | |
70 | =head2 Text Style |
71 | |
72 | You may also smoothly change your font style by calling any of the following |
73 | methods: |
74 | |
75 | $font->normal; # resets font styling, making text "normal" |
76 | $font->bold; # sets bold style for font |
77 | $font->italic; # sets italic style for font |
78 | $font->underline; # sets underline style for font |
79 | |
80 | |
81 | =head2 Ascent/Descent values |
82 | |
83 | Ascent is the number of pixels from the font baseline to the top of the font, while |
84 | descent is the number of pixels from the font baseline to the bottom of the font. |
85 | |
86 | $font->ascent; # height in pixels of the font ascent |
87 | $font->descent; # height in pixels of the font descent |
88 | |
89 | =head2 height |
90 | |
91 | my $height = $font->height; |
92 | |
93 | Returns the height, in pixels, of the actual rendered text. This is the |
94 | average size for each glyph in the font. |
95 | |
96 | =head2 width(@text) |
97 | |
98 | my $width = $font->width("Choose your destiny"); |
99 | |
100 | Returns the dimensions needed to render the text. This can be used to help |
101 | determine the positioning needed for text before it is rendered. It can also |
102 | be used for wordwrapping and other layout effects. |
103 | |
104 | Be aware that most fonts - notably, non-monospaced ("ms") ones - use kerning |
105 | which adjusts the widths for specific letter pairs. For example, the width |
106 | for "ae" will not always match the width for "a" + "e". |
107 | |
108 | =head2 print ($surface, $top, $left, @text) |
109 | |
110 | Directly draws text to an existing surface. Receives the target L<< SDL::Surface >> |
111 | object and the relative top (y) and left (x) coordinates to put the text in. |
112 | The last parameter may be a string or an array or strings with the text to be |
113 | written. |
114 | |
115 | |
116 | =head1 AUTHOR |
117 | |
118 | David J. Goehrig |
119 | |
120 | =head1 SEE ALSO |
121 | |
122 | L<perl>, L<SDL>, L<< SDL::Surface >> |