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.034";
   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::Type1',
  25         module=>'Imager/Font/Type1.pm',
  26         files=>'.*\.pfb$',
  27         description => 'T1Lib',
  28         checktype => 1,
  29        },
  30    ft2=>{
  31          class=>'Imager::Font::FT2',
  32          module=>'Imager/Font/FT2.pm',
  33          files=>'.*\.(pfa|pfb|otf|ttf|fon|fnt|dfont|pcf(\.gz)?)$',
  34          description => 'FreeType 2.x',
  35         },
  36    ifs=>{
  37          class=>'Imager::Font::Image',
  38          module=>'Imager/Font/Image.pm',
  39          files=>'.*\.ifs$',
  40         },
  41    w32=>{
  42          class=>'Imager::Font::W32',
  43          module=>'Imager/Font/W32.pm',
  44          description => 'Win32 GDI Fonts',
  45         },
  46   );
  47
  48 # this currently should only contain file based types, don't add w32
  49 my @priority = qw(t1 tt ft2 ifs);
  50
  51 sub new {
  52   my $class = shift;
  53   my $self = {};
  54   my ($file, $type, $id);
  55   my %hsh=(color => Imager::Color->new(255,0,0,0),
  56            size => 15,
  57            @_);
  58
  59   bless $self,$class;
  60
  61   if ($hsh{'file'}) {
  62     $file = $hsh{'file'};
  63
  64     $type = $hsh{'type'};
  65     if (defined $type) {
  66       unless ($drivers{$type}) {
  67         Imager->_set_error("Unknown font type $type");
  68         return;
  69       }
  70
  71       unless ($Imager::formats{$type}) {
  72         Imager->_set_error("The $type {$drivers{$type}) font driver is not installed");
  73         return;
  74       }
  75     }
  76     else {
  77       for my $drv (@priority) {
  78         undef $type;
  79         my $re = $drivers{$drv}{files} or next;
  80         if ($file =~ /$re/i) {
  81           if (eval { require $drivers{$drv}{module}; 1 } and !( $drivers{$drv}{checktype} && !$Imager::formats{$drv} )) {
  82             $type = $drv;
  83             last;
  84           }
  85         }
  86       }
  87     }
  88     if (!defined($type)) {
  89       # some types we can support, but the driver isn't available
  90       # work out which drivers support it, so we can provide the user
  91       # some useful information on how to get it working
  92       my @not_here;
  93       for my $driver_name (keys %drivers) {
  94         my $driver = $drivers{$driver_name};
  95         push @not_here, "$driver_name ($driver->{description})"
  96           if $driver->{files} && $file =~ /$driver->{files}/i;
  97       }
  98       if (@not_here) {
  99         $Imager::ERRSTR = "No font drivers enabled that can support this file, rebuild Imager with any of ".join(", ", @not_here)." to use this font file";
 100       }
 101       else {
 102         $Imager::ERRSTR = "No font type found for $hsh{'file'}";
 103       }
 104       return;
 105     }
 106   } elsif ($hsh{face}) {
 107     $type = "w32";
 108   } else {
 109     $Imager::ERRSTR="No font file specified";
 110     return;
 111   }
 112
 113   if ($drivers{$type}{checktype} && !$Imager::formats{$type}) {
 114     $Imager::ERRSTR = "`$type' not enabled";
 115     return;
 116   }
 117
 118   # here we should have the font type or be dead already.
 119
 120   require $drivers{$type}{module};
 121   return $drivers{$type}{class}->new(%hsh);
 122 }
 123
 124 # returns first defined parameter
 125 sub _first {
 126   for (@_) {
 127     return $_ if defined $_;
 128   }
 129   return undef;
 130 }
 131
 132 sub draw {
 133   my $self = shift;
 134   my %input = ('x' => 0, 'y' => 0, @_);
 135   unless ($input{image}) {
 136     $Imager::ERRSTR = 'No image supplied to $font->draw()';
 137     return;
 138   }
 139   my $image = $input{image};
 140   $input{string} = _first($input{string}, $input{text});
 141   unless (defined $input{string}) {
 142     $image->_set_error("Missing required parameter 'string'");
 143     return;
 144   }
 145   $input{aa} = _first($input{aa}, $input{antialias}, $self->{aa}, 1);
 146   # the original draw code worked this out but didn't use it
 147   $input{align} = _first($input{align}, $self->{align});
 148   $input{color} = _first($input{color}, $self->{color});
 149   $input{color} = Imager::_color($input{'color'});
 150
 151   $input{size} = _first($input{size}, $self->{size});
 152   unless (defined $input{size}) {
 153     $image->_set_error("No font size provided");
 154     return undef;
 155   }
 156   $input{align} = _first($input{align}, 1);
 157   $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
 158   $input{vlayout} = _first($input{vlayout}, $self->{vlayout}, 0);
 159
 160   my $result = $self->_draw(%input);
 161   unless ($result) {
 162     $image->_set_error($image->_error_as_msg());
 163   }
 164
 165   return $result;
 166 }
 167
 168 sub align {
 169   my $self = shift;
 170   my %input = ( halign => 'left', valign => 'baseline',
 171                 'x' => 0, 'y' => 0, @_ );
 172
 173   # image needs to be supplied, but can be supplied as undef
 174   unless (exists $input{image}) {
 175     Imager->_set_error("Missing required parameter 'image'");
 176     return;
 177   }
 178
 179   my $errors_to = $input{image} || 'Imager';
 180
 181   my $text = _first($input{string}, $input{text});
 182   unless (defined $text) {
 183     $errors_to->_set_error("Missing required parameter 'string'");
 184     return;
 185   }
 186
 187   my $size = _first($input{size}, $self->{size});
 188   my $utf8 = _first($input{utf8}, 0);
 189
 190   my $bbox = $self->bounding_box(string=>$text, size=>$size, utf8=>$utf8);
 191   my $valign = $input{valign};
 192   $valign = 'baseline'
 193     unless $valign && $valign =~ /^(?:top|center|bottom|baseline)$/;
 194
 195   my $halign = $input{halign};
 196   $halign = 'start'
 197     unless $halign && $halign =~ /^(?:left|start|center|end|right)$/;
 198
 199   my $x = $input{'x'};
 200   my $y = $input{'y'};
 201
 202   if ($valign eq 'top') {
 203     $y += $bbox->ascent;
 204   }
 205   elsif ($valign eq 'center') {
 206     $y += $bbox->ascent - $bbox->text_height / 2;
 207   }
 208   elsif ($valign eq 'bottom') {
 209     $y += $bbox->descent;
 210   }
 211   # else baseline is the default
 212
 213   if ($halign eq 'left') {
 214     $x -= $bbox->start_offset;
 215   }
 216   elsif ($halign eq 'start') {
 217     # nothing to do
 218   }
 219   elsif ($halign eq 'center') {
 220     $x -= $bbox->start_offset + $bbox->total_width / 2;
 221   }
 222   elsif ($halign eq 'end') {
 223     $x -= $bbox->advance_width;
 224   }
 225   elsif ($halign eq 'right') {
 226     $x -= $bbox->advance_width - $bbox->right_bearing;
 227   }
 228   $x = int($x);
 229   $y = int($y);
 230
 231   if ($input{image}) {
 232     delete @input{qw/x y/};
 233     $self->draw(%input, 'x' => $x, 'y' => $y, align=>1)
 234       or return;
 235   }
 236
 237   return ($x+$bbox->start_offset, $y-$bbox->ascent,
 238           $x+$bbox->end_offset, $y-$bbox->descent+1);
 239 }
 240
 241 sub bounding_box {
 242   my $self=shift;
 243   my %input=@_;
 244
 245   if (!exists $input{'string'}) {
 246     $Imager::ERRSTR='string parameter missing';
 247     return;
 248   }
 249   $input{size} ||= $self->{size};
 250   $input{sizew} = _first($input{sizew}, $self->{sizew}, 0);
 251   $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
 252
 253   my @box = $self->_bounding_box(%input);
 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
 549
 550 =item bounding_box
 551
 552 Returns the bounding box for the specified string.  Example:
 553
 554   my ($neg_width,
 555       $global_descent,
 556       $pos_width,
 557       $global_ascent,
 558       $descent,
 559       $ascent,
 560       $advance_width,
 561       $right_bearing) = $font->bounding_box(string => "A Fool");
 562
 563   my $bbox_object = $font->bounding_box(string => "A Fool");
 564
 565 =over
 566
 567 =item C<$neg_width>
 568
 569 the relative start of a the string.  In some
 570 cases this can be a negative number, in that case the first letter
 571 stretches to the left of the starting position that is specified in
 572 the string method of the Imager class
 573
 574 =item C<$global_descent>
 575
 576 how far down the lowest letter of the entire font reaches below the
 577 baseline (this is often j).
 578
 579 =item C<$pos_width>
 580
 581 how wide the string from
 582 the starting position is.  The total width of the string is
 583 C<$pos_width-$neg_width>.
 584
 585 =item C<$descent>
 586
 587 =item C<$ascent>
 588
 589 the same as <$global_descent> and <$global_ascent> except that they
 590 are only for the characters that appear in the string.
 591
 592 =item C<$advance_width>
 593
 594 the distance from the start point that the next string output should
 595 start at, this is often the same as C<$pos_width>, but can be
 596 different if the final character overlaps the right side of its
 597 character cell.
 598
 599 =item C<$right_bearing>
 600
 601 The distance from the right side of the final glyph to the end of the
 602 advance width.  If the final glyph overflows the advance width this
 603 value is negative.
 604
 605 =back
 606
 607 Obviously we can stuff all the results into an array just as well:
 608
 609   @metrics = $font->bounding_box(string => "testing 123");
 610
 611 Note that extra values may be added, so $metrics[-1] isn't supported.
 612 It's possible to translate the output by a passing coordinate to the
 613 bounding box method:
 614
 615   @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
 616
 617 This gives the bounding box as if the string had been put down at C<(x,y)>
 618 By giving bounding_box 'canon' as a true value it's possible to measure
 619 the space needed for the string:
 620
 621   @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
 622
 623 This returns the same values in $metrics[0] and $metrics[1],
 624 but:
 625
 626  $bbox[2] - horizontal space taken by glyphs
 627  $bbox[3] - vertical space taken by glyphs
 628
 629 Returns an L<Imager::Font::BBox> object in scalar context, so you can
 630 avoid all those confusing indexes.  This has methods as named above,
 631 with some extra convenience methods.
 632
 633 Parameters are:
 634
 635 =over
 636
 637 =item *
 638
 639 C<string> - the string to calculate the bounding box for.  Required.
 640
 641 =item *
 642
 643 C<size> - the font size to use.  Default: value set in
 644 Imager::Font->new(), or 15.
 645
 646 =item *
 647
 648 C<sizew> - the font width to use.  Default to the value of the C<size>
 649 parameter.
 650
 651 =item *
 652
 653 C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
 654 For versions of perl that support Unicode (5.6 and later), this will
 655 be enabled automatically if the 'string' parameter is already a UTF-8
 656 string. See L<UTF-8> for more information.  Default: the C<utf8> value
 657 passed to Imager::Font->new(...) or 0.
 658
 659 =item *
 660
 661 C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
 662 box.  Ignored in scalar context.
 663
 664 =item *
 665
 666 C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
 667 then $pos_width and $global_ascent values will returned as the width
 668 and height of the text instead.
 669
 670 =back
 671
 672 =item string()
 673
 674 The $img->string(...) method is now documented in
 675 L<Imager::Draw/string>
 676
 677 =item align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)
 678
 679 Higher level text output - outputs the text aligned as specified
 680 around the given point (x,y).
 681
 682   # "Hello" centered at 100, 100 in the image.
 683   my ($left, $top, $right, $bottom) =
 684     $font->align(string=>"Hello",
 685                  x=>100, y=>100,
 686                  halign=>'center', valign=>'center',
 687                  image=>$image);
 688
 689 Takes the same parameters as $font->draw(), and the following extra
 690 parameters:
 691
 692 =over
 693
 694 =item *
 695
 696 C<valign> - Possible values are:
 697
 698 =over
 699
 700 =item C<top>
 701
 702 Point is at the top of the text.
 703
 704 =item C<bottom>
 705
 706 Point is at the bottom of the text.
 707
 708 =item C<baseline>
 709
 710 Point is on the baseline of the text (default.)
 711
 712 =item C<center>
 713
 714 Point is vertically centered within the text.
 715
 716 =back
 717
 718 =item *
 719
 720 C<halign>
 721
 722 =over
 723
 724 =item *
 725
 726 C<left> - the point is at the left of the text.
 727
 728 =item *
 729
 730 C<start> - the point is at the start point of the text.
 731
 732 =item *
 733
 734 C<center> - the point is horizontally centered within the text.
 735
 736 =item *
 737
 738 C<right> - the point is at the right end of the text.
 739
 740 =item *
 741
 742 C<end> - the point is at the end point of the text.
 743
 744 =back
 745
 746 =item *
 747
 748 C<image> - The image to draw to.  Set to C<undef> to avoid drawing but
 749 still calculate the bounding box.
 750
 751 =back
 752
 753 Returns a list specifying the bounds of the drawn text.
 754
 755 =item dpi()
 756
 757 =item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
 758
 759 =item dpi(dpi=>$dpi)
 760
 761 Set or retrieve the spatial resolution of the image in dots per inch.
 762 The default is 72 dpi.
 763
 764 This isn't implemented for all font types yet.
 765
 766 Possible parameters are:
 767
 768 =over
 769
 770 =item *
 771
 772 C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
 773 per inch.
 774
 775 =item *
 776
 777 C<dpi> - set both horizontal and vertical resolution to this value.
 778
 779 =back
 780
 781 Returns a list containing the previous C<xdpi>, C<ydpi> values.
 782
 783 =item 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 =item draw
 861
 862 This is used by Imager's string() method to implement drawing text.
 863 See L<Imager::Draw/string>.
 864
 865 =back
 866
 867 =head1 MULTIPLE MASTER FONTS
 868
 869 The FreeType 2 driver supports multiple master fonts:
 870
 871 =over
 872
 873 =item is_mm()
 874
 875 Test if the font is a multiple master font.
 876
 877 =item mm_axes()
 878
 879 Returns a list of the axes that can be changes in the font.  Each
 880 entry is an array reference which contains:
 881
 882 =over
 883
 884 =item 1.
 885
 886 Name of the axis.
 887
 888 =item 2.
 889
 890 minimum value for this axis.
 891
 892 =item 3.
 893
 894 maximum value for this axis
 895
 896 =back
 897
 898 =item set_mm_coords(coords=>\@values)
 899
 900 Blends an interpolated design from the master fonts.  @values must
 901 contain as many values as there are axes in the font.
 902
 903 =back
 904
 905 For example, to select the minimum value in each axis:
 906
 907   my @axes = $font->mm_axes;
 908   my @coords = map $_->[1], @axes;
 909   $font->set_mm_coords(coords=>\@coords);
 910
 911 It's possible other drivers will support multiple master fonts in the
 912 future, check if your selected font object supports the is_mm() method
 913 using the can() method.
 914
 915 =head1 UTF-8
 916
 917 There are 2 ways of rendering Unicode characters with Imager:
 918
 919 =over
 920
 921 =item *
 922
 923 For versions of perl that support it, use perl's native UTF-8 strings.
 924 This is the simplest method.
 925
 926 =item *
 927
 928 Hand build your own UTF-8 encoded strings.  Only recommended if your
 929 version of perl has no UTF-8 support.
 930
 931 =back
 932
 933 Imager won't construct characters for you, so if want to output
 934 Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
 935 your font doesn't support it, Imager will I<not> build it from 0041
 936 "LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
 937
 938 To check if a driver supports UTF-8 call the utf8() method:
 939
 940 =over
 941
 942 =item utf8()
 943
 944 Return true if the font supports UTF-8.
 945
 946 =back
 947
 948 =head2 Native UTF-8 Support
 949
 950 If your version of perl supports UTF-8 and the driver supports UTF-8,
 951 just use the $im->string() method, and it should do the right thing.
 952
 953 =head2 Build your own
 954
 955 In this case you need to build your own UTF-8 encoded characters.
 956
 957 For example:
 958
 959  $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
 960
 961 You need to be be careful with versions of perl that have UTF-8
 962 support, since your string may end up doubly UTF-8 encoded.
 963
 964 For example:
 965
 966  $x = "A\xE2\x80\x90\x41\x{2010}";
 967  substr($x, -1, 0) = "";
 968  # at this point $x is has the UTF-8 flag set, but has 5 characters,
 969  # none, of which is the constructed UTF-8 character
 970
 971 The test script t/t38ft2font.t has a small example of this after the
 972 comment:
 973
 974   # an attempt using emulation of UTF-8
 975
 976 =head1 DRIVER CONTROL
 977
 978 If you don't supply a 'type' parameter to Imager::Font->new(), but you
 979 do supply a 'file' parameter, Imager will attempt to guess which font
 980 driver to used based on the extension of the font file.
 981
 982 Since some formats can be handled by more than one driver, a priority
 983 list is used to choose which one should be used, if a given format can
 984 be handled by more than one driver.
 985
 986 =over
 987
 988 =item priorities
 989
 990 The current priorities can be retrieved with:
 991
 992   @drivers = Imager::Font->priorities();
 993
 994 You can set new priorities and save the old priorities with:
 995
 996   @old = Imager::Font->priorities(@drivers);
 997
 998 If you supply driver names that are not currently supported, they will
 999 be ignored.
1000
1001 Imager supports both T1Lib and FreeType 2 for working with Type 1
1002 fonts, but currently only T1Lib does any caching, so by default T1Lib
1003 is given a higher priority.  Since Imager's FreeType 2 support can also
1004 do font transformations, you may want to give that a higher priority:
1005
1006   my @old = Imager::Font->priorities(qw(tt ft2 t1));
1007
1008 =item register
1009
1010 Registers an extra font driver.  Accepts the following parameters:
1011
1012 =over
1013
1014 =item *
1015
1016 type - a brief identifier for the font driver.  You can supply this
1017 value to C<< Imager::Font->new() >> to create fonts of this type.
1018 Required.
1019
1020 =item *
1021
1022 class - the font class name.  Imager will attempted to load this
1023 module by name.  Required.
1024
1025 =item *
1026
1027 files - a regular expression to match against file names.  If supplied
1028 this must be a valid perl regular expression.  If not supplied you can
1029 only create fonts of this type by supplying the C<type> parameter to
1030 C<< Imager::Font->new() >>
1031
1032 =item *
1033
1034 description - a brief description of the font driver.  Defaults to the
1035 value supplied in C<class>.
1036
1037 =back
1038
1039 =back
1040
1041 =head1 AUTHOR
1042
1043 Arnar M. Hrafnkelsson, addi@umich.edu
1044 And a great deal of help from others - see the F<README> for a complete
1045 list.
1046
1047 =head1 BUGS
1048
1049 The $pos_width member returned by the bounding_box() method has
1050 historically returned different values from different drivers.  The
1051 FreeType 1.x and 2.x, and the Win32 drivers return the max of the
1052 advance width and the right edge of the right-most glyph.  The Type 1
1053 driver always returns the right edge of the right-most glyph.
1054
1055 The newer advance_width and right_bearing values allow access to any
1056 of the above.
1057
1058 =head1 REVISION
1059
1060 $Revision$
1061
1062 =head1 SEE ALSO
1063
1064 Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
1065 Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
1066
1067  http://imager.perl.org/
1068
1069 =cut
1070
1071