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