1HarfBuzz::Shaper(3)   User Contributed Perl Documentation  HarfBuzz::Shaper(3)
2
3
4

NAME

6       HarfBuzz::Shaper - Use HarfBuzz for text shaping
7

SYNOPSIS

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
16       The result is an array of hashes, one element for each glyph to be
17       typeset.
18

DESCRIPTION

20       HarfBuzz::Shaper is a perl module that provides access to a small
21       subset of the native HarfBuzz library.
22
23       The subset is suitable for typesetting programs that need to deal with
24       complex languages like Devanagari, Hebrew or Arabic.
25
26       This module is intended to be used with module Text::Layout. Feel free
27       to (ab)use it for other purposes.
28
29       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
33           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
40       Note that the number of glyphs does not necessarily match the number of
41       input characters!
42

DISCLAIMER

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
48       <https://lists.freedesktop.org/mailman/listinfo/harfbuzz>
49

METHODS

51   $hb = HarfBuzz::Shaper->new( [ options ] )
52       Creates a new shaper object.
53
54       Options:
55
56font = > font filename
57
58size = > text size
59
60   $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
64   $hb->set_font( font filename [ , size ] )
65       Explicit way to set the font (and, optionally, the size) used for
66       shaping.
67
68       The settings persist across shaper() calls. Call without arguments to
69       remove the settings.
70
71       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
75   $hb->set_size( size )
76       Explicit way to set the font size used for shaping.
77
78       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
82       The setting persist across shaper() calls. Call without arguments to
83       remove the setting.
84
85   $hb->set_text( text [ , ... ] )
86       Sets the text to shape. Multiple arguments are concatenated.
87
88       Note that the text must be Perl strings.
89
90       The setting persist across shaper() calls. Call without arguments to
91       remove the setting.
92
93   $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
100       Multiple feature strings may be supplied.
101
102       Call without arguments to remove the persistent features.
103
104   $hb->add_features( feat [ , ... ] )
105       Just like set_features, but the specified features are added to the set
106       of persistent features.
107
108   $hb->set_language( lang )
109       Sets the language for shaping. lang must be a string containing a valid
110       BCP-47 language code.
111
112       The setting persist across shaper() calls. Call without arguments to
113       remove the setting.
114
115   $hb->get_language
116       Returns the language currently set for this shaper, as a string.
117
118       When called after a successful shaper() call, it returns the actual
119       value used by shaper().
120
121   $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
126       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
129       The setting persist across shaper() calls. Call without arguments to
130       remove the setting.
131
132   $hb->get_script
133       Returns the script currently set for this shaper, as a string.
134
135       When called after a successful shaper() call, it returns the actual
136       value used by shaper().
137
138   $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
143       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
146       The setting persist across shaper() calls. Call without arguments to
147       remove the setting.
148
149   $hb->get_direction
150       Returns the direction currently set for this shaper, as a string.
151
152       When called after a successful shaper() call, it returns the actual
153       value used by shaper().
154
155   $info = $hb->shaper( [ ref to features ] )
156       Performs the actual shape operation.
157
158       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
165       Upon completion an array of hashes is returned with one element for
166       each glyph to be rendered.
167
168       The hash contains the following items:
169
170           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
177       Note that the number of glyphs does not necessarily match the number of
178       input characters!
179
180   $info = $hb->get_extents
181       Get the extents of the (shaped) buffer.
182
183       Upon completion an array of hashes is returned with one element for
184       each glyph.
185
186       The hash contains the following items:
187
188           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
194       The values are scaled to the font size as set with set_size().
195
196       Note that the number of glyphs does not necessarily match the number of
197       input characters!
198
199   $info = $hb->get_font_extents(dir)
200       Get the extents of the font in the given direction.
201
202       dir may be omitted, it defaults to the direction currently set, or
203       'ltr' if no direction was set.
204
205       Upon completion returns a hash with the following items:
206
207           ascend     The height of typographic ascenders.
208           descend    The height of typographic ascenders.
209           line_gap   The suggested line-spacing gap.
210
211       The values are scaled to the font size as set with set_size().
212
213       Note that typically ascender is positive and descender negative, in
214       coordinate systems that grow up.
215

SEE ALSO

217       Text::Layout
218
219       HarfBuzz website and documentation:
220       <https://harfbuzz.github.io/index.html>.
221

BUGS AND DEFICIENCIES

223       It probably leaks memory. We'll see.
224

SUPPORT AND DOCUMENTATION

226       Development of this module takes place on GitHub:
227       https://github.com/sciurius/perl-HarfBuzz-Shaper.
228
229       You can find documentation for this module with the perldoc command.
230
231           perldoc HarfBuzz::Shaper
232
233       Please report any bugs or feature requests using the issue tracker on
234       GitHub.
235
236       HarfBuzz website and documentation:
237       <https://harfbuzz.github.io/index.html>.
238
240       Copyright (C) 2020 by Johan Vromans
241
242       This library is free software; you can redistribute it and/or modify it
243       under the same terms as Perl itself.
244
245
246
247perl v5.36.0                      2023-01-20               HarfBuzz::Shaper(3)
Impressum