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