lib/Imager/Font.pm

   1 package Imager::Font;
   2
   3 use Imager::Color;
   4 use strict;
   5 use vars qw(%T1_Paths %TT_Paths %T1_Cache %TT_Cache $TT_CSize $TT_CSize $T1AA);
   6
   7 # This class is a container
   8 # and works for both truetype and t1 fonts.
   9
  10
  11 # $T1AA is in there because for some reason (probably cache related) antialiasing
  12 # is a system wide setting in t1 lib.
  13
  14 sub t1_set_aa_level {
  15   if (!defined $T1AA or $_[0] != $T1AA) {
  16     Imager::i_t1_set_aa($_[0]);
  17     $T1AA=$_[0];
  18   }
  19 }
  20
  21 # search method
  22 # 1. start by checking if file is the parameter
  23 # 1a. if so qualify path and compare to the cache.
  24 # 2a. if in cache - take it's id from there and increment count.
  25 #
  26
  27 sub new {
  28   my $class = shift;
  29   my $self ={};
  30   my ($file,$type,$id);
  31   my %hsh=(color=>Imager::Color->new(255,0,0,0),
  32            size=>15,
  33            @_);
  34
  35   bless $self,$class;
  36
  37   if ($hsh{'file'}) {
  38     $file=$hsh{'file'};
  39     if ( $file !~ m/^\// ) {
  40       $file='./'.$file;
  41       if (! -e $file) {
  42         $Imager::ERRSTR="Font $file not found";
  43         return();
  44       }
  45     }
  46
  47     $type=$hsh{'type'};
  48     if (!defined($type) or $type !~ m/^(t1|tt)/) {
  49       $type='tt' if $file =~ m/\.ttf$/i;
  50       $type='t1' if $file =~ m/\.pfb$/i;
  51     }
  52     if (!defined($type)) {
  53       $Imager::ERRSTR="Font type not found";
  54       return;
  55     }
  56   } else {
  57     $Imager::ERRSTR="No font file specified";
  58     return;
  59   }
  60
  61   if (!$Imager::formats{$type}) {
  62     $Imager::ERRSTR="`$type' not enabled";
  63     return;
  64   }
  65
  66   # here we should have the font type or be dead already.
  67
  68   if ($type eq 't1') {
  69     $id=Imager::i_t1_new($file);
  70   }
  71
  72   if ($type eq 'tt') {
  73     $id=Imager::i_tt_new($file);
  74   }
  75
  76   $self->{'aa'}=$hsh{'aa'}||'0';
  77   $self->{'file'}=$file;
  78   $self->{'id'}=$id;
  79   $self->{'type'}=$type;
  80   $self->{'size'}=$hsh{'size'};
  81   $self->{'color'}=$hsh{'color'};
  82   return $self;
  83 }
  84
  85
  86
  87
  88
  89
  90 sub bounding_box {
  91   my $self=shift;
  92   my %input=@_;
  93   my @box;
  94
  95   if (!exists $input{'string'}) { $Imager::ERRSTR='string parameter missing'; return; }
  96
  97   if ($self->{type} eq 't1') {
  98     @box=Imager::i_t1_bbox($self->{id}, defined($input{size}) ? $input{size} :$self->{size},
  99                            $input{string}, length($input{string}));
 100   }
 101   if ($self->{type} eq 'tt') {
 102     @box=Imager::i_tt_bbox($self->{id}, defined($input{size}) ? $input{size} :$self->{size},
 103                            $input{string}, length($input{string}));
 104   }
 105
 106   if(exists $input{'x'} and exists $input{'y'}) {
 107     my($gdescent, $gascent)=@box[1,3];
 108     $box[1]=$input{'y'}-$gascent;      # top = base - ascent (Y is down)
 109     $box[3]=$input{'y'}-$gdescent;     # bottom = base - descent (Y is down, descent is negative)
 110     $box[0]+=$input{'x'};
 111     $box[2]+=$input{'x'};
 112   } elsif (exists $input{'canon'}) {
 113     $box[3]-=$box[1];    # make it cannoical (ie (0,0) - (width, height))
 114     $box[2]-=$box[0];
 115   }
 116   return @box;
 117 }
 118
 119 1;
 120
 121
 122
 123 __END__
 124
 125 =head1 NAME
 126
 127 Imager::Font - Font handling for Imager.
 128
 129 =head1 SYNOPSIS
 130
 131   $t1font = Imager::Font->new(file => 'pathtofont.pfb');
 132   $ttfont = Imager::Font->new(file => 'pathtofont.ttf');
 133
 134   $blue = Imager::Color->new("#0000FF");
 135   $font = Imager::Font->new(file  => 'pathtofont.ttf',
 136                             color => $blue,
 137                             size  => 30);
 138
 139   ($neg_width,
 140    $global_descent,
 141    $pos_width,
 142    $global_ascent,
 143    $descent,
 144    $ascent) = $font->bounding_box(string=>"Foo");
 145
 146   $logo = $font->logo(text   => "Slartibartfast Enterprises",
 147                       size   => 40,
 148                       border => 5,
 149                       color  => $green);
 150   # logo is proposed - doesn't exist yet
 151
 152
 153   $img->string(font  => $font,
 154              text  => "Model-XYZ",
 155              x     => 15,
 156              y     => 40,
 157              size  => 40,
 158              color => $red
 159              aa    => 1);
 160
 161   # Documentation in Imager.pm
 162
 163 =head1 DESCRIPTION
 164
 165 This module handles creating Font objects used by imager.  The module
 166 also handles querying fonts for sizes and such.  If both T1lib and
 167 freetype were avaliable at the time of compilation then Imager should
 168 be able to work with both truetype fonts and t1 postscript fonts.  To
 169 check if Imager is t1 or truetype capable you can use something like
 170 this:
 171
 172   use Imager;
 173   print "Has truetype"      if $Imager::formats{tt};
 174   print "Has t1 postscript" if $Imager::formats{t1};
 175
 176
 177 =over 4
 178
 179 =item new
 180
 181 This creates a font object to pass to functions that take a font argument.
 182
 183   $font = Imager::Font->new(file  => 'denmark.ttf',
 184                             color => $blue,
 185                             size  => 30,
 186                             aa    => 1);
 187
 188 This creates a font which is the truetype font denmark.ttf.  It's
 189 default color is $blue, default size is 30 pixels and it's rendered
 190 antialised by default.  Imager can see which type of font a file is by
 191 looking at the suffix of the filename for the font.  A suffix of 'ttf'
 192 is taken to mean a truetype font while a suffix of 'pfb' is taken to
 193 mean a t1 postscript font.  If Imager cannot tell which type a font is
 194 you can tell it explicitly by using the C<type> parameter:
 195
 196   $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
 197   $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
 198
 199 If any of the C<color>, C<size> or C<aa> parameters are omitted when
 200 calling C<Imager::Font->new()> the they take the following values:
 201
 202
 203   color => Imager::Color->new(255, 0, 0, 0);  # this default should be changed
 204   size  => 15
 205   aa    => 0
 206
 207 =item bounding_box
 208 Returns the bounding box for the specified string.  Example:
 209
 210   ($neg_width,
 211    $global_descent,
 212    $pos_width,
 213    $global_ascent,
 214    $descent,
 215    $ascent) = $font->bounding_box(string => "A Fool");
 216
 217 The C<$neg_width> is the relative start of a the string.  In some
 218 cases this can be a negative number, in that case the first letter
 219 stretches to the left of the starting position that is specified in
 220 the string method of the Imager class.  <$global_descent> is the how
 221 far down the lowest letter of the entire font reaches below the
 222 baseline (this is often j).  C<$pos_width> is how wide the string from
 223 from the starting position is.  The total width of the string is
 224 C<$pos_width-$neg_width>.  C<$descent> and C<$ascent> are the as
 225 <$global_descent> and <$global_ascent> except that they are only for
 226 the characters that appear in the string.  Obviously we can stuff all
 227 the results into an array just as well:
 228
 229   @metrics = $font->bounding_box(string => "testing 123");
 230
 231 Note that extra values may be added, so $metrics[-1] isn't supported.
 232 It's possible to translate the output by a passing coordinate to the
 233 bounding box method:
 234
 235   @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
 236
 237 This gives the bounding box as if the string had been put down at C<(x,y)>
 238 By giving bounding_box 'canon' as a true value it's possible to measure
 239 the space needed for the string:
 240
 241   @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
 242
 243 This returns tha same values in $metrics[0] and $metrics[1],
 244 but:
 245
 246  $bbox[2] - horizontal space taken by glyphs
 247  $bbox[3] - vertical space taken by glyphs
 248
 249
 250
 251 =item string
 252
 253 This is a method of the Imager class but because it's described in
 254 here since it belongs to the font routines.  Example:
 255
 256   $img=Imager->new();
 257   $img=read(file=>"test.jpg");
 258   $img->string(font=>$t1font,
 259                text=>"Model-XYZ",
 260                x=>0,
 261                y=>40,
 262                size=>40,
 263                color=>$red);
 264   $img->write(file=>"testout.jpg");
 265
 266 This would put a 40 pixel high text in the top left corner of an
 267 image.  If you measure the actuall pixels it varies since the fonts
 268 usually do not use their full height.  It seems that the color and
 269 size can be specified twice.  When a font is created only the actual
 270 font specified matters.  It his however convenient to store default
 271 values in a font, such as color and size.  If parameters are passed to
 272 the string function they are used instead of the defaults stored in
 273 the font.
 274
 275 If string() is called with the C<channel> parameter then the color
 276 isn't used and the font is drawn in only one channel of the image.
 277 This can be quite handy to create overlays.  See the examples for tips
 278 about this.
 279
 280 Sometimes it is necessary to know how much space a string takes before
 281 rendering it.  The bounding_box() method described earlier can be used
 282 for that.
 283
 284
 285 =item logo
 286
 287 This method doesn't exist yet but is under consideration.  It would mostly
 288 be helpful for generating small tests and such.  Its proposed interface is:
 289
 290   $img = $font->logo(string=>"Plan XYZ", color=>$blue, border=>7);
 291
 292 This would be nice for writing (admittedly multiline) one liners like:
 293
 294 Imager::Font->new(file=>"arial.ttf", color=>$blue, aa=>1)
 295             ->string(text=>"Plan XYZ", border=>5)
 296             ->write(file=>"xyz.png");
 297
 298
 299
 300 =back
 301
 302 =head1 AUTHOR
 303
 304 Arnar M. Hrafnkelsson, addi@umich.edu
 305 And a great deal of help from others - see the README for a complete
 306 list.
 307
 308 =head1 SEE ALSO
 309
 310 Imager(3)
 311 http://www.eecs.umich.edu/~addi/perl/Imager/
 312
 313 =cut
 314
 315