8ae571e5a7754a8b4570aaa17e2258d92ea3a19a
[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.033";
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 This module handles creating Font objects used by imager.  The module
375 also handles querying fonts for sizes and such.  If both T1lib and
376 freetype were avaliable at the time of compilation then Imager should
377 be able to work with both truetype fonts and t1 postscript fonts.  To
378 check if Imager is t1 or truetype capable you can use something like
379 this:
380
381   use Imager;
382   print "Has truetype"      if $Imager::formats{tt};
383   print "Has t1 postscript" if $Imager::formats{t1};
384   print "Has Win32 fonts"   if $Imager::formats{w32};
385   print "Has Freetype2"     if $Imager::formats{ft2};
386
387 =over 4
388
389 =item new
390
391 This creates a font object to pass to functions that take a font argument.
392
393   $font = Imager::Font->new(file  => 'denmark.ttf',
394                             index => 0,
395                             color => $blue,
396                             size  => 30,
397                             aa    => 1);
398
399 This creates a font which is the truetype font denmark.ttf.  It's
400 default color is $blue, default size is 30 pixels and it's rendered
401 antialised by default.  Imager can see which type of font a file is by
402 looking at the suffix of the filename for the font.  A suffix of 'ttf'
403 is taken to mean a truetype font while a suffix of 'pfb' is taken to
404 mean a t1 postscript font.  If Imager cannot tell which type a font is
405 you can tell it explicitly by using the C<type> parameter:
406
407   $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
408   $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
409
410 The C<index> parameter is used to select a single face from a font
411 file containing more than one face, for example, from a Macintosh font
412 suitcase or a .dfont file.
413
414 If any of the C<color>, C<size> or C<aa> parameters are omitted when
415 calling C<< Imager::Font->new() >> the they take the following values:
416
417   color => Imager::Color->new(255, 0, 0, 0);  # this default should be changed
418   size  => 15
419   aa    => 0
420   index => 0
421
422 To use Win32 fonts supply the facename of the font:
423
424   $font = Imager::Font->new(face=>'Arial Bold Italic');
425
426 There isn't any access to other logical font attributes, but this
427 typically isn't necessary for Win32 TrueType fonts, since you can
428 contruct the full name of the font as above.
429
430 Other logical font attributes may be added if there is sufficient demand.
431
432 Parameters:
433
434 =over
435
436 =item *
437
438 file - name of the file to load the font from.
439
440 =item *
441
442 face - face name.  This is used only under Win32 to create a GDI based
443 font.  This is ignored if the C<file> parameter is supplied.
444
445 =item *
446
447 type - font driver to use.  Currently the permitted values for this are:
448
449 =over
450
451 =item *
452
453 tt - Freetype 1.x driver.  Supports TTF fonts.
454
455 =item *
456
457 t1 - T1 Lib driver.  Supports Postscript Type 1 fonts.  Allows for
458 synthesis of underline, strikethrough and overline.
459
460 =item *
461
462 ft2 - Freetype 2.x driver.  Supports many different font formats.
463 Also supports the transform() method.
464
465 =back
466
467 =item *
468
469 color - the default color used with this font.  Default: red.
470
471 =item *
472
473 size - the default size used with this font.  Default: 15.
474
475 =item *
476
477 utf8 - if non-zero then text supplied to $img->string(...) and
478 $font->bounding_box(...) is assumed to be UTF 8 encoded by default.
479
480 =item *
481
482 align - the default value for the $img->string(...) C<align>
483 parameter.  Default: 1.
484
485 =item *
486
487 vlayout - the default value for the $img->string(...) C<vlayout>
488 parameter.  Default: 0.
489
490 =item *
491
492 aa - the default value for the $im->string(...) C<aa> parameter.
493 Default: 0.
494
495 =item *
496
497 index - for font file containing multiple fonts this selects which
498 font to use.  This is useful for Macintosh DFON (.dfont) and suitcase
499 font files.
500
501 If you want to use a suitcase font you will need to tell Imager to use
502 the FreeType 2.x driver by setting C<type> to C<'ft2'>:
503
504   my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
505     or die Imager->errstr;
506
507 =back
508
509
510
511 =item bounding_box
512
513 Returns the bounding box for the specified string.  Example:
514
515   my ($neg_width,
516       $global_descent,
517       $pos_width,
518       $global_ascent,
519       $descent,
520       $ascent,
521       $advance_width,
522       $right_bearing) = $font->bounding_box(string => "A Fool");
523
524   my $bbox_object = $font->bounding_box(string => "A Fool");
525
526 =over
527
528 =item C<$neg_width>
529
530 the relative start of a the string.  In some
531 cases this can be a negative number, in that case the first letter
532 stretches to the left of the starting position that is specified in
533 the string method of the Imager class
534
535 =item C<$global_descent> 
536
537 how far down the lowest letter of the entire font reaches below the
538 baseline (this is often j).
539
540 =item C<$pos_width>
541
542 how wide the string from
543 the starting position is.  The total width of the string is
544 C<$pos_width-$neg_width>.
545
546 =item C<$descent> 
547
548 =item C<$ascent> 
549
550 the same as <$global_descent> and <$global_ascent> except that they
551 are only for the characters that appear in the string.
552
553 =item C<$advance_width>
554
555 the distance from the start point that the next string output should
556 start at, this is often the same as C<$pos_width>, but can be
557 different if the final character overlaps the right side of its
558 character cell.
559
560 =item C<$right_bearing>
561
562 The distance from the right side of the final glyph to the end of the
563 advance width.  If the final glyph overflows the advance width this
564 value is negative.
565
566 =back
567
568 Obviously we can stuff all the results into an array just as well:
569
570   @metrics = $font->bounding_box(string => "testing 123");
571
572 Note that extra values may be added, so $metrics[-1] isn't supported.
573 It's possible to translate the output by a passing coordinate to the
574 bounding box method:
575
576   @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
577
578 This gives the bounding box as if the string had been put down at C<(x,y)>
579 By giving bounding_box 'canon' as a true value it's possible to measure
580 the space needed for the string:
581
582   @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
583
584 This returns tha same values in $metrics[0] and $metrics[1],
585 but:
586
587  $bbox[2] - horizontal space taken by glyphs
588  $bbox[3] - vertical space taken by glyphs
589
590 Returns an L<Imager::Font::BBox> object in scalar context, so you can
591 avoid all those confusing indices.  This has methods as named above,
592 with some extra convenience methods.
593
594 Parameters are:
595
596 =over
597
598 =item *
599
600 string - the string to calculate the bounding box for.  Required.
601
602 =item *
603
604 size - the font size to use.  Default: value set in
605 Imager::Font->new(), or 15.
606
607 =item *
608
609 sizew - the font width to use.  Default to the value of the C<size>
610 parameter.
611
612 =item *
613
614 utf8 - For drivers that support it, treat the string as UTF8 encoded.
615 For versions of perl that support Unicode (5.6 and later), this will
616 be enabled automatically if the 'string' parameter is already a UTF8
617 string. See L<UTF8> for more information.  Default: the C<utf8> value
618 passed to Imager::Font->new(...) or 0.
619
620 =item *
621
622 x, y - offsets applied to @box[0..3] to give you a adjusted bounding
623 box.  Ignored in scalar context.
624
625 =item *
626
627 canon - if non-zero and the C<x>, C<y> parameters are not supplied,
628 then $pos_width and $global_ascent values will returned as the width
629 and height of the text instead.
630
631 =back
632
633 =item string
634
635 The $img->string(...) method is now documented in
636 L<Imager::Draw/string>
637
638 =item align(string=>$text, size=>$size, x=>..., y=>..., valign => ..., halign=>...)
639
640 Higher level text output - outputs the text aligned as specified
641 around the given point (x,y).
642
643   # "Hello" centered at 100, 100 in the image.
644   my ($left, $top, $right, $bottom) = 
645     $font->align(string=>"Hello",
646                  x=>100, y=>100, 
647                  halign=>'center', valign=>'center', 
648                  image=>$image);
649
650 Takes the same parameters as $font->draw(), and the following extra
651 parameters:
652
653 =over
654
655 =item valign
656
657 Possible values are:
658
659 =over
660
661 =item top
662
663 Point is at the top of the text.
664
665 =item bottom
666
667 Point is at the bottom of the text.
668
669 =item baseline
670
671 Point is on the baseline of the text (default.)
672
673 =item center
674
675 Point is vertically centered within the text.
676
677 =back
678
679 =item halign
680
681 =over
682
683 =item left
684
685 The point is at the left of the text.
686
687 =item start
688
689 The point is at the start point of the text.
690
691 =item center
692
693 The point is horizontally centered within the text.
694
695 =item right
696
697 The point is at the right end of the text.
698
699 =item end
700
701 The point is at the end point of the text.
702
703 =back
704
705 =item image
706
707 The image to draw to.  Set to C<undef> to avoid drawing but still
708 calculate the bounding box.
709
710 =back
711
712 Returns a list specifying the bounds of the drawn text.
713
714 =item dpi()
715
716 =item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
717
718 =item dpi(dpi=>$dpi)
719
720 Set or retrieve the spatial resolution of the image in dots per inch.
721 The default is 72 dpi.
722
723 This isn't implemented for all font types yet.
724
725 Possible parameters are:
726
727 =over
728
729 =item *
730
731 xdpi, ydpi - set the horizontal and vertical resolution in dots per
732 inch.
733
734 =item *
735
736 dpi - set both horizontal and vertical resolution to this value.
737
738 =back
739
740 Returns a list containing the previous xdpi, ydpi values.
741
742 =item transform(matrix=>$matrix)
743
744 Applies a transformation to the font, where matrix is an array ref of
745 numbers representing a 2 x 3 matrix:
746
747   [  $matrix->[0],  $matrix->[1],  $matrix->[2],
748      $matrix->[3],  $matrix->[4],  $matrix->[5]   ]
749
750 Not all font types support transformations, these will return false.
751
752 It's possible that a driver will disable hinting if you use a
753 transformation, to prevent discontinuities in the transformations.
754 See the end of the test script t/t38ft2font.t for an example.
755
756 Currently only the ft2 (Freetype 2.x) driver supports the transform()
757 method.
758
759 See samples/slant_text.pl for a sample using this function.
760
761 Note that the transformation is done in font co-ordinates where y
762 increases as you move up, not image co-ordinates where y decreases as
763 you move up.
764
765 =item has_chars(string=>$text)
766
767 Checks if the characters in $text are defined by the font.
768
769 In a list context returns a list of true or false value corresponding
770 to the characters in $text, true if the character is defined, false if
771 not.  In scalar context returns a string of NUL or non-NUL
772 characters.  Supports UTF8 where the font driver supports UTF8.
773
774 Not all fonts support this method (use $font->can("has_chars") to
775 check.)
776
777 =over
778
779 =item *
780
781 string - string of characters to check for.  Required.  Must contain
782 at least one character.
783
784 =item *
785
786 utf8 - For drivers that support it, treat the string as UTF8 encoded.
787 For versions of perl that support Unicode (5.6 and later), this will
788 be enabled automatically if the 'string' parameter is already a UTF8
789 string. See L<UTF8> for more information.  Default: the C<utf8> value
790 passed to Imager::Font->new(...) or 0.
791
792 =back
793
794 =item face_name()
795
796 Returns the internal name of the face.  Not all font types support
797 this method yet.
798
799 =item glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
800
801 Returns a list of glyph names for each of the characters in the
802 string.  If the character has no name then C<undef> is returned for
803 the character.
804
805 Some font files do not include glyph names, in this case Freetype 2
806 will not return any names.  Freetype 1 can return standard names even
807 if there are no glyph names in the font.
808
809 Freetype 2 has an API function that returns true only if the font has
810 "reliable glyph names", unfortunately this always returns false for
811 TTF fonts.  This can avoid the check of this API by supplying
812 C<reliable_only> as 0.  The consequences of using this on an unknown
813 font may be unpredictable, since the Freetype documentation doesn't
814 say how those name tables are unreliable, or how FT2 handles them.
815
816 Both Freetype 1.x and 2.x allow support for glyph names to not be
817 included.
818
819 =item draw
820
821 This is used by Imager's string() method to implement drawing text.
822 See L<Imager::Draw/string>.
823
824 =back
825
826 =head1 MULTIPLE MASTER FONTS
827
828 The Freetype 2 driver supports multiple master fonts:
829
830 =over
831
832 =item is_mm()
833
834 Test if the font is a multiple master font.
835
836 =item mm_axes()
837
838 Returns a list of the axes that can be changes in the font.  Each
839 entry is an array reference which contains:
840
841 =over
842
843 =item 1.
844
845 Name of the axis.
846
847 =item 2.
848
849 minimum value for this axis.
850
851 =item 3.
852
853 maximum value for this axis
854
855 =back
856
857 =item set_mm_coords(coords=>\@values)
858
859 Blends an interpolated design from the master fonts.  @values must
860 contain as many values as there are axes in the font.
861
862 =back
863
864 For example, to select the minimum value in each axis:
865
866   my @axes = $font->mm_axes;
867   my @coords = map $_->[1], @axes;
868   $font->set_mm_coords(coords=>\@coords);
869
870 It's possible other drivers will support multiple master fonts in the
871 future, check if your selected font object supports the is_mm() method
872 using the can() method.
873
874 =head1 UTF8
875
876 There are 2 ways of rendering Unicode characters with Imager:
877
878 =over
879
880 =item *
881
882 For versions of perl that support it, use perl's native UTF8 strings.
883 This is the simplest method.
884
885 =item *
886
887 Hand build your own UTF8 encoded strings.  Only recommended if your
888 version of perl has no UTF8 support.
889
890 =back
891
892 Imager won't construct characters for you, so if want to output
893 unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
894 your font doesn't support it, Imager will I<not> build it from 0041
895 "LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
896
897 To check if a driver supports UTF8 call the utf8 method:
898
899 =over
900
901 =item utf8
902
903 Return true if the font supports UTF8.
904
905 =back
906
907 =head2 Native UTF8 Support
908
909 If your version of perl supports UTF8 and the driver supports UTF8,
910 just use the $im->string() method, and it should do the right thing.
911
912 =head2 Build your own
913
914 In this case you need to build your own UTF8 encoded characters.
915
916 For example:
917
918  $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
919
920 You need to be be careful with versions of perl that have UTF8
921 support, since your string may end up doubly UTF8 encoded.
922
923 For example:
924
925  $x = "A\xE2\x80\x90\x41\x{2010}";
926  substr($x, -1, 0) = ""; 
927  # at this point $x is has the UTF8 flag set, but has 5 characters,
928  # none, of which is the constructed UTF8 character
929
930 The test script t/t38ft2font.t has a small example of this after the 
931 comment:
932
933   # an attempt using emulation of UTF8
934
935 =head1 DRIVER CONTROL
936
937 If you don't supply a 'type' parameter to Imager::Font->new(), but you
938 do supply a 'file' parameter, Imager will attempt to guess which font
939 driver to used based on the extension of the font file.
940
941 Since some formats can be handled by more than one driver, a priority
942 list is used to choose which one should be used, if a given format can
943 be handled by more than one driver.
944
945 =over
946
947 =item priorities
948
949 The current priorities can be retrieved with:
950
951   @drivers = Imager::Font->priorities();
952
953 You can set new priorities and save the old priorities with:
954
955   @old = Imager::Font->priorities(@drivers);
956
957 =back
958
959 If you supply driver names that are not currently supported, they will
960 be ignored.
961
962 Imager supports both T1Lib and Freetype2 for working with Type 1
963 fonts, but currently only T1Lib does any caching, so by default T1Lib
964 is given a higher priority.  Since Imager's Freetype2 support can also
965 do font transformations, you may want to give that a higher priority:
966
967   my @old = Imager::Font->priorities(qw(tt ft2 t1));
968
969 =head1 AUTHOR
970
971 Arnar M. Hrafnkelsson, addi@umich.edu
972 And a great deal of help from others - see the README for a complete
973 list.
974
975 =head1 BUGS
976
977 You need to modify this class to add new font types.
978
979 The $pos_width member returned by the bounding_box() method has
980 historically returned different values from different drivers.  The
981 Freetype 1.x and 2.x, and the Win32 drivers return the max of the
982 advance width and the right edge of the right-most glyph.  The Type 1
983 driver always returns the right edge of the right-most glyph.
984
985 The newer advance_width and right_bearing values allow access to any
986 of the above.
987
988 =head1 REVISION
989
990 $Revision$
991
992 =head1 SEE ALSO
993
994 Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
995 Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
996
997  http://imager.perl.org/
998
999 =cut
1000
1001