Font::FreeType(3pm) User Contributed Perl Documentation Font::FreeType(3pm)NAMEFont::FreeType - read font files and render glyphs from Perl using
FreeType2
SYNOPSIS
use Font::FreeType;
my $freetype = Font::FreeType->new;
my $face = $freetype->face('Vera.ttf');
$face->set_char_size(24, 24, 100, 100);
my $glyph = $face->glyph_from_char('A');
DESCRIPTION
This module allows Perl programs to conveniently read information from
font files. All the font access is done through the FreeType2 library,
which supports many formats. It can render images of characters with
high-quality hinting and antialiasing, extract metrics information, and
extract the outlines of characters in scalable formats like TrueType.
Warning: this module is currently in 'beta' stage. It'll be another
release or two before it stabilizes. The API may change in ways that
break programs based on it, but I don't think it will change much.
Some of the values returned may be wrong, or not scaled correctly. See
the TODO file to get a handle on how far along this work is.
Contributions welcome, particularly if you know more than I do (which
isn't much) about fonts and the FreeType2 library.
The Font::FreeType API is not intended to replicate the C API of the
FreeType library -- it offers a much more Perl-friendly interface.
The quickest way to get started with this library is to look at the
examples in the examples directory of the distribution. Full details
of the API are contained in this documentation, and (more importantly)
the documentation for the Font::FreeType::Face and
Font::FreeType::Glyph classes.
To use the library, first create a Font::FreeType object. This can be
used to load faces from files, for example:
my $freetype = Font::FreeType->new;
my $face = $freetype->face('Vera.ttf');
If your font is scalable (i.e., not a bitmapped font) then set the size
and resolution you want to see it at, for example 24pt at 100dpi:
$face->set_char_size(24, 24, 100, 100);
Then load a particular glyph (an image of a character), either by
character code (in Unicode) or the actual character:
my $glyph = $face->glyph_from_char_code(65);
my $glyph = $face->glyph_from_char('A');
Glyphs can be rendered to bitmap images, among other things:
my $bitmap = $glyph->bitmap;
See the documentation for Font::FreeType::Glyph for details of the
format of the bitmap array reference that returns, and for other ways
to get information about a glyph.
METHODS
Unless otherwise stated, all methods will die if there is an error.
new()
Create a new 'instance' of the freetype library and return the
object. This is a class method, which doesn't take any arguments.
If you only want to load one face, then it's probably not even
worth saving the object to a variable:
my $face = Font::FreeType->new->face('Vera.ttf');
face(filename, %options)
Return a Font::FreeType::Face object representing a font face from
the specified file.
The "index" option specifies which face to load from the file. It
defaults to 0, and since most fonts only contain one face it rarely
needs to be provided.
The "load_flags" option takes various flags which alter the way
glyphs are loaded. The default is usually OK for rendering fonts
to bitmap images. When extracting outlines from fonts, be sure to
set the FT_LOAD_NO_HINTING flag.
The following load flags are available. They can be combined with
the bitwise OR operator ("|"). The symbols are exported by the
module and so will be available once you do "use Font::FreeType".
FT_LOAD_DEFAULT
The same as doing nothing special.
FT_LOAD_CROP_BITMAP
Remove extraneous black bits round the edges of bitmaps when
loading embedded bitmaps.
FT_LOAD_FORCE_AUTOHINT
Use FreeType's own automatic hinting algorithm rather than the
normal TrueType one. Probably only useful for testing the
FreeType library.
FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH
Probably only useful for loading fonts with wrong metrics.
FT_LOAD_IGNORE_TRANSFORM
Don't transform glyphs. This module doesn't yet have support
for transformations.
FT_LOAD_LINEAR_DESIGN
Don't scale the metrics.
FT_LOAD_NO_AUTOHINT
Don't use the FreeType autohinting algorithm. Hinting with
other algorithms (such as the TrueType one) will still be done
if possible. Apparently some fonts look worse with the
autohinter than without any hinting.
This option is only available with FreeType 2.1.3 or newer.
FT_LOAD_NO_BITMAP
Don't load embedded bitmaps provided with scalable fonts.
Bitmap fonts are still loaded normally. This probably doesn't
make much difference in the current version of this module, as
embedded bitmaps aren't deliberately used.
FT_LOAD_NO_HINTING
Prevents the coordinates of the outline from being adjusted
('grid fitted') to the current size. Hinting should be turned
on when rendering bitmap images of glyphs, and off when
extracting the outline information if you don't know at what
resolution it will be rendered. For example, when converting
glyphs to PostScript or PDF, use this to turn the hinting off.
FT_LOAD_NO_SCALE
Don't scale the font's outline or metrics to the right size.
This will currently generate bad numbers. To be fixed in a
later version.
FT_LOAD_PEDANTIC
Raise errors when a font file is broken, rather than trying to
work around it.
FT_LOAD_VERTICAL_LAYOUT
Return metrics and glyphs suitable for vertical layout. This
module doesn't yet provide any intentional support for vertical
layout, so this probably won't be much use.
version()
Returns the version number of the underlying FreeType library being
used. If called in scalar context returns a string containing
three numbers in the format "major.minor.patch". In list context
returns the three numbers as separate values.
SEE ALSO
Font::FreeType::Face, Font::FreeType::Glyph
AUTHOR
Geoff Richards <qef@laxan.com>
COPYRIGHT
Copyright 2004, Geoff Richards.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.10.0 2004-09-11 Font::FreeType(3pm)
