Initial revision
[imager.git] / lib / Imager / Font.pm
CommitLineData
02d1d628
AMH
1package Imager::Font;
2
3use Imager::Color;
4use strict;
5use vars qw(%T1_Paths %TT_Paths %T1_Cache %TT_Cache $TT_CSize $TT_CSize $T1AA);
6
7# This class is a container
8# and works for both truetype and t1 fonts.
9
10
11# $T1AA is in there because for some reason (probably cache related) antialiasing
12# is a system wide setting in t1 lib.
13
14sub t1_set_aa_level {
15 if (!defined $T1AA or $_[0] != $T1AA) {
16 Imager::i_t1_set_aa($_[0]);
17 $T1AA=$_[0];
18 }
19}
20
21# search method
22# 1. start by checking if file is the parameter
23# 1a. if so qualify path and compare to the cache.
24# 2a. if in cache - take it's id from there and increment count.
25#
26
27sub new {
28 my $class = shift;
29 my $self ={};
30 my ($file,$type,$id);
31 my %hsh=(color=>Imager::Color->new(255,0,0,0),
32 size=>15,
33 @_);
34
35 bless $self,$class;
36
37 if ($hsh{'file'}) {
38 $file=$hsh{'file'};
39 if ( $file !~ m/^\// ) {
40 $file='./'.$file;
41 if (! -e $file) {
42 $Imager::ERRSTR="Font $file not found";
43 return();
44 }
45 }
46
47 $type=$hsh{'type'};
48 if (!defined($type) or $type !~ m/^(t1|tt)/) {
49 $type='tt' if $file =~ m/\.ttf$/i;
50 $type='t1' if $file =~ m/\.pfb$/i;
51 }
52 if (!defined($type)) {
53 $Imager::ERRSTR="Font type not found";
54 return;
55 }
56 } else {
57 $Imager::ERRSTR="No font file specified";
58 return;
59 }
60
61 if (!$Imager::formats{$type}) {
62 $Imager::ERRSTR="`$type' not enabled";
63 return;
64 }
65
66 # here we should have the font type or be dead already.
67
68 if ($type eq 't1') {
69 $id=Imager::i_t1_new($file);
70 }
71
72 if ($type eq 'tt') {
73 $id=Imager::i_tt_new($file);
74 }
75
76 $self->{'aa'}=$hsh{'aa'}||'0';
77 $self->{'file'}=$file;
78 $self->{'id'}=$id;
79 $self->{'type'}=$type;
80 $self->{'size'}=$hsh{'size'};
81 $self->{'color'}=$hsh{'color'};
82 return $self;
83}
84
85
86
87
88
89
90sub bounding_box {
91 my $self=shift;
92 my %input=@_;
93 my @box;
94
95 if (!exists $input{'string'}) { $Imager::ERRSTR='string parameter missing'; return; }
96
97 if ($self->{type} eq 't1') {
98 @box=Imager::i_t1_bbox($self->{id}, defined($input{size}) ? $input{size} :$self->{size},
99 $input{string}, length($input{string}));
100 }
101 if ($self->{type} eq 'tt') {
102 @box=Imager::i_tt_bbox($self->{id}, defined($input{size}) ? $input{size} :$self->{size},
103 $input{string}, length($input{string}));
104 }
105
106 if(exists $input{'x'} and exists $input{'y'}) {
107 my($gdescent, $gascent)=@box[1,3];
108 $box[1]=$input{'y'}-$gascent; # top = base - ascent (Y is down)
109 $box[3]=$input{'y'}-$gdescent; # bottom = base - descent (Y is down, descent is negative)
110 $box[0]+=$input{'x'};
111 $box[2]+=$input{'x'};
112 } elsif (exists $input{'canon'}) {
113 $box[3]-=$box[1]; # make it cannoical (ie (0,0) - (width, height))
114 $box[2]-=$box[0];
115 }
116 return @box;
117}
118
1191;
120
121
122
123__END__
124
125=head1 NAME
126
127Imager::Font - Font handling for Imager.
128
129=head1 SYNOPSIS
130
131 $t1font = Imager::Font->new(file => 'pathtofont.pfb');
132 $ttfont = Imager::Font->new(file => 'pathtofont.ttf');
133
134 $blue = Imager::Color->new("#0000FF");
135 $font = Imager::Font->new(file => 'pathtofont.ttf',
136 color => $blue,
137 size => 30);
138
139 ($neg_width,
140 $global_descent,
141 $pos_width,
142 $global_ascent,
143 $descent,
144 $ascent) = $font->bounding_box(string=>"Foo");
145
146 $logo = $font->logo(text => "Slartibartfast Enterprises",
147 size => 40,
148 border => 5,
149 color => $green);
150 # logo is proposed - doesn't exist yet
151
152
153 $img->string(font => $font,
154 text => "Model-XYZ",
155 x => 15,
156 y => 40,
157 size => 40,
158 color => $red
159 aa => 1);
160
161 # Documentation in Imager.pm
162
163=head1 DESCRIPTION
164
165This module handles creating Font objects used by imager. The module
166also handles querying fonts for sizes and such. If both T1lib and
167freetype were avaliable at the time of compilation then Imager should
168be able to work with both truetype fonts and t1 postscript fonts. To
169check if Imager is t1 or truetype capable you can use something like
170this:
171
172 use Imager;
173 print "Has truetype" if $Imager::formats{tt};
174 print "Has t1 postscript" if $Imager::formats{t1};
175
176
177=over 4
178
179=item new
180
181This creates a font object to pass to functions that take a font argument.
182
183 $font = Imager::Font->new(file => 'denmark.ttf',
184 color => $blue,
185 size => 30,
186 aa => 1);
187
188This creates a font which is the truetype font denmark.ttf. It's
189default color is $blue, default size is 30 pixels and it's rendered
190antialised by default. Imager can see which type of font a file is by
191looking at the suffix of the filename for the font. A suffix of 'ttf'
192is taken to mean a truetype font while a suffix of 'pfb' is taken to
193mean a t1 postscript font. If Imager cannot tell which type a font is
194you can tell it explicitly by using the C<type> parameter:
195
196 $t1font = Imager::Font->new(file => 'fruitcase', type => 't1');
197 $ttfont = Imager::Font->new(file => 'arglebarf', type => 'tt');
198
199If any of the C<color>, C<size> or C<aa> parameters are omitted when
200calling C<Imager::Font->new()> the they take the following values:
201
202
203 color => Imager::Color->new(255, 0, 0, 0); # this default should be changed
204 size => 15
205 aa => 0
206
207=item bounding_box
208Returns the bounding box for the specified string. Example:
209
210 ($neg_width,
211 $global_descent,
212 $pos_width,
213 $global_ascent,
214 $descent,
215 $ascent) = $font->bounding_box(string => "A Fool");
216
217The C<$neg_width> is the relative start of a the string. In some
218cases this can be a negative number, in that case the first letter
219stretches to the left of the starting position that is specified in
220the string method of the Imager class. <$global_descent> is the how
221far down the lowest letter of the entire font reaches below the
222baseline (this is often j). C<$pos_width> is how wide the string from
223from the starting position is. The total width of the string is
224C<$pos_width-$neg_width>. C<$descent> and C<$ascent> are the as
225<$global_descent> and <$global_ascent> except that they are only for
226the characters that appear in the string. Obviously we can stuff all
227the results into an array just as well:
228
229 @metrics = $font->bounding_box(string => "testing 123");
230
231Note that extra values may be added, so $metrics[-1] isn't supported.
232It's possible to translate the output by a passing coordinate to the
233bounding box method:
234
235 @metrics = $font->bounding_box(string => "testing 123", x=>45, y=>34);
236
237This gives the bounding box as if the string had been put down at C<(x,y)>
238By giving bounding_box 'canon' as a true value it's possible to measure
239the space needed for the string:
240
241 @metrics = $font->bounding_box(string=>"testing",size=>15,canon=>1);
242
243This returns tha same values in $metrics[0] and $metrics[1],
244but:
245
246 $bbox[2] - horizontal space taken by glyphs
247 $bbox[3] - vertical space taken by glyphs
248
249
250
251=item string
252
253This is a method of the Imager class but because it's described in
254here since it belongs to the font routines. Example:
255
256 $img=Imager->new();
257 $img=read(file=>"test.jpg");
258 $img->string(font=>$t1font,
259 text=>"Model-XYZ",
260 x=>0,
261 y=>40,
262 size=>40,
263 color=>$red);
264 $img->write(file=>"testout.jpg");
265
266This would put a 40 pixel high text in the top left corner of an
267image. If you measure the actuall pixels it varies since the fonts
268usually do not use their full height. It seems that the color and
269size can be specified twice. When a font is created only the actual
270font specified matters. It his however convenient to store default
271values in a font, such as color and size. If parameters are passed to
272the string function they are used instead of the defaults stored in
273the font.
274
275If string() is called with the C<channel> parameter then the color
276isn't used and the font is drawn in only one channel of the image.
277This can be quite handy to create overlays. See the examples for tips
278about this.
279
280Sometimes it is necessary to know how much space a string takes before
281rendering it. The bounding_box() method described earlier can be used
282for that.
283
284
285=item logo
286
287This method doesn't exist yet but is under consideration. It would mostly
288be helpful for generating small tests and such. Its proposed interface is:
289
290 $img = $font->logo(string=>"Plan XYZ", color=>$blue, border=>7);
291
292This would be nice for writing (admittedly multiline) one liners like:
293
294Imager::Font->new(file=>"arial.ttf", color=>$blue, aa=>1)
295 ->string(text=>"Plan XYZ", border=>5)
296 ->write(file=>"xyz.png");
297
298
299
300=back
301
302=head1 AUTHOR
303
304Arnar M. Hrafnkelsson, addi@umich.edu
305And a great deal of help from others - see the README for a complete
306list.
307
308=head1 SEE ALSO
309
310Imager(3)
311http://www.eecs.umich.edu/~addi/perl/Imager/
312
313=cut
314
315