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.036";
   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 cannoical (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 =item bounding_box()
 549
 550 Returns the bounding box for the specified string.  Example:
 551
 552   my ($neg_width,
 553       $global_descent,
 554       $pos_width,
 555       $global_ascent,
 556       $descent,
 557       $ascent,
 558       $advance_width,
 559       $right_bearing) = $font->bounding_box(string => "A Fool");
 560
 561   my $bbox_object = $font->bounding_box(string => "A Fool");
 562
 563 =over
 564
 565 =item C<$neg_width>
 566
 567 the relative start of a the string.  In some
 568 cases this can be a negative number, in that case the first letter
 569 stretches to the left of the starting position that is specified in
 570 the string method of the Imager class
 571
 572 =item C<$global_descent>
 573
 574 how far down the lowest letter of the entire font reaches below the
 575 baseline (this is often j).
 576
 577 =item C<$pos_width>
 578
 579 how wide the string from
 580 the starting position is.  The total width of the string is
 581 C<$pos_width-$neg_width>.
 582
 583 =item C<$descent>
 584
 585 =item C<$ascent>
 586
 587 the same as <$global_descent> and <$global_ascent> except that they
 588 are only for the characters that appear in the string.
 589
 590 =item C<$advance_width>
 591
 592 the distance from the start point that the next string output should
 593 start at, this is often the same as C<$pos_width>, but can be
 594 different if the final character overlaps the right side of its
 595 character cell.
 596
 597 =item C<$right_bearing>
 598
 599 The distance from the right side of the final glyph to the end of the
 600 advance width.  If the final glyph overflows the advance width this
 601 value is negative.
 602
 603 =back
 604
 605 Obviously we can stuff all the results into an array just as well:
 606
 607   @metrics = $font->bounding_box(string => "testing 123");
 608
 609 Note that extra values may be added, so $metrics[-1] isn't supported.
 610 It's possible to translate the output by a passing coordinate to the
 611 bounding box method:
 612
 613   @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
 614
 615 This gives the bounding box as if the string had been put down at C<(x,y)>
 616 By giving bounding_box 'canon' as a true value it's possible to measure
 617 the space needed for the string:
 618
 619   @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
 620
 621 This returns the same values in $metrics[0] and $metrics[1],
 622 but:
 623
 624  $bbox[2] - horizontal space taken by glyphs
 625  $bbox[3] - vertical space taken by glyphs
 626
 627 Returns an L<Imager::Font::BBox> object in scalar context, so you can
 628 avoid all those confusing indexes.  This has methods as named above,
 629 with some extra convenience methods.
 630
 631 Parameters are:
 632
 633 =over
 634
 635 =item *
 636
 637 C<string> - the string to calculate the bounding box for.  Required.
 638
 639 =item *
 640
 641 C<size> - the font size to use.  Default: value set in
 642 Imager::Font->new(), or 15.
 643
 644 =item *
 645
 646 C<sizew> - the font width to use.  Default to the value of the C<size>
 647 parameter.
 648
 649 =item *
 650
 651 C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
 652 For versions of perl that support Unicode (5.6 and later), this will
 653 be enabled automatically if the 'string' parameter is already a UTF-8
 654 string. See L</UTF-8> for more information.  Default: the C<utf8> value
 655 passed to Imager::Font->new(...) or 0.
 656
 657 =item *
 658
 659 C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
 660 box.  Ignored in scalar context.
 661
 662 =item *
 663
 664 C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
 665 then $pos_width and $global_ascent values will returned as the width
 666 and height of the text instead.
 667
 668 =back
 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.
 752
 753 =item dpi()
 754
 755 =item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
 756
 757 =item dpi(dpi=>$dpi)
 758
 759 Set or retrieve the spatial resolution of the image in dots per inch.
 760 The default is 72 dpi.
 761
 762 This isn't implemented for all font types yet.
 763
 764 Possible parameters are:
 765
 766 =over
 767
 768 =item *
 769
 770 C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
 771 per inch.
 772
 773 =item *
 774
 775 C<dpi> - set both horizontal and vertical resolution to this value.
 776
 777 =back
 778
 779 Returns a list containing the previous C<xdpi>, C<ydpi> values.
 780
 781 =item transform()
 782
 783   $font->transform(matrix=>$matrix);
 784
 785 Applies a transformation to the font, where matrix is an array ref of
 786 numbers representing a 2 x 3 matrix:
 787
 788   [  $matrix->[0],  $matrix->[1],  $matrix->[2],
 789      $matrix->[3],  $matrix->[4],  $matrix->[5]   ]
 790
 791 Not all font types support transformations, these will return false.
 792
 793 It's possible that a driver will disable hinting if you use a
 794 transformation, to prevent discontinuities in the transformations.
 795 See the end of the test script t/t38ft2font.t for an example.
 796
 797 Currently only the ft2 (FreeType 2.x) driver supports the transform()
 798 method.
 799
 800 See samples/slant_text.pl for a sample using this function.
 801
 802 Note that the transformation is done in font co-ordinates where y
 803 increases as you move up, not image co-ordinates where y decreases as
 804 you move up.
 805
 806 =item has_chars(string=>$text)
 807
 808 Checks if the characters in $text are defined by the font.
 809
 810 In a list context returns a list of true or false value corresponding
 811 to the characters in $text, true if the character is defined, false if
 812 not.  In scalar context returns a string of C<NUL> or non-C<NUL>
 813 characters.  Supports UTF-8 where the font driver supports UTF-8.
 814
 815 Not all fonts support this method (use $font->can("has_chars") to
 816 check.)
 817
 818 =over
 819
 820 =item *
 821
 822 C<string> - string of characters to check for.  Required.  Must contain
 823 at least one character.
 824
 825 =item *
 826
 827 C<utf8> - For drivers that support it, treat the string as UTF-8
 828 encoded.  For versions of perl that support Unicode (5.6 and later),
 829 this will be enabled automatically if the 'string' parameter is
 830 already a UTF-8 string. See L</UTF-8> for more information.  Default:
 831 the C<utf8> value passed to Imager::Font->new(...) or 0.
 832
 833 =back
 834
 835 =item face_name()
 836
 837 Returns the internal name of the face.  Not all font types support
 838 this method yet.
 839
 840 =item glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
 841
 842 Returns a list of glyph names for each of the characters in the
 843 string.  If the character has no name then C<undef> is returned for
 844 the character.
 845
 846 Some font files do not include glyph names, in this case FreeType 2
 847 will not return any names.  FreeType 1 can return standard names even
 848 if there are no glyph names in the font.
 849
 850 FreeType 2 has an API function that returns true only if the font has
 851 "reliable glyph names", unfortunately this always returns false for
 852 TrueType fonts.  This can avoid the check of this API by supplying
 853 C<reliable_only> as 0.  The consequences of using this on an unknown
 854 font may be unpredictable, since the FreeType documentation doesn't
 855 say how those name tables are unreliable, or how FT2 handles them.
 856
 857 Both FreeType 1.x and 2.x allow support for glyph names to not be
 858 included.
 859
 860 If the supplied C<string> is marked as UTF-8 or the C<utf8> parameter
 861 is true and the supplied string does not contain valid UTF-8, returns
 862 an empty string and set an error message readable from C<<
 863 Imager->errstr >>,
 864
 865 =item can_glyph_names()
 866
 867 As a class method, returns true if the underlying library supports
 868 returning glyph names.
 869
 870 As an object method, returns true if the supplied font supports
 871 returning glyph names.
 872
 873 =item draw
 874
 875 This is used by Imager's string() method to implement drawing text.
 876 See L<Imager::Draw/string()>.
 877
 878 =back
 879
 880 =head1 MULTIPLE MASTER FONTS
 881
 882 The FreeType 2 driver supports multiple master fonts:
 883
 884 =over
 885
 886 =item is_mm()
 887
 888 Test if the font is a multiple master font.
 889
 890 =item mm_axes()
 891
 892 Returns a list of the axes that can be changes in the font.  Each
 893 entry is an array reference which contains:
 894
 895 =over
 896
 897 =item 1.
 898
 899 Name of the axis.
 900
 901 =item 2.
 902
 903 minimum value for this axis.
 904
 905 =item 3.
 906
 907 maximum value for this axis
 908
 909 =back
 910
 911 =item set_mm_coords(coords=>\@values)
 912
 913 Blends an interpolated design from the master fonts.  @values must
 914 contain as many values as there are axes in the font.
 915
 916 =back
 917
 918 For example, to select the minimum value in each axis:
 919
 920   my @axes = $font->mm_axes;
 921   my @coords = map $_->[1], @axes;
 922   $font->set_mm_coords(coords=>\@coords);
 923
 924 It's possible other drivers will support multiple master fonts in the
 925 future, check if your selected font object supports the is_mm() method
 926 using the can() method.
 927
 928 =head1 UTF-8
 929
 930 There are 2 ways of rendering Unicode characters with Imager:
 931
 932 =over
 933
 934 =item *
 935
 936 For versions of perl that support it, use perl's native UTF-8 strings.
 937 This is the simplest method.
 938
 939 =item *
 940
 941 Hand build your own UTF-8 encoded strings.  Only recommended if your
 942 version of perl has no UTF-8 support.
 943
 944 =back
 945
 946 Imager won't construct characters for you, so if want to output
 947 Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
 948 your font doesn't support it, Imager will I<not> build it from 0041
 949 "LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
 950
 951 To check if a driver supports UTF-8 call the utf8() method:
 952
 953 =over
 954
 955 =item utf8()
 956
 957 Return true if the font supports UTF-8.
 958
 959 =back
 960
 961 =head2 Native UTF-8 Support
 962
 963 If your version of perl supports UTF-8 and the driver supports UTF-8,
 964 just use the $im->string() method, and it should do the right thing.
 965
 966 =head2 Build your own
 967
 968 In this case you need to build your own UTF-8 encoded characters.
 969
 970 For example:
 971
 972  $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
 973
 974 You need to be be careful with versions of perl that have UTF-8
 975 support, since your string may end up doubly UTF-8 encoded.
 976
 977 For example:
 978
 979  $x = "A\xE2\x80\x90\x41\x{2010}";
 980  substr($x, -1, 0) = "";
 981  # at this point $x is has the UTF-8 flag set, but has 5 characters,
 982  # none, of which is the constructed UTF-8 character
 983
 984 The test script t/t38ft2font.t has a small example of this after the
 985 comment:
 986
 987   # an attempt using emulation of UTF-8
 988
 989 =head1 DRIVER CONTROL
 990
 991 If you don't supply a 'type' parameter to Imager::Font->new(), but you
 992 do supply a 'file' parameter, Imager will attempt to guess which font
 993 driver to used based on the extension of the font file.
 994
 995 Since some formats can be handled by more than one driver, a priority
 996 list is used to choose which one should be used, if a given format can
 997 be handled by more than one driver.
 998
 999 =over
1000
1001 =item priorities
1002
1003 The current priorities can be retrieved with:
1004
1005   @drivers = Imager::Font->priorities();
1006
1007 You can set new priorities and save the old priorities with:
1008
1009   @old = Imager::Font->priorities(@drivers);
1010
1011 If you supply driver names that are not currently supported, they will
1012 be ignored.
1013
1014 Imager supports both T1Lib and FreeType 2 for working with Type 1
1015 fonts, but currently only T1Lib does any caching, so by default T1Lib
1016 is given a higher priority.  Since Imager's FreeType 2 support can also
1017 do font transformations, you may want to give that a higher priority:
1018
1019   my @old = Imager::Font->priorities(qw(tt ft2 t1));
1020
1021 =item register
1022
1023 Registers an extra font driver.  Accepts the following parameters:
1024
1025 =over
1026
1027 =item *
1028
1029 type - a brief identifier for the font driver.  You can supply this
1030 value to C<< Imager::Font->new() >> to create fonts of this type.
1031 Required.
1032
1033 =item *
1034
1035 class - the font class name.  Imager will attempted to load this
1036 module by name.  Required.
1037
1038 =item *
1039
1040 files - a regular expression to match against file names.  If supplied
1041 this must be a valid perl regular expression.  If not supplied you can
1042 only create fonts of this type by supplying the C<type> parameter to
1043 C<< Imager::Font->new() >>
1044
1045 =item *
1046
1047 description - a brief description of the font driver.  Defaults to the
1048 value supplied in C<class>.
1049
1050 =back
1051
1052 =back
1053
1054 =head1 AUTHOR
1055
1056 Arnar M. Hrafnkelsson, addi@umich.edu
1057 And a great deal of help from others - see the F<README> for a complete
1058 list.
1059
1060 =head1 BUGS
1061
1062 The $pos_width member returned by the bounding_box() method has
1063 historically returned different values from different drivers.  The
1064 FreeType 1.x and 2.x, and the Win32 drivers return the max of the
1065 advance width and the right edge of the right-most glyph.  The Type 1
1066 driver always returns the right edge of the right-most glyph.
1067
1068 The newer advance_width and right_bearing values allow access to any
1069 of the above.
1070
1071 =head1 REVISION
1072
1073 $Revision$
1074
1075 =head1 SEE ALSO
1076
1077 Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
1078 Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
1079
1080  http://imager.perl.org/
1081
1082 =cut
1083
1084