TODO, TTF
+TTF
+ +The constants are exported by default. You can avoid this by doing:
+use SDL::TTF (); + ++
and access them directly:
+SDL::TTF::TTF_HINTING_NORMAL; + ++
Available constants for "hinting":
+Available constants for "style":
+Query the initilization status of the truetype font API. -You may, of course, use this before SDL::TTF::init to avoid initializing twice in a row. Or use this to determine if you need to call -SDL::TTF::quit.
+You may, of course, use this before SDL::TTF::init to avoid initializing twice in a row. Or use this to determine if you need to +call SDL::TTF::quit.Shutdown and cleanup the truetype font API. -After calling this the SDL::TTF functions should not be used, excepting SDL::TTF::was_init. You may, of course, use SDL::TTF::init to -use the functionality again
+After calling this the SDL::TTF functions should not be used, excepting SDL::TTF::was_init. You may, of course, use +SDL::TTF::init to use the functionality again use SDL::TTF;
use SDL::TTF::Font;
- my $font = SDL::TTF::open_font('arial.ttf', '24);
+ my $font = SDL::TTF::open_font('arial.ttf', 24);
@@ -277,6 +318,24 @@ Still, sometimes the underline or strikethrough may be outside of the generated
this case, you should probably turn off these styles and draw your own strikethroughs and underlines.
+my $outline = SDL::TTF::get_font_outline($font); + ++
Get the current outline width of the font, in pixels.
+Note: at least SDL_ttf 2.0.10 needed
+ +SDL::TTF::get_font_outline($font, $outline); + ++
Set the outline pixel width of the loaded font. Use 0(zero) to turn off outlining.
Note: at least SDL_ttf 2.0.10 needed
+ +Get the current kerning setting of the loaded font.
Returns: 0(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(1).
Note: at least SDL_ttf 2.0.10 needed
+Note: This function returns wrong values: See http://bugzilla.libsdl.org/show_bug.cgi?id=973
my $font_height = SDL::TTF::font_height($font);+
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 +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 +printing, so you are responsible for line spacing, see the SDL::TTF::font_line_skip as well.
my $font_ascent = SDL::TTF::font_ascent($font); - like( $font_ascent, '/^[-]?\d+$/', "[font_ascent] offset from the baseline to the top of the font is $font_ascent" ); + ++
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
+baseline.
+It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's maxy metric to resolve the top
+of the rectangle used when blitting the glyph on the screen.
Example:
+ my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
+
+ $rect->y( $top + SDL::TTF::font_ascent($font) - $maxy );
@@ -356,7 +428,16 @@ overlapping glyphs or abnormal spacing within words.
my $font_descent = SDL::TTF::font_descent($font); - like( $font_descent, '/^[-]?\d+$/', "[font_descent] offset from the baseline to the bottom of the font is $font_descent" ); + ++
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
+the font.
+It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's maxy metric to resolve the top
+of the rectangle used when blitting the glyph on the screen.
Example:
+ my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
+
+ $rect->y( $bottom - SDL::TTF::font_descent($font) - $maxy );
@@ -364,9 +445,10 @@ overlapping glyphs or abnormal spacing within words.
my $font_line_skip = SDL::TTF::font_line_skip($font); - like( $font_line_skip, '/^[-]?\d+$/', "[font_line_skip] recommended spacing between lines of text is $font_line_skip" );+
Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the SDL::TTF::font_height of the +font.
my $font_faces = SDL::TTF::font_faces($font); -ok( $font_faces, "[font_faces] font has $font_faces faces" );
+my $font_faces = SDL::TTF::font_faces($font); + ++
Get the number of faces ("sub-fonts") available in the loaded font. This is a count of the number of specific fonts (based on size and style +and other typographical features perhaps) contained in the font itself.
my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font); -like( $font_face_is_fixed_width, '/^[01]$/', "[font_face_is_fixed_width] is $font_face_is_fixed_width" );
+my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font); + ++
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
+in the font is the same width, thus you can assume that a rendered string's width is going to be the result of glyph_width * string_length.
Returns: >0 if font is a fixed width font. 0 if not a fixed width font.
my $font_face_family_name = SDL::TTF::font_face_family_name($font); -ok( $font_face_family_name, "[font_face_family_name] is $font_face_family_name" );
+my $font_face_family_name = SDL::TTF::font_face_family_name($font); + ++
Get the current font face family name from the loaded font. This information is not for every font available.
+Example:
+ my $font = SDL::TTF::open_font('arialuni.ttf', 8);
+
+ printf("%s\n", SDL::TTF::font_face_family_name($font)); # will print "Arial Unicode MS"
+
+
my $font_face_style_name = SDL::TTF::font_face_style_name($font); -ok( $font_face_style_name, "[font_face_style_name] is $font_face_style_name" );
+my $font_face_style_name = SDL::TTF::font_face_style_name($font); + ++
Get the current font face style name from the loaded font. This information is not for every font available.
+Example:
+ my $font = SDL::TTF::open_font('arialuni.ttf', 8);
+
+ printf("%s\n", SDL::TTF::font_face_style_name($font)); # will print "Regular"
+
+
my $glyph_is_provided = SDL::TTF::glyph_is_provided($font, $unicode_char); + ++
Get the status of the availability of the glyph from the loaded font.
+Returns: the index of the glyph in font, or 0 for an undefined character code.
+Note: 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.
+Note: at least SDL_ttf 2.0.10 needed
+Example:
+ print("We have this char!\n") if SDL::TTF::glyph_is_provided($font, "\0M");
+
+
my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, 'M') };
-is( scalar @glyph_metrics, 5, "[glyph_metrics] (minx, maxx, miny, maxy, advance) = (" . join(', ', @glyph_metrics) . ")" );
+ my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, $unicode_char) };
+
+
+Get desired glyph metrics of the UNICODE char from the loaded font.
+See also: The FreeType2 Documentation Tutorial
+Note: 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.
+Example:
+ my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
@@ -419,81 +541,257 @@ is( scalar @glyph_metrics, 5, &
my ($width, $height) = @{ SDL::TTF::size_text($font, 'Hallo World!') };
+ my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
+Calculate the resulting surface size of the LATIN1 encoded text rendered using $font. No actual rendering is done, however correct kerning
+is done to get the actual width. The height returned is the same as you can get using SDL::TTF::font_height.
my ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') };
+ my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) };
+
+
+Calculate the resulting surface size of the UTF8 encoded text rendered using $font. No actual rendering is done, however correct kerning is
+done to get the actual width. The height returned in h is the same as you can get using SDL::TTF::font_height.
+Note that the first example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
+Examples:
+ ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') }; # plain text, if your script is in utf8 or ansi-format
+
+ # or
+
+ ($width, $height) = @{ SDL::TTF::size_utf8($font, "\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF") }; # utf8 hex-data
+
+ # or
+
+ use Unicode::String;
+ my $unicode = utf8($data_from_somwhere);
+ ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode->utf8) }; # utf8 via Unicode::String
my ($width, $height) = @{ SDL::TTF::size_unicode($font, 'Hallo World!') };
+ my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) };
+Calculate the resulting surface size of the UNICODE encoded text rendered using $font. No actual rendering is done, however correct kerning
+is done to get the actual width. The height returned in h is the same as you can get using SDL::TTF::font_height.
+$text has to be:
+"hallo" will look like "\0h\0a\0l\0l\0o"
+"hallo" will look like "\xFE\xFF\0h\0a\0l\0l\0o"
+"hallo" will look like "\xFF\xFEh\0a\0l\0l\0o\0"
+You may use Unicode::String for this.
my $surface = SDL::TTF::render_glyph_solid($font, $char, $color); + ++
Render the unicode encoded char onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
+Note: The unicode char has to be passed exactly like for SDL::TTF::size_unicode.
+Note: See space-character bug. You have to upgrade libfreetype2 to at least version 2.3.5
my $surface = SDL::TTF::render_text_solid($font, $text, $color); + ++
Render the LATIN1 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
+Note: See space-character bug. You have to upgrade libfreetype2 to at least +version 2.3.5
+Example:
+ use SDL;
+ use SDL::Rect;
+ use SDL::Video;
+ use SDL::Color;
+ use SDL::TTF;
+ use SDL::TTF::Font;
+
+ SDL::init(SDL_INIT_VIDEO);
+ SDL::TTF::init();
+ my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
+ my $font = SDL::TTF::open_font('test/data/aircut3.ttf', '24');
+ die 'Coudnt make font '. SDL::get_error if !$font;
+ my $surface = SDL::TTF::render_text_solid($font, 'Hallo!', SDL::Color->new(0xFF,0xFF,0xFF));
+ SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
+ SDL::Video::update_rect($display, 0, 0, 0, 0);
+ SDL::delay(5000);
+
+
my $surface = SDL::TTF::render_utf8_solid($font, $text, $color); + ++
Render the UTF8 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
+Note: See space-character bug. You have to upgrade libfreetype2 to at least +version 2.3.5
Note: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062
+my $surface = SDL::TTF::render_unicode_solid($font, $text, $color); + ++
Render the unicode encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
+Note: The unicode test has to be passed exactly like for SDL::TTF::size_unicode.
+Note: See space-character bug. You have to upgrade libfreetype2 to at least +version 2.3.5
my $surface = SDL::TTF::render_glyph_shaded($font, $char, $color, $background_color); + ++
Render the unicode encoded char onto a new surface. The surface is filled with $background_color. After that you can blit this surface to
+your display-surface.
Note: The unicode char has to be passed exactly like for SDL::TTF::size_unicode.
my $surface = SDL::TTF::render_text_shaded($font, $text, $color, $background_color); + ++
Render the LATIN1 encoded text onto a new surface. The surface is filled with $background_color. After that you can blit this surface to
+your display-surface.
Example:
+ use SDL;
+ use SDL::Video;
+ use SDL::Color;
+ use SDL::TTF;
+ use SDL::TTF::Font;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ SDL::TTF::init();
+
+ my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
+ my $font = SDL::TTF::open_font('arial.ttf', '24');
+ my $white = SDL::Color->new(0xFF, 0xFF, 0xFF);
+ my $black = SDL::Color->new(0x00, 0x00, 0x00);
+ my $surface = SDL::TTF::render_text_solid($font, 'Hallo!', $white, $black);
+
+ SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
+ SDL::Video::update_rect($display, 0, 0, 0, 0);
+
+ SDL::delay(5000);
+
+
my $surface = SDL::TTF::render_utf8_shaded($font, $text, $color, $background_color); + ++
Render the UTF8 encoded text onto a new surface. The surface is filled with $background_color. After that you can blit this surface to
+your display-surface.
my $surface = SDL::TTF::render_unicode_shaded($font, $text, $color, $background_color); + ++
Render the unicode encoded text onto a new surface. The surface is filled with $background_color. After that you can blit this surface to
+your display-surface.
Note: The unicode text has to be passed exactly like for SDL::TTF::size_unicode.
my $surface = SDL::TTF::render_glyph_blended($font, $char, $color); + ++
Render the unicode encoded char onto a new surface. After that you can blit this surface to your display-surface.
+Note: The unicode char has to be passed exactly like for SDL::TTF::size_unicode.
+ +my $surface = SDL::TTF::render_text_blended($font, $text, $color); + ++
Render the LATIN1 encoded text onto a new surface. After that you can blit this surface to your display-surface.
+Example:
+ use SDL;
+ use SDL::Video;
+ use SDL::Color;
+ use SDL::TTF;
+ use SDL::TTF::Font;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ SDL::TTF::init();
+
+ my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
+ my $font = SDL::TTF::open_font('arial.ttf', '24');
+ my $surface = SDL::TTF::render_text_blended($font, 'Hallo!', SDL::Color->new(0xFF,0xFF,0xFF));
+
+ SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
+ SDL::Video::update_rect($display, 0, 0, 0, 0);
+
+ SDL::delay(5000);
+
+
my $surface = SDL::TTF::render_utf8_blended($font, $text, $color); + ++
Render the UTF8 encoded text onto a new surface. After that you can blit this surface to your display-surface.
+ +my $surface = SDL::TTF::render_unicode_blended($font, $text, $color); + ++
Render the unicode encoded text onto a new surface. After that you can blit this surface to your display-surface.
+Note: The unicode char has to be passed exactly like for SDL::TTF::size_unicode.