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