1HarfBuzz::Shaper(3) User Contributed Perl Documentation HarfBuzz::Shaper(3)
2
6 HarfBuzz::Shaper - Use HarfBuzz for text shaping
7
9 use HarfBuzz::Shaper;
10 my $hb = HarfBuzz::Shaper->new;
11 $hb->set_font('LiberationSans.ttf');
12 $hb->set_size(36);
13 $hb->set_text("Hello!");
14 my $info = $hb->shaper;
15 The result is an array of hashes, one element for each glyph to be
17 typeset.
18
20 HarfBuzz::Shaper is a perl module that provides access to a small
21 subset of the native HarfBuzz library.
22 The subset is suitable for typesetting programs that need to deal with
24 complex languages like Devanagari, Hebrew or Arabic.
25 This module is intended to be used with module Text::Layout. Feel free
27 to (ab)use it for other purposes.
28 Following the above example, the returned info is an array of hashes,
30 one element for each glyph to be typeset. The hash contains the
31 following items:
32 ax: horizontal advance
34 ay: vertical advance
35 dx: horizontal offset
36 dy: vertical offset
37 g: glyph index in font (CId)
38 name: glyph name
39 Note that the number of glyphs does not necessarily match the number of
41 input characters!
42
44 This module provides a thin interface layer between Perl and the native
45 HarfBuzz library. It is agnostic with regard to the details of multi-
46 language typesetting. HarfBuzz has a friendly community to help you.
47 <https://lists.freedesktop.org/mailman/listinfo/harfbuzz>
49
51 $hb = HarfBuzz::Shaper->new( [ options ] )
52 Creates a new shaper object.
53 Options:
55 • font = > font filename
57 • size = > text size
59 $hb->reset( [ full ] )
61 Reset (clear) the buffer settings for font, size, language, direction
62 and script. With full, also clears the font cache.
63 $hb->set_font( font filename [ , size ] )
65 Explicit way to set the font (and, optionally, the size) used for
66 shaping.
67 The settings persist across shaper() calls. Call without arguments to
69 remove the settings.
70 The font must be a TrueType or OpenType font. Font information is
72 cached internally, after the first call subsequent calls with the same
73 font filename are very fast.
74 $hb->set_size( size )
76 Explicit way to set the font size used for shaping.
77 Note that the font size will in general affect details of the
79 appearance, A 5 point fontsize magnified 10 times is not identical to
80 50 point font size.
81 The setting persist across shaper() calls. Call without arguments to
83 remove the setting.
84 $hb->set_text( text [ , ... ] )
86 Sets the text to shape. Multiple arguments are concatenated.
87 Note that the text must be Perl strings.
89 The setting persist across shaper() calls. Call without arguments to
91 remove the setting.
92 $hb->set_features( feat [ , ... ] )
94 Sets persistent features for shaping. Features are strings as described
95 in
96 <https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>
97 and
98 <https://css-tricks.com/almanac/properties/f/font-feature-settings/#values>.
99 Multiple feature strings may be supplied.
101 Call without arguments to remove the persistent features.
103 $hb->add_features( feat [ , ... ] )
105 Just like set_features, but the specified features are added to the set
106 of persistent features.
107 $hb->set_language( lang )
109 Sets the language for shaping. lang must be a string containing a valid
110 BCP-47 language code.
111 The setting persist across shaper() calls. Call without arguments to
113 remove the setting.
114 $hb->get_language
116 Returns the language currently set for this shaper, as a string.
117 When called after a successful shaper() call, it returns the actual
119 value used by shaper().
120 $hb->set_script( script )
122 Sets the script (alphabet) for shaping. script must be a string
123 containing a valid ISO-15924 script code. For example, "Latn" for the
124 Latin (Western European) script, or "Arab" for arabic script.
125 If you don't set a script, shaper() will make a guess based on the text
127 string. This may or may not yield desired results.
128 The setting persist across shaper() calls. Call without arguments to
130 remove the setting.
131 $hb->get_script
133 Returns the script currently set for this shaper, as a string.
134 When called after a successful shaper() call, it returns the actual
136 value used by shaper().
137 $hb->set_direction( dir )
139 Sets the direction for shaping. dir must be a string containing a valid
140 direction setting: LTR (left-to-right), RTL (right-to-left), TTB (top-
141 to-bottom), or BTT (bottom-to-top).
142 If you don't set a direction, shaper() will make a guess based on the
144 text string. This may or may not yield desired results.
145 The setting persist across shaper() calls. Call without arguments to
147 remove the setting.
148 $hb->get_direction
150 Returns the direction currently set for this shaper, as a string.
151 When called after a successful shaper() call, it returns the actual
153 value used by shaper().
154 $info = $hb->shaper( [ ref to features ] )
156 Performs the actual shape operation.
157 features is a reference to an array of feature strings. The features
159 will be added to the list of features already set with
160 set_features/add_features. If the first (or only) feature is "none" all
161 current features will be ignored and only subsequent features are taken
162 into account. Changes apply to this call only, the persistent set of
163 featutes is not modified.
164 Upon completion an array of hashes is returned with one element for
166 each glyph to be rendered.
167 The hash contains the following items:
169 ax: horizontal advance
171 ay: vertical advance
172 dx: horizontal offset
173 dy: vertical offset
174 g: glyph index in font (CId)
175 name: glyph name
176 Note that the number of glyphs does not necessarily match the number of
178 input characters!
179 $info = $hb->get_extents
181 Get the extents of the (shaped) buffer.
182 Upon completion an array of hashes is returned with one element for
184 each glyph.
185 The hash contains the following items:
187 x_bearing Distance from the x-origin to the left extremum of the glyph.
189 y_bearing Distance from the top extremum of the glyph to the y-origin.
190 width; Distance from the left extremum of the glyph to the right extremum.
191 height Distance from the top extremum of the glyph to the bottom extremum.
192 g Glyph index in font (CId)
193 The values are scaled to the font size as set with set_size().
195 Note that the number of glyphs does not necessarily match the number of
197 input characters!
198 $info = $hb->get_font_extents(dir)
200 Get the extents of the font in the given direction.
201 dir may be omitted, it defaults to the direction currently set, or
203 'ltr' if no direction was set.
204 Upon completion returns a hash with the following items:
206 ascend The height of typographic ascenders.
208 descend The height of typographic ascenders.
209 line_gap The suggested line-spacing gap.
210 The values are scaled to the font size as set with set_size().
212 Note that typically ascender is positive and descender negative, in
214 coordinate systems that grow up.
215
217 Text::Layout
218 HarfBuzz website and documentation:
220 <https://harfbuzz.github.io/index.html>.
221
223 It probably leaks memory. We'll see.
224
226 Development of this module takes place on GitHub:
227 https://github.com/sciurius/perl-HarfBuzz-Shaper.
228 You can find documentation for this module with the perldoc command.
230 perldoc HarfBuzz::Shaper
232 Please report any bugs or feature requests using the issue tracker on
234 GitHub.
235 HarfBuzz website and documentation:
237 <https://harfbuzz.github.io/index.html>.
238
240 Copyright (C) 2020 by Johan Vromans
241 This library is free software; you can redistribute it and/or modify it
243 under the same terms as Perl itself.
244perl v5.36.0 2023-01-20 HarfBuzz::Shaper(3)