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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

EXPORT

Global Variables

bitmap format

sub render_table

sub render_list

sub get_bitmap

sub bitmap_as_xpm

sub bitmap_as_text

sub bitmap_width

sub init

sub get_glyph_index

sub set_transform

sub render

sub height

sub width

sub get_byte

AUTHOR

Liscense

SEE ALSO

Module Install Instructions