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