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