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 @@
SDL::TTF - True Type Font functions (libfreetype)
+ +TODO, TTF
+ +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); + ++ +
my $version = SDL::TTF::compile_time_version(); + ++
This gives you the SDL::Version object which SDL_ttf was present at compile time.
+ +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.
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.
+ +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
+ +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); + ++ +
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.
+ +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); + ++ +
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.
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.
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; + ++ +
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.
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
+ +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:
+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); + ++ +
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
+ +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
+ +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); + ++
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 ); + ++ +
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 ); + ++ +
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.
+ +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); + ++
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); + ++
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); + ++
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, $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") }; + ++ +
my ($width, $height) = @{ SDL::TTF::size_text($font, 'Hallo World!') }; + ++ +
my ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') }; + ++ +
my ($width, $height) = @{ SDL::TTF::size_unicode($font, 'Hallo World!') }; + ++ +
Note: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062
+ +Tobias Leich [FROGGS]
+