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