X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pages%2FSDL-TTF.html-inc;h=9779aaa0309d854bb45571851659c9e512c299d4;hb=c5291845aae25078edccea7589f9dd9aae805c3e;hp=0b1624d4683565d8ea536315f756dc2d1dd5fc20;hpb=90d38009447c9feb22dfa396c0e9556bc35b7413;p=sdlgit%2FSDL-Site.git diff --git a/pages/SDL-TTF.html-inc b/pages/SDL-TTF.html-inc index 0b1624d..9779aaa 100644 --- a/pages/SDL-TTF.html-inc +++ b/pages/SDL-TTF.html-inc @@ -1,9 +1,586 @@

Index

-
+ +
+

NAME

Top

+
+

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

+ +
+

CATEGORY

Top

+
+

TODO, TTF

+ +
+

METHODS

Top

+
+ +
+

General methods

+
+ +
+

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);
+
+
+ +
+

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.

+ +
+

init

+
+
 my $success = SDL::TTF::init();
+
+
+

Initialize the truetype font API. +This must be called before using other functions in this library, except SDL::TTF::was_init and SDL::TTF::linked_version. +SDL does not have to be initialized before this call.

+

Returns: 0 on success, -1 on any error.

+ +
+

was_init

+
+
 my $was_init = SDL::TTF::was_init();
+
+
+

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.

+ +
+

quit

+
+
 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

+ +
+

Management functions

+
+ +
+

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 SDL::TTF::open_font_index(..., ..., $index = 0). This can load TTF and FON files.

+

Returns: a SDL::TTF::Font object. undef is returned on errors.

+

Example:

+
 use SDL::TTF;
+ use SDL::TTF::Font;
+
+ my $font = SDL::TTF::open_font('arial.ttf', '24);
+
+
+ +
+

open_font_index

+
+
 my $font = SDL::TTF::open_font($font_file, $point_size, $face_index);
+
+
+

This is the same as 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.

+ +
+

open_font_RW

+
+
 my $font = SDL::TTF::open_font_RW($rwops_object, $free, $point_size);
+
+
+

This is the same as SDL::TTF::open_font, except you can pass an SDL::RWOps-object. If you pass true as $free, the 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);
+
+
+ +
+

open_font_index_RW

+
+
 my $font = SDL::TTF::open_font_index_RW($rwops_object, $free, $point_size, $face_index);
+
+
+

This is the same as SDL::TTF::open_font_index, except you can pass an SDL::RWOps-object. If you pass true as $free, the +SDL::RWOps-object will be freed by SDL_ttf library. Don't do this, perl will free this object for you.

+ +
+

Attributes

+
+ +
+

Global attributes

+
+ +
+

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 UNICODE_BOM_NATIVE or +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.

+ +
+

Font style

+
+ +
+

get_font_style

+
+
 SDL::TTF::get_font_style($font);
+
+
+

Returns: The style as a bitmask composed of the following masks:

+ + +

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;
+
+
+ +
+

set_font_style

+
+
 SDL::TTF::set_font_style($font, $style);
+
+
+

Set the rendering style of the loaded font.

+

Note: TTF_STYLE_UNDERLINE may cause surfaces created by 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 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.

+ +
+

get_font_outline

+
+
 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

+ +
+

set_font_outline

+
+
 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

+ +
+

Font settings

+
+ +
+

get_font_hinting

+
+
 my $hinting = SDL::TTF::get_font_hinting($font);
+
+
+

Get the current hinting setting of the loaded font.

+

Note: at least SDL_ttf 2.0.10 needed

+

Returns the hinting type matching one of the following defined values:

+ + + +
+

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.

+

Note: at least SDL_ttf 2.0.10 needed

+

Example:

+
 SDL::TTF::set_font_hinting($font, TTF_HINTING_LIGHT);
+
+
+ +
+

get_font_kerning

+
+
 my $kerning_enabled = SDL::TTF::get_font_kerning($font);
+
+
+

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

+ +
+

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 0 to disable kerning, 1 to enable.

+

Note: at least SDL_ttf 2.0.10 needed

+ +
+

Font metrics

+
+ +
+

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 SDL::TTF::font_line_skip as well.

+ +
+

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 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 );
+
+
+ +
+

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 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 );
+
+
+ +
+

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 SDL::TTF::font_height of the +font.

+ +
+

Face attributes

+
+ +
+

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.

+ +
+

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.

+ +
+

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"
+
+
+ +
+

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"
+
+
+ +
+

Glyphs

+
+ +
+

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.

+

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");
+
+
+ +
+

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") };
+
+
+ +
+

Text metrics

+
+ +
+

size_text

+
+
 my ($width, $height) = @{ SDL::TTF::size_text($font, 'Hallo World!') };
+
+
+ +
+

size_utf8

+
+
 my ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') };
+
+
+ +
+

size_unicode

+
+
 my ($width, $height) = @{ SDL::TTF::size_unicode($font, 'Hallo World!') };
+
+
+ +
+

Font Rendering

+
+ +
+

render_glyph_solid

+
+ +
+

render_glyph_shaded

+
+ +
+

render_glyph_blended

+
+ +
+

render_text_solid

+
+

Note: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062

+ +
+

render_text_shaded

+
+ +
+

render_text_blended

+
+ +
+

render_utf8_solid

+
+ +
+

render_utf8_shaded

+
+ +
+

render_utf8_blended

+
+ +
+

render_unicode_solid

+
+ +
+

render_unicode_shaded

+
+ +
+

render_unicode_blended

+
+ +
+

AUTHOR

Top

+
+

Tobias Leich [FROGGS]

+
+

SEE ALSO

Top

+
+

SDL::TTF::Font, Unicode::String, SDL::Video, SDL::Surface

+
\ No newline at end of file