huge spelling update and spell checking patch
[imager.git] / lib / Imager / Font.pm
1 package Imager::Font;
2
3 use Imager::Color;
4 use strict;
5 use vars qw($VERSION);
6
7 $VERSION = "1.034";
8
9 # the aim here is that we can:
10 #  - add file based types in one place: here
11 #  - make sure we only attempt to create types that exist
12 #  - give reasonable defaults
13 #  - give the user some control over which types get used
14 my %drivers =
15   (
16    tt=>{
17         class=>'Imager::Font::Truetype',
18         module=>'Imager/Font/Truetype.pm',
19         files=>'.*\.ttf$',
20         description => 'FreeType 1.x',
21        },
22    t1=>{
23         class=>'Imager::Font::Type1',
24         module=>'Imager/Font/Type1.pm',
25         files=>'.*\.pfb$',
26         description => 'T1Lib',
27        },
28    ft2=>{
29          class=>'Imager::Font::FreeType2',
30          module=>'Imager/Font/FreeType2.pm',
31          files=>'.*\.(pfa|pfb|otf|ttf|fon|fnt|dfont|pcf(\.gz)?)$',
32          description => 'FreeType 2.x',
33         },
34    ifs=>{
35          class=>'Imager::Font::Image',
36          module=>'Imager/Font/Image.pm',
37          files=>'.*\.ifs$',
38         },
39    w32=>{
40          class=>'Imager::Font::Win32',
41          module=>'Imager/Font/Win32.pm',
42          description => 'Win32 GDI Fonts',
43         },
44   );
45
46 # this currently should only contain file based types, don't add w32
47 my @priority = qw(t1 tt ft2 ifs);
48
49 # when Imager::Font is loaded, Imager.xs has not been bootstrapped yet
50 # this function is called from Imager.pm to finish initialization
51 sub __init {
52   @priority = grep Imager::i_has_format($_), @priority;
53   for my $driver_name (grep Imager::i_has_format($_), keys %drivers) {
54     $drivers{$driver_name}{enabled} = 1;
55   }
56 }
57
58 # search method
59 # 1. start by checking if file is the parameter
60 # 1a. if so qualify path and compare to the cache.
61 # 2a. if in cache - take it's id from there and increment count.
62 #
63
64 sub new {
65   my $class = shift;
66   my $self = {};
67   my ($file, $type, $id);
68   my %hsh=(color => Imager::Color->new(255,0,0,0),
69            size => 15,
70            @_);
71
72   bless $self,$class;
73
74   if ($hsh{'file'}) {
75     $file = $hsh{'file'};
76     if ( $file !~ m/^\// ) {
77       $file = './'.$file;
78       if (! -e $file) {
79         $Imager::ERRSTR = "Font $file not found";
80         return();
81       }
82     }
83
84     $type = $hsh{'type'};
85     if (!defined($type) or !$drivers{$type} or !$drivers{$type}{enabled}) {
86       for my $drv (@priority) {
87         undef $type;
88         my $re = $drivers{$drv}{files} or next;
89         if ($file =~ /$re/i) {
90           $type = $drv;
91           last;
92         }
93       }
94     }
95     if (!defined($type)) {
96       # some types we can support, but the driver isn't available
97       # work out which drivers support it, so we can provide the user
98       # some useful information on how to get it working
99       my @not_here;
100       for my $driver_name (keys %drivers) {
101         my $driver = $drivers{$driver_name};
102         push @not_here, "$driver_name ($driver->{description})"
103           if $driver->{files} && $file =~ /$driver->{files}/i;
104       }
105       if (@not_here) {
106         $Imager::ERRSTR = "No font drivers enabled that can support this file, rebuild Imager with any of ".join(", ", @not_here)." to use this font file";
107       }
108       else {
109         $Imager::ERRSTR = "No font type found for $hsh{'file'}";
110       }
111       return;
112     }
113   } elsif ($hsh{face}) {
114     $type = "w32";
115   } else {
116     $Imager::ERRSTR="No font file specified";
117     return;
118   }
119
120   if (!$Imager::formats{$type}) {
121     $Imager::ERRSTR = "`$type' not enabled";
122     return;
123   }
124
125   # here we should have the font type or be dead already.
126
127   require $drivers{$type}{module};
128   return $drivers{$type}{class}->new(%hsh);
129 }
130
131 # returns first defined parameter
132 sub _first {
133   for (@_) {
134     return $_ if defined $_;
135   }
136   return undef;
137 }
138
139 sub draw {
140   my $self = shift;
141   my %input = ('x' => 0, 'y' => 0, @_);
142   unless ($input{image}) {
143     $Imager::ERRSTR = 'No image supplied to $font->draw()';
144     return;
145   }
146   my $image = $input{image};
147   $input{string} = _first($input{string}, $input{text});
148   unless (defined $input{string}) {
149     $image->_set_error("Missing required parameter 'string'");
150     return;
151   }
152   $input{aa} = _first($input{aa}, $input{antialias}, $self->{aa}, 1);
153   # the original draw code worked this out but didn't use it
154   $input{align} = _first($input{align}, $self->{align});
155   $input{color} = _first($input{color}, $self->{color});
156   $input{color} = Imager::_color($input{'color'});
157
158   $input{size} = _first($input{size}, $self->{size});
159   unless (defined $input{size}) {
160     $image->_set_error("No font size provided");
161     return undef;
162   }
163   $input{align} = _first($input{align}, 1);
164   $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
165   $input{vlayout} = _first($input{vlayout}, $self->{vlayout}, 0);
166
167   my $result = $self->_draw(%input);
168   unless ($result) {
169     $image->_set_error($image->_error_as_msg());
170   }
171
172   return $result;
173 }
174
175 sub align {
176   my $self = shift;
177   my %input = ( halign => 'left', valign => 'baseline', 
178                 'x' => 0, 'y' => 0, @_ );
179
180   # image needs to be supplied, but can be supplied as undef
181   unless (exists $input{image}) {
182     Imager->_set_error("Missing required parameter 'image'");
183     return;
184   }
185
186   my $errors_to = $input{image} || 'Imager';
187
188   my $text = _first($input{string}, $input{text});
189   unless (defined $text) {
190     $errors_to->_set_error("Missing required parameter 'string'");
191     return;
192   }
193
194   my $size = _first($input{size}, $self->{size});
195   my $utf8 = _first($input{utf8}, 0);
196
197   my $bbox = $self->bounding_box(string=>$text, size=>$size, utf8=>$utf8);
198   my $valign = $input{valign};
199   $valign = 'baseline'
200     unless $valign && $valign =~ /^(?:top|center|bottom|baseline)$/;
201
202   my $halign = $input{halign};
203   $halign = 'start' 
204     unless $halign && $halign =~ /^(?:left|start|center|end|right)$/;
205
206   my $x = $input{'x'};
207   my $y = $input{'y'};
208
209   if ($valign eq 'top') {
210     $y += $bbox->ascent;
211   }
212   elsif ($valign eq 'center') {
213     $y += $bbox->ascent - $bbox->text_height / 2;
214   }
215   elsif ($valign eq 'bottom') {
216     $y += $bbox->descent;
217   }
218   # else baseline is the default
219
220   if ($halign eq 'left') {
221     $x -= $bbox->start_offset;
222   }
223   elsif ($halign eq 'start') {
224     # nothing to do
225   }
226   elsif ($halign eq 'center') {
227     $x -= $bbox->start_offset + $bbox->total_width / 2;
228   }
229   elsif ($halign eq 'end') {
230     $x -= $bbox->advance_width;
231   }
232   elsif ($halign eq 'right') {
233     $x -= $bbox->advance_width - $bbox->right_bearing;
234   }
235   $x = int($x);
236   $y = int($y);
237
238   if ($input{image}) {
239     delete @input{qw/x y/};
240     $self->draw(%input, 'x' => $x, 'y' => $y, align=>1)
241       or return;
242   }
243
244   return ($x+$bbox->start_offset, $y-$bbox->ascent, 
245           $x+$bbox->end_offset, $y-$bbox->descent+1);
246 }
247
248 sub bounding_box {
249   my $self=shift;
250   my %input=@_;
251
252   if (!exists $input{'string'}) { 
253     $Imager::ERRSTR='string parameter missing'; 
254     return;
255   }
256   $input{size} ||= $self->{size};
257   $input{sizew} = _first($input{sizew}, $self->{sizew}, 0);
258   $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
259
260   my @box = $self->_bounding_box(%input);
261
262   if (wantarray) {
263     if(@box && exists $input{'x'} and exists $input{'y'}) {
264       my($gdescent, $gascent)=@box[1,3];
265       $box[1]=$input{'y'}-$gascent;      # top = base - ascent (Y is down)
266       $box[3]=$input{'y'}-$gdescent;     # bottom = base - descent (Y is down, descent is negative)
267       $box[0]+=$input{'x'};
268       $box[2]+=$input{'x'};
269     } elsif (@box && $input{'canon'}) {
270       $box[3]-=$box[1];    # make it cannoical (ie (0,0) - (width, height))
271       $box[2]-=$box[0];
272     }
273     return @box;
274   }
275   else {
276     require Imager::Font::BBox;
277
278     return Imager::Font::BBox->new(@box);
279   }
280 }
281
282 sub dpi {
283   my $self = shift;
284
285   # I'm assuming a default of 72 dpi
286   my @old = (72, 72);
287   if (@_) {
288     $Imager::ERRSTR = "Setting dpi not implemented for this font type";
289     return;
290   }
291
292   return @old;
293 }
294
295 sub transform {
296   my $self = shift;
297
298   my %hsh = @_;
299
300   # this is split into transform() and _transform() so we can 
301   # implement other tags like: degrees=>12, which would build a
302   # 12 degree rotation matrix
303   # but I'll do that later
304   unless ($hsh{matrix}) {
305     $Imager::ERRSTR = "You need to supply a matrix";
306     return;
307   }
308
309   return $self->_transform(%hsh);
310 }
311
312 sub _transform {
313   $Imager::ERRSTR = "This type of font cannot be transformed";
314   return;
315 }
316
317 sub utf8 {
318   return 0;
319 }
320
321 sub priorities {
322   my $self = shift;
323   my @old = @priority;
324
325   if (@_) {
326     @priority = grep Imager::i_has_format($_), @_;
327   }
328   return @old;
329 }
330
331 1;
332
333 __END__
334
335 =head1 NAME
336
337 Imager::Font - Font handling for Imager.
338
339 =head1 SYNOPSIS
340
341   use Imager;
342
343   $t1font = Imager::Font->new(file => 'pathtofont.pfb');
344   $ttfont = Imager::Font->new(file => 'pathtofont.ttf');
345   $w32font = Imager::Font->new(face => 'Times New Roman');
346
347   $blue = Imager::Color->new("#0000FF");
348   $font = Imager::Font->new(file  => 'pathtofont.ttf',
349                             color => $blue,
350                             size  => 30);
351
352   ($neg_width,
353    $global_descent,
354    $pos_width,
355    $global_ascent,
356    $descent,
357    $ascent,
358    $advance_width,
359    $right_bearing) = $font->bounding_box(string=>"Foo");
360
361   my $bbox_object = $font->bounding_box(string=>"Foo");
362
363   # documented in Imager::Draw
364   $img->string(font  => $font,
365              text  => "Model-XYZ",
366              x     => 15,
367              y     => 40,
368              size  => 40,
369              color => $red,
370              aa    => 1);
371
372 =head1 DESCRIPTION
373
374 =for stopwords TrueType FreeType
375
376 This module handles creating Font objects used by Imager.  The module
377 also handles querying fonts for sizes and such.  If both T1lib and
378 FreeType were available at the time of compilation then Imager should
379 be able to work with both TrueType fonts and t1 Postscript fonts.  To
380 check if Imager is t1 or TrueType capable you can use something like
381 this:
382
383   use Imager;
384   print "Has truetype"      if $Imager::formats{tt};
385   print "Has t1 postscript" if $Imager::formats{t1};
386   print "Has Win32 fonts"   if $Imager::formats{w32};
387   print "Has Freetype2"     if $Imager::formats{ft2};
388
389 =over 4
390
391 =item new
392
393 This creates a font object to pass to functions that take a font argument.
394
395   $font = Imager::Font->new(file  => 'denmark.ttf',
396                             index => 0,
397                             color => $blue,
398                             size  => 30,
399                             aa    => 1);
400
401 This creates a font which is the TrueType font F<denmark.ttf>.  It's
402 default color is $blue, default size is 30 pixels and it's rendered
403 anti-aliased by default.  Imager can see which type of font a file is
404 by looking at the suffix of the file name for the font.  A suffix of
405 C<ttf> is taken to mean a TrueType font while a suffix of C<pfb> is
406 taken to mean a Type 1 Postscript font.  If Imager cannot tell which
407 type a font is you can tell it explicitly by using the C<type>
408 parameter:
409
410   $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
411   $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
412
413 The C<index> parameter is used to select a single face from a font
414 file containing more than one face, for example, from a Macintosh font
415 suitcase or a C<.dfont> file.
416
417 If any of the C<color>, C<size> or C<aa> parameters are omitted when
418 calling C<< Imager::Font->new() >> the they take the following values:
419
420   color => Imager::Color->new(255, 0, 0, 0);  # this default should be changed
421   size  => 15
422   aa    => 0
423   index => 0
424
425 To use Win32 fonts supply the face name of the font:
426
427   $font = Imager::Font->new(face=>'Arial Bold Italic');
428
429 There isn't any access to other logical font attributes, but this
430 typically isn't necessary for Win32 TrueType fonts, since you can
431 construct the full name of the font as above.
432
433 Other logical font attributes may be added if there is sufficient demand.
434
435 Parameters:
436
437 =over
438
439 =item *
440
441 C<file> - name of the file to load the font from.
442
443 =item *
444
445 =for stopwords GDI
446
447 C<face> - face name.  This is used only under Win32 to create a GDI based
448 font.  This is ignored if the C<file> parameter is supplied.
449
450 =item *
451
452 C<type> - font driver to use.  Currently the permitted values for this are:
453
454 =over
455
456 =item *
457
458 C<tt> - FreeType 1.x driver.  Supports TrueType (C<.ttf>) fonts.
459
460 =item *
461
462 =for stopwords strikethrough overline
463
464 C<t1> - T1 Lib driver.  Supports Postscript Type 1 fonts.  Allows for
465 synthesis of underline, strikethrough and overline.
466
467 =item *
468
469 C<ft2> - FreeType 2.x driver.  Supports many different font formats.
470 Also supports the transform() method.
471
472 =back
473
474 =item *
475
476 C<color> - the default color used with this font.  Default: red.
477
478 =item *
479
480 C<size> - the default size used with this font.  Default: 15.
481
482 =item *
483
484 C<utf8> - if non-zero then text supplied to $img->string(...) and
485 $font->bounding_box(...) is assumed to be UTF-8 encoded by default.
486
487 =item *
488
489 C<align> - the default value for the $img->string(...) C<align>
490 parameter.  Default: 1.
491
492 =item *
493
494 C<vlayout> - the default value for the $img->string(...) C<vlayout>
495 parameter.  Default: 0.
496
497 =item *
498
499 C<aa> - the default value for the $im->string(...) C<aa> parameter.
500 Default: 0.
501
502 =item *
503
504 C<index> - for font file containing multiple fonts this selects which
505 font to use.  This is useful for Macintosh C<DFON> (F<.dfont>) and suitcase
506 font files.
507
508 If you want to use a suitcase font you will need to tell Imager to use
509 the FreeType 2.x driver by setting C<type> to C<'ft2'>:
510
511   my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
512     or die Imager->errstr;
513
514 =back
515
516
517
518 =item bounding_box
519
520 Returns the bounding box for the specified string.  Example:
521
522   my ($neg_width,
523       $global_descent,
524       $pos_width,
525       $global_ascent,
526       $descent,
527       $ascent,
528       $advance_width,
529       $right_bearing) = $font->bounding_box(string => "A Fool");
530
531   my $bbox_object = $font->bounding_box(string => "A Fool");
532
533 =over
534
535 =item C<$neg_width>
536
537 the relative start of a the string.  In some
538 cases this can be a negative number, in that case the first letter
539 stretches to the left of the starting position that is specified in
540 the string method of the Imager class
541
542 =item C<$global_descent> 
543
544 how far down the lowest letter of the entire font reaches below the
545 baseline (this is often j).
546
547 =item C<$pos_width>
548
549 how wide the string from
550 the starting position is.  The total width of the string is
551 C<$pos_width-$neg_width>.
552
553 =item C<$descent> 
554
555 =item C<$ascent> 
556
557 the same as <$global_descent> and <$global_ascent> except that they
558 are only for the characters that appear in the string.
559
560 =item C<$advance_width>
561
562 the distance from the start point that the next string output should
563 start at, this is often the same as C<$pos_width>, but can be
564 different if the final character overlaps the right side of its
565 character cell.
566
567 =item C<$right_bearing>
568
569 The distance from the right side of the final glyph to the end of the
570 advance width.  If the final glyph overflows the advance width this
571 value is negative.
572
573 =back
574
575 Obviously we can stuff all the results into an array just as well:
576
577   @metrics = $font->bounding_box(string => "testing 123");
578
579 Note that extra values may be added, so $metrics[-1] isn't supported.
580 It's possible to translate the output by a passing coordinate to the
581 bounding box method:
582
583   @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
584
585 This gives the bounding box as if the string had been put down at C<(x,y)>
586 By giving bounding_box 'canon' as a true value it's possible to measure
587 the space needed for the string:
588
589   @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
590
591 This returns the same values in $metrics[0] and $metrics[1],
592 but:
593
594  $bbox[2] - horizontal space taken by glyphs
595  $bbox[3] - vertical space taken by glyphs
596
597 Returns an L<Imager::Font::BBox> object in scalar context, so you can
598 avoid all those confusing indexes.  This has methods as named above,
599 with some extra convenience methods.
600
601 Parameters are:
602
603 =over
604
605 =item *
606
607 C<string> - the string to calculate the bounding box for.  Required.
608
609 =item *
610
611 C<size> - the font size to use.  Default: value set in
612 Imager::Font->new(), or 15.
613
614 =item *
615
616 C<sizew> - the font width to use.  Default to the value of the C<size>
617 parameter.
618
619 =item *
620
621 C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
622 For versions of perl that support Unicode (5.6 and later), this will
623 be enabled automatically if the 'string' parameter is already a UTF-8
624 string. See L<UTF-8> for more information.  Default: the C<utf8> value
625 passed to Imager::Font->new(...) or 0.
626
627 =item *
628
629 C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
630 box.  Ignored in scalar context.
631
632 =item *
633
634 C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
635 then $pos_width and $global_ascent values will returned as the width
636 and height of the text instead.
637
638 =back
639
640 =item string()
641
642 The $img->string(...) method is now documented in
643 L<Imager::Draw/string>
644
645 =item align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)
646
647 Higher level text output - outputs the text aligned as specified
648 around the given point (x,y).
649
650   # "Hello" centered at 100, 100 in the image.
651   my ($left, $top, $right, $bottom) = 
652     $font->align(string=>"Hello",
653                  x=>100, y=>100, 
654                  halign=>'center', valign=>'center', 
655                  image=>$image);
656
657 Takes the same parameters as $font->draw(), and the following extra
658 parameters:
659
660 =over
661
662 =item *
663
664 C<valign> - Possible values are:
665
666 =over
667
668 =item C<top>
669
670 Point is at the top of the text.
671
672 =item C<bottom>
673
674 Point is at the bottom of the text.
675
676 =item C<baseline>
677
678 Point is on the baseline of the text (default.)
679
680 =item C<center>
681
682 Point is vertically centered within the text.
683
684 =back
685
686 =item *
687
688 C<halign>
689
690 =over
691
692 =item *
693
694 C<left> - the point is at the left of the text.
695
696 =item *
697
698 C<start> - the point is at the start point of the text.
699
700 =item *
701
702 C<center> - the point is horizontally centered within the text.
703
704 =item *
705
706 C<right> - the point is at the right end of the text.
707
708 =item *
709
710 C<end> - the point is at the end point of the text.
711
712 =back
713
714 =item *
715
716 C<image> - The image to draw to.  Set to C<undef> to avoid drawing but
717 still calculate the bounding box.
718
719 =back
720
721 Returns a list specifying the bounds of the drawn text.
722
723 =item dpi()
724
725 =item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
726
727 =item dpi(dpi=>$dpi)
728
729 Set or retrieve the spatial resolution of the image in dots per inch.
730 The default is 72 dpi.
731
732 This isn't implemented for all font types yet.
733
734 Possible parameters are:
735
736 =over
737
738 =item *
739
740 C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
741 per inch.
742
743 =item *
744
745 C<dpi> - set both horizontal and vertical resolution to this value.
746
747 =back
748
749 Returns a list containing the previous C<xdpi>, C<ydpi> values.
750
751 =item transform(matrix=>$matrix)
752
753 Applies a transformation to the font, where matrix is an array ref of
754 numbers representing a 2 x 3 matrix:
755
756   [  $matrix->[0],  $matrix->[1],  $matrix->[2],
757      $matrix->[3],  $matrix->[4],  $matrix->[5]   ]
758
759 Not all font types support transformations, these will return false.
760
761 It's possible that a driver will disable hinting if you use a
762 transformation, to prevent discontinuities in the transformations.
763 See the end of the test script t/t38ft2font.t for an example.
764
765 Currently only the ft2 (FreeType 2.x) driver supports the transform()
766 method.
767
768 See samples/slant_text.pl for a sample using this function.
769
770 Note that the transformation is done in font co-ordinates where y
771 increases as you move up, not image co-ordinates where y decreases as
772 you move up.
773
774 =item has_chars(string=>$text)
775
776 Checks if the characters in $text are defined by the font.
777
778 In a list context returns a list of true or false value corresponding
779 to the characters in $text, true if the character is defined, false if
780 not.  In scalar context returns a string of C<NUL> or non-C<NUL>
781 characters.  Supports UTF-8 where the font driver supports UTF-8.
782
783 Not all fonts support this method (use $font->can("has_chars") to
784 check.)
785
786 =over
787
788 =item *
789
790 C<string> - string of characters to check for.  Required.  Must contain
791 at least one character.
792
793 =item *
794
795 C<utf8> - For drivers that support it, treat the string as UTF-8
796 encoded.  For versions of perl that support Unicode (5.6 and later),
797 this will be enabled automatically if the 'string' parameter is
798 already a UTF-8 string. See L<UTF-8> for more information.  Default:
799 the C<utf8> value passed to Imager::Font->new(...) or 0.
800
801 =back
802
803 =item face_name()
804
805 Returns the internal name of the face.  Not all font types support
806 this method yet.
807
808 =item glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
809
810 Returns a list of glyph names for each of the characters in the
811 string.  If the character has no name then C<undef> is returned for
812 the character.
813
814 Some font files do not include glyph names, in this case FreeType 2
815 will not return any names.  FreeType 1 can return standard names even
816 if there are no glyph names in the font.
817
818 FreeType 2 has an API function that returns true only if the font has
819 "reliable glyph names", unfortunately this always returns false for
820 TrueType fonts.  This can avoid the check of this API by supplying
821 C<reliable_only> as 0.  The consequences of using this on an unknown
822 font may be unpredictable, since the FreeType documentation doesn't
823 say how those name tables are unreliable, or how FT2 handles them.
824
825 Both FreeType 1.x and 2.x allow support for glyph names to not be
826 included.
827
828 =item draw
829
830 This is used by Imager's string() method to implement drawing text.
831 See L<Imager::Draw/string>.
832
833 =back
834
835 =head1 MULTIPLE MASTER FONTS
836
837 The FreeType 2 driver supports multiple master fonts:
838
839 =over
840
841 =item is_mm()
842
843 Test if the font is a multiple master font.
844
845 =item mm_axes()
846
847 Returns a list of the axes that can be changes in the font.  Each
848 entry is an array reference which contains:
849
850 =over
851
852 =item 1.
853
854 Name of the axis.
855
856 =item 2.
857
858 minimum value for this axis.
859
860 =item 3.
861
862 maximum value for this axis
863
864 =back
865
866 =item set_mm_coords(coords=>\@values)
867
868 Blends an interpolated design from the master fonts.  @values must
869 contain as many values as there are axes in the font.
870
871 =back
872
873 For example, to select the minimum value in each axis:
874
875   my @axes = $font->mm_axes;
876   my @coords = map $_->[1], @axes;
877   $font->set_mm_coords(coords=>\@coords);
878
879 It's possible other drivers will support multiple master fonts in the
880 future, check if your selected font object supports the is_mm() method
881 using the can() method.
882
883 =head1 UTF-8
884
885 There are 2 ways of rendering Unicode characters with Imager:
886
887 =over
888
889 =item *
890
891 For versions of perl that support it, use perl's native UTF-8 strings.
892 This is the simplest method.
893
894 =item *
895
896 Hand build your own UTF-8 encoded strings.  Only recommended if your
897 version of perl has no UTF-8 support.
898
899 =back
900
901 Imager won't construct characters for you, so if want to output
902 Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
903 your font doesn't support it, Imager will I<not> build it from 0041
904 "LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
905
906 To check if a driver supports UTF-8 call the utf8() method:
907
908 =over
909
910 =item utf8()
911
912 Return true if the font supports UTF-8.
913
914 =back
915
916 =head2 Native UTF-8 Support
917
918 If your version of perl supports UTF-8 and the driver supports UTF-8,
919 just use the $im->string() method, and it should do the right thing.
920
921 =head2 Build your own
922
923 In this case you need to build your own UTF-8 encoded characters.
924
925 For example:
926
927  $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
928
929 You need to be be careful with versions of perl that have UTF-8
930 support, since your string may end up doubly UTF-8 encoded.
931
932 For example:
933
934  $x = "A\xE2\x80\x90\x41\x{2010}";
935  substr($x, -1, 0) = ""; 
936  # at this point $x is has the UTF-8 flag set, but has 5 characters,
937  # none, of which is the constructed UTF-8 character
938
939 The test script t/t38ft2font.t has a small example of this after the 
940 comment:
941
942   # an attempt using emulation of UTF-8
943
944 =head1 DRIVER CONTROL
945
946 If you don't supply a 'type' parameter to Imager::Font->new(), but you
947 do supply a 'file' parameter, Imager will attempt to guess which font
948 driver to used based on the extension of the font file.
949
950 Since some formats can be handled by more than one driver, a priority
951 list is used to choose which one should be used, if a given format can
952 be handled by more than one driver.
953
954 =over
955
956 =item priorities
957
958 The current priorities can be retrieved with:
959
960   @drivers = Imager::Font->priorities();
961
962 You can set new priorities and save the old priorities with:
963
964   @old = Imager::Font->priorities(@drivers);
965
966 =back
967
968 If you supply driver names that are not currently supported, they will
969 be ignored.
970
971 Imager supports both T1Lib and FreeType 2 for working with Type 1
972 fonts, but currently only T1Lib does any caching, so by default T1Lib
973 is given a higher priority.  Since Imager's FreeType 2 support can also
974 do font transformations, you may want to give that a higher priority:
975
976   my @old = Imager::Font->priorities(qw(tt ft2 t1));
977
978 =head1 AUTHOR
979
980 Arnar M. Hrafnkelsson, addi@umich.edu
981 And a great deal of help from others - see the F<README> for a complete
982 list.
983
984 =head1 BUGS
985
986 You need to modify this class to add new font types.
987
988 The $pos_width member returned by the bounding_box() method has
989 historically returned different values from different drivers.  The
990 FreeType 1.x and 2.x, and the Win32 drivers return the max of the
991 advance width and the right edge of the right-most glyph.  The Type 1
992 driver always returns the right edge of the right-most glyph.
993
994 The newer advance_width and right_bearing values allow access to any
995 of the above.
996
997 =head1 REVISION
998
999 $Revision$
1000
1001 =head1 SEE ALSO
1002
1003 Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
1004 Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
1005
1006  http://imager.perl.org/
1007
1008 =cut
1009
1010