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

MULTIPLE MASTER FONTS

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

UTF-8

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

DRIVER CONTROL

493       If you don't supply a 'type' parameter to Imager::Font->new(), but you
494       do supply a 'file' parameter, Imager will attempt to guess which font
495       driver to used based on the extension of the font file.
496
497       Since some formats can be handled by more than one driver, a priority
498       list is used to choose which one should be used, if a given format can
499       be handled by more than one driver.
500
501       priorities
502           The current priorities can be retrieved with:
503
504             @drivers = Imager::Font->priorities();
505
506           You can set new priorities and save the old priorities with:
507
508             @old = Imager::Font->priorities(@drivers);
509
510           If you supply driver names that are not currently supported, they
511           will be ignored.
512
513           Note that by default the priority list no longer includes "tt" and
514           "t1", so typically you will need to have Imager::Font::FT2
515           installed to create fonts with Imager.
516
517             my @old = Imager::Font->priorities(qw(tt ft2 t1));
518
519       register
520           Registers an extra font driver.  Accepts the following parameters:
521
522           •   type - a brief identifier for the font driver.  You can supply
523               this value to "Imager::Font->new()" to create fonts of this
524               type.  Required.
525
526           •   class - the font class name.  Imager will attempted to load
527               this module by name.  Required.
528
529           •   files - a regular expression to match against file names.  If
530               supplied this must be a valid perl regular expression.  If not
531               supplied you can only create fonts of this type by supplying
532               the "type" parameter to "Imager::Font->new()"
533
534           •   description - a brief description of the font driver.  Defaults
535               to the value supplied in "class".
536

AUTHOR

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

BUGS

542       The $pos_width member returned by the bounding_box() method has
543       historically returned different values from different drivers.  The
544       FreeType 1.x and 2.x, and the Win32 drivers return the max of the
545       advance width and the right edge of the right-most glyph.  The Type 1
546       driver always returns the right edge of the right-most glyph.
547
548       The newer advance_width and right_bearing values allow access to any of
549       the above.
550

REVISION

552       $Revision$
553