Imager::Font(3pm)

1Imager::Font(3)       User Contributed Perl Documentation      Imager::Font(3)
2
3
4

NAME

6       Imager::Font - Font handling for Imager.
7

SYNOPSIS

9         $t1font = Imager::Font->new(file => 'pathtofont.pfb');
10         $ttfont = Imager::Font->new(file => 'pathtofont.ttf');
11         $w32font = Imager::Font->new(face => 'Times New Roman');
12
13         $blue = Imager::Color->new("#0000FF");
14         $font = Imager::Font->new(file  => 'pathtofont.ttf',
15                                   color => $blue,
16                                   size  => 30);
17
18         ($neg_width,
19          $global_descent,
20          $pos_width,
21          $global_ascent,
22          $descent,
23          $ascent,
24          $advance_width,
25          $right_bearing) = $font->bounding_box(string=>"Foo");
26
27         my $bbox_object = $font->bounding_box(string=>"Foo");
28
29         # documented in Imager::Draw
30         $img->string(font  => $font,
31                    text  => "Model-XYZ",
32                    x     => 15,
33                    y     => 40,
34                    size  => 40,
35                    color => $red,
36                    aa    => 1);
37

DESCRIPTION

39       This module handles creating Font objects used by imager.  The module
40       also handles querying fonts for sizes and such.  If both T1lib and
41       freetype were avaliable at the time of compilation then Imager should
42       be able to work with both truetype fonts and t1 postscript fonts.  To
43       check if Imager is t1 or truetype capable you can use something like
44       this:
45
46         use Imager;
47         print "Has truetype"      if $Imager::formats{tt};
48         print "Has t1 postscript" if $Imager::formats{t1};
49         print "Has Win32 fonts"   if $Imager::formats{w32};
50         print "Has Freetype2"     if $Imager::formats{ft2};
51
52       new This creates a font object to pass to functions that take a font
53           argument.
54
55             $font = Imager::Font->new(file  => 'denmark.ttf',
56                                       index => 0,
57                                       color => $blue,
58                                       size  => 30,
59                                       aa    => 1);
60
61           This creates a font which is the truetype font denmark.ttf.  It's
62           default color is $blue, default size is 30 pixels and it's rendered
63           antialised by default.  Imager can see which type of font a file is
64           by looking at the suffix of the filename for the font.  A suffix of
65           'ttf' is taken to mean a truetype font while a suffix of 'pfb' is
66           taken to mean a t1 postscript font.  If Imager cannot tell which
67           type a font is you can tell it explicitly by using the "type"
68           parameter:
69
70             $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
71             $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
72
73           The "index" parameter is used to select a single face from a font
74           file containing more than one face, for example, from a Macintosh
75           font suitcase or a .dfont file.
76
77           If any of the "color", "size" or "aa" parameters are omitted when
78           calling "Imager::Font-"new()> the they take the following values:
79
80             color => Imager::Color->new(255, 0, 0, 0);  # this default should be changed
81             size  => 15
82             aa    => 0
83             index => 0
84
85           To use Win32 fonts supply the facename of the font:
86
87             $font = Imager::Font->new(face=>'Arial Bold Italic');
88
89           There isn't any access to other logical font attributes, but this
90           typically isn't necessary for Win32 TrueType fonts, since you can
91           contruct the full name of the font as above.
92
93           Other logical font attributes may be added if there is sufficient
94           demand.
95
96           Parameters:
97
98           *   file - name of the file to load the font from.
99
100           *   face - face name.  This is used only under Win32 to create a
101               GDI based font.  This is ignored if the "file" parameter is
102               supplied.
103
104           *   type - font driver to use.  Currently the permitted values for
105               this are:
106
107               *   tt - Freetype 1.x driver.  Supports TTF fonts.
108
109               *   t1 - T1 Lib driver.  Supports Postscript Type 1 fonts.
110                   Allows for synthesis of underline, strikethrough and over‐
111                   line.
112
113               *   ft2 - Freetype 2.x driver.  Supports many different font
114                   formats.  Also supports the transform() method.
115
116           *   color - the default color used with this font.  Default: red.
117
118           *   size - the default size used with this font.  Default: 15.
119
120           *   utf8 - if non-zero then text supplied to $img->string(...) and
121               $font->bounding_box(...) is assumed to be UTF 8 encoded by
122               default.
123
124           *   align - the default value for the $img->string(...) "align"
125               parameter.  Default: 1.
126
127           *   vlayout - the default value for the $img->string(...) "vlayout"
128               parameter.  Default: 0.
129
130           *   aa - the default value for the $im->string(...) "aa" parameter.
131               Default: 0.
132
133           *   index - for font file containing multiple fonts this selects
134               which font to use.  This is useful for Macintosh DFON (.dfont)
135               and suitcase font files.
136
137               If you want to use a suitcase font you will need to tell Imager
138               to use the FreeType 2.x driver by setting "type" to 'ft2':
139
140                 my $font = Imager::Font->new(file=>$file, index => 1, type=>'ft2')
141                   or die Imager->errstr;
142
143       bounding_box
144           Returns the bounding box for the specified string.  Example:
145
146             my ($neg_width,
147                 $global_descent,
148                 $pos_width,
149                 $global_ascent,
150                 $descent,
151                 $ascent,
152                 $advance_width,
153                 $right_bearing) = $font->bounding_box(string => "A Fool");
154
155             my $bbox_object = $font->bounding_box(string => "A Fool");
156
157           $neg_width
158               the relative start of a the string.  In some cases this can be
159               a negative number, in that case the first letter stretches to
160               the left of the starting position that is specified in the
161               string method of the Imager class
162
163           $global_descent
164               how far down the lowest letter of the entire font reaches below
165               the baseline (this is often j).
166
167           $pos_width
168               how wide the string from the starting position is.  The total
169               width of the string is "$pos_width-$neg_width".
170
171           $descent
172           $ascent
173               the same as <$global_descent> and <$global_ascent> except that
174               they are only for the characters that appear in the string.
175
176           $advance_width
177               the distance from the start point that the next string output
178               should start at, this is often the same as $pos_width, but can
179               be different if the final character overlaps the right side of
180               its character cell.
181
182           $right_bearing
183               The distance from the right side of the final glyph to the end
184               of the advance width.  If the final glyph overflows the advance
185               width this value is negative.
186
187           Obviously we can stuff all the results into an array just as well:
188
189             @metrics = $font->bounding_box(string => "testing 123");
190
191           Note that extra values may be added, so $metrics[-1] isn't sup‐
192           ported.  It's possible to translate the output by a passing coordi‐
193           nate to the bounding box method:
194
195             @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
196
197           This gives the bounding box as if the string had been put down at
198           "(x,y)" By giving bounding_box 'canon' as a true value it's possi‐
199           ble to measure the space needed for the string:
200
201             @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
202
203           This returns tha same values in $metrics[0] and $metrics[1], but:
204
205            $bbox[2] - horizontal space taken by glyphs
206            $bbox[3] - vertical space taken by glyphs
207
208           Returns an Imager::Font::BBox object in scalar context, so you can
209           avoid all those confusing indices.  This has methods as named
210           above, with some extra convenience methods.
211
212           Parameters are:
213
214           *   string - the string to calculate the bounding box for.
215               Required.
216
217           *   size - the font size to use.  Default: value set in
218               Imager::Font->new(), or 15.
219
220           *   sizew - the font width to use.  Default to the value of the
221               "size" parameter.
222
223           *   utf8 - For drivers that support it, treat the string as UTF8
224               encoded.  For versions of perl that support Unicode (5.6 and
225               later), this will be enabled automatically if the 'string'
226               parameter is already a UTF8 string. See UTF8 for more informa‐
227               tion.  Default: the "utf8" value passed to
228               Imager::Font->new(...) or 0.
229
230           *   x, y - offsets applied to @box[0..3] to give you a adjusted
231               bounding box.  Ignored in scalar context.
232
233           *   canon - if non-zero and the "x", "y" parameters are not sup‐
234               plied, then $pos_width and $global_ascent values will returned
235               as the width and height of the text instead.
236
237       string
238           The $img->string(...) method is now documented in "string" in
239           Imager::Draw
240
241       align(string=>$text, size=>$size, x=>..., y=>..., valign => ...,
242       halign=>...)
243           Higher level text output - outputs the text aligned as specified
244           around the given point (x,y).
245
246             # "Hello" centered at 100, 100 in the image.
247             my ($left, $top, $right, $bottom) =
248               $font->align(string=>"Hello",
249                            x=>100, y=>100,
250                            halign=>'center', valign=>'center',
251                            image=>$image);
252
253           Takes the same parameters as $font->draw(), and the following extra
254           parameters:
255
256           valign
257               Possible values are:
258
259               top Point is at the top of the text.
260
261               bottom
262                   Point is at the bottom of the text.
263
264               baseline
265                   Point is on the baseline of the text (default.)
266
267               center
268                   Point is vertically centered within the text.
269
270           halign
271               left
272                   The point is at the left of the text.
273
274               start
275                   The point is at the start point of the text.
276
277               center
278                   The point is horizontally centered within the text.
279
280               right
281                   The point is at the right end of the text.
282
283               end The point is at the end point of the text.
284
285           image
286               The image to draw to.  Set to "undef" to avoid drawing but
287               still calculate the bounding box.
288
289           Returns a list specifying the bounds of the drawn text.
290
291       dpi()
292       dpi(xdpi=>$xdpi, ydpi=>$ydpi)
293       dpi(dpi=>$dpi)
294           Set or retrieve the spatial resolution of the image in dots per
295           inch.  The default is 72 dpi.
296
297           This isn't implemented for all font types yet.
298
299           Possible parameters are:
300
301           *   xdpi, ydpi - set the horizontal and vertical resolution in dots
302               per inch.
303
304           *   dpi - set both horizontal and vertical resolution to this
305               value.
306
307           Returns a list containing the previous xdpi, ydpi values.
308
309       transform(matrix=>$matrix)
310           Applies a transformation to the font, where matrix is an array ref
311           of numbers representing a 2 x 3 matrix:
312
313             [  $matrix->[0],  $matrix->[1],  $matrix->[2],
314                $matrix->[3],  $matrix->[4],  $matrix->[5]   ]
315
316           Not all font types support transformations, these will return
317           false.
318
319           It's possible that a driver will disable hinting if you use a
320           transformation, to prevent discontinuities in the transformations.
321           See the end of the test script t/t38ft2font.t for an example.
322
323           Currently only the ft2 (Freetype 2.x) driver supports the trans‐
324           form() method.
325
326           See samples/slant_text.pl for a sample using this function.
327
328           Note that the transformation is done in font co-ordinates where y
329           increases as you move up, not image co-ordinates where y decreases
330           as you move up.
331
332       has_chars(string=>$text)
333           Checks if the characters in $text are defined by the font.
334
335           In a list context returns a list of true or false value correspond‐
336           ing to the characters in $text, true if the character is defined,
337           false if not.  In scalar context returns a string of NUL or non-NUL
338           characters.  Supports UTF8 where the font driver supports UTF8.
339
340           Not all fonts support this method (use $font->can("has_chars") to
341           check.)
342
343           *   string - string of characters to check for.  Required.  Must
344               contain at least one character.
345
346           *   utf8 - For drivers that support it, treat the string as UTF8
347               encoded.  For versions of perl that support Unicode (5.6 and
348               later), this will be enabled automatically if the 'string'
349               parameter is already a UTF8 string. See UTF8 for more informa‐
350               tion.  Default: the "utf8" value passed to
351               Imager::Font->new(...) or 0.
352
353       face_name()
354           Returns the internal name of the face.  Not all font types support
355           this method yet.
356
357       glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
358           Returns a list of glyph names for each of the characters in the
359           string.  If the character has no name then "undef" is returned for
360           the character.
361
362           Some font files do not include glyph names, in this case Freetype 2
363           will not return any names.  Freetype 1 can return standard names
364           even if there are no glyph names in the font.
365
366           Freetype 2 has an API function that returns true only if the font
367           has "reliable glyph names", unfortunately this always returns false
368           for TTF fonts.  This can avoid the check of this API by supplying
369           "reliable_only" as 0.  The consequences of using this on an unknown
370           font may be unpredictable, since the Freetype documentation doesn't
371           say how those name tables are unreliable, or how FT2 handles them.
372
373           Both Freetype 1.x and 2.x allow support for glyph names to not be
374           included.
375
376       draw
377           This is used by Imager's string() method to implement drawing text.
378           See "string" in Imager::Draw.
379

MULTIPLE MASTER FONTS

381       The Freetype 2 driver supports multiple master fonts:
382
383       is_mm()
384           Test if the font is a multiple master font.
385
386       mm_axes()
387           Returns a list of the axes that can be changes in the font.  Each
388           entry is an array reference which contains:
389
390           1.  Name of the axis.
391
392           2.  minimum value for this axis.
393
394           3.  maximum value for this axis
395
396       set_mm_coords(coords=>\@values)
397           Blends an interpolated design from the master fonts.  @values must
398           contain as many values as there are axes in the font.
399
400       For example, to select the minimum value in each axis:
401
402         my @axes = $font->mm_axes;
403         my @coords = map $_->[1], @axes;
404         $font->set_mm_coords(coords=>\@coords);
405
406       It's possible other drivers will support multiple master fonts in the
407       future, check if your selected font object supports the is_mm() method
408       using the can() method.
409

UTF8

411       There are 2 ways of rendering Unicode characters with Imager:
412
413       ·   For versions of perl that support it, use perl's native UTF8
414           strings.  This is the simplest method.
415
416       ·   Hand build your own UTF8 encoded strings.  Only recommended if your
417           version of perl has no UTF8 support.
418
419       Imager won't construct characters for you, so if want to output unicode
420       character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and your font
421       doesn't support it, Imager will not build it from 0041 "LATIN CAPITAL
422       LETTER A" and 0308 "COMBINING DIAERESIS".
423
424       To check if a driver supports UTF8 call the utf8 method:
425
426       utf8
427           Return true if the font supports UTF8.
428
429       Native UTF8 Support
430
431       If your version of perl supports UTF8 and the driver supports UTF8,
432       just use the $im->string() method, and it should do the right thing.
433
434       Build your own
435
436       In this case you need to build your own UTF8 encoded characters.
437
438       For example:
439
440        $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
441
442       You need to be be careful with versions of perl that have UTF8 support,
443       since your string may end up doubly UTF8 encoded.
444
445       For example:
446
447        $x = "A\xE2\x80\x90\x41\x{2010}";
448        substr($x, -1, 0) = "";
449        # at this point $x is has the UTF8 flag set, but has 5 characters,
450        # none, of which is the constructed UTF8 character
451
452       The test script t/t38ft2font.t has a small example of this after the
453       comment:
454
455         # an attempt using emulation of UTF8
456

DRIVER CONTROL

458       If you don't supply a 'type' parameter to Imager::Font->new(), but you
459       do supply a 'file' parameter, Imager will attempt to guess which font
460       driver to used based on the extension of the font file.
461
462       Since some formats can be handled by more than one driver, a priority
463       list is used to choose which one should be used, if a given format can
464       be handled by more than one driver.
465
466       priorities
467           The current priorities can be retrieved with:
468
469             @drivers = Imager::Font->priorities();
470
471           You can set new priorities and save the old priorities with:
472
473             @old = Imager::Font->priorities(@drivers);
474
475       If you supply driver names that are not currently supported, they will
476       be ignored.
477
478       Imager supports both T1Lib and Freetype2 for working with Type 1 fonts,
479       but currently only T1Lib does any caching, so by default T1Lib is given
480       a higher priority.  Since Imager's Freetype2 support can also do font
481       transformations, you may want to give that a higher priority:
482
483         my @old = Imager::Font->priorities(qw(tt ft2 t1));
484

AUTHOR

486       Arnar M. Hrafnkelsson, addi@umich.edu And a great deal of help from
487       others - see the README for a complete list.
488

BUGS

490       You need to modify this class to add new font types.
491
492       The $pos_width member returned by the bounding_box() method has histor‐
493       ically returned different values from different drivers.  The Freetype
494       1.x and 2.x, and the Win32 drivers return the max of the advance width
495       and the right edge of the right-most glyph.  The Type 1 driver always
496       returns the right edge of the right-most glyph.
497
498       The newer advance_width and right_bearing values allow access to any of
499       the above.
500

REVISION

502       $Revision: 1263 $
503