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