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