NAME

OpenGL::FTGL - interface to the FTGL library (to use arbitrary fonts in OpenGL applications).

SYNOPSIS

#!/usr/bin/perl
use strict;
use warnings;
use OpenGL ':all';
use OpenGL::FTGL ':all';

my $font = ftglCreateOutlineFont("/path_to/Arial.ttf")
  or die $!;
ftglSetFontFaceSize($font, 72);

sub display {
  glClear(GL_COLOR_BUFFER_BIT);    # clear window
  glPushMatrix();
    glTranslatef(50, 80, 0);       # translate...
    glRotatef(20, 0, 0, 1);        # and rotate the text
    ftglRenderFont($font, "Hello World!");
  glPopMatrix();
  glFlush();
}

glutInit();
glutInitWindowSize(600, 300);           # 600 x 300 pixel window
glutCreateWindow("Hello OpenGL::FTGL"); # window title
glutDisplayFunc(\&display);  # callback invoked when window opened

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluOrtho2D(0, 600, 0, 300);
glMatrixMode(GL_MODELVIEW);

glutMainLoop();              # enter event loop

DESCRIPTION

OpenGL doesn't provide direct font support. FTGL is a free, open source library which makes possible to use TrueType or OpenType fonts in an OpenGL application.

FUNCTIONS

The seven ftglCreate* functions take as parameter $fontfile which is the path to a font file. The supported formats are those of the FreeType2 library:

- TrueType fonts (and collections)
- Type 1 fonts
- CID-keyed Type 1 fonts
- CFF fonts
- OpenType fonts (both TrueType and CFF variants)
- SFNT-based bitmap fonts
- X11 PCF fonts
- Windows FNT fonts
- BDF fonts (including anti-aliased ones)
- PFR fonts
- Type 42 fonts (limited support)

These functions return an FTGL $font object or undef if an error occurs.

If the variable $font goes out of scope or receives another value, the font is automatically destroyed. Don't worry yourself about the ftglDestroyFont function.

• $font = ftglCreateBitmapFont( $fontfile );

  Bitmap fonts use 1-bit (2-colour) rasterised glyphs. A bitmap font cannot be directly rotated or scaled.

• $font = ftglCreatePixmapFont( $fontfile );

  Pixmap fonts use 8-bit (256 levels) rasterised glyphs. A pixmap font cannot be directly rotated or scaled.

• $font = ftglCreateOutlineFont( $fontfile );

  Outline fonts use OpenGL lines.

• $font = ftglCreatePolygonFont( $fontfile );

  Polygon fonts use planar triangle meshes and can be texture-mapped.

• $font = ftglCreateExtrudeFont( $fontfile );

  Extruded fonts are extruded polygon fonts, with the front, back and side meshes renderable separately to apply different effects and materials.

• $font = ftglCreateTextureFont( $fontfile );

  Texture fonts use one texture per glyph. They are fast because glyphs are stored permanently in the video card's memory

• $font = ftglCreateBufferFont( $fontfile );

  Buffer fonts use one texture per line of text. They tend to be faster than texture fonts when the same line of text needs to be rendered for more than one frame.

• ftglRenderFont ( $font, $string [, $mode] );

  Render a $string of characters with $font. The optional render $mode is an ORed-together combination of

  FTGL_RENDER_FRONT
  FTGL_RENDER_BACK
  FTGL_RENDER_SIDE
  FTGL_RENDER_ALL    ( = FTGL_RENDER_FRONT | FTGL_RENDER_BACK | FTGL_RENDER_SIDE )

  Default value for $mode is FTGL_RENDER_ALL.

• $success = ftglSetFontCharMap ( $font, $encoding );

  Set the character map for the $font. $encoding is one of the FreeType char map code:

  FT_ENCODING_NONE          FT_ENCODING_MS_SYMBOL       FT_ENCODING_UNICODE
  FT_ENCODING_SJIS          FT_ENCODING_GB2312          FT_ENCODING_BIG5
  FT_ENCODING_WANSUNG       FT_ENCODING_JOHAB           FT_ENCODING_MS_SJIS
  FT_ENCODING_MS_GB2312     FT_ENCODING_MS_BIG5         FT_ENCODING_MS_WANSUNG
  FT_ENCODING_MS_JOHAB      FT_ENCODING_ADOBE_STANDARD  FT_ENCODING_ADOBE_EXPERT
  FT_ENCODING_ADOBE_CUSTOM  FT_ENCODING_ADOBE_LATIN_1   FT_ENCODING_OLD_LATIN_2
  FT_ENCODING_APPLE_ROMAN

  Return 1 if $encoding was valid and set correctly.

  By default, when a new face object is created, (FreeType) lists all the charmaps contained in the font face and selects the one that supports Unicode character codes if it finds one. Otherwise, it tries to find support for Latin-1, then ASCII.

  It then gives up. In this case FTGL will set the charmap to the first it finds in the fonts charmap list. You can explicitly set the char encoding with ftglSetFontCharMap.

• @list = ftglGetFontCharMapList ( $font );

  Return the list of character maps in the $font.

• $success = ftglSetFontFaceSize ( $font, $size [, $resolution] );

  Set the character size of $font to the $size in point (1/72 inc). The optional parameter $resolution set the resolution of the target device (default value of 72 if omited).

  Return 1 if $size was set correctly.

• ftglSetFontDepth ( $font, $depth );

  Set the extrusion distance $depth for the $font.

  Only implemented if $font is an ExtrudeFont.

• ftglSetFontOutset ( $font, $front, $back );

  Set the outset distance for the $font.

  Only OutlineFont, PolygoneFont and ExtrudeFont implement $front outset.

  Only ExtrudeFont implement $back outset.

• ftglSetFontDisplayList ( $font, $useList);

  Enable or disable the use of Display Lists inside FTGL for the $font.

  Set $useList to 1 turns ON display lists. 0 turns OFF display lists.

• $size = ftglGetFontFaceSize ( $font );

  Get the $font size in point (1/72 inch).

• $advance = ftglGetFontAdvance ( $font, $string );

  Get the advance width for $string using $font.

• $ascender = ftglGetFontAscender ( $font );

  Get the global ascender height for the $font.

• $descender = ftglGetFontDescender ( $font );

  Get the global descender height for the $font.

• $height = ftglGetFontLineHeight ( $font );

  Get the line spacing for the $font.

• @boundingbox = ftglGetFontBBox ( $font, $sting [, $len] );

  Get the bounding box for the $string using the $font.

  If present, the optional parameter $len specifies the number of character of $string to be checked.

  The function return the bounding box's lower left near and upper right far 3D coordinates.

• $errornumber = ftglGetFontError ( $font );

  Query a $font for errors. Return the current error code.

• $errornumber = ftglGetFontErrorMsg ( $font );

  Query a $font for errors. Return the current error message.

EXPORT

Nothing by default; the function names and constants must be explicitly exported.

Export Tags:

• :ftgl

  exports all the ftgl* functions.

• :FTGL_

  exports the FTGL_ constants

• :FT_

  exports FT_ENCODING constants

• :all

  exports all.

SEE ALSO

The FTGL library home page:

http://ftgl.sourceforge.net/docs/html/index.html

The FreeType 2 home page:

http://www.freetype.org/freetype2/

AUTHOR

J-L Morel <jl_morel@bribes.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by J-L Morel. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.