lib/Imager/Font.pm

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