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