X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fdocs%2FTTFont.pod;fp=lib%2Fdocs%2FTTFont.pod;h=d7bbae0257d2adea2b714b2106deee49dbc33e14;hb=896b04ee008898e1c1edbdd432bedaa8643400dc;hp=0000000000000000000000000000000000000000;hpb=b3cdeb39a431b026168c4060bf74001fcee07493;p=sdlgit%2FSDL_perl.git

diff --git a/lib/docs/TTFont.pod b/lib/docs/TTFont.pod
new file mode 100644
index 0000000..d7bbae0
--- /dev/null
+++ b/lib/docs/TTFont.pod
@@ -0,0 +1,122 @@
+=head1 NAME
+
+SDL::TTFont - a SDL perl extension
+
+=head1 SYNOPSIS
+
+  $font = SDL::TTFont->new( -name => "Utopia.ttf", -size => 18 );
+	
+=head1 DESCRIPTION
+
+L<< SDL::TTFont >> is a module for applying true type fonts to L<< SDL::Surface >>.
+
+=head1 METHODS
+
+=head2 new
+
+Instanciates a new font surface. It accepts the following parameters:
+
+=head3 -name
+
+=head3 -n
+
+The font filename (possibly with proper path) to be used. B<< This options is mandatory >>.
+
+=head3 -size
+
+=head3 -s
+
+The font size (height, in pixels) to be used. B<< This option is mandatory >>.
+
+=head3 -foreground
+
+=head3 -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.
+
+=head3 -background
+
+=head3 -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.
+
+=head3 -mode
+
+=head3 -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.
+
+=head2 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
+
+=head2 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
+
+
+=head2 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
+
+=head2 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.
+
+=head2 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".
+
+=head2 print ($surface, $top, $left, @text)
+
+Directly draws text to an existing surface. Receives the target L<< 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.
+
+
+=head1 AUTHOR
+
+David J. Goehrig
+
+=head1 SEE ALSO
+
+L<perl>, L<SDL>, L<< SDL::Surface >>