eliminate use vars
[imager.git] / lib / Imager / Font.pm
CommitLineData
02d1d628 1package Imager::Font;
ee64a81f 2use 5.006;
02d1d628
AMH
3use Imager::Color;
4use strict;
f17b46d8 5
ee64a81f 6our $VERSION = "1.039";
02d1d628 7
faa9b3e7
TC
8# the aim here is that we can:
9# - add file based types in one place: here
10# - make sure we only attempt to create types that exist
11# - give reasonable defaults
12# - give the user some control over which types get used
13my %drivers =
14 (
15 tt=>{
16 class=>'Imager::Font::Truetype',
17 module=>'Imager/Font/Truetype.pm',
18 files=>'.*\.ttf$',
0561d49c 19 description => 'FreeType 1.x',
9413a3f3 20 checktype => 1,
faa9b3e7
TC
21 },
22 t1=>{
a556912d
TC
23 class=>'Imager::Font::T1',
24 module=>'Imager/Font/T1.pm',
faa9b3e7 25 files=>'.*\.pfb$',
0561d49c 26 description => 'T1Lib',
faa9b3e7
TC
27 },
28 ft2=>{
50c75381
TC
29 class=>'Imager::Font::FT2',
30 module=>'Imager/Font/FT2.pm',
cb024708 31 files=>'.*\.(pfa|pfb|otf|ttf|fon|fnt|dfont|pcf(\.gz)?)$',
0561d49c 32 description => 'FreeType 2.x',
faa9b3e7 33 },
b4d8a00b
AMH
34 ifs=>{
35 class=>'Imager::Font::Image',
36 module=>'Imager/Font/Image.pm',
37 files=>'.*\.ifs$',
38 },
faa9b3e7 39 w32=>{
2e3464cd
TC
40 class=>'Imager::Font::W32',
41 module=>'Imager/Font/W32.pm',
0561d49c 42 description => 'Win32 GDI Fonts',
faa9b3e7
TC
43 },
44 );
45
46# this currently should only contain file based types, don't add w32
ef1a1df1 47my @priority = qw(ft2 ifs);
faa9b3e7 48
02d1d628
AMH
49sub new {
50 my $class = shift;
b4d8a00b
AMH
51 my $self = {};
52 my ($file, $type, $id);
61e5a61a 53 my %hsh=(color => Imager::Color->new(255,0,0,255),
b4d8a00b 54 size => 15,
02d1d628
AMH
55 @_);
56
57 bless $self,$class;
58
b4d8a00b
AMH
59 if ($hsh{'file'}) {
60 $file = $hsh{'file'};
02d1d628 61
b4d8a00b 62 $type = $hsh{'type'};
50c75381
TC
63 if (defined $type) {
64 unless ($drivers{$type}) {
65 Imager->_set_error("Unknown font type $type");
66 return;
67 }
68
69 unless ($Imager::formats{$type}) {
70 Imager->_set_error("The $type {$drivers{$type}) font driver is not installed");
71 return;
72 }
73 }
74 else {
faa9b3e7
TC
75 for my $drv (@priority) {
76 undef $type;
77 my $re = $drivers{$drv}{files} or next;
78 if ($file =~ /$re/i) {
529cba64 79 if (eval { require $drivers{$drv}{module}; 1 } and !( $drivers{$drv}{checktype} && !$Imager::formats{$drv} )) {
9413a3f3
TC
80 $type = $drv;
81 last;
82 }
faa9b3e7
TC
83 }
84 }
02d1d628
AMH
85 }
86 if (!defined($type)) {
0561d49c
TC
87 # some types we can support, but the driver isn't available
88 # work out which drivers support it, so we can provide the user
89 # some useful information on how to get it working
90 my @not_here;
91 for my $driver_name (keys %drivers) {
92 my $driver = $drivers{$driver_name};
93 push @not_here, "$driver_name ($driver->{description})"
94 if $driver->{files} && $file =~ /$driver->{files}/i;
95 }
96 if (@not_here) {
97 $Imager::ERRSTR = "No font drivers enabled that can support this file, rebuild Imager with any of ".join(", ", @not_here)." to use this font file";
98 }
99 else {
100 $Imager::ERRSTR = "No font type found for $hsh{'file'}";
101 }
02d1d628
AMH
102 return;
103 }
faa9b3e7
TC
104 } elsif ($hsh{face}) {
105 $type = "w32";
02d1d628
AMH
106 } else {
107 $Imager::ERRSTR="No font file specified";
108 return;
109 }
110
9413a3f3 111 if ($drivers{$type}{checktype} && !$Imager::formats{$type}) {
b4d8a00b 112 $Imager::ERRSTR = "`$type' not enabled";
02d1d628
AMH
113 return;
114 }
115
116 # here we should have the font type or be dead already.
117
faa9b3e7
TC
118 require $drivers{$type}{module};
119 return $drivers{$type}{class}->new(%hsh);
02d1d628
AMH
120}
121
96190b6e
TC
122# returns first defined parameter
123sub _first {
124 for (@_) {
125 return $_ if defined $_;
126 }
127 return undef;
128}
02d1d628 129
96190b6e
TC
130sub draw {
131 my $self = shift;
9d540150 132 my %input = ('x' => 0, 'y' => 0, @_);
96190b6e
TC
133 unless ($input{image}) {
134 $Imager::ERRSTR = 'No image supplied to $font->draw()';
135 return;
136 }
47d51ac6 137 my $image = $input{image};
96190b6e
TC
138 $input{string} = _first($input{string}, $input{text});
139 unless (defined $input{string}) {
47d51ac6 140 $image->_set_error("Missing required parameter 'string'");
96190b6e
TC
141 return;
142 }
143 $input{aa} = _first($input{aa}, $input{antialias}, $self->{aa}, 1);
144 # the original draw code worked this out but didn't use it
145 $input{align} = _first($input{align}, $self->{align});
146 $input{color} = _first($input{color}, $self->{color});
3799c4d1
TC
147 $input{color} = Imager::_color($input{'color'});
148
96190b6e
TC
149 $input{size} = _first($input{size}, $self->{size});
150 unless (defined $input{size}) {
47d51ac6 151 $image->_set_error("No font size provided");
96190b6e
TC
152 return undef;
153 }
154 $input{align} = _first($input{align}, 1);
faa9b3e7
TC
155 $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
156 $input{vlayout} = _first($input{vlayout}, $self->{vlayout}, 0);
157
47d51ac6
TC
158 my $result = $self->_draw(%input);
159 unless ($result) {
160 $image->_set_error($image->_error_as_msg());
161 }
162
163 return $result;
96190b6e 164}
02d1d628 165
3799c4d1
TC
166sub align {
167 my $self = shift;
168 my %input = ( halign => 'left', valign => 'baseline',
169 'x' => 0, 'y' => 0, @_ );
170
3799c4d1
TC
171 # image needs to be supplied, but can be supplied as undef
172 unless (exists $input{image}) {
173 Imager->_set_error("Missing required parameter 'image'");
174 return;
175 }
47d51ac6
TC
176
177 my $errors_to = $input{image} || 'Imager';
178
179 my $text = _first($input{string}, $input{text});
180 unless (defined $text) {
181 $errors_to->_set_error("Missing required parameter 'string'");
182 return;
183 }
184
3799c4d1
TC
185 my $size = _first($input{size}, $self->{size});
186 my $utf8 = _first($input{utf8}, 0);
b4d8a00b 187
3799c4d1
TC
188 my $bbox = $self->bounding_box(string=>$text, size=>$size, utf8=>$utf8);
189 my $valign = $input{valign};
190 $valign = 'baseline'
191 unless $valign && $valign =~ /^(?:top|center|bottom|baseline)$/;
b4d8a00b 192
3799c4d1
TC
193 my $halign = $input{halign};
194 $halign = 'start'
195 unless $halign && $halign =~ /^(?:left|start|center|end|right)$/;
196
197 my $x = $input{'x'};
198 my $y = $input{'y'};
b4d8a00b 199
3799c4d1
TC
200 if ($valign eq 'top') {
201 $y += $bbox->ascent;
202 }
203 elsif ($valign eq 'center') {
204 $y += $bbox->ascent - $bbox->text_height / 2;
205 }
206 elsif ($valign eq 'bottom') {
207 $y += $bbox->descent;
208 }
209 # else baseline is the default
210
211 if ($halign eq 'left') {
212 $x -= $bbox->start_offset;
213 }
214 elsif ($halign eq 'start') {
215 # nothing to do
216 }
217 elsif ($halign eq 'center') {
218 $x -= $bbox->start_offset + $bbox->total_width / 2;
219 }
a7ccc5e2
TC
220 elsif ($halign eq 'end') {
221 $x -= $bbox->advance_width;
222 }
223 elsif ($halign eq 'right') {
224 $x -= $bbox->advance_width - $bbox->right_bearing;
3799c4d1
TC
225 }
226 $x = int($x);
227 $y = int($y);
228
229 if ($input{image}) {
230 delete @input{qw/x y/};
231 $self->draw(%input, 'x' => $x, 'y' => $y, align=>1)
232 or return;
3799c4d1
TC
233 }
234
235 return ($x+$bbox->start_offset, $y-$bbox->ascent,
236 $x+$bbox->end_offset, $y-$bbox->descent+1);
237}
238
02d1d628
AMH
239sub bounding_box {
240 my $self=shift;
241 my %input=@_;
02d1d628 242
96190b6e
TC
243 if (!exists $input{'string'}) {
244 $Imager::ERRSTR='string parameter missing';
245 return;
02d1d628 246 }
96190b6e 247 $input{size} ||= $self->{size};
90654457 248 $input{sizew} = _first($input{sizew}, $self->{sizew}, 0);
fec2a434 249 $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
96190b6e 250
19e0b86f
TC
251 my @box = $self->_bounding_box(%input)
252 or return;
02d1d628 253
3799c4d1
TC
254 if (wantarray) {
255 if(@box && exists $input{'x'} and exists $input{'y'}) {
256 my($gdescent, $gascent)=@box[1,3];
257 $box[1]=$input{'y'}-$gascent; # top = base - ascent (Y is down)
258 $box[3]=$input{'y'}-$gdescent; # bottom = base - descent (Y is down, descent is negative)
259 $box[0]+=$input{'x'};
260 $box[2]+=$input{'x'};
261 } elsif (@box && $input{'canon'}) {
5237562b 262 $box[3]-=$box[1]; # make it canonical (ie (0,0) - (width, height))
3799c4d1
TC
263 $box[2]-=$box[0];
264 }
265 return @box;
266 }
267 else {
268 require Imager::Font::BBox;
269
270 return Imager::Font::BBox->new(@box);
02d1d628 271 }
02d1d628
AMH
272}
273
faa9b3e7
TC
274sub dpi {
275 my $self = shift;
276
277 # I'm assuming a default of 72 dpi
278 my @old = (72, 72);
279 if (@_) {
280 $Imager::ERRSTR = "Setting dpi not implemented for this font type";
281 return;
282 }
283
284 return @old;
285}
286
287sub transform {
288 my $self = shift;
289
290 my %hsh = @_;
291
292 # this is split into transform() and _transform() so we can
293 # implement other tags like: degrees=>12, which would build a
294 # 12 degree rotation matrix
295 # but I'll do that later
296 unless ($hsh{matrix}) {
297 $Imager::ERRSTR = "You need to supply a matrix";
298 return;
299 }
b4d8a00b 300
faa9b3e7
TC
301 return $self->_transform(%hsh);
302}
303
304sub _transform {
305 $Imager::ERRSTR = "This type of font cannot be transformed";
306 return;
307}
308
309sub utf8 {
310 return 0;
311}
312
313sub priorities {
314 my $self = shift;
315 my @old = @priority;
316
317 if (@_) {
9413a3f3 318 @priority = @_;
faa9b3e7
TC
319 }
320 return @old;
321}
322
9413a3f3
TC
323sub register {
324 my ($self, %opts) = @_;
325
326 my $type = delete $opts{type};
327 my $class = delete $opts{class};
328 my $files = delete $opts{files};
329 my $description = delete $opts{description} || $class;
330
331 defined $type
332 or return Imager->_set_error("No type parameter supplied to Imager::Font->regster");
333
334 defined $class
335 or return Imager->_set_error("No class parameter supplied to Imager::Font->register");
336
337 if ($files) {
338 eval { qr/$files/ }
339 or return Imager->_set_error("files isn't a valid regexp");
340 }
341
342 if ($drivers{$type} && $drivers{$type}{class} ne $class) {
343 Imager->_set_error("Font type $type already registered as $drivers{$type}{class}");
344 return;
345 }
346
347 (my $module = $class . ".pm") =~ s(::)(/)g;
348
349 my $driver =
350 {
351 class => $class,
352 module => $module,
353 description => $description,
354 };
355 $files and $driver->{files} = $files;
356
357 $drivers{$type} = $driver;
358
359 1;
360}
361
02d1d628
AMH
3621;
363
02d1d628
AMH
364__END__
365
366=head1 NAME
367
368Imager::Font - Font handling for Imager.
369
370=head1 SYNOPSIS
371
74d27b0b
TC
372 use Imager;
373
02d1d628
AMH
374 $t1font = Imager::Font->new(file => 'pathtofont.pfb');
375 $ttfont = Imager::Font->new(file => 'pathtofont.ttf');
faa9b3e7 376 $w32font = Imager::Font->new(face => 'Times New Roman');
02d1d628
AMH
377
378 $blue = Imager::Color->new("#0000FF");
379 $font = Imager::Font->new(file => 'pathtofont.ttf',
380 color => $blue,
381 size => 30);
382
383 ($neg_width,
384 $global_descent,
385 $pos_width,
386 $global_ascent,
387 $descent,
8a35bed5 388 $ascent,
dc35bde9
TC
389 $advance_width,
390 $right_bearing) = $font->bounding_box(string=>"Foo");
02d1d628 391
e4892b2c 392 my $bbox_object = $font->bounding_box(string=>"Foo");
02d1d628 393
e4892b2c 394 # documented in Imager::Draw
02d1d628
AMH
395 $img->string(font => $font,
396 text => "Model-XYZ",
397 x => 15,
398 y => 40,
399 size => 40,
5b0d044f 400 color => $red,
02d1d628
AMH
401 aa => 1);
402
02d1d628
AMH
403=head1 DESCRIPTION
404
5715f7c3
TC
405=for stopwords TrueType FreeType
406
ef1a1df1
TC
407This module manages, the font object returned by Imager::Font->new
408will typically be of a class derived from Imager::Font.
02d1d628
AMH
409
410=over 4
411
412=item new
413
414This creates a font object to pass to functions that take a font argument.
415
416 $font = Imager::Font->new(file => 'denmark.ttf',
1ae57608 417 index => 0,
02d1d628
AMH
418 color => $blue,
419 size => 30,
420 aa => 1);
421
5715f7c3 422This creates a font which is the TrueType font F<denmark.ttf>. It's
02d1d628 423default color is $blue, default size is 30 pixels and it's rendered
5715f7c3
TC
424anti-aliased by default. Imager can see which type of font a file is
425by looking at the suffix of the file name for the font. A suffix of
426C<ttf> is taken to mean a TrueType font while a suffix of C<pfb> is
427taken to mean a Type 1 Postscript font. If Imager cannot tell which
428type a font is you can tell it explicitly by using the C<type>
429parameter:
02d1d628
AMH
430
431 $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
432 $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
433
1ae57608
TC
434The C<index> parameter is used to select a single face from a font
435file containing more than one face, for example, from a Macintosh font
5715f7c3 436suitcase or a C<.dfont> file.
1ae57608 437
02d1d628 438If any of the C<color>, C<size> or C<aa> parameters are omitted when
de3ca2fd 439calling C<< Imager::Font->new() >> the they take the following values:
02d1d628 440
02d1d628
AMH
441 color => Imager::Color->new(255, 0, 0, 0); # this default should be changed
442 size => 15
443 aa => 0
1ae57608 444 index => 0
02d1d628 445
5715f7c3 446To use Win32 fonts supply the face name of the font:
faa9b3e7
TC
447
448 $font = Imager::Font->new(face=>'Arial Bold Italic');
449
450There isn't any access to other logical font attributes, but this
451typically isn't necessary for Win32 TrueType fonts, since you can
5715f7c3 452construct the full name of the font as above.
faa9b3e7
TC
453
454Other logical font attributes may be added if there is sufficient demand.
455
e4892b2c
TC
456Parameters:
457
458=over
459
460=item *
461
5715f7c3 462C<file> - name of the file to load the font from.
e4892b2c
TC
463
464=item *
465
5715f7c3
TC
466=for stopwords GDI
467
468C<face> - face name. This is used only under Win32 to create a GDI based
e4892b2c
TC
469font. This is ignored if the C<file> parameter is supplied.
470
471=item *
472
5715f7c3 473C<type> - font driver to use. Currently the permitted values for this are:
e4892b2c
TC
474
475=over
476
477=item *
478
5715f7c3 479C<tt> - FreeType 1.x driver. Supports TrueType (C<.ttf>) fonts.
e4892b2c
TC
480
481=item *
482
5715f7c3
TC
483=for stopwords strikethrough overline
484
485C<t1> - T1 Lib driver. Supports Postscript Type 1 fonts. Allows for
e4892b2c
TC
486synthesis of underline, strikethrough and overline.
487
488=item *
489
5715f7c3 490C<ft2> - FreeType 2.x driver. Supports many different font formats.
e4892b2c
TC
491Also supports the transform() method.
492
493=back
494
495=item *
496
5715f7c3 497C<color> - the default color used with this font. Default: red.
e4892b2c
TC
498
499=item *
500
5715f7c3 501C<size> - the default size used with this font. Default: 15.
e4892b2c
TC
502
503=item *
504
5715f7c3
TC
505C<utf8> - if non-zero then text supplied to $img->string(...) and
506$font->bounding_box(...) is assumed to be UTF-8 encoded by default.
e4892b2c
TC
507
508=item *
509
5715f7c3 510C<align> - the default value for the $img->string(...) C<align>
e4892b2c
TC
511parameter. Default: 1.
512
513=item *
514
5715f7c3 515C<vlayout> - the default value for the $img->string(...) C<vlayout>
e4892b2c
TC
516parameter. Default: 0.
517
518=item *
519
5715f7c3 520C<aa> - the default value for the $im->string(...) C<aa> parameter.
e4892b2c
TC
521Default: 0.
522
d5d8322f
TC
523=item *
524
5715f7c3
TC
525C<index> - for font file containing multiple fonts this selects which
526font to use. This is useful for Macintosh C<DFON> (F<.dfont>) and suitcase
d5d8322f
TC
527font files.
528
529If you want to use a suitcase font you will need to tell Imager to use
530the FreeType 2.x driver by setting C<type> to C<'ft2'>:
531
532 my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
533 or die Imager->errstr;
534
e4892b2c
TC
535=back
536
18f4c4ae
TC
537Returns the new font object on success. Returns C<undef> on failure
538and sets an error message readable with C<< Imager->errstr >>.
539
67d441b2 540=item bounding_box()
faa9b3e7 541
02d1d628
AMH
542Returns the bounding box for the specified string. Example:
543
3799c4d1
TC
544 my ($neg_width,
545 $global_descent,
546 $pos_width,
547 $global_ascent,
548 $descent,
549 $ascent,
dc35bde9
TC
550 $advance_width,
551 $right_bearing) = $font->bounding_box(string => "A Fool");
3799c4d1
TC
552
553 my $bbox_object = $font->bounding_box(string => "A Fool");
554
555=over
556
557=item C<$neg_width>
02d1d628 558
3799c4d1 559the relative start of a the string. In some
02d1d628
AMH
560cases this can be a negative number, in that case the first letter
561stretches to the left of the starting position that is specified in
3799c4d1
TC
562the string method of the Imager class
563
564=item C<$global_descent>
565
566how far down the lowest letter of the entire font reaches below the
567baseline (this is often j).
568
569=item C<$pos_width>
570
571how wide the string from
572the starting position is. The total width of the string is
573C<$pos_width-$neg_width>.
574
575=item C<$descent>
576
577=item C<$ascent>
578
579the same as <$global_descent> and <$global_ascent> except that they
580are only for the characters that appear in the string.
581
582=item C<$advance_width>
583
584the distance from the start point that the next string output should
585start at, this is often the same as C<$pos_width>, but can be
586different if the final character overlaps the right side of its
587character cell.
588
dc35bde9
TC
589=item C<$right_bearing>
590
591The distance from the right side of the final glyph to the end of the
592advance width. If the final glyph overflows the advance width this
593value is negative.
594
3799c4d1
TC
595=back
596
597Obviously we can stuff all the results into an array just as well:
02d1d628
AMH
598
599 @metrics = $font->bounding_box(string => "testing 123");
600
601Note that extra values may be added, so $metrics[-1] isn't supported.
602It's possible to translate the output by a passing coordinate to the
603bounding box method:
604
605 @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
606
607This gives the bounding box as if the string had been put down at C<(x,y)>
608By giving bounding_box 'canon' as a true value it's possible to measure
609the space needed for the string:
610
611 @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
612
5715f7c3 613This returns the same values in $metrics[0] and $metrics[1],
02d1d628
AMH
614but:
615
616 $bbox[2] - horizontal space taken by glyphs
617 $bbox[3] - vertical space taken by glyphs
618
3799c4d1 619Returns an L<Imager::Font::BBox> object in scalar context, so you can
5715f7c3 620avoid all those confusing indexes. This has methods as named above,
3799c4d1 621with some extra convenience methods.
02d1d628 622
e4892b2c 623Parameters are:
faa9b3e7
TC
624
625=over
626
e4892b2c 627=item *
faa9b3e7 628
5715f7c3 629C<string> - the string to calculate the bounding box for. Required.
faa9b3e7 630
e4892b2c 631=item *
faa9b3e7 632
5715f7c3 633C<size> - the font size to use. Default: value set in
e4892b2c 634Imager::Font->new(), or 15.
faa9b3e7 635
e4892b2c 636=item *
faa9b3e7 637
5715f7c3 638C<sizew> - the font width to use. Default to the value of the C<size>
e4892b2c 639parameter.
faa9b3e7 640
e4892b2c 641=item *
faa9b3e7 642
5715f7c3 643C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
e4892b2c 644For versions of perl that support Unicode (5.6 and later), this will
5715f7c3 645be enabled automatically if the 'string' parameter is already a UTF-8
67d441b2 646string. See L</UTF-8> for more information. Default: the C<utf8> value
e4892b2c 647passed to Imager::Font->new(...) or 0.
faa9b3e7 648
e4892b2c 649=item *
faa9b3e7 650
5715f7c3 651C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
e4892b2c 652box. Ignored in scalar context.
faa9b3e7 653
e4892b2c 654=item *
faa9b3e7 655
5715f7c3 656C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
e4892b2c
TC
657then $pos_width and $global_ascent values will returned as the width
658and height of the text instead.
faa9b3e7
TC
659
660=back
661
18f4c4ae 662On success returns either the list of bounds, or a bounding box object
6ba40cf1
TC
663in scalar context. Returns an empty list or C<undef> on failure and
664sets an error message readable with C<< Imager->errstr >>.
18f4c4ae 665
629cab50
TC
666The transformation matrix set by L</transform()> has no effect on the
667result of this method - the bounds of the untransformed text is
668returned.
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
18f4c4ae
TC
751Returns a list specifying the bounds of the drawn text on success.
752Returns an empty list on failure, if an C<image> parameter was
753supplied the error message can be read with C<< $image->errstr >>,
754otherwise it's available as C<< Imager->errstr >>.
3799c4d1 755
faa9b3e7
TC
756=item dpi()
757
758=item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
759
760=item dpi(dpi=>$dpi)
761
77c06476 762Set or retrieve the spatial resolution of the image in dots per inch.
faa9b3e7
TC
763The default is 72 dpi.
764
765This isn't implemented for all font types yet.
766
e4892b2c
TC
767Possible parameters are:
768
769=over
770
771=item *
772
5715f7c3
TC
773C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
774per inch.
e4892b2c
TC
775
776=item *
777
5715f7c3 778C<dpi> - set both horizontal and vertical resolution to this value.
e4892b2c
TC
779
780=back
781
18f4c4ae
TC
782Returns a list containing the previous C<xdpi>, C<ydpi> values on
783success. Returns an empty list on failure, with an error message
784returned in C<< Imager->errstr >>.
e4892b2c 785
67d441b2
TC
786=item transform()
787
788 $font->transform(matrix=>$matrix);
faa9b3e7
TC
789
790Applies a transformation to the font, where matrix is an array ref of
791numbers representing a 2 x 3 matrix:
792
793 [ $matrix->[0], $matrix->[1], $matrix->[2],
794 $matrix->[3], $matrix->[4], $matrix->[5] ]
795
796Not all font types support transformations, these will return false.
797
798It's possible that a driver will disable hinting if you use a
799transformation, to prevent discontinuities in the transformations.
800See the end of the test script t/t38ft2font.t for an example.
02d1d628 801
5715f7c3 802Currently only the ft2 (FreeType 2.x) driver supports the transform()
a53f48bb
TC
803method.
804
ef1ab93b
TC
805See samples/slant_text.pl for a sample using this function.
806
807Note that the transformation is done in font co-ordinates where y
808increases as you move up, not image co-ordinates where y decreases as
809you move up.
810
629cab50
TC
811C<transform()> has no effect on the results of L</bounding_box()>.
812
18f4c4ae
TC
813Returns true on success. Returns false on failure with the cause
814readable from C<< Imager->errstr >>.
815
3dec2c92
TC
816=item has_chars(string=>$text)
817
818Checks if the characters in $text are defined by the font.
819
820In a list context returns a list of true or false value corresponding
821to the characters in $text, true if the character is defined, false if
5715f7c3
TC
822not. In scalar context returns a string of C<NUL> or non-C<NUL>
823characters. Supports UTF-8 where the font driver supports UTF-8.
3dec2c92
TC
824
825Not all fonts support this method (use $font->can("has_chars") to
826check.)
827
18f4c4ae
TC
828On error, returns an empty list or undef in scalar context, and sets
829an error message readable with C<< Imager->errstr >>.
830
e4892b2c
TC
831=over
832
833=item *
02d1d628 834
5715f7c3 835C<string> - string of characters to check for. Required. Must contain
e4892b2c 836at least one character.
02d1d628 837
e4892b2c 838=item *
02d1d628 839
5715f7c3
TC
840C<utf8> - For drivers that support it, treat the string as UTF-8
841encoded. For versions of perl that support Unicode (5.6 and later),
842this will be enabled automatically if the 'string' parameter is
67d441b2 843already a UTF-8 string. See L</UTF-8> for more information. Default:
5715f7c3 844the C<utf8> value passed to Imager::Font->new(...) or 0.
02d1d628 845
e4892b2c 846=back
02d1d628 847
3799c4d1
TC
848=item face_name()
849
850Returns the internal name of the face. Not all font types support
18f4c4ae
TC
851this method yet, so you should check with C<< $font->can("face_name")
852>> before calling C<face_name>.
3799c4d1 853
a4168bea 854=item glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
3799c4d1
TC
855
856Returns a list of glyph names for each of the characters in the
857string. If the character has no name then C<undef> is returned for
858the character.
859
5715f7c3
TC
860Some font files do not include glyph names, in this case FreeType 2
861will not return any names. FreeType 1 can return standard names even
3799c4d1
TC
862if there are no glyph names in the font.
863
5715f7c3 864FreeType 2 has an API function that returns true only if the font has
a4168bea 865"reliable glyph names", unfortunately this always returns false for
5715f7c3 866TrueType fonts. This can avoid the check of this API by supplying
a4168bea 867C<reliable_only> as 0. The consequences of using this on an unknown
5715f7c3 868font may be unpredictable, since the FreeType documentation doesn't
a4168bea
TC
869say how those name tables are unreliable, or how FT2 handles them.
870
5715f7c3 871Both FreeType 1.x and 2.x allow support for glyph names to not be
3799c4d1
TC
872included.
873
932f9afb
TC
874If the supplied C<string> is marked as UTF-8 or the C<utf8> parameter
875is true and the supplied string does not contain valid UTF-8, returns
876an empty string and set an error message readable from C<<
877Imager->errstr >>,
878
89f86ebd
TC
879=item can_glyph_names()
880
881As a class method, returns true if the underlying library supports
882returning glyph names.
883
884As an object method, returns true if the supplied font supports
885returning glyph names.
886
d5556805
TC
887=item draw
888
889This is used by Imager's string() method to implement drawing text.
67d441b2 890See L<Imager::Draw/string()>.
d5556805 891
faa9b3e7
TC
892=back
893
3e882362
TC
894=head1 MULTIPLE MASTER FONTS
895
5715f7c3 896The FreeType 2 driver supports multiple master fonts:
3e882362
TC
897
898=over
899
900=item is_mm()
901
902Test if the font is a multiple master font.
903
904=item mm_axes()
905
906Returns a list of the axes that can be changes in the font. Each
907entry is an array reference which contains:
908
909=over
910
911=item 1.
912
913Name of the axis.
914
915=item 2.
916
917minimum value for this axis.
918
919=item 3.
920
921maximum value for this axis
922
923=back
924
925=item set_mm_coords(coords=>\@values)
926
927Blends an interpolated design from the master fonts. @values must
928contain as many values as there are axes in the font.
929
930=back
931
932For example, to select the minimum value in each axis:
933
934 my @axes = $font->mm_axes;
935 my @coords = map $_->[1], @axes;
936 $font->set_mm_coords(coords=>\@coords);
937
938It's possible other drivers will support multiple master fonts in the
939future, check if your selected font object supports the is_mm() method
940using the can() method.
941
5715f7c3 942=head1 UTF-8
faa9b3e7
TC
943
944There are 2 ways of rendering Unicode characters with Imager:
02d1d628 945
faa9b3e7
TC
946=over
947
948=item *
949
5715f7c3 950For versions of perl that support it, use perl's native UTF-8 strings.
faa9b3e7
TC
951This is the simplest method.
952
953=item *
954
5715f7c3
TC
955Hand build your own UTF-8 encoded strings. Only recommended if your
956version of perl has no UTF-8 support.
02d1d628
AMH
957
958=back
959
faa9b3e7 960Imager won't construct characters for you, so if want to output
5715f7c3 961Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
faa9b3e7
TC
962your font doesn't support it, Imager will I<not> build it from 0041
963"LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
964
5715f7c3 965To check if a driver supports UTF-8 call the utf8() method:
d5556805
TC
966
967=over
968
5715f7c3 969=item utf8()
d5556805 970
5715f7c3 971Return true if the font supports UTF-8.
d5556805
TC
972
973=back
974
5715f7c3 975=head2 Native UTF-8 Support
faa9b3e7 976
5715f7c3 977If your version of perl supports UTF-8 and the driver supports UTF-8,
faa9b3e7
TC
978just use the $im->string() method, and it should do the right thing.
979
980=head2 Build your own
981
5715f7c3 982In this case you need to build your own UTF-8 encoded characters.
faa9b3e7
TC
983
984For example:
985
986 $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
987
5237562b 988You need to be careful with versions of perl that have UTF-8
5715f7c3 989support, since your string may end up doubly UTF-8 encoded.
faa9b3e7
TC
990
991For example:
992
993 $x = "A\xE2\x80\x90\x41\x{2010}";
994 substr($x, -1, 0) = "";
5715f7c3
TC
995 # at this point $x is has the UTF-8 flag set, but has 5 characters,
996 # none, of which is the constructed UTF-8 character
faa9b3e7 997
18f4c4ae 998The test script t/t38ft2font.t has a small example of this after the
faa9b3e7
TC
999comment:
1000
5715f7c3 1001 # an attempt using emulation of UTF-8
faa9b3e7
TC
1002
1003=head1 DRIVER CONTROL
1004
1005If you don't supply a 'type' parameter to Imager::Font->new(), but you
1006do supply a 'file' parameter, Imager will attempt to guess which font
1007driver to used based on the extension of the font file.
1008
1009Since some formats can be handled by more than one driver, a priority
1010list is used to choose which one should be used, if a given format can
1011be handled by more than one driver.
1012
d5556805
TC
1013=over
1014
1015=item priorities
1016
1017The current priorities can be retrieved with:
faa9b3e7
TC
1018
1019 @drivers = Imager::Font->priorities();
1020
1021You can set new priorities and save the old priorities with:
1022
1023 @old = Imager::Font->priorities(@drivers);
1024
1025If you supply driver names that are not currently supported, they will
1026be ignored.
1027
ef1a1df1
TC
1028Note that by default the priority list no longer includes C<tt> and
1029C<t1>, so typically you will need to have L<Imager::Font::FT2>
1030installed to create fonts with Imager.
faa9b3e7
TC
1031
1032 my @old = Imager::Font->priorities(qw(tt ft2 t1));
1033
9413a3f3
TC
1034=item register
1035
1036Registers an extra font driver. Accepts the following parameters:
1037
1038=over
1039
1040=item *
1041
1042type - a brief identifier for the font driver. You can supply this
1043value to C<< Imager::Font->new() >> to create fonts of this type.
1044Required.
1045
1046=item *
1047
1048class - the font class name. Imager will attempted to load this
1049module by name. Required.
1050
1051=item *
1052
1053files - a regular expression to match against file names. If supplied
1054this must be a valid perl regular expression. If not supplied you can
1055only create fonts of this type by supplying the C<type> parameter to
1056C<< Imager::Font->new() >>
1057
1058=item *
1059
1060description - a brief description of the font driver. Defaults to the
1061value supplied in C<class>.
1062
1063=back
1064
1065=back
1066
02d1d628
AMH
1067=head1 AUTHOR
1068
1069Arnar M. Hrafnkelsson, addi@umich.edu
5715f7c3 1070And a great deal of help from others - see the F<README> for a complete
02d1d628
AMH
1071list.
1072
96190b6e
TC
1073=head1 BUGS
1074
7fdbfba8
TC
1075The $pos_width member returned by the bounding_box() method has
1076historically returned different values from different drivers. The
5715f7c3 1077FreeType 1.x and 2.x, and the Win32 drivers return the max of the
7fdbfba8
TC
1078advance width and the right edge of the right-most glyph. The Type 1
1079driver always returns the right edge of the right-most glyph.
1080
1081The newer advance_width and right_bearing values allow access to any
1082of the above.
1083
e4892b2c
TC
1084=head1 REVISION
1085
1086$Revision$
1087
02d1d628
AMH
1088=head1 SEE ALSO
1089
412e7a35 1090Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
3799c4d1 1091Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
412e7a35 1092
8f22b8d8 1093 http://imager.perl.org/
02d1d628
AMH
1094
1095=cut
1096
1097