lib/Imager/Font.pm

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