NAME
FONT::FT2 - Perl extension for FreeType 2
SYNOPSIS
use FONT::FT2 ':all';
my $retval = init("/usr/share/fonts/ttf/gkai00mp.ttf"); #italic
$retval = render_table (40, 56, 2, 2, [65, 66, 0x4eba, 0x4ebb], ['0xff0000', '0x00ff00', '0x0000ff', undef], 0x20000, 0x20000);
open(OUTPUT, '> temp.xpm');
print OUTPUT bitmap_as_xpm($retval);
close(OUTPUT);
DESCRIPTION
This is a set of subroutine for using Freetype 2 from Perl. For now, this is mostly a functional
implimentation, and is not yet intended to be perfect subroutine to subroutine remap of Freetype 2.
Although, that is a goal.
EXPORT
None by default.
Global Variables
@error_messages = Messages explaining a failure.
@messages = Normal messages.
$debug = undef when no debugging is wished. A debugging level when
debugging is enabled. Note, debug messages are stored in
@debug_messages regardless. Not normally used in a library.
@debug_messages = Debugging messages
# @debug_messages = ([debug_level, $subroutine_name, $message], etc);
# debug_level 1 = stop/start of procedures.
# debug_level 2 = stop/start of procedure sections
# debug_level 3 = procedure wide variables
# debug_level 4 = looping
bitmap format
Generally, the bitmaps passed around internally by FONT::FT2 are a
reference to a hash. The hash contains (at least) the keys 'ok', 'error',
'width','height','bitmap'. 'width' and 'height' are the size of the
bitmap in pixels. 'bitmap' is a reference to a one dimentional array representing
the pixels of the bitmap. The pixels for now are just 1's, 0's, and undef's. Soon,
you will have grayscale images representated as values from 0->255. And, you will
have colors represented by an eight byte string, representing the hex RGB value for
colors such as '0xFF00FF' for purple.
When OK is not defined, the bitmap is not valid. Often, OK will be defined, but
error will be as well. If error is defined, it will contain an error message.
Bitmaps are left to right, then down. So, the first row of pixels in the bitmap will
be the first set of data.
sub render_table
Description:
subroutine render table returns a string containing a xpm pixmap representation of the string of
characters in table format. Upon failure, a message is appended to error messages and undef is returned.
See
Syntax:
my $retval = render_table ($column_width, $row_height, $rows, $columns, $chars, $colors, $char_height, $char_width);
Where:
$retval = A standard FONT::FT2 bitmap (see section "bitmap format"). Undef on
failure.
$column_width = the width of each column to produce in pixels
$row_height = the height of each row to produce (ie, cell height) in pixels
$rows = the number of rows
$columns = the number of columns
$chars = a reference to a one dimentional array of char codes to produce. Only
valid numbers are accepted. Strings of numbers fail. So, 0x30b9 works but '0x30b9' doesn't.
use int() and hex() to convert string to number.
$colors = a reference to a one dimentional array of colors to use for those characters, undef for no color
$char_height = the height of the characters to produce (in freetype units, 0x10000 is safe)
$char_width = the width of the characters to produce (in freetype units, 0x10000 is safe)
sub render_list
Description:
subroutine render_list is a simple renderer.
Syntax:
my $retval = render_list ( $angle, $char_height, $char_width, @chars );
Where:
$retval = A standard FONT::FT2 bitmap (see section "bitmap format"). Undef on
failure.
$angle = the angle in radians to use to rotate the characters.
$char_height = the height of the characters to produce (in freetype units, 0x10000 is safe)
$char_width = the width of the characters to produce (in freetype units, 0x10000 is safe)
@chars = an of char codes to produce. Only valid numbers are accepted.
Strings of numbers fail. So, 0x30b9 works but '0x30b9' doesn't.
Use int() and hex() to convert string to number.
sub get_bitmap
Description:
subroutine get_bitmap returns the bitmap representing the character.
Syntax:
my @bitmap = get_bitmap( $glyph_index );
Where:
$glyph_index = the index of the glyph in the font record
@bitmap = An array of integers representing the bitmap.
ones and zeros in the case of a non-grayscale bitmap. 0-255 in
the case of a 256 shade grayscale bitmap. Warning, the width
of the bitmap and the width of the character may not match. The
width of the bitmap is the first multiple of eight equal or
greater than the width of the character.
sub bitmap_as_xpm
Description:
subroutine bitmap_as_xpm returns a set of text lines representing the bitmap,
in the format of an X windows X Pix Map, or XPM.
Upon failure, undef is returned.
Syntax:
my $text = bitmap_as_xpm( $rh_bitmap );
Where:
$text = the text representation of the bitmap
$rh_bitmap = a reference to a hash representing the FONT::FT2 internal
bitmap format.
Caveats:
bitmap_as_xpm only supports about 62 colors for now.
Example:
my $text = bitmap_as_xpm( $rh_bitmap );
sub bitmap_as_text
Description:
subroutine bitmap_as_text returns a set of text lines representing the bitmap,
including line feeds.
Syntax:
my $text = bitmap_as_text( $rh_bitmap, $set_bit, $not_set_bit );
Where:
$text = the text representation of the bitmap
$rh_bitmap = a reference to a hash representing the FONT::FT2 internal
bitmap format.
$set_bit = the character to use for bits in the bitmap that are set
$not_set_bit = the character to use for bits in the bitmap that are not set
Example:
my $text = bitmap_as_text( $rh_bitmap, 'X', '.' );
sub bitmap_width
Description:
subroutine bitmap_width returns the width of a characters bitmap. This may be larger than the
width of the character. Because, bitmaps returns by Freetype 2 are multiples of 8 in width.
Syntax:
my $bitmap_width = bitmap_width( $width );
Where:
$bitmap_width = undef on failure, the width of the bitmap on success.
$width = the width of the actual character in the bitmap.
sub init
Description:
subroutine init initializes Freetype 2 and loads the font file.
Syntax:
$retval = FT2::init ( $font_file );
Where:
$retval = undef on failure. true on success.
$font_file = the name of the font to be loaded.
sub get_glyph_index
Description:
subroutine get_glyph_index returns the font's internal index for a character.
Syntax:
$glyph_index = get_glyph_index ( $character_code );
Where:
$glyph_index = undef on failure, an integer for the index of the character
on success.
$character_code = the standard integer identifier for the character, normally
the ASCII/Unicode value.
sub set_transform
Description:
subroutine set_transform set's the angle, height, and width of the character to be returns. If
someone could send me examples of other transforms (non size/rotate transforms) in Freetype 2
I would appreciate it.
Syntax:
$retval = set_transform ( $angle, $height, $width );
Where:
$angle = the angle to rotate the character in Radians (0 for no rotation)
$height = the height to generate the character in. Apparently a value of about 5000
here represents about 1 pixel. A safe value is 0x10000.
$width = the width to generate the character in. A safe value is 0x10000.
sub render
Description:
subroutine render renders the bitmap in RAM following the prespecified parameters.
Syntax:
$retval = FONT::FT2::render ( $glyph_index );
Where:
$glyph_index = the font file's index for this character as specified by the
get_glyph_index function.
sub height
Description:
subroutine height returns the height of a rendered character in pixels.
Syntax:
$height = FONT::FT2::height ( $glyph_index );
Where:
$height = undef on failure, the height of the character in pixels on success.
$glyph_index = the font file's index for this character as specified by the
get_glyph_index function.
sub width
Description:
subroutine width returns the width of a rendered character in pixels.
Syntax:
$width = FONT::FT2::width ( $glyph_index );
Where:
$width = undef on failure, the width of the character in pixels on success.
$glyph_index = the font file's index for this character as specified by the
get_glyph_index function.
sub get_byte
Description:
subroutine get_byte returns any byte in the internal freetype bitmap. This subroutine was creates because
any get_bitmap function would need to return an array. But, the only supported array time I understoon
was char *, which ends the string at a null character (of which there are many in a character bitmap).
This subroutine is not intended for the end user.
Calling get_byte with an index larger than the bitmap will only return characters within the bitmap.
Syntax:
my $byte = FONT::FT2::get_byte ( $index );
Where
$byte = A byte (could be considered a char) representing one byte of the bitmap.
$index = The offset of the byte to be returned
AUTHOR
Andrew Robertson <tuxthepenquin@yahoo.com>
Liscense
GPL 2.
SEE ALSO
perl(1).