.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Imager::Font 3pm"
.TH Imager::Font 3pm "2011-11-25" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Imager::Font \- Font handling for Imager.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Imager;
\&
\&  $t1font = Imager::Font\->new(file => \*(Aqpathtofont.pfb\*(Aq);
\&  $ttfont = Imager::Font\->new(file => \*(Aqpathtofont.ttf\*(Aq);
\&  $w32font = Imager::Font\->new(face => \*(AqTimes New Roman\*(Aq);
\&
\&  $blue = Imager::Color\->new("#0000FF");
\&  $font = Imager::Font\->new(file  => \*(Aqpathtofont.ttf\*(Aq,
\&                            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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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:
.PP
.Vb 5
\&  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};
.Ve
.IP "new" 4
.IX Item "new"
This creates a font object to pass to functions that take a font argument.
.Sp
.Vb 5
\&  $font = Imager::Font\->new(file  => \*(Aqdenmark.ttf\*(Aq,
\&                            index => 0,
\&                            color => $blue,
\&                            size  => 30,
\&                            aa    => 1);
.Ve
.Sp
This creates a font which is the TrueType font \fIdenmark.ttf\fR.  It's
default color is \f(CW$blue\fR, 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
\&\f(CW\*(C`ttf\*(C'\fR is taken to mean a TrueType font while a suffix of \f(CW\*(C`pfb\*(C'\fR 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 \f(CW\*(C`type\*(C'\fR
parameter:
.Sp
.Vb 2
\&  $t1font = Imager::Font\->new(file => \*(Aqfruitcase\*(Aq, type => \*(Aqt1\*(Aq);
\&  $ttfont = Imager::Font\->new(file => \*(Aqarglebarf\*(Aq, type => \*(Aqtt\*(Aq);
.Ve
.Sp
The \f(CW\*(C`index\*(C'\fR 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 \f(CW\*(C`.dfont\*(C'\fR file.
.Sp
If any of the \f(CW\*(C`color\*(C'\fR, \f(CW\*(C`size\*(C'\fR or \f(CW\*(C`aa\*(C'\fR parameters are omitted when
calling \f(CW\*(C`Imager::Font\->new()\*(C'\fR the they take the following values:
.Sp
.Vb 4
\&  color => Imager::Color\->new(255, 0, 0, 0);  # this default should be changed
\&  size  => 15
\&  aa    => 0
\&  index => 0
.Ve
.Sp
To use Win32 fonts supply the face name of the font:
.Sp
.Vb 1
\&  $font = Imager::Font\->new(face=>\*(AqArial Bold Italic\*(Aq);
.Ve
.Sp
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.
.Sp
Other logical font attributes may be added if there is sufficient demand.
.Sp
Parameters:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`file\*(C'\fR \- name of the file to load the font from.
.IP "\(bu" 4

.Sp
\&\f(CW\*(C`face\*(C'\fR \- face name.  This is used only under Win32 to create a \s-1GDI\s0 based
font.  This is ignored if the \f(CW\*(C`file\*(C'\fR parameter is supplied.
.IP "\(bu" 4
\&\f(CW\*(C`type\*(C'\fR \- font driver to use.  Currently the permitted values for this are:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`tt\*(C'\fR \- FreeType 1.x driver.  Supports TrueType (\f(CW\*(C`.ttf\*(C'\fR) fonts.
.IP "\(bu" 4

.Sp
\&\f(CW\*(C`t1\*(C'\fR \- T1 Lib driver.  Supports Postscript Type 1 fonts.  Allows for
synthesis of underline, strikethrough and overline.
.IP "\(bu" 4
\&\f(CW\*(C`ft2\*(C'\fR \- FreeType 2.x driver.  Supports many different font formats.
Also supports the \fItransform()\fR method.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`color\*(C'\fR \- the default color used with this font.  Default: red.
.IP "\(bu" 4
\&\f(CW\*(C`size\*(C'\fR \- the default size used with this font.  Default: 15.
.IP "\(bu" 4
\&\f(CW\*(C`utf8\*(C'\fR \- if non-zero then text supplied to \f(CW$img\fR\->string(...) and
\&\f(CW$font\fR\->bounding_box(...) is assumed to be \s-1UTF\-8\s0 encoded by default.
.IP "\(bu" 4
\&\f(CW\*(C`align\*(C'\fR \- the default value for the \f(CW$img\fR\->string(...) \f(CW\*(C`align\*(C'\fR
parameter.  Default: 1.
.IP "\(bu" 4
\&\f(CW\*(C`vlayout\*(C'\fR \- the default value for the \f(CW$img\fR\->string(...) \f(CW\*(C`vlayout\*(C'\fR
parameter.  Default: 0.
.IP "\(bu" 4
\&\f(CW\*(C`aa\*(C'\fR \- the default value for the \f(CW$im\fR\->string(...) \f(CW\*(C`aa\*(C'\fR parameter.
Default: 0.
.IP "\(bu" 4
\&\f(CW\*(C`index\*(C'\fR \- for font file containing multiple fonts this selects which
font to use.  This is useful for Macintosh \f(CW\*(C`DFON\*(C'\fR (\fI.dfont\fR) and suitcase
font files.
.Sp
If you want to use a suitcase font you will need to tell Imager to use
the FreeType 2.x driver by setting \f(CW\*(C`type\*(C'\fR to \f(CW\*(Aqft2\*(Aq\fR:
.Sp
.Vb 2
\&  my $font = Imager::Font\->new(file=>$file, index => 1, type=>\*(Aqft2\*(Aq)
\&    or die Imager\->errstr;
.Ve
.RE
.RS 4
.RE
.IP "\fIbounding_box()\fR" 4
.IX Item "bounding_box()"
Returns the bounding box for the specified string.  Example:
.Sp
.Vb 8
\&  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");
.Ve
.RS 4
.ie n .IP "$neg_width" 4
.el .IP "\f(CW$neg_width\fR" 4
.IX Item "$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
.ie n .IP "$global_descent" 4
.el .IP "\f(CW$global_descent\fR" 4
.IX Item "$global_descent"
how far down the lowest letter of the entire font reaches below the
baseline (this is often j).
.ie n .IP "$pos_width" 4
.el .IP "\f(CW$pos_width\fR" 4
.IX Item "$pos_width"
how wide the string from
the starting position is.  The total width of the string is
\&\f(CW\*(C`$pos_width\-$neg_width\*(C'\fR.
.ie n .IP "$descent" 4
.el .IP "\f(CW$descent\fR" 4
.IX Item "$descent"
.PD 0
.ie n .IP "$ascent" 4
.el .IP "\f(CW$ascent\fR" 4
.IX Item "$ascent"
.PD
the same as <$global_descent> and <$global_ascent> except that they
are only for the characters that appear in the string.
.ie n .IP "$advance_width" 4
.el .IP "\f(CW$advance_width\fR" 4
.IX Item "$advance_width"
the distance from the start point that the next string output should
start at, this is often the same as \f(CW$pos_width\fR, but can be
different if the final character overlaps the right side of its
character cell.
.ie n .IP "$right_bearing" 4
.el .IP "\f(CW$right_bearing\fR" 4
.IX Item "$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.
.RE
.RS 4
.Sp
Obviously we can stuff all the results into an array just as well:
.Sp
.Vb 1
\&  @metrics = $font\->bounding_box(string => "testing 123");
.Ve
.Sp
Note that extra values may be added, so \f(CW$metrics\fR[\-1] isn't supported.
It's possible to translate the output by a passing coordinate to the
bounding box method:
.Sp
.Vb 1
\&  @metrics = $font\->bounding_box(string => "testing 123", x=>45, y=>34);
.Ve
.Sp
This gives the bounding box as if the string had been put down at \f(CW\*(C`(x,y)\*(C'\fR
By giving bounding_box 'canon' as a true value it's possible to measure
the space needed for the string:
.Sp
.Vb 1
\&  @metrics = $font\->bounding_box(string=>"testing",size=>15,canon=>1);
.Ve
.Sp
This returns the same values in \f(CW$metrics\fR[0] and \f(CW$metrics\fR[1],
but:
.Sp
.Vb 2
\& $bbox[2] \- horizontal space taken by glyphs
\& $bbox[3] \- vertical space taken by glyphs
.Ve
.Sp
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.
.Sp
Parameters are:
.IP "\(bu" 4
\&\f(CW\*(C`string\*(C'\fR \- the string to calculate the bounding box for.  Required.
.IP "\(bu" 4
\&\f(CW\*(C`size\*(C'\fR \- the font size to use.  Default: value set in
Imager::Font\->\fInew()\fR, or 15.
.IP "\(bu" 4
\&\f(CW\*(C`sizew\*(C'\fR \- the font width to use.  Default to the value of the \f(CW\*(C`size\*(C'\fR
parameter.
.IP "\(bu" 4
\&\f(CW\*(C`utf8\*(C'\fR \- For drivers that support it, treat the string as \s-1UTF\-8\s0 encoded.
For versions of perl that support Unicode (5.6 and later), this will
be enabled automatically if the 'string' parameter is already a \s-1UTF\-8\s0
string. See \*(L"\s-1UTF\-8\s0\*(R" for more information.  Default: the \f(CW\*(C`utf8\*(C'\fR value
passed to Imager::Font\->new(...) or 0.
.IP "\(bu" 4
\&\f(CW\*(C`x\*(C'\fR, \f(CW\*(C`y\*(C'\fR \- offsets applied to \f(CW@box\fR[0..3] to give you a adjusted bounding
box.  Ignored in scalar context.
.IP "\(bu" 4
\&\f(CW\*(C`canon\*(C'\fR \- if non-zero and the \f(CW\*(C`x\*(C'\fR, \f(CW\*(C`y\*(C'\fR parameters are not supplied,
then \f(CW$pos_width\fR and \f(CW$global_ascent\fR values will returned as the width
and height of the text instead.
.RE
.RS 4
.RE
.IP "\fIstring()\fR" 4
.IX Item "string()"
The \f(CW$img\fR\->string(...) method is now documented in
\&\*(L"\fIstring()\fR\*(R" in Imager::Draw
.IP "align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)" 4
.IX Item "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).
.Sp
.Vb 6
\&  # "Hello" centered at 100, 100 in the image.
\&  my ($left, $top, $right, $bottom) = 
\&    $font\->align(string=>"Hello",
\&                 x=>100, y=>100, 
\&                 halign=>\*(Aqcenter\*(Aq, valign=>\*(Aqcenter\*(Aq, 
\&                 image=>$image);
.Ve
.Sp
Takes the same parameters as \f(CW$font\fR\->\fIdraw()\fR, and the following extra
parameters:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`valign\*(C'\fR \- Possible values are:
.RS 4
.ie n .IP """top""" 4
.el .IP "\f(CWtop\fR" 4
.IX Item "top"
Point is at the top of the text.
.ie n .IP """bottom""" 4
.el .IP "\f(CWbottom\fR" 4
.IX Item "bottom"
Point is at the bottom of the text.
.ie n .IP """baseline""" 4
.el .IP "\f(CWbaseline\fR" 4
.IX Item "baseline"
Point is on the baseline of the text (default.)
.ie n .IP """center""" 4
.el .IP "\f(CWcenter\fR" 4
.IX Item "center"
Point is vertically centered within the text.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`halign\*(C'\fR
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`left\*(C'\fR \- the point is at the left of the text.
.IP "\(bu" 4
\&\f(CW\*(C`start\*(C'\fR \- the point is at the start point of the text.
.IP "\(bu" 4
\&\f(CW\*(C`center\*(C'\fR \- the point is horizontally centered within the text.
.IP "\(bu" 4
\&\f(CW\*(C`right\*(C'\fR \- the point is at the right end of the text.
.IP "\(bu" 4
\&\f(CW\*(C`end\*(C'\fR \- the point is at the end point of the text.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`image\*(C'\fR \- The image to draw to.  Set to \f(CW\*(C`undef\*(C'\fR to avoid drawing but
still calculate the bounding box.
.RE
.RS 4
.Sp
Returns a list specifying the bounds of the drawn text.
.RE
.IP "\fIdpi()\fR" 4
.IX Item "dpi()"
.PD 0
.IP "dpi(xdpi=>$xdpi, ydpi=>$ydpi)" 4
.IX Item "dpi(xdpi=>$xdpi, ydpi=>$ydpi)"
.IP "dpi(dpi=>$dpi)" 4
.IX Item "dpi(dpi=>$dpi)"
.PD
Set or retrieve the spatial resolution of the image in dots per inch.
The default is 72 dpi.
.Sp
This isn't implemented for all font types yet.
.Sp
Possible parameters are:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`xdpi\*(C'\fR, \f(CW\*(C`ydpi\*(C'\fR \- set the horizontal and vertical resolution in dots
per inch.
.IP "\(bu" 4
\&\f(CW\*(C`dpi\*(C'\fR \- set both horizontal and vertical resolution to this value.
.RE
.RS 4
.Sp
Returns a list containing the previous \f(CW\*(C`xdpi\*(C'\fR, \f(CW\*(C`ydpi\*(C'\fR values.
.RE
.IP "\fItransform()\fR" 4
.IX Item "transform()"
.Vb 1
\&  $font\->transform(matrix=>$matrix);
.Ve
.Sp
Applies a transformation to the font, where matrix is an array ref of
numbers representing a 2 x 3 matrix:
.Sp
.Vb 2
\&  [  $matrix\->[0],  $matrix\->[1],  $matrix\->[2],
\&     $matrix\->[3],  $matrix\->[4],  $matrix\->[5]   ]
.Ve
.Sp
Not all font types support transformations, these will return false.
.Sp
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.
.Sp
Currently only the ft2 (FreeType 2.x) driver supports the \fItransform()\fR
method.
.Sp
See samples/slant_text.pl for a sample using this function.
.Sp
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.
.IP "has_chars(string=>$text)" 4
.IX Item "has_chars(string=>$text)"
Checks if the characters in \f(CW$text\fR are defined by the font.
.Sp
In a list context returns a list of true or false value corresponding
to the characters in \f(CW$text\fR, true if the character is defined, false if
not.  In scalar context returns a string of \f(CW\*(C`NUL\*(C'\fR or non\-\f(CW\*(C`NUL\*(C'\fR
characters.  Supports \s-1UTF\-8\s0 where the font driver supports \s-1UTF\-8\s0.
.Sp
Not all fonts support this method (use \f(CW$font\fR\->can(\*(L"has_chars\*(R") to
check.)
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`string\*(C'\fR \- string of characters to check for.  Required.  Must contain
at least one character.
.IP "\(bu" 4
\&\f(CW\*(C`utf8\*(C'\fR \- For drivers that support it, treat the string as \s-1UTF\-8\s0
encoded.  For versions of perl that support Unicode (5.6 and later),
this will be enabled automatically if the 'string' parameter is
already a \s-1UTF\-8\s0 string. See \*(L"\s-1UTF\-8\s0\*(R" for more information.  Default:
the \f(CW\*(C`utf8\*(C'\fR value passed to Imager::Font\->new(...) or 0.
.RE
.RS 4
.RE
.IP "\fIface_name()\fR" 4
.IX Item "face_name()"
Returns the internal name of the face.  Not all font types support
this method yet.
.IP "glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );" 4
.IX Item "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 \f(CW\*(C`undef\*(C'\fR is returned for
the character.
.Sp
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.
.Sp
FreeType 2 has an \s-1API\s0 function that returns true only if the font has
\&\*(L"reliable glyph names\*(R", unfortunately this always returns false for
TrueType fonts.  This can avoid the check of this \s-1API\s0 by supplying
\&\f(CW\*(C`reliable_only\*(C'\fR 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 \s-1FT2\s0 handles them.
.Sp
Both FreeType 1.x and 2.x allow support for glyph names to not be
included.
.IP "draw" 4
.IX Item "draw"
This is used by Imager's \fIstring()\fR method to implement drawing text.
See \*(L"\fIstring()\fR\*(R" in Imager::Draw.
.SH "MULTIPLE MASTER FONTS"
.IX Header "MULTIPLE MASTER FONTS"
The FreeType 2 driver supports multiple master fonts:
.IP "\fIis_mm()\fR" 4
.IX Item "is_mm()"
Test if the font is a multiple master font.
.IP "\fImm_axes()\fR" 4
.IX Item "mm_axes()"
Returns a list of the axes that can be changes in the font.  Each
entry is an array reference which contains:
.RS 4
.IP "1." 4
Name of the axis.
.IP "2." 4
minimum value for this axis.
.IP "3." 4
maximum value for this axis
.RE
.RS 4
.RE
.IP "set_mm_coords(coords=>\e@values)" 4
.IX Item "set_mm_coords(coords=>@values)"
Blends an interpolated design from the master fonts.  \f(CW@values\fR must
contain as many values as there are axes in the font.
.PP
For example, to select the minimum value in each axis:
.PP
.Vb 3
\&  my @axes = $font\->mm_axes;
\&  my @coords = map $_\->[1], @axes;
\&  $font\->set_mm_coords(coords=>\e@coords);
.Ve
.PP
It's possible other drivers will support multiple master fonts in the
future, check if your selected font object supports the \fIis_mm()\fR method
using the \fIcan()\fR method.
.SH "UTF\-8"
.IX Header "UTF-8"
There are 2 ways of rendering Unicode characters with Imager:
.IP "\(bu" 4
For versions of perl that support it, use perl's native \s-1UTF\-8\s0 strings.
This is the simplest method.
.IP "\(bu" 4
Hand build your own \s-1UTF\-8\s0 encoded strings.  Only recommended if your
version of perl has no \s-1UTF\-8\s0 support.
.PP
Imager won't construct characters for you, so if want to output
Unicode character 00C3 \*(L"\s-1LATIN\s0 \s-1CAPITAL\s0 \s-1LETTER\s0 A \s-1WITH\s0 \s-1DIAERESIS\s0\*(R", and
your font doesn't support it, Imager will \fInot\fR build it from 0041
\&\*(L"\s-1LATIN\s0 \s-1CAPITAL\s0 \s-1LETTER\s0 A\*(R" and 0308 \*(L"\s-1COMBINING\s0 \s-1DIAERESIS\s0\*(R".
.PP
To check if a driver supports \s-1UTF\-8\s0 call the \fIutf8()\fR method:
.IP "\fIutf8()\fR" 4
.IX Item "utf8()"
Return true if the font supports \s-1UTF\-8\s0.
.SS "Native \s-1UTF\-8\s0 Support"
.IX Subsection "Native UTF-8 Support"
If your version of perl supports \s-1UTF\-8\s0 and the driver supports \s-1UTF\-8\s0,
just use the \f(CW$im\fR\->\fIstring()\fR method, and it should do the right thing.
.SS "Build your own"
.IX Subsection "Build your own"
In this case you need to build your own \s-1UTF\-8\s0 encoded characters.
.PP
For example:
.PP
.Vb 1
\& $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
.Ve
.PP
You need to be be careful with versions of perl that have \s-1UTF\-8\s0
support, since your string may end up doubly \s-1UTF\-8\s0 encoded.
.PP
For example:
.PP
.Vb 4
\& $x = "A\exE2\ex80\ex90\ex41\ex{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
.Ve
.PP
The test script t/t38ft2font.t has a small example of this after the 
comment:
.PP
.Vb 1
\&  # an attempt using emulation of UTF\-8
.Ve
.SH "DRIVER CONTROL"
.IX Header "DRIVER CONTROL"
If you don't supply a 'type' parameter to Imager::Font\->\fInew()\fR, 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.
.PP
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.
.IP "priorities" 4
.IX Item "priorities"
The current priorities can be retrieved with:
.Sp
.Vb 1
\&  @drivers = Imager::Font\->priorities();
.Ve
.Sp
You can set new priorities and save the old priorities with:
.Sp
.Vb 1
\&  @old = Imager::Font\->priorities(@drivers);
.Ve
.Sp
If you supply driver names that are not currently supported, they will
be ignored.
.Sp
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:
.Sp
.Vb 1
\&  my @old = Imager::Font\->priorities(qw(tt ft2 t1));
.Ve
.IP "register" 4
.IX Item "register"
Registers an extra font driver.  Accepts the following parameters:
.RS 4
.IP "\(bu" 4
type \- a brief identifier for the font driver.  You can supply this
value to \f(CW\*(C`Imager::Font\->new()\*(C'\fR to create fonts of this type.
Required.
.IP "\(bu" 4
class \- the font class name.  Imager will attempted to load this
module by name.  Required.
.IP "\(bu" 4
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 \f(CW\*(C`type\*(C'\fR parameter to
\&\f(CW\*(C`Imager::Font\->new()\*(C'\fR
.IP "\(bu" 4
description \- a brief description of the font driver.  Defaults to the
value supplied in \f(CW\*(C`class\*(C'\fR.
.RE
.RS 4
.RE
.SH "AUTHOR"
.IX Header "AUTHOR"
Arnar M. Hrafnkelsson, addi@umich.edu
And a great deal of help from others \- see the \fI\s-1README\s0\fR for a complete
list.
.SH "BUGS"
.IX Header "BUGS"
The \f(CW$pos_width\fR member returned by the \fIbounding_box()\fR 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.
.PP
The newer advance_width and right_bearing values allow access to any
of the above.
.SH "REVISION"
.IX Header "REVISION"
\&\f(CW$Revision\fR$
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIImager\fR\|(3), \fIImager::Font::FreeType2\fR\|(3), \fIImager::Font::Type1\fR\|(3),
\&\fIImager::Font::Win32\fR\|(3), \fIImager::Font::Truetype\fR\|(3), \fIImager::Font::BBox\fR\|(3)
.PP
.Vb 1
\& http://imager.perl.org/
.Ve