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