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.039";
   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(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 canonical (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 manages, the font object returned by Imager::Font->new
 409 will typically be of a class derived from Imager::Font.
 410
 411 =over 4
 412
 413 =item new
 414
 415 This creates a font object to pass to functions that take a font argument.
 416
 417   $font = Imager::Font->new(file  => 'denmark.ttf',
 418                             index => 0,
 419                             color => $blue,
 420                             size  => 30,
 421                             aa    => 1);
 422
 423 This creates a font which is the TrueType font F<denmark.ttf>.  It's
 424 default color is $blue, default size is 30 pixels and it's rendered
 425 anti-aliased by default.  Imager can see which type of font a file is
 426 by looking at the suffix of the file name for the font.  A suffix of
 427 C<ttf> is taken to mean a TrueType font while a suffix of C<pfb> is
 428 taken to mean a Type 1 Postscript font.  If Imager cannot tell which
 429 type a font is you can tell it explicitly by using the C<type>
 430 parameter:
 431
 432   $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
 433   $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
 434
 435 The C<index> parameter is used to select a single face from a font
 436 file containing more than one face, for example, from a Macintosh font
 437 suitcase or a C<.dfont> file.
 438
 439 If any of the C<color>, C<size> or C<aa> parameters are omitted when
 440 calling C<< Imager::Font->new() >> the they take the following values:
 441
 442   color => Imager::Color->new(255, 0, 0, 0);  # this default should be changed
 443   size  => 15
 444   aa    => 0
 445   index => 0
 446
 447 To use Win32 fonts supply the face name of the font:
 448
 449   $font = Imager::Font->new(face=>'Arial Bold Italic');
 450
 451 There isn't any access to other logical font attributes, but this
 452 typically isn't necessary for Win32 TrueType fonts, since you can
 453 construct the full name of the font as above.
 454
 455 Other logical font attributes may be added if there is sufficient demand.
 456
 457 Parameters:
 458
 459 =over
 460
 461 =item *
 462
 463 C<file> - name of the file to load the font from.
 464
 465 =item *
 466
 467 =for stopwords GDI
 468
 469 C<face> - face name.  This is used only under Win32 to create a GDI based
 470 font.  This is ignored if the C<file> parameter is supplied.
 471
 472 =item *
 473
 474 C<type> - font driver to use.  Currently the permitted values for this are:
 475
 476 =over
 477
 478 =item *
 479
 480 C<tt> - FreeType 1.x driver.  Supports TrueType (C<.ttf>) fonts.
 481
 482 =item *
 483
 484 =for stopwords strikethrough overline
 485
 486 C<t1> - T1 Lib driver.  Supports Postscript Type 1 fonts.  Allows for
 487 synthesis of underline, strikethrough and overline.
 488
 489 =item *
 490
 491 C<ft2> - FreeType 2.x driver.  Supports many different font formats.
 492 Also supports the transform() method.
 493
 494 =back
 495
 496 =item *
 497
 498 C<color> - the default color used with this font.  Default: red.
 499
 500 =item *
 501
 502 C<size> - the default size used with this font.  Default: 15.
 503
 504 =item *
 505
 506 C<utf8> - if non-zero then text supplied to $img->string(...) and
 507 $font->bounding_box(...) is assumed to be UTF-8 encoded by default.
 508
 509 =item *
 510
 511 C<align> - the default value for the $img->string(...) C<align>
 512 parameter.  Default: 1.
 513
 514 =item *
 515
 516 C<vlayout> - the default value for the $img->string(...) C<vlayout>
 517 parameter.  Default: 0.
 518
 519 =item *
 520
 521 C<aa> - the default value for the $im->string(...) C<aa> parameter.
 522 Default: 0.
 523
 524 =item *
 525
 526 C<index> - for font file containing multiple fonts this selects which
 527 font to use.  This is useful for Macintosh C<DFON> (F<.dfont>) and suitcase
 528 font files.
 529
 530 If you want to use a suitcase font you will need to tell Imager to use
 531 the FreeType 2.x driver by setting C<type> to C<'ft2'>:
 532
 533   my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
 534     or die Imager->errstr;
 535
 536 =back
 537
 538 Returns the new font object on success. Returns C<undef> on failure
 539 and sets an error message readable with C<< Imager->errstr >>.
 540
 541 =item bounding_box()
 542
 543 Returns the bounding box for the specified string.  Example:
 544
 545   my ($neg_width,
 546       $global_descent,
 547       $pos_width,
 548       $global_ascent,
 549       $descent,
 550       $ascent,
 551       $advance_width,
 552       $right_bearing) = $font->bounding_box(string => "A Fool");
 553
 554   my $bbox_object = $font->bounding_box(string => "A Fool");
 555
 556 =over
 557
 558 =item C<$neg_width>
 559
 560 the relative start of a the string.  In some
 561 cases this can be a negative number, in that case the first letter
 562 stretches to the left of the starting position that is specified in
 563 the string method of the Imager class
 564
 565 =item C<$global_descent>
 566
 567 how far down the lowest letter of the entire font reaches below the
 568 baseline (this is often j).
 569
 570 =item C<$pos_width>
 571
 572 how wide the string from
 573 the starting position is.  The total width of the string is
 574 C<$pos_width-$neg_width>.
 575
 576 =item C<$descent>
 577
 578 =item C<$ascent>
 579
 580 the same as <$global_descent> and <$global_ascent> except that they
 581 are only for the characters that appear in the string.
 582
 583 =item C<$advance_width>
 584
 585 the distance from the start point that the next string output should
 586 start at, this is often the same as C<$pos_width>, but can be
 587 different if the final character overlaps the right side of its
 588 character cell.
 589
 590 =item C<$right_bearing>
 591
 592 The distance from the right side of the final glyph to the end of the
 593 advance width.  If the final glyph overflows the advance width this
 594 value is negative.
 595
 596 =back
 597
 598 Obviously we can stuff all the results into an array just as well:
 599
 600   @metrics = $font->bounding_box(string => "testing 123");
 601
 602 Note that extra values may be added, so $metrics[-1] isn't supported.
 603 It's possible to translate the output by a passing coordinate to the
 604 bounding box method:
 605
 606   @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
 607
 608 This gives the bounding box as if the string had been put down at C<(x,y)>
 609 By giving bounding_box 'canon' as a true value it's possible to measure
 610 the space needed for the string:
 611
 612   @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
 613
 614 This returns the same values in $metrics[0] and $metrics[1],
 615 but:
 616
 617  $bbox[2] - horizontal space taken by glyphs
 618  $bbox[3] - vertical space taken by glyphs
 619
 620 Returns an L<Imager::Font::BBox> object in scalar context, so you can
 621 avoid all those confusing indexes.  This has methods as named above,
 622 with some extra convenience methods.
 623
 624 Parameters are:
 625
 626 =over
 627
 628 =item *
 629
 630 C<string> - the string to calculate the bounding box for.  Required.
 631
 632 =item *
 633
 634 C<size> - the font size to use.  Default: value set in
 635 Imager::Font->new(), or 15.
 636
 637 =item *
 638
 639 C<sizew> - the font width to use.  Default to the value of the C<size>
 640 parameter.
 641
 642 =item *
 643
 644 C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
 645 For versions of perl that support Unicode (5.6 and later), this will
 646 be enabled automatically if the 'string' parameter is already a UTF-8
 647 string. See L</UTF-8> for more information.  Default: the C<utf8> value
 648 passed to Imager::Font->new(...) or 0.
 649
 650 =item *
 651
 652 C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
 653 box.  Ignored in scalar context.
 654
 655 =item *
 656
 657 C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
 658 then $pos_width and $global_ascent values will returned as the width
 659 and height of the text instead.
 660
 661 =back
 662
 663 On success returns either the list of bounds, or a bounding box object
 664 in scalar context.  Returns an empty list or C<undef> on failure and
 665 sets an error message readable with C<< Imager->errstr >>.
 666
 667 The transformation matrix set by L</transform()> has no effect on the
 668 result of this method - the bounds of the untransformed text is
 669 returned.
 670
 671 =item string()
 672
 673 The $img->string(...) method is now documented in
 674 L<Imager::Draw/string()>
 675
 676 =item align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)
 677
 678 Higher level text output - outputs the text aligned as specified
 679 around the given point (x,y).
 680
 681   # "Hello" centered at 100, 100 in the image.
 682   my ($left, $top, $right, $bottom) =
 683     $font->align(string=>"Hello",
 684                  x=>100, y=>100,
 685                  halign=>'center', valign=>'center',
 686                  image=>$image);
 687
 688 Takes the same parameters as $font->draw(), and the following extra
 689 parameters:
 690
 691 =over
 692
 693 =item *
 694
 695 C<valign> - Possible values are:
 696
 697 =over
 698
 699 =item C<top>
 700
 701 Point is at the top of the text.
 702
 703 =item C<bottom>
 704
 705 Point is at the bottom of the text.
 706
 707 =item C<baseline>
 708
 709 Point is on the baseline of the text (default.)
 710
 711 =item C<center>
 712
 713 Point is vertically centered within the text.
 714
 715 =back
 716
 717 =item *
 718
 719 C<halign>
 720
 721 =over
 722
 723 =item *
 724
 725 C<left> - the point is at the left of the text.
 726
 727 =item *
 728
 729 C<start> - the point is at the start point of the text.
 730
 731 =item *
 732
 733 C<center> - the point is horizontally centered within the text.
 734
 735 =item *
 736
 737 C<right> - the point is at the right end of the text.
 738
 739 =item *
 740
 741 C<end> - the point is at the end point of the text.
 742
 743 =back
 744
 745 =item *
 746
 747 C<image> - The image to draw to.  Set to C<undef> to avoid drawing but
 748 still calculate the bounding box.
 749
 750 =back
 751
 752 Returns a list specifying the bounds of the drawn text on success.
 753 Returns an empty list on failure, if an C<image> parameter was
 754 supplied the error message can be read with C<< $image->errstr >>,
 755 otherwise it's available as C<< Imager->errstr >>.
 756
 757 =item dpi()
 758
 759 =item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
 760
 761 =item dpi(dpi=>$dpi)
 762
 763 Set or retrieve the spatial resolution of the image in dots per inch.
 764 The default is 72 dpi.
 765
 766 This isn't implemented for all font types yet.
 767
 768 Possible parameters are:
 769
 770 =over
 771
 772 =item *
 773
 774 C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
 775 per inch.
 776
 777 =item *
 778
 779 C<dpi> - set both horizontal and vertical resolution to this value.
 780
 781 =back
 782
 783 Returns a list containing the previous C<xdpi>, C<ydpi> values on
 784 success.  Returns an empty list on failure, with an error message
 785 returned in C<< Imager->errstr >>.
 786
 787 =item transform()
 788
 789   $font->transform(matrix=>$matrix);
 790
 791 Applies a transformation to the font, where matrix is an array ref of
 792 numbers representing a 2 x 3 matrix:
 793
 794   [  $matrix->[0],  $matrix->[1],  $matrix->[2],
 795      $matrix->[3],  $matrix->[4],  $matrix->[5]   ]
 796
 797 Not all font types support transformations, these will return false.
 798
 799 It's possible that a driver will disable hinting if you use a
 800 transformation, to prevent discontinuities in the transformations.
 801 See the end of the test script t/t38ft2font.t for an example.
 802
 803 Currently only the ft2 (FreeType 2.x) driver supports the transform()
 804 method.
 805
 806 See samples/slant_text.pl for a sample using this function.
 807
 808 Note that the transformation is done in font co-ordinates where y
 809 increases as you move up, not image co-ordinates where y decreases as
 810 you move up.
 811
 812 C<transform()> has no effect on the results of L</bounding_box()>.
 813
 814 Returns true on success.  Returns false on failure with the cause
 815 readable from C<< Imager->errstr >>.
 816
 817 =item has_chars(string=>$text)
 818
 819 Checks if the characters in $text are defined by the font.
 820
 821 In a list context returns a list of true or false value corresponding
 822 to the characters in $text, true if the character is defined, false if
 823 not.  In scalar context returns a string of C<NUL> or non-C<NUL>
 824 characters.  Supports UTF-8 where the font driver supports UTF-8.
 825
 826 Not all fonts support this method (use $font->can("has_chars") to
 827 check.)
 828
 829 On error, returns an empty list or undef in scalar context, and sets
 830 an error message readable with C<< Imager->errstr >>.
 831
 832 =over
 833
 834 =item *
 835
 836 C<string> - string of characters to check for.  Required.  Must contain
 837 at least one character.
 838
 839 =item *
 840
 841 C<utf8> - For drivers that support it, treat the string as UTF-8
 842 encoded.  For versions of perl that support Unicode (5.6 and later),
 843 this will be enabled automatically if the 'string' parameter is
 844 already a UTF-8 string. See L</UTF-8> for more information.  Default:
 845 the C<utf8> value passed to Imager::Font->new(...) or 0.
 846
 847 =back
 848
 849 =item face_name()
 850
 851 Returns the internal name of the face.  Not all font types support
 852 this method yet, so you should check with C<< $font->can("face_name")
 853 >> before calling C<face_name>.
 854
 855 =item glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
 856
 857 Returns a list of glyph names for each of the characters in the
 858 string.  If the character has no name then C<undef> is returned for
 859 the character.
 860
 861 Some font files do not include glyph names, in this case FreeType 2
 862 will not return any names.  FreeType 1 can return standard names even
 863 if there are no glyph names in the font.
 864
 865 FreeType 2 has an API function that returns true only if the font has
 866 "reliable glyph names", unfortunately this always returns false for
 867 TrueType fonts.  This can avoid the check of this API by supplying
 868 C<reliable_only> as 0.  The consequences of using this on an unknown
 869 font may be unpredictable, since the FreeType documentation doesn't
 870 say how those name tables are unreliable, or how FT2 handles them.
 871
 872 Both FreeType 1.x and 2.x allow support for glyph names to not be
 873 included.
 874
 875 If the supplied C<string> is marked as UTF-8 or the C<utf8> parameter
 876 is true and the supplied string does not contain valid UTF-8, returns
 877 an empty string and set an error message readable from C<<
 878 Imager->errstr >>,
 879
 880 =item can_glyph_names()
 881
 882 As a class method, returns true if the underlying library supports
 883 returning glyph names.
 884
 885 As an object method, returns true if the supplied font supports
 886 returning glyph names.
 887
 888 =item draw
 889
 890 This is used by Imager's string() method to implement drawing text.
 891 See L<Imager::Draw/string()>.
 892
 893 =back
 894
 895 =head1 MULTIPLE MASTER FONTS
 896
 897 The FreeType 2 driver supports multiple master fonts:
 898
 899 =over
 900
 901 =item is_mm()
 902
 903 Test if the font is a multiple master font.
 904
 905 =item mm_axes()
 906
 907 Returns a list of the axes that can be changes in the font.  Each
 908 entry is an array reference which contains:
 909
 910 =over
 911
 912 =item 1.
 913
 914 Name of the axis.
 915
 916 =item 2.
 917
 918 minimum value for this axis.
 919
 920 =item 3.
 921
 922 maximum value for this axis
 923
 924 =back
 925
 926 =item set_mm_coords(coords=>\@values)
 927
 928 Blends an interpolated design from the master fonts.  @values must
 929 contain as many values as there are axes in the font.
 930
 931 =back
 932
 933 For example, to select the minimum value in each axis:
 934
 935   my @axes = $font->mm_axes;
 936   my @coords = map $_->[1], @axes;
 937   $font->set_mm_coords(coords=>\@coords);
 938
 939 It's possible other drivers will support multiple master fonts in the
 940 future, check if your selected font object supports the is_mm() method
 941 using the can() method.
 942
 943 =head1 UTF-8
 944
 945 There are 2 ways of rendering Unicode characters with Imager:
 946
 947 =over
 948
 949 =item *
 950
 951 For versions of perl that support it, use perl's native UTF-8 strings.
 952 This is the simplest method.
 953
 954 =item *
 955
 956 Hand build your own UTF-8 encoded strings.  Only recommended if your
 957 version of perl has no UTF-8 support.
 958
 959 =back
 960
 961 Imager won't construct characters for you, so if want to output
 962 Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
 963 your font doesn't support it, Imager will I<not> build it from 0041
 964 "LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
 965
 966 To check if a driver supports UTF-8 call the utf8() method:
 967
 968 =over
 969
 970 =item utf8()
 971
 972 Return true if the font supports UTF-8.
 973
 974 =back
 975
 976 =head2 Native UTF-8 Support
 977
 978 If your version of perl supports UTF-8 and the driver supports UTF-8,
 979 just use the $im->string() method, and it should do the right thing.
 980
 981 =head2 Build your own
 982
 983 In this case you need to build your own UTF-8 encoded characters.
 984
 985 For example:
 986
 987  $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
 988
 989 You need to be careful with versions of perl that have UTF-8
 990 support, since your string may end up doubly UTF-8 encoded.
 991
 992 For example:
 993
 994  $x = "A\xE2\x80\x90\x41\x{2010}";
 995  substr($x, -1, 0) = "";
 996  # at this point $x is has the UTF-8 flag set, but has 5 characters,
 997  # none, of which is the constructed UTF-8 character
 998
 999 The test script t/t38ft2font.t has a small example of this after the
1000 comment:
1001
1002   # an attempt using emulation of UTF-8
1003
1004 =head1 DRIVER CONTROL
1005
1006 If you don't supply a 'type' parameter to Imager::Font->new(), but you
1007 do supply a 'file' parameter, Imager will attempt to guess which font
1008 driver to used based on the extension of the font file.
1009
1010 Since some formats can be handled by more than one driver, a priority
1011 list is used to choose which one should be used, if a given format can
1012 be handled by more than one driver.
1013
1014 =over
1015
1016 =item priorities
1017
1018 The current priorities can be retrieved with:
1019
1020   @drivers = Imager::Font->priorities();
1021
1022 You can set new priorities and save the old priorities with:
1023
1024   @old = Imager::Font->priorities(@drivers);
1025
1026 If you supply driver names that are not currently supported, they will
1027 be ignored.
1028
1029 Note that by default the priority list no longer includes C<tt> and
1030 C<t1>, so typically you will need to have L<Imager::Font::FT2>
1031 installed to create fonts with Imager.
1032
1033   my @old = Imager::Font->priorities(qw(tt ft2 t1));
1034
1035 =item register
1036
1037 Registers an extra font driver.  Accepts the following parameters:
1038
1039 =over
1040
1041 =item *
1042
1043 type - a brief identifier for the font driver.  You can supply this
1044 value to C<< Imager::Font->new() >> to create fonts of this type.
1045 Required.
1046
1047 =item *
1048
1049 class - the font class name.  Imager will attempted to load this
1050 module by name.  Required.
1051
1052 =item *
1053
1054 files - a regular expression to match against file names.  If supplied
1055 this must be a valid perl regular expression.  If not supplied you can
1056 only create fonts of this type by supplying the C<type> parameter to
1057 C<< Imager::Font->new() >>
1058
1059 =item *
1060
1061 description - a brief description of the font driver.  Defaults to the
1062 value supplied in C<class>.
1063
1064 =back
1065
1066 =back
1067
1068 =head1 AUTHOR
1069
1070 Arnar M. Hrafnkelsson, addi@umich.edu
1071 And a great deal of help from others - see the F<README> for a complete
1072 list.
1073
1074 =head1 BUGS
1075
1076 The $pos_width member returned by the bounding_box() method has
1077 historically returned different values from different drivers.  The
1078 FreeType 1.x and 2.x, and the Win32 drivers return the max of the
1079 advance width and the right edge of the right-most glyph.  The Type 1
1080 driver always returns the right edge of the right-most glyph.
1081
1082 The newer advance_width and right_bearing values allow access to any
1083 of the above.
1084
1085 =head1 REVISION
1086
1087 $Revision$
1088
1089 =head1 SEE ALSO
1090
1091 Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
1092 Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
1093
1094  http://imager.perl.org/
1095
1096 =cut
1097
1098