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