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           Returns the new font object on success. Returns "undef" on failure
153           and sets an error message readable with "Imager->errstr".
154
155       bounding_box()
156           Returns the bounding box for the specified string.  Example:
157
158             my ($neg_width,
159                 $global_descent,
160                 $pos_width,
161                 $global_ascent,
162                 $descent,
163                 $ascent,
164                 $advance_width,
165                 $right_bearing) = $font->bounding_box(string => "A Fool");
166
167             my $bbox_object = $font->bounding_box(string => "A Fool");
168
169           $neg_width
170               the relative start of a the string.  In some cases this can be
171               a negative number, in that case the first letter stretches to
172               the left of the starting position that is specified in the
173               string method of the Imager class
174
175           $global_descent
176               how far down the lowest letter of the entire font reaches below
177               the baseline (this is often j).
178
179           $pos_width
180               how wide the string from the starting position is.  The total
181               width of the string is "$pos_width-$neg_width".
182
183           $descent
184           $ascent
185               the same as <$global_descent> and <$global_ascent> except that
186               they are only for the characters that appear in the string.
187
188           $advance_width
189               the distance from the start point that the next string output
190               should start at, this is often the same as $pos_width, but can
191               be different if the final character overlaps the right side of
192               its character cell.
193
194           $right_bearing
195               The distance from the right side of the final glyph to the end
196               of the advance width.  If the final glyph overflows the advance
197               width this value is negative.
198
199           Obviously we can stuff all the results into an array just as well:
200
201             @metrics = $font->bounding_box(string => "testing 123");
202
203           Note that extra values may be added, so $metrics[-1] isn't
204           supported.  It's possible to translate the output by a passing
205           coordinate to the bounding box method:
206
207             @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
208
209           This gives the bounding box as if the string had been put down at
210           "(x,y)" By giving bounding_box 'canon' as a true value it's
211           possible to measure the space needed for the string:
212
213             @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
214
215           This returns the same values in $metrics[0] and $metrics[1], but:
216
217            $bbox[2] - horizontal space taken by glyphs
218            $bbox[3] - vertical space taken by glyphs
219
220           Returns an Imager::Font::BBox object in scalar context, so you can
221           avoid all those confusing indexes.  This has methods as named
222           above, with some extra convenience methods.
223
224           Parameters are:
225
226           ·   "string" - the string to calculate the bounding box for.
227               Required.
228
229           ·   "size" - the font size to use.  Default: value set in
230               Imager::Font->new(), or 15.
231
232           ·   "sizew" - the font width to use.  Default to the value of the
233               "size" parameter.
234
235           ·   "utf8" - For drivers that support it, treat the string as UTF-8
236               encoded.  For versions of perl that support Unicode (5.6 and
237               later), this will be enabled automatically if the 'string'
238               parameter is already a UTF-8 string. See "UTF-8" for more
239               information.  Default: the "utf8" value passed to
240               Imager::Font->new(...) or 0.
241
242           ·   "x", "y" - offsets applied to @box[0..3] to give you a adjusted
243               bounding box.  Ignored in scalar context.
244
245           ·   "canon" - if non-zero and the "x", "y" parameters are not
246               supplied, then $pos_width and $global_ascent values will
247               returned as the width and height of the text instead.
248
249           On success returns either the list of bounds, or a bounding box
250           object in scalar context.  Returns an empty list or "undef" on
251           failure and sets an error message readable with "Imager->errstr".
252
253           The transformation matrix set by "transform()" has no effect on the
254           result of this method - the bounds of the untransformed text is
255           returned.
256
257       string()
258           The $img->string(...) method is now documented in "string()" in
259           Imager::Draw
260
261       align(string=>$text,size=>$size,x=>...,y=>...,valign =>
262       ...,halign=>...)
263           Higher level text output - outputs the text aligned as specified
264           around the given point (x,y).
265
266             # "Hello" centered at 100, 100 in the image.
267             my ($left, $top, $right, $bottom) =
268               $font->align(string=>"Hello",
269                            x=>100, y=>100,
270                            halign=>'center', valign=>'center',
271                            image=>$image);
272
273           Takes the same parameters as $font->draw(), and the following extra
274           parameters:
275
276           ·   "valign" - Possible values are:
277
278               "top"
279                   Point is at the top of the text.
280
281               "bottom"
282                   Point is at the bottom of the text.
283
284               "baseline"
285                   Point is on the baseline of the text (default.)
286
287               "center"
288                   Point is vertically centered within the text.
289
290           ·   "halign"
291
292               ·   "left" - the point is at the left of the text.
293
294               ·   "start" - the point is at the start point of the text.
295
296               ·   "center" - the point is horizontally centered within the
297                   text.
298
299               ·   "right" - the point is at the right end of the text.
300
301               ·   "end" - the point is at the end point of the text.
302
303           ·   "image" - The image to draw to.  Set to "undef" to avoid
304               drawing but still calculate the bounding box.
305
306           Returns a list specifying the bounds of the drawn text on success.
307           Returns an empty list on failure, if an "image" parameter was
308           supplied the error message can be read with "$image->errstr",
309           otherwise it's available as "Imager->errstr".
310
311       dpi()
312       dpi(xdpi=>$xdpi, ydpi=>$ydpi)
313       dpi(dpi=>$dpi)
314           Set or retrieve the spatial resolution of the image in dots per
315           inch.  The default is 72 dpi.
316
317           This isn't implemented for all font types yet.
318
319           Possible parameters are:
320
321           ·   "xdpi", "ydpi" - set the horizontal and vertical resolution in
322               dots per inch.
323
324           ·   "dpi" - set both horizontal and vertical resolution to this
325               value.
326
327           Returns a list containing the previous "xdpi", "ydpi" values on
328           success.  Returns an empty list on failure, with an error message
329           returned in "Imager->errstr".
330
331       transform()
332             $font->transform(matrix=>$matrix);
333
334           Applies a transformation to the font, where matrix is an array ref
335           of numbers representing a 2 x 3 matrix:
336
337             [  $matrix->[0],  $matrix->[1],  $matrix->[2],
338                $matrix->[3],  $matrix->[4],  $matrix->[5]   ]
339
340           Not all font types support transformations, these will return
341           false.
342
343           It's possible that a driver will disable hinting if you use a
344           transformation, to prevent discontinuities in the transformations.
345           See the end of the test script t/t38ft2font.t for an example.
346
347           Currently only the ft2 (FreeType 2.x) driver supports the
348           transform() method.
349
350           See samples/slant_text.pl for a sample using this function.
351
352           Note that the transformation is done in font co-ordinates where y
353           increases as you move up, not image co-ordinates where y decreases
354           as you move up.
355
356           "transform()" has no effect on the results of "bounding_box()".
357
358           Returns true on success.  Returns false on failure with the cause
359           readable from "Imager->errstr".
360
361       has_chars(string=>$text)
362           Checks if the characters in $text are defined by the font.
363
364           In a list context returns a list of true or false value
365           corresponding to the characters in $text, true if the character is
366           defined, false if not.  In scalar context returns a string of "NUL"
367           or non-"NUL" characters.  Supports UTF-8 where the font driver
368           supports UTF-8.
369
370           Not all fonts support this method (use $font->can("has_chars") to
371           check.)
372
373           On error, returns an empty list or undef in scalar context, and
374           sets an error message readable with "Imager->errstr".
375
376           ·   "string" - string of characters to check for.  Required.  Must
377               contain at least one character.
378
379           ·   "utf8" - For drivers that support it, treat the string as UTF-8
380               encoded.  For versions of perl that support Unicode (5.6 and
381               later), this will be enabled automatically if the 'string'
382               parameter is already a UTF-8 string. See "UTF-8" for more
383               information.  Default: the "utf8" value passed to
384               Imager::Font->new(...) or 0.
385
386       face_name()
387           Returns the internal name of the face.  Not all font types support
388           this method yet, so you should check with "$font->can("face_name")"
389           before calling "face_name".
390
391       glyph_names(string=>$string [, utf8=>$utf8 ][, reliable_only=>0 ] );
392           Returns a list of glyph names for each of the characters in the
393           string.  If the character has no name then "undef" is returned for
394           the character.
395
396           Some font files do not include glyph names, in this case FreeType 2
397           will not return any names.  FreeType 1 can return standard names
398           even if there are no glyph names in the font.
399
400           FreeType 2 has an API function that returns true only if the font
401           has "reliable glyph names", unfortunately this always returns false
402           for TrueType fonts.  This can avoid the check of this API by
403           supplying "reliable_only" as 0.  The consequences of using this on
404           an unknown font may be unpredictable, since the FreeType
405           documentation doesn't say how those name tables are unreliable, or
406           how FT2 handles them.
407
408           Both FreeType 1.x and 2.x allow support for glyph names to not be
409           included.
410
411           If the supplied "string" is marked as UTF-8 or the "utf8" parameter
412           is true and the supplied string does not contain valid UTF-8,
413           returns an empty string and set an error message readable from
414           "Imager->errstr",
415
416       can_glyph_names()
417           As a class method, returns true if the underlying library supports
418           returning glyph names.
419
420           As an object method, returns true if the supplied font supports
421           returning glyph names.
422
423       draw
424           This is used by Imager's string() method to implement drawing text.
425           See "string()" in Imager::Draw.
426

MULTIPLE MASTER FONTS

428       The FreeType 2 driver supports multiple master fonts:
429
430       is_mm()
431           Test if the font is a multiple master font.
432
433       mm_axes()
434           Returns a list of the axes that can be changes in the font.  Each
435           entry is an array reference which contains:
436
437           1.  Name of the axis.
438
439           2.  minimum value for this axis.
440
441           3.  maximum value for this axis
442
443       set_mm_coords(coords=>\@values)
444           Blends an interpolated design from the master fonts.  @values must
445           contain as many values as there are axes in the font.
446
447       For example, to select the minimum value in each axis:
448
449         my @axes = $font->mm_axes;
450         my @coords = map $_->[1], @axes;
451         $font->set_mm_coords(coords=>\@coords);
452
453       It's possible other drivers will support multiple master fonts in the
454       future, check if your selected font object supports the is_mm() method
455       using the can() method.
456

UTF-8

458       There are 2 ways of rendering Unicode characters with Imager:
459
460       ·   For versions of perl that support it, use perl's native UTF-8
461           strings.  This is the simplest method.
462
463       ·   Hand build your own UTF-8 encoded strings.  Only recommended if
464           your version of perl has no UTF-8 support.
465
466       Imager won't construct characters for you, so if want to output Unicode
467       character 00C3 "LATIN CAPITAL LETTER A WITH DIAERESIS", and your font
468       doesn't support it, Imager will not build it from 0041 "LATIN CAPITAL
469       LETTER A" and 0308 "COMBINING DIAERESIS".
470
471       To check if a driver supports UTF-8 call the utf8() method:
472
473       utf8()
474           Return true if the font supports UTF-8.
475
476   Native UTF-8 Support
477       If your version of perl supports UTF-8 and the driver supports UTF-8,
478       just use the $im->string() method, and it should do the right thing.
479
480   Build your own
481       In this case you need to build your own UTF-8 encoded characters.
482
483       For example:
484
485        $x = pack("C*", 0xE2, 0x80, 0x90); # character code 0x2010 HYPHEN
486
487       You need to be careful with versions of perl that have UTF-8 support,
488       since your string may end up doubly UTF-8 encoded.
489
490       For example:
491
492        $x = "A\xE2\x80\x90\x41\x{2010}";
493        substr($x, -1, 0) = "";
494        # at this point $x is has the UTF-8 flag set, but has 5 characters,
495        # none, of which is the constructed UTF-8 character
496
497       The test script t/t38ft2font.t has a small example of this after the
498       comment:
499
500         # an attempt using emulation of UTF-8
501

DRIVER CONTROL

503       If you don't supply a 'type' parameter to Imager::Font->new(), but you
504       do supply a 'file' parameter, Imager will attempt to guess which font
505       driver to used based on the extension of the font file.
506
507       Since some formats can be handled by more than one driver, a priority
508       list is used to choose which one should be used, if a given format can
509       be handled by more than one driver.
510
511       priorities
512           The current priorities can be retrieved with:
513
514             @drivers = Imager::Font->priorities();
515
516           You can set new priorities and save the old priorities with:
517
518             @old = Imager::Font->priorities(@drivers);
519
520           If you supply driver names that are not currently supported, they
521           will be ignored.
522
523           Imager supports both T1Lib and FreeType 2 for working with Type 1
524           fonts, but currently only T1Lib does any caching, so by default
525           T1Lib is given a higher priority.  Since Imager's FreeType 2
526           support can also do font transformations, you may want to give that
527           a higher priority:
528
529             my @old = Imager::Font->priorities(qw(tt ft2 t1));
530
531       register
532           Registers an extra font driver.  Accepts the following parameters:
533
534           ·   type - a brief identifier for the font driver.  You can supply
535               this value to "Imager::Font->new()" to create fonts of this
536               type.  Required.
537
538           ·   class - the font class name.  Imager will attempted to load
539               this module by name.  Required.
540
541           ·   files - a regular expression to match against file names.  If
542               supplied this must be a valid perl regular expression.  If not
543               supplied you can only create fonts of this type by supplying
544               the "type" parameter to "Imager::Font->new()"
545
546           ·   description - a brief description of the font driver.  Defaults
547               to the value supplied in "class".
548

AUTHOR

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

BUGS

554       The $pos_width member returned by the bounding_box() method has
555       historically returned different values from different drivers.  The
556       FreeType 1.x and 2.x, and the Win32 drivers return the max of the
557       advance width and the right edge of the right-most glyph.  The Type 1
558       driver always returns the right edge of the right-most glyph.
559
560       The newer advance_width and right_bearing values allow access to any of
561       the above.
562

REVISION

564       $Revision$
565