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