Imager::Font - Font handling for Imager. |
Imager::Font - Font handling for Imager.
use Imager;
$t1font = Imager::Font->new(file => 'pathtofont.pfb'); $ttfont = Imager::Font->new(file => 'pathtofont.ttf'); $w32font = Imager::Font->new(face => 'Times New Roman');
$blue = Imager::Color->new("#0000FF"); $font = Imager::Font->new(file => 'pathtofont.ttf', color => $blue, size => 30);
($neg_width, $global_descent, $pos_width, $global_ascent, $descent, $ascent, $advance_width, $right_bearing) = $font->bounding_box(string=>"Foo");
my $bbox_object = $font->bounding_box(string=>"Foo");
# documented in Imager::Draw $img->string(font => $font, text => "Model-XYZ", x => 15, y => 40, size => 40, color => $red, aa => 1);
This module handles creating Font objects used by Imager. The module also handles querying fonts for sizes and such. If both T1lib and FreeType were available at the time of compilation then Imager should be able to work with both TrueType fonts and t1 Postscript fonts. To check if Imager is t1 or TrueType capable you can use something like this:
use Imager; print "Has truetype" if $Imager::formats{tt}; print "Has t1 postscript" if $Imager::formats{t1}; print "Has Win32 fonts" if $Imager::formats{w32}; print "Has Freetype2" if $Imager::formats{ft2};
$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()
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
$global_descent
$pos_width
$pos_width-$neg_width
.
$descent
$ascent
$advance_width
$pos_width
, but can be
different if the final character overlaps the right side of its
character cell.
$right_bearing
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 the Imager::Font::BBox manpage 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()
string(...)
method is now documented in
string() in the Imager::Draw manpage
# "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
bottom
baseline
center
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()
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
.
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()
$font->can("face_name")
>> before calling C<face_name>
.
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 an object method, returns true if the supplied font supports returning glyph names.
string()
method to implement drawing text.
See string() in the Imager::Draw manpage.
The FreeType 2 driver supports multiple master fonts:
is_mm()
mm_axes()
For example, to select the minimum value in each axis:
my @axes = $font->mm_axes; my @coords = map $_->[1], @axes; $font->set_mm_coords(coords=>\@coords);
It's possible other drivers will support multiple master fonts in the
future, check if your selected font object supports the is_mm()
method
using the can()
method.
There are 2 ways of rendering Unicode characters with Imager:
Imager won't construct characters for you, so if want to output Unicode character 00C3 ``LATIN CAPITAL LETTER A WITH DIAERESIS'', and your font doesn't support it, Imager will not build it from 0041 ``LATIN CAPITAL LETTER A'' and 0308 ``COMBINING DIAERESIS''.
To check if a driver supports UTF-8 call the utf8()
method:
utf8()
If your version of perl supports UTF-8 and the driver supports UTF-8,
just use the $im->string()
method, and it should do the right thing.
In this case you need to build your own UTF-8 encoded characters.
For example:
$x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
You need to be careful with versions of perl that have UTF-8 support, since your string may end up doubly UTF-8 encoded.
For example:
$x = "A\xE2\x80\x90\x41\x{2010}"; substr($x, -1, 0) = ""; # at this point $x is has the UTF-8 flag set, but has 5 characters, # none, of which is the constructed UTF-8 character
The test script t/t38ft2font.t has a small example of this after the comment:
# an attempt using emulation of UTF-8
If you don't supply a 'type' parameter to Imager::Font->new(), but you do supply a 'file' parameter, Imager will attempt to guess which font driver to used based on the extension of the font file.
Since some formats can be handled by more than one driver, a priority list is used to choose which one should be used, if a given format can be handled by more than one driver.
@drivers = Imager::Font->priorities();
You can set new priorities and save the old priorities with:
@old = Imager::Font->priorities(@drivers);
If you supply driver names that are not currently supported, they will be ignored.
Imager supports both T1Lib and FreeType 2 for working with Type 1 fonts, but currently only T1Lib does any caching, so by default T1Lib is given a higher priority. Since Imager's FreeType 2 support can also do font transformations, you may want to give that a higher priority:
my @old = Imager::Font->priorities(qw(tt ft2 t1));
Imager::Font->new()
to create fonts of this type.
Required.
class - the font class name. Imager will attempted to load this
module by name. Required.
files - a regular expression to match against file names. If supplied
this must be a valid perl regular expression. If not supplied you can
only create fonts of this type by supplying the type
parameter to
Imager::Font->new()
description - a brief description of the font driver. Defaults to the
value supplied in class
.
Arnar M. Hrafnkelsson, addi@umich.edu And a great deal of help from others - see the README for a complete list.
The $pos_width member returned by the bounding_box()
method has
historically returned different values from different drivers. The
FreeType 1.x and 2.x, and the Win32 drivers return the max of the
advance width and the right edge of the right-most glyph. The Type 1
driver always returns the right edge of the right-most glyph.
The newer advance_width and right_bearing values allow access to any of the above.
$Revision$
Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3), Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
http://imager.perl.org/
Imager::Font - Font handling for Imager. |