The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

SDL::TTFont - a SDL perl extension

SYNOPSIS

  $font = SDL::TTFont->new( -name => "Utopia.ttf", -size => 18 );
        

DESCRIPTION

SDL::TTFont is a module for applying true type fonts to SDL::Surface.

METHODS

new

Instanciates a new font surface. It accepts the following parameters:

-name

-n

The font filename (possibly with proper path) to be used. This options is mandatory.

-size

-s

The font size (height, in pixels) to be used. This option is mandatory.

-foreground

-fg

Foreground color for the font surface (i.e. the actual font color). It expects a SDL::Color value. If omitted, black is used as font color.

-background

-bg

Background color for the font surface (i.e. the font background color). It expects a SDL::Color value. If omitted , white is used for the background.

-mode

-m

Font mode. If omitted, SDL::TEXT_SHADED is used. Note that this class provides human friendly accessors for setting different modes, so you should probably use them instead. See below for further details.

Text Modes

The SDL::TTFont accepts three different types (shaded, solid, blended) for three different encodings (text, utf8, unicode).

  $font->text_shaded;       # sets mode to SDL::TEXT_SHADED
  $font->text_solid;        # sets mode to SDL::TEXT_SOLID
  $font->text_blended;      # sets mode to SDL::TEXT_BLENDED
  
  $font->utf8_shaded;       # sets mode to SDL::UTF8_SHADED
  $font->utf8_solid;        # sets mode to SDL::UTF8_SOLID
  $font->utf8_blended;      # sets mode to SDL::UTF8_BLENDED
  
  $font->unicode_shaded;    # sets mode to SDL::UNICODE_SHADED
  $font->unicode_solid;     # sets mode to SDL::UNICODE_SOLID
  $font->unicode_blended;   # sets mode to SDL::UNICODE_BLENDED

Text Style

You may also smoothly change your font style by calling any of the following methods:

  $font->normal;       # resets font styling, making text "normal"
  $font->bold;         # sets bold style for font
  $font->italic;       # sets italic style for font
  $font->underline;    # sets underline style for font

Ascent/Descent values

Ascent is the number of pixels from the font baseline to the top of the font, while descent is the number of pixels from the font baseline to the bottom of the font.

  $font->ascent;      # height in pixels of the font ascent
  $font->descent;     # height in pixels of the font descent

height

  my $height = $font->height;
  

Returns the height, in pixels, of the actual rendered text. This is the average size for each glyph in the font.

width(@text)

  my $width = $font->width("Choose your destiny");

Returns the dimensions needed to render the text. This can be used to help determine the positioning needed for text before it is rendered. It can also be used for wordwrapping and other layout effects.

Be aware that most fonts - notably, non-monospaced ("ms") ones - use kerning which adjusts the widths for specific letter pairs. For example, the width for "ae" will not always match the width for "a" + "e".

Directly draws text to an existing surface. Receives the target SDL::Surface object and the relative top (y) and left (x) coordinates to put the text in. The last parameter may be a string or an array or strings with the text to be written.

AUTHOR

David J. Goehrig

SEE ALSO

perl, SDL, SDL::Surface