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

DESCRIPTION

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

MULTIPLE MASTER FONTS

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

UTF-8

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

DRIVER CONTROL

466       If you don't supply a 'type' parameter to Imager::Font->new(), but you
467       do supply a 'file' parameter, Imager will attempt to guess which font
468       driver to used based on the extension of the font file.
469
470       Since some formats can be handled by more than one driver, a priority
471       list is used to choose which one should be used, if a given format can
472       be handled by more than one driver.
473
474       priorities
475           The current priorities can be retrieved with:
476
477             @drivers = Imager::Font->priorities();
478
479           You can set new priorities and save the old priorities with:
480
481             @old = Imager::Font->priorities(@drivers);
482
483           If you supply driver names that are not currently supported, they
484           will be ignored.
485
486           Imager supports both T1Lib and FreeType 2 for working with Type 1
487           fonts, but currently only T1Lib does any caching, so by default
488           T1Lib is given a higher priority.  Since Imager's FreeType 2
489           support can also do font transformations, you may want to give that
490           a higher priority:
491
492             my @old = Imager::Font->priorities(qw(tt ft2 t1));
493
494       register
495           Registers an extra font driver.  Accepts the following parameters:
496
497           ·   type - a brief identifier for the font driver.  You can supply
498               this value to "Imager::Font->new()" to create fonts of this
499               type.  Required.
500
501           ·   class - the font class name.  Imager will attempted to load
502               this module by name.  Required.
503
504           ·   files - a regular expression to match against file names.  If
505               supplied this must be a valid perl regular expression.  If not
506               supplied you can only create fonts of this type by supplying
507               the "type" parameter to "Imager::Font->new()"
508
509           ·   description - a brief description of the font driver.  Defaults
510               to the value supplied in "class".
511

AUTHOR

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

BUGS

517       The $pos_width member returned by the bounding_box() method has
518       historically returned different values from different drivers.  The
519       FreeType 1.x and 2.x, and the Win32 drivers return the max of the
520       advance width and the right edge of the right-most glyph.  The Type 1
521       driver always returns the right edge of the right-most glyph.
522
523       The newer advance_width and right_bearing values allow access to any of
524       the above.
525

REVISION

527       $Revision$
528