This module manages, the font object returned by Imager::Font->new will typically be of a class derived
from Imager::Font.
new This creates a font object to pass to functions that take a font argument.
$font = Imager::Font->new(file => 'denmark.ttf',
index => 0,
color => $blue,
size => 30,
aa => 1);
This creates a font which is the TrueType font denmark.ttf. It's default color is $blue, default
size is 30 pixels and it's rendered anti-aliased by default. Imager can see which type of font a
file is by looking at the suffix of the file name for the font. A suffix of "ttf" is taken to mean a
TrueType font while a suffix of "pfb" is taken to mean a Type 1 Postscript font. If Imager cannot
tell which type a font is you can tell it explicitly by using the "type" parameter:
$t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
$ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
The "index" parameter is used to select a single face from a font file containing more than one face,
for example, from a Macintosh font suitcase or a ".dfont" file.
If any of the "color", "size" or "aa" parameters are omitted when calling "Imager::Font->new()" the
they take the following values:
color => Imager::Color->new(255, 0, 0, 0); # this default should be changed
size => 15
aa => 0
index => 0
To use Win32 fonts supply the face name of the font:
$font = Imager::Font->new(face=>'Arial Bold Italic');
There isn't any access to other logical font attributes, but this typically isn't necessary for Win32
TrueType fonts, since you can construct the full name of the font as above.
Other logical font attributes may be added if there is sufficient demand.
Parameters:
• "file" - name of the file to load the font from.
•
"face" - face name. This is used only under Win32 to create a GDI based font. This is ignored
if the "file" parameter is supplied.
• "type" - font driver to use. Currently the permitted values for this are:
• "tt" - FreeType 1.x driver. Supports TrueType (".ttf") fonts.
•
"t1" - T1 Lib driver. Supports Postscript Type 1 fonts. Allows for synthesis of underline,
strikethrough and overline.
• "ft2" - FreeType 2.x driver. Supports many different font formats. Also supports the
transform() method.
• "color" - the default color used with this font. Default: red.
• "size" - the default size used with this font. Default: 15.
• "utf8" - if non-zero then text supplied to $img->string(...) and $font->bounding_box(...) is
assumed to be UTF-8 encoded by default.
• "align" - the default value for the $img->string(...) "align" parameter. Default: 1.
• "vlayout" - the default value for the $img->string(...) "vlayout" parameter. Default: 0.
• "aa" - the default value for the $im->string(...) "aa" parameter. Default: 0.
• "index" - for font file containing multiple fonts this selects which font to use. This is useful
for Macintosh "DFON" (.dfont) and suitcase font files.
If you want to use a suitcase font you will need to tell Imager to use the FreeType 2.x driver by
setting "type" to 'ft2':
my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
or die Imager->errstr;
Returns the new font object on success. Returns "undef" on failure and sets an error message readable
with "Imager->errstr".
bounding_box()
Returns the bounding box for the specified string. Example:
my ($neg_width,
$global_descent,
$pos_width,
$global_ascent,
$descent,
$ascent,
$advance_width,
$right_bearing) = $font->bounding_box(string => "A Fool");
my $bbox_object = $font->bounding_box(string => "A Fool");
$neg_width
the relative start of a the string. In some cases this can be a negative number, in that case
the first letter stretches to the left of the starting position that is specified in the string
method of the Imager class
$global_descent
how far down the lowest letter of the entire font reaches below the baseline (this is often j).
$pos_width
how wide the string from the starting position is. The total width of the string is
"$pos_width-$neg_width".
$descent
$ascent
the same as <$global_descent> and <$global_ascent> except that they are only for the characters
that appear in the string.
$advance_width
the distance from the start point that the next string output should start at, this is often the
same as $pos_width, but can be different if the final character overlaps the right side of its
character cell.
$right_bearing
The distance from the right side of the final glyph to the end of the advance width. If the
final glyph overflows the advance width this value is negative.
Obviously we can stuff all the results into an array just as well:
@metrics = $font->bounding_box(string => "testing 123");
Note that extra values may be added, so $metrics[-1] isn't supported. It's possible to translate the
output by a passing coordinate to the bounding box method:
@metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
This gives the bounding box as if the string had been put down at "(x,y)" By giving bounding_box
'canon' as a true value it's possible to measure the space needed for the string:
@metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
This returns the same values in $metrics[0] and $metrics[1], but:
$bbox[2] - horizontal space taken by glyphs
$bbox[3] - vertical space taken by glyphs
Returns an Imager::Font::BBox object in scalar context, so you can avoid all those confusing indexes.
This has methods as named above, with some extra convenience methods.
Parameters are:
• "string" - the string to calculate the bounding box for. Required.
• "size" - the font size to use. Default: value set in Imager::Font->new(), or 15.
• "sizew" - the font width to use. Default to the value of the "size" parameter.
• "utf8" - For drivers that support it, treat the string as UTF-8 encoded. For versions of perl
that support Unicode (5.6 and later), this will be enabled automatically if the 'string'
parameter is already a UTF-8 string. See "UTF-8" for more information. Default: the "utf8" value
passed to Imager::Font->new(...) or 0.
• "x", "y" - offsets applied to @box[0..3] to give you a adjusted bounding box. Ignored in scalar
context.
• "canon" - if non-zero and the "x", "y" parameters are not supplied, then $pos_width and
$global_ascent values will returned as the width and height of the text instead.
On success returns either the list of bounds, or a bounding box object in scalar context. Returns an
empty list or "undef" on failure and sets an error message readable with "Imager->errstr".
The transformation matrix set by "transform()" has no effect on the result of this method - the
bounds of the untransformed text is returned.
string()
The $img->string(...) method is now documented in "string()" in Imager::Draw
align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)
Higher level text output - outputs the text aligned as specified around the given point (x,y).
# "Hello" centered at 100, 100 in the image.
my ($left, $top, $right, $bottom) =
$font->align(string=>"Hello",
x=>100, y=>100,
halign=>'center', valign=>'center',
image=>$image);
Takes the same parameters as $font->draw(), and the following extra parameters:
• "valign" - Possible values are:
"top"
Point is at the top of the text.
"bottom"
Point is at the bottom of the text.
"baseline"
Point is on the baseline of the text (default.)
"center"
Point is vertically centered within the text.
• "halign"
• "left" - the point is at the left of the text.
• "start" - the point is at the start point of the text.
• "center" - the point is horizontally centered within the text.
• "right" - the point is at the right end of the text.
• "end" - the point is at the end point of the text.
• "image" - The image to draw to. Set to "undef" to avoid drawing but still calculate the bounding
box.
Returns a list specifying the bounds of the drawn text on success. Returns an empty list on failure,
if an "image" parameter was supplied the error message can be read with "$image->errstr", otherwise
it's available as "Imager->errstr".
dpi()
dpi(xdpi=>$xdpi, ydpi=>$ydpi)
dpi(dpi=>$dpi)
Set or retrieve the spatial resolution of the image in dots per inch. The default is 72 dpi.
This isn't implemented for all font types yet.
Possible parameters are:
• "xdpi", "ydpi" - set the horizontal and vertical resolution in dots per inch.
• "dpi" - set both horizontal and vertical resolution to this value.
Returns a list containing the previous "xdpi", "ydpi" values on success. Returns an empty list on
failure, with an error message returned in "Imager->errstr".
transform()
$font->transform(matrix=>$matrix);
Applies a transformation to the font, where matrix is an array ref of numbers representing a 2 x 3
matrix:
[ $matrix->[0], $matrix->[1], $matrix->[2],
$matrix->[3], $matrix->[4], $matrix->[5] ]
Not all font types support transformations, these will return false.
It's possible that a driver will disable hinting if you use a transformation, to prevent
discontinuities in the transformations. See the end of the test script t/t38ft2font.t for an
example.
Currently only the ft2 (FreeType 2.x) driver supports the transform() method.
See samples/slant_text.pl for a sample using this function.
Note that the transformation is done in font co-ordinates where y increases as you move up, not image
co-ordinates where y decreases as you move up.
transform() has no effect on the results of "bounding_box()".
Returns true on success. Returns false on failure with the cause readable from "Imager->errstr".
has_chars(string=>$text)
Checks if the characters in $text are defined by the font.
In a list context returns a list of true or false value corresponding to the characters in $text,
true if the character is defined, false if not. In scalar context returns a string of "NUL" or
non-"NUL" characters. Supports UTF-8 where the font driver supports UTF-8.
Not all fonts support this method (use $font->can("has_chars") to check.)
On error, returns an empty list or undef in scalar context, and sets an error message readable with
"Imager->errstr".
• "string" - string of characters to check for. Required. Must contain at least one character.
• "utf8" - For drivers that support it, treat the string as UTF-8 encoded. For versions of perl
that support Unicode (5.6 and later), this will be enabled automatically if the 'string'
parameter is already a UTF-8 string. See "UTF-8" for more information. Default: the "utf8" value
passed to Imager::Font->new(...) or 0.
face_name()
Returns the internal name of the face. Not all font types support this method yet, so you should
check with "$font->can("face_name")" before calling "face_name".
glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
Returns a list of glyph names for each of the characters in the string. If the character has no name
then "undef" is returned for the character.
Some font files do not include glyph names, in this case FreeType 2 will not return any names.
FreeType 1 can return standard names even if there are no glyph names in the font.
FreeType 2 has an API function that returns true only if the font has "reliable glyph names",
unfortunately this always returns false for TrueType fonts. This can avoid the check of this API by
supplying "reliable_only" as 0. The consequences of using this on an unknown font may be
unpredictable, since the FreeType documentation doesn't say how those name tables are unreliable, or
how FT2 handles them.
Both FreeType 1.x and 2.x allow support for glyph names to not be included.
If the supplied "string" is marked as UTF-8 or the "utf8" parameter is true and the supplied string
does not contain valid UTF-8, returns an empty string and set an error message readable from
"Imager->errstr",
can_glyph_names()
As a class method, returns true if the underlying library supports returning glyph names.
As an object method, returns true if the supplied font supports returning glyph names.
draw
This is used by Imager's string() method to implement drawing text. See "string()" in Imager::Draw.
Install Now
PNG Icons
