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