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