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
56       •   font = > font filename
57
58       •   size = > 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

SEE ALSO

181       Text::Layout
182
183       HarfBuzz website and documentation:
184       <https://harfbuzz.github.io/index.html>.
185

BUGS AND DEFICIENCIES

187       It probably leaks memory. We'll see.
188

SUPPORT AND DOCUMENTATION

190       Development of this module takes place on GitHub:
191       https://github.com/sciurius/perl-HarfBuzz-Shaper.
192
193       You can find documentation for this module with the perldoc command.
194
195           perldoc HarfBuzz::Shaper
196
197       Please report any bugs or feature requests using the issue tracker on
198       GitHub.
199
200       HarfBuzz website and documentation:
201       <https://harfbuzz.github.io/index.html>.
202

204       Copyright (C) 2020 by Johan Vromans
205
206       This library is free software; you can redistribute it and/or modify it
207       under the same terms as Perl itself.
208
209
210
211perl v5.34.0                      2021-07-22               HarfBuzz::Shaper(3)
Impressum