/lib/pods/SDL/TTF.pod
http://github.com/PerlGameDev/SDL · Unknown · 676 lines · 378 code · 298 blank · 0 comment · 0 complexity · 33ab0c10a52b8cfffb070d79d66a1d9d MD5 · raw file
- =pod
- =head1 NAME
- SDL::TTF - True Type Font functions (libfreetype)
- =head1 CATEGORY
- TTF
- =head1 CONSTANTS
- 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":
- =over 4
- =item *
- TTF_HINTING_NORMAL
- =item *
- TTF_HINTING_LIGHT
- =item *
- TTF_HINTING_MONO
- =item *
- TTF_HINTING_NONE
- =back
- Available constants for "style":
- =over 4
- =item *
- TTF_STYLE_NORMAL
- =item *
- TTF_STYLE_BOLD
- =item *
- TTF_STYLE_ITALIC
- =item *
- TTF_STYLE_UNDERLINE
- =item *
- TTF_STYLE_STRIKETHROUGH
- =back
- =head1 METHODS
- =head2 General methods
- =head3 linked_version
- my $version = SDL::TTF::linked_version();
- This gives you the SDL::Version object which SDL_ttf lib is used on the system.
- No prior initialization needs to be done before these function is called.
- Example:
- use SDL::TTF;
- use SDL::Version;
-
- my $version = SDL::TTF::linked_version();
-
- printf("got version: %d.%d.%d\n", $version->major, $version->minor, $version->patch);
- =head3 compile_time_version
- my $version = SDL::TTF::compile_time_version();
- This gives you the SDL::Version object which SDL_ttf was present at compile time.
- =head3 init
- my $success = SDL::TTF::init();
- Initialize the truetype font API.
- This must be called before using other functions in this library, except L<SDL::TTF::was_init|SDL::TTF/"was_init"> and L<SDL::TTF::linked_version|SDL::TTF/"linked_version">.
- SDL does not have to be initialized before this call.
- Returns: C<0> on success, C<-1> on any error.
- =head3 was_init
- my $was_init = SDL::TTF::was_init();
- Query the initialization status of the truetype font API.
- You may, of course, use this before L<SDL::TTF::init|SDL::TTF/"init"> to avoid initializing twice in a row. Or use this to determine if you need to
- call L<SDL::TTF::quit|SDL::TTF/"quit">.
- =head3 quit
- SDL::TTF::quit();
- Shutdown and cleanup the truetype font API.
- After calling this the SDL::TTF functions should not be used, excepting L<SDL::TTF::was_init|SDL::TTF/"was_init">. You may, of course, use
- L<SDL::TTF::init|SDL::TTF/"init"> to use the functionality again
- =head2 Management functions
- =head3 open_font
- my $font = SDL::TTF::open_font($font_file, $point_size);
- Load file for use as a font, at the given size. This is actually C<SDL::TTF::open_font_index(..., ..., $index = 0)>. This can load TTF, OTF and FON files.
- Returns: a L<SDL::TTF::Font> object. C<undef> is returned on errors.
- Example:
- use SDL::TTF;
- use SDL::TTF::Font;
-
- my $font = SDL::TTF::open_font('arial.ttf', 24);
- =head3 open_font_index
- my $font = SDL::TTF::open_font($font_file, $point_size, $face_index);
- This is the same as L<SDL::TTF::open_font|SDL::TTF/"open_font">, except you can specify the face index of a font file containing multiple faces.
- This can load TTF and FON files.
- =head3 open_font_RW
- my $font = SDL::TTF::open_font_RW($rwops_object, $free, $point_size);
- This is the same as L<SDL::TTF::open_font|SDL::TTF/"open_font">, except you can pass an L<SDL::RWOps>-object. If you pass true as C<$free>, the L<SDL::RWOps>-object
- will be freed by SDL_ttf library. Don't do this, perl will free this object for you.
- Example:
- my $font = SDL::TTF::open_font_RW(SDL::RWOps->new_file($font_file, 'r'), 0, 24);
- =head3 open_font_index_RW
- my $font = SDL::TTF::open_font_index_RW($rwops_object, $free, $point_size, $face_index);
- This is the same as L<SDL::TTF::open_font_index|SDL::TTF/"open_font_index">, except you can pass an L<SDL::RWOps>-object. If you pass true as C<$free>, the
- L<SDL::RWOps>-object will be freed by SDL_ttf library. Don't do this, perl will free this object for you.
- =head2 Attributes
- =head3 Global attributes
- =head4 byte_swapped_unicode
- SDL::TTF::byte_swapped_unicode( $bool );
- This function tells SDL_ttf whether UNICODE (2 bytes per character) text is generally byteswapped. A C<UNICODE_BOM_NATIVE> or
- C<UNICODE_BOM_SWAPPED> character in a string will temporarily override this setting for the remainder of that string, however this setting
- will be restored for the next one. The default mode is non-swapped, native endianness of the CPU.
- =head3 Font style
- =head4 get_font_style
- SDL::TTF::get_font_style($font);
- Returns: The style as a bitmask composed of the following masks:
- =over 4
- =item *
- TTF_STYLE_NORMAL
- =item *
- TTF_STYLE_BOLD
- =item *
- TTF_STYLE_ITALIC
- =item *
- TTF_STYLE_UNDERLINE
- =item *
- TTF_STYLE_STRIKETHROUGH (since SDL_ttf 2.0.10)
- =back
- Example:
- my $style = SDL::TTF::get_font_style($font);
-
- print("normal\n") if $style == TTF_STYLE_NORMAL;
- print("bold\n") if $style & TTF_STYLE_BOLD;
- print("italic\n") if $style & TTF_STYLE_ITALIC;
- print("underline\n") if $style & TTF_STYLE_UNDERLINE;
- print("strikethrough\n") if $style & TTF_STYLE_STRIKETHROUGH;
- =head4 set_font_style
- SDL::TTF::set_font_style($font, $style);
-
- Set the rendering style of the loaded font.
- B<Note>: C<TTF_STYLE_UNDERLINE> may cause surfaces created by C<SDL::TTF::render_glyph_*> functions to be extended vertically, downward only,
- 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
- to place a glyph using glyph metrics.
- On the other hand C<TTF_STYLE_STRIKETHROUGH> doesn't extend the glyph, since this would invalidate the metrics used to position the glyph when
- blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter
- about glyph blitting math than they are currently designed for.
- Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In
- this case, you should probably turn off these styles and draw your own strikethroughs and underlines.
- =head4 get_font_outline
- my $outline = SDL::TTF::get_font_outline($font);
- Get the current outline width of the font, in pixels.
- B<Note>: at least SDL_ttf 2.0.10 needed
- =head4 set_font_outline
- SDL::TTF::set_font_outline($font, $outline);
- Set the outline pixel width of the loaded font. Use C<0>(zero) to turn off outlining.
- B<Note>: at least SDL_ttf 2.0.10 needed
- =head3 Font settings
- =head4 get_font_hinting
- my $hinting = SDL::TTF::get_font_hinting($font);
- Get the current hinting setting of the loaded font.
- B<Note>: at least SDL_ttf 2.0.10 needed
- Returns the hinting type matching one of the following defined values:
- =over 4
- =item *
- TTF_HINTING_NORMAL
- =item *
- TTF_HINTING_LIGHT
- =item *
- TTF_HINTING_MONO
- =item *
- TTF_HINTING_NONE
- =back
- =head4 set_font_hinting
- SDL::TTF::set_font_hinting($font, $hinting);
- Set the hinting of the loaded font. You should experiment with this setting if you know which font you are using beforehand, especially when
- 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.
- B<Note>: at least SDL_ttf 2.0.10 needed
- Example:
- SDL::TTF::set_font_hinting($font, TTF_HINTING_LIGHT);
- =head4 get_font_kerning
- my $kerning_enabled = SDL::TTF::get_font_kerning($font);
- Get the current kerning setting of the loaded font.
- Returns: C<0>(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(C<1>).
- B<Note>: at least SDL_ttf 2.0.10 needed
- B<Note>: This function returns wrong values: See L<http://bugzilla.libsdl.org/show_bug.cgi?id=973>
- =head4 set_font_kerning
- SDL::TTF::set_font_kerning($font, $kerning_enabled);
- Set whether to use kerning when rendering the loaded font. This has no effect on individual glyphs, but rather when rendering whole strings of
- 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
- overlapping glyphs or abnormal spacing within words.
- Pass C<0> to disable kerning, 1 to enable.
- B<Note>: at least SDL_ttf 2.0.10 needed
- =head3 Font metrics
- =head4 font_height
- 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 L<SDL::TTF::font_line_skip|SDL::TTF/"font_line_skip"> as well.
- =head4 font_ascent
- my $font_ascent = SDL::TTF::font_ascent($font);
- 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 C<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 );
- =head4 font_descent
- my $font_descent = SDL::TTF::font_descent($font);
- 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 C<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 );
- =head4 font_line_skip
- my $font_line_skip = SDL::TTF::font_line_skip($font);
-
- Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the L<SDL::TTF::font_height|SDL::TTF/"font_height"> of the
- font.
- =head3 Face attributes
- =head4 font_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.
- =head4 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 C<glyph_width * string_length>.
- Returns: C<E<gt>0> if font is a fixed width font. C<0> if not a fixed width font.
- =head4 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"
- =head4 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"
- =head3 Glyphs
- =head4 glyph_is_provided
- 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.
- B<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.
- B<Note>: at least SDL_ttf 2.0.10 needed
- Example:
- print("We have this char!\n") if SDL::TTF::glyph_is_provided($font, "\0M");
- =head4 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: L<The FreeType2 Documentation Tutorial|http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html>
- B<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") };
- =head3 Text metrics
- =head4 size_text
- my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
- Calculate the resulting surface size of the LATIN1 encoded text rendered using C<$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 L<SDL::TTF::font_height|SDL::TTF/"font_height">.
- =head4 size_utf8
- my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) };
- Calculate the resulting surface size of the UTF8 encoded text rendered using C<$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 L<SDL::TTF::font_height|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, 'Hello 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_somewhere);
- ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode->utf8) }; # utf8 via Unicode::String
- =head4 size_unicode
- my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) };
- Calculate the resulting surface size of the UNICODE encoded text rendered using C<$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 L<SDL::TTF::font_height|SDL::TTF/"font_height">.
- C<$text> has to be:
- =over 4
- =item UTF16BE without BOM
- "hello" will look like "\0h\0e\0l\0l\0o"
- =item UTF16BE with BOM
- "hello" will look like "\xFE\xFF\0h\0e\0l\0l\0o"
- =item UTF16LE with BOM
- "hello" will look like "\xFF\xFEh\0e\0l\0l\0o\0"
- =back
- You may use Unicode::String for this.
- =head2 Font Rendering
- =head3 Solid
- =head4 render_glyph_solid
- 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.
- B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
- B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least version 2.3.5
- =head4 render_text_solid
- 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.
- B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. 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('somefont.ttf', '24');
- die 'Coudnt make font '. SDL::get_error if !$font;
- my $surface = SDL::TTF::render_text_solid($font, 'Hello!', 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);
- =head4 render_utf8_solid
- 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.
- B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least
- version 2.3.5
- =head4 render_unicode_solid
- 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.
- B<Note>: The unicode test has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
- B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least
- version 2.3.5
- =head3 Shaded
- =head4 render_glyph_shaded
- 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 C<$background_color>. After that you can blit this surface to
- your display-surface.
- B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
- =head4 render_text_shaded
- 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 C<$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, 'Hello!', $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);
- =head4 render_utf8_shaded
- 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 C<$background_color>. After that you can blit this surface to
- your display-surface.
- =head4 render_unicode_shaded
- 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 C<$background_color>. After that you can blit this surface to
- your display-surface.
- B<Note>: The unicode text has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
- =head3 Blended
- =head4 render_glyph_blended
- 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.
- B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
- =head4 render_text_blended
- 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, 'Hello!', 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);
- =head4 render_utf8_blended
- 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.
- =head4 render_unicode_blended
- 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.
- B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
- =head1 AUTHORS
- See L<SDL/AUTHORS>.
- =head1 SEE ALSO
- L<SDL::TTF::Font>, L<Unicode::String>, L<SDL::Video>, L<SDL::Surface>
- =cut