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