6 our $VERSION = "1.039";
8 # the aim here is that we can:
9 # - add file based types in one place: here
10 # - make sure we only attempt to create types that exist
11 # - give reasonable defaults
12 # - give the user some control over which types get used
16 class=>'Imager::Font::Truetype',
17 module=>'Imager/Font/Truetype.pm',
19 description => 'FreeType 1.x',
23 class=>'Imager::Font::T1',
24 module=>'Imager/Font/T1.pm',
26 description => 'T1Lib',
29 class=>'Imager::Font::FT2',
30 module=>'Imager/Font/FT2.pm',
31 files=>'.*\.(pfa|pfb|otf|ttf|fon|fnt|dfont|pcf(\.gz)?)$',
32 description => 'FreeType 2.x',
35 class=>'Imager::Font::Image',
36 module=>'Imager/Font/Image.pm',
40 class=>'Imager::Font::W32',
41 module=>'Imager/Font/W32.pm',
42 description => 'Win32 GDI Fonts',
46 # this currently should only contain file based types, don't add w32
47 my @priority = qw(ft2 ifs);
52 my ($file, $type, $id);
53 my %hsh=(color => Imager::Color->new(255,0,0,255),
64 unless ($drivers{$type}) {
65 Imager->_set_error("Unknown font type $type");
69 unless ($Imager::formats{$type}) {
70 Imager->_set_error("The $type {$drivers{$type}) font driver is not installed");
75 for my $drv (@priority) {
77 my $re = $drivers{$drv}{files} or next;
78 if ($file =~ /$re/i) {
79 if (eval { require $drivers{$drv}{module}; 1 } and !( $drivers{$drv}{checktype} && !$Imager::formats{$drv} )) {
86 if (!defined($type)) {
87 # some types we can support, but the driver isn't available
88 # work out which drivers support it, so we can provide the user
89 # some useful information on how to get it working
91 for my $driver_name (keys %drivers) {
92 my $driver = $drivers{$driver_name};
93 push @not_here, "$driver_name ($driver->{description})"
94 if $driver->{files} && $file =~ /$driver->{files}/i;
97 $Imager::ERRSTR = "No font drivers enabled that can support this file, rebuild Imager with any of ".join(", ", @not_here)." to use this font file";
100 $Imager::ERRSTR = "No font type found for $hsh{'file'}";
104 } elsif ($hsh{face}) {
107 $Imager::ERRSTR="No font file specified";
111 if ($drivers{$type}{checktype} && !$Imager::formats{$type}) {
112 $Imager::ERRSTR = "`$type' not enabled";
116 # here we should have the font type or be dead already.
118 require $drivers{$type}{module};
119 return $drivers{$type}{class}->new(%hsh);
122 # returns first defined parameter
125 return $_ if defined $_;
132 my %input = ('x' => 0, 'y' => 0, @_);
133 unless ($input{image}) {
134 $Imager::ERRSTR = 'No image supplied to $font->draw()';
137 my $image = $input{image};
138 $input{string} = _first($input{string}, $input{text});
139 unless (defined $input{string}) {
140 $image->_set_error("Missing required parameter 'string'");
143 $input{aa} = _first($input{aa}, $input{antialias}, $self->{aa}, 1);
144 # the original draw code worked this out but didn't use it
145 $input{align} = _first($input{align}, $self->{align});
146 $input{color} = _first($input{color}, $self->{color});
147 $input{color} = Imager::_color($input{'color'});
149 $input{size} = _first($input{size}, $self->{size});
150 unless (defined $input{size}) {
151 $image->_set_error("No font size provided");
154 $input{align} = _first($input{align}, 1);
155 $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
156 $input{vlayout} = _first($input{vlayout}, $self->{vlayout}, 0);
158 my $result = $self->_draw(%input);
160 $image->_set_error($image->_error_as_msg());
168 my %input = ( halign => 'left', valign => 'baseline',
169 'x' => 0, 'y' => 0, @_ );
171 # image needs to be supplied, but can be supplied as undef
172 unless (exists $input{image}) {
173 Imager->_set_error("Missing required parameter 'image'");
177 my $errors_to = $input{image} || 'Imager';
179 my $text = _first($input{string}, $input{text});
180 unless (defined $text) {
181 $errors_to->_set_error("Missing required parameter 'string'");
185 my $size = _first($input{size}, $self->{size});
186 my $utf8 = _first($input{utf8}, 0);
188 my $bbox = $self->bounding_box(string=>$text, size=>$size, utf8=>$utf8);
189 my $valign = $input{valign};
191 unless $valign && $valign =~ /^(?:top|center|bottom|baseline)$/;
193 my $halign = $input{halign};
195 unless $halign && $halign =~ /^(?:left|start|center|end|right)$/;
200 if ($valign eq 'top') {
203 elsif ($valign eq 'center') {
204 $y += $bbox->ascent - $bbox->text_height / 2;
206 elsif ($valign eq 'bottom') {
207 $y += $bbox->descent;
209 # else baseline is the default
211 if ($halign eq 'left') {
212 $x -= $bbox->start_offset;
214 elsif ($halign eq 'start') {
217 elsif ($halign eq 'center') {
218 $x -= $bbox->start_offset + $bbox->total_width / 2;
220 elsif ($halign eq 'end') {
221 $x -= $bbox->advance_width;
223 elsif ($halign eq 'right') {
224 $x -= $bbox->advance_width - $bbox->right_bearing;
230 delete @input{qw/x y/};
231 $self->draw(%input, 'x' => $x, 'y' => $y, align=>1)
235 return ($x+$bbox->start_offset, $y-$bbox->ascent,
236 $x+$bbox->end_offset, $y-$bbox->descent+1);
243 if (!exists $input{'string'}) {
244 $Imager::ERRSTR='string parameter missing';
247 $input{size} ||= $self->{size};
248 $input{sizew} = _first($input{sizew}, $self->{sizew}, 0);
249 $input{utf8} = _first($input{utf8}, $self->{utf8}, 0);
251 my @box = $self->_bounding_box(%input)
255 if(@box && exists $input{'x'} and exists $input{'y'}) {
256 my($gdescent, $gascent)=@box[1,3];
257 $box[1]=$input{'y'}-$gascent; # top = base - ascent (Y is down)
258 $box[3]=$input{'y'}-$gdescent; # bottom = base - descent (Y is down, descent is negative)
259 $box[0]+=$input{'x'};
260 $box[2]+=$input{'x'};
261 } elsif (@box && $input{'canon'}) {
262 $box[3]-=$box[1]; # make it canonical (ie (0,0) - (width, height))
268 require Imager::Font::BBox;
270 return Imager::Font::BBox->new(@box);
277 # I'm assuming a default of 72 dpi
280 $Imager::ERRSTR = "Setting dpi not implemented for this font type";
292 # this is split into transform() and _transform() so we can
293 # implement other tags like: degrees=>12, which would build a
294 # 12 degree rotation matrix
295 # but I'll do that later
296 unless ($hsh{matrix}) {
297 $Imager::ERRSTR = "You need to supply a matrix";
301 return $self->_transform(%hsh);
305 $Imager::ERRSTR = "This type of font cannot be transformed";
324 my ($self, %opts) = @_;
326 my $type = delete $opts{type};
327 my $class = delete $opts{class};
328 my $files = delete $opts{files};
329 my $description = delete $opts{description} || $class;
332 or return Imager->_set_error("No type parameter supplied to Imager::Font->regster");
335 or return Imager->_set_error("No class parameter supplied to Imager::Font->register");
339 or return Imager->_set_error("files isn't a valid regexp");
342 if ($drivers{$type} && $drivers{$type}{class} ne $class) {
343 Imager->_set_error("Font type $type already registered as $drivers{$type}{class}");
347 (my $module = $class . ".pm") =~ s(::)(/)g;
353 description => $description,
355 $files and $driver->{files} = $files;
357 $drivers{$type} = $driver;
368 Imager::Font - Font handling for Imager.
374 $t1font = Imager::Font->new(file => 'pathtofont.pfb');
375 $ttfont = Imager::Font->new(file => 'pathtofont.ttf');
376 $w32font = Imager::Font->new(face => 'Times New Roman');
378 $blue = Imager::Color->new("#0000FF");
379 $font = Imager::Font->new(file => 'pathtofont.ttf',
390 $right_bearing) = $font->bounding_box(string=>"Foo");
392 my $bbox_object = $font->bounding_box(string=>"Foo");
394 # documented in Imager::Draw
395 $img->string(font => $font,
405 =for stopwords TrueType FreeType
407 This module manages, the font object returned by Imager::Font->new
408 will typically be of a class derived from Imager::Font.
414 This creates a font object to pass to functions that take a font argument.
416 $font = Imager::Font->new(file => 'denmark.ttf',
422 This creates a font which is the TrueType font F<denmark.ttf>. It's
423 default color is $blue, default size is 30 pixels and it's rendered
424 anti-aliased by default. Imager can see which type of font a file is
425 by looking at the suffix of the file name for the font. A suffix of
426 C<ttf> is taken to mean a TrueType font while a suffix of C<pfb> is
427 taken to mean a Type 1 Postscript font. If Imager cannot tell which
428 type a font is you can tell it explicitly by using the C<type>
431 $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
432 $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
434 The C<index> parameter is used to select a single face from a font
435 file containing more than one face, for example, from a Macintosh font
436 suitcase or a C<.dfont> file.
438 If any of the C<color>, C<size> or C<aa> parameters are omitted when
439 calling C<< Imager::Font->new() >> the they take the following values:
441 color => Imager::Color->new(255, 0, 0, 0); # this default should be changed
446 To use Win32 fonts supply the face name of the font:
448 $font = Imager::Font->new(face=>'Arial Bold Italic');
450 There isn't any access to other logical font attributes, but this
451 typically isn't necessary for Win32 TrueType fonts, since you can
452 construct the full name of the font as above.
454 Other logical font attributes may be added if there is sufficient demand.
462 C<file> - name of the file to load the font from.
468 C<face> - face name. This is used only under Win32 to create a GDI based
469 font. This is ignored if the C<file> parameter is supplied.
473 C<type> - font driver to use. Currently the permitted values for this are:
479 C<tt> - FreeType 1.x driver. Supports TrueType (C<.ttf>) fonts.
483 =for stopwords strikethrough overline
485 C<t1> - T1 Lib driver. Supports Postscript Type 1 fonts. Allows for
486 synthesis of underline, strikethrough and overline.
490 C<ft2> - FreeType 2.x driver. Supports many different font formats.
491 Also supports the transform() method.
497 C<color> - the default color used with this font. Default: red.
501 C<size> - the default size used with this font. Default: 15.
505 C<utf8> - if non-zero then text supplied to $img->string(...) and
506 $font->bounding_box(...) is assumed to be UTF-8 encoded by default.
510 C<align> - the default value for the $img->string(...) C<align>
511 parameter. Default: 1.
515 C<vlayout> - the default value for the $img->string(...) C<vlayout>
516 parameter. Default: 0.
520 C<aa> - the default value for the $im->string(...) C<aa> parameter.
525 C<index> - for font file containing multiple fonts this selects which
526 font to use. This is useful for Macintosh C<DFON> (F<.dfont>) and suitcase
529 If you want to use a suitcase font you will need to tell Imager to use
530 the FreeType 2.x driver by setting C<type> to C<'ft2'>:
532 my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
533 or die Imager->errstr;
537 Returns the new font object on success. Returns C<undef> on failure
538 and sets an error message readable with C<< Imager->errstr >>.
542 Returns the bounding box for the specified string. Example:
551 $right_bearing) = $font->bounding_box(string => "A Fool");
553 my $bbox_object = $font->bounding_box(string => "A Fool");
559 the relative start of a the string. In some
560 cases this can be a negative number, in that case the first letter
561 stretches to the left of the starting position that is specified in
562 the string method of the Imager class
564 =item C<$global_descent>
566 how far down the lowest letter of the entire font reaches below the
567 baseline (this is often j).
571 how wide the string from
572 the starting position is. The total width of the string is
573 C<$pos_width-$neg_width>.
579 the same as <$global_descent> and <$global_ascent> except that they
580 are only for the characters that appear in the string.
582 =item C<$advance_width>
584 the distance from the start point that the next string output should
585 start at, this is often the same as C<$pos_width>, but can be
586 different if the final character overlaps the right side of its
589 =item C<$right_bearing>
591 The distance from the right side of the final glyph to the end of the
592 advance width. If the final glyph overflows the advance width this
597 Obviously we can stuff all the results into an array just as well:
599 @metrics = $font->bounding_box(string => "testing 123");
601 Note that extra values may be added, so $metrics[-1] isn't supported.
602 It's possible to translate the output by a passing coordinate to the
605 @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
607 This gives the bounding box as if the string had been put down at C<(x,y)>
608 By giving bounding_box 'canon' as a true value it's possible to measure
609 the space needed for the string:
611 @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
613 This returns the same values in $metrics[0] and $metrics[1],
616 $bbox[2] - horizontal space taken by glyphs
617 $bbox[3] - vertical space taken by glyphs
619 Returns an L<Imager::Font::BBox> object in scalar context, so you can
620 avoid all those confusing indexes. This has methods as named above,
621 with some extra convenience methods.
629 C<string> - the string to calculate the bounding box for. Required.
633 C<size> - the font size to use. Default: value set in
634 Imager::Font->new(), or 15.
638 C<sizew> - the font width to use. Default to the value of the C<size>
643 C<utf8> - For drivers that support it, treat the string as UTF-8 encoded.
644 For versions of perl that support Unicode (5.6 and later), this will
645 be enabled automatically if the 'string' parameter is already a UTF-8
646 string. See L</UTF-8> for more information. Default: the C<utf8> value
647 passed to Imager::Font->new(...) or 0.
651 C<x>, C<y> - offsets applied to @box[0..3] to give you a adjusted bounding
652 box. Ignored in scalar context.
656 C<canon> - if non-zero and the C<x>, C<y> parameters are not supplied,
657 then $pos_width and $global_ascent values will returned as the width
658 and height of the text instead.
662 On success returns either the list of bounds, or a bounding box object
663 in scalar context. Returns an empty list or C<undef> on failure and
664 sets an error message readable with C<< Imager->errstr >>.
666 The transformation matrix set by L</transform()> has no effect on the
667 result of this method - the bounds of the untransformed text is
672 The $img->string(...) method is now documented in
673 L<Imager::Draw/string()>
675 =item align(string=>$text,size=>$size,x=>...,y=>...,valign => ...,halign=>...)
677 Higher level text output - outputs the text aligned as specified
678 around the given point (x,y).
680 # "Hello" centered at 100, 100 in the image.
681 my ($left, $top, $right, $bottom) =
682 $font->align(string=>"Hello",
684 halign=>'center', valign=>'center',
687 Takes the same parameters as $font->draw(), and the following extra
694 C<valign> - Possible values are:
700 Point is at the top of the text.
704 Point is at the bottom of the text.
708 Point is on the baseline of the text (default.)
712 Point is vertically centered within the text.
724 C<left> - the point is at the left of the text.
728 C<start> - the point is at the start point of the text.
732 C<center> - the point is horizontally centered within the text.
736 C<right> - the point is at the right end of the text.
740 C<end> - the point is at the end point of the text.
746 C<image> - The image to draw to. Set to C<undef> to avoid drawing but
747 still calculate the bounding box.
751 Returns a list specifying the bounds of the drawn text on success.
752 Returns an empty list on failure, if an C<image> parameter was
753 supplied the error message can be read with C<< $image->errstr >>,
754 otherwise it's available as C<< Imager->errstr >>.
758 =item dpi(xdpi=>$xdpi, ydpi=>$ydpi)
762 Set or retrieve the spatial resolution of the image in dots per inch.
763 The default is 72 dpi.
765 This isn't implemented for all font types yet.
767 Possible parameters are:
773 C<xdpi>, C<ydpi> - set the horizontal and vertical resolution in dots
778 C<dpi> - set both horizontal and vertical resolution to this value.
782 Returns a list containing the previous C<xdpi>, C<ydpi> values on
783 success. Returns an empty list on failure, with an error message
784 returned in C<< Imager->errstr >>.
788 $font->transform(matrix=>$matrix);
790 Applies a transformation to the font, where matrix is an array ref of
791 numbers representing a 2 x 3 matrix:
793 [ $matrix->[0], $matrix->[1], $matrix->[2],
794 $matrix->[3], $matrix->[4], $matrix->[5] ]
796 Not all font types support transformations, these will return false.
798 It's possible that a driver will disable hinting if you use a
799 transformation, to prevent discontinuities in the transformations.
800 See the end of the test script t/t38ft2font.t for an example.
802 Currently only the ft2 (FreeType 2.x) driver supports the transform()
805 See samples/slant_text.pl for a sample using this function.
807 Note that the transformation is done in font co-ordinates where y
808 increases as you move up, not image co-ordinates where y decreases as
811 C<transform()> has no effect on the results of L</bounding_box()>.
813 Returns true on success. Returns false on failure with the cause
814 readable from C<< Imager->errstr >>.
816 =item has_chars(string=>$text)
818 Checks if the characters in $text are defined by the font.
820 In a list context returns a list of true or false value corresponding
821 to the characters in $text, true if the character is defined, false if
822 not. In scalar context returns a string of C<NUL> or non-C<NUL>
823 characters. Supports UTF-8 where the font driver supports UTF-8.
825 Not all fonts support this method (use $font->can("has_chars") to
828 On error, returns an empty list or undef in scalar context, and sets
829 an error message readable with C<< Imager->errstr >>.
835 C<string> - string of characters to check for. Required. Must contain
836 at least one character.
840 C<utf8> - For drivers that support it, treat the string as UTF-8
841 encoded. For versions of perl that support Unicode (5.6 and later),
842 this will be enabled automatically if the 'string' parameter is
843 already a UTF-8 string. See L</UTF-8> for more information. Default:
844 the C<utf8> value passed to Imager::Font->new(...) or 0.
850 Returns the internal name of the face. Not all font types support
851 this method yet, so you should check with C<< $font->can("face_name")
852 >> before calling C<face_name>.
854 =item glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
856 Returns a list of glyph names for each of the characters in the
857 string. If the character has no name then C<undef> is returned for
860 Some font files do not include glyph names, in this case FreeType 2
861 will not return any names. FreeType 1 can return standard names even
862 if there are no glyph names in the font.
864 FreeType 2 has an API function that returns true only if the font has
865 "reliable glyph names", unfortunately this always returns false for
866 TrueType fonts. This can avoid the check of this API by supplying
867 C<reliable_only> as 0. The consequences of using this on an unknown
868 font may be unpredictable, since the FreeType documentation doesn't
869 say how those name tables are unreliable, or how FT2 handles them.
871 Both FreeType 1.x and 2.x allow support for glyph names to not be
874 If the supplied C<string> is marked as UTF-8 or the C<utf8> parameter
875 is true and the supplied string does not contain valid UTF-8, returns
876 an empty string and set an error message readable from C<<
879 =item can_glyph_names()
881 As a class method, returns true if the underlying library supports
882 returning glyph names.
884 As an object method, returns true if the supplied font supports
885 returning glyph names.
889 This is used by Imager's string() method to implement drawing text.
890 See L<Imager::Draw/string()>.
894 =head1 MULTIPLE MASTER FONTS
896 The FreeType 2 driver supports multiple master fonts:
902 Test if the font is a multiple master font.
906 Returns a list of the axes that can be changes in the font. Each
907 entry is an array reference which contains:
917 minimum value for this axis.
921 maximum value for this axis
925 =item set_mm_coords(coords=>\@values)
927 Blends an interpolated design from the master fonts. @values must
928 contain as many values as there are axes in the font.
932 For example, to select the minimum value in each axis:
934 my @axes = $font->mm_axes;
935 my @coords = map $_->[1], @axes;
936 $font->set_mm_coords(coords=>\@coords);
938 It's possible other drivers will support multiple master fonts in the
939 future, check if your selected font object supports the is_mm() method
940 using the can() method.
944 There are 2 ways of rendering Unicode characters with Imager:
950 For versions of perl that support it, use perl's native UTF-8 strings.
951 This is the simplest method.
955 Hand build your own UTF-8 encoded strings. Only recommended if your
956 version of perl has no UTF-8 support.
960 Imager won't construct characters for you, so if want to output
961 Unicode character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and
962 your font doesn't support it, Imager will I<not> build it from 0041
963 "LATIN CAPITAL LETTER A" and 0308 "COMBINING DIAERESIS".
965 To check if a driver supports UTF-8 call the utf8() method:
971 Return true if the font supports UTF-8.
975 =head2 Native UTF-8 Support
977 If your version of perl supports UTF-8 and the driver supports UTF-8,
978 just use the $im->string() method, and it should do the right thing.
980 =head2 Build your own
982 In this case you need to build your own UTF-8 encoded characters.
986 $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
988 You need to be careful with versions of perl that have UTF-8
989 support, since your string may end up doubly UTF-8 encoded.
993 $x = "A\xE2\x80\x90\x41\x{2010}";
994 substr($x, -1, 0) = "";
995 # at this point $x is has the UTF-8 flag set, but has 5 characters,
996 # none, of which is the constructed UTF-8 character
998 The test script t/t38ft2font.t has a small example of this after the
1001 # an attempt using emulation of UTF-8
1003 =head1 DRIVER CONTROL
1005 If you don't supply a 'type' parameter to Imager::Font->new(), but you
1006 do supply a 'file' parameter, Imager will attempt to guess which font
1007 driver to used based on the extension of the font file.
1009 Since some formats can be handled by more than one driver, a priority
1010 list is used to choose which one should be used, if a given format can
1011 be handled by more than one driver.
1017 The current priorities can be retrieved with:
1019 @drivers = Imager::Font->priorities();
1021 You can set new priorities and save the old priorities with:
1023 @old = Imager::Font->priorities(@drivers);
1025 If you supply driver names that are not currently supported, they will
1028 Note that by default the priority list no longer includes C<tt> and
1029 C<t1>, so typically you will need to have L<Imager::Font::FT2>
1030 installed to create fonts with Imager.
1032 my @old = Imager::Font->priorities(qw(tt ft2 t1));
1036 Registers an extra font driver. Accepts the following parameters:
1042 type - a brief identifier for the font driver. You can supply this
1043 value to C<< Imager::Font->new() >> to create fonts of this type.
1048 class - the font class name. Imager will attempted to load this
1049 module by name. Required.
1053 files - a regular expression to match against file names. If supplied
1054 this must be a valid perl regular expression. If not supplied you can
1055 only create fonts of this type by supplying the C<type> parameter to
1056 C<< Imager::Font->new() >>
1060 description - a brief description of the font driver. Defaults to the
1061 value supplied in C<class>.
1069 Arnar M. Hrafnkelsson, addi@umich.edu
1070 And a great deal of help from others - see the F<README> for a complete
1075 The $pos_width member returned by the bounding_box() method has
1076 historically returned different values from different drivers. The
1077 FreeType 1.x and 2.x, and the Win32 drivers return the max of the
1078 advance width and the right edge of the right-most glyph. The Type 1
1079 driver always returns the right edge of the right-most glyph.
1081 The newer advance_width and right_bearing values allow access to any
1090 Imager(3), Imager::Font::FreeType2(3), Imager::Font::Type1(3),
1091 Imager::Font::Win32(3), Imager::Font::Truetype(3), Imager::Font::BBox(3)
1093 http://imager.perl.org/