Provided by: libharfbuzz-shaper-perl_0.031+ds-1_amd64 
NAME
HarfBuzz::Shaper - Use HarfBuzz for text shaping
SYNOPSIS
use HarfBuzz::Shaper;
my $hb = HarfBuzz::Shaper->new;
$hb->set_font('LiberationSans.ttf');
$hb->set_size(36);
$hb->set_text("Hello!");
my $info = $hb->shaper;
The result is an array of hashes, one element for each glyph to be typeset.
DESCRIPTION
HarfBuzz::Shaper is a perl module that provides access to a small subset of the native HarfBuzz library.
The subset is suitable for typesetting programs that need to deal with complex languages like Devanagari,
Hebrew or Arabic.
This module is intended to be used with module Text::Layout. Feel free to (ab)use it for other purposes.
Following the above example, the returned info is an array of hashes, one element for each glyph to be
typeset. The hash contains the following items:
ax: horizontal advance
ay: vertical advance
dx: horizontal offset
dy: vertical offset
g: glyph index in font (CId)
name: glyph name
Note that the number of glyphs does not necessarily match the number of input characters!
DISCLAIMER
This module provides a thin interface layer between Perl and the native HarfBuzz library. It is agnostic
with regard to the details of multi-language typesetting. HarfBuzz has a friendly community to help you.
<https://lists.freedesktop.org/mailman/listinfo/harfbuzz>
METHODS
$hb = HarfBuzz::Shaper->new( [ options ] )
Creates a new shaper object.
Options:
• font = > font filename
• size = > text size
$hb->reset( [ full ] )
Reset (clear) the buffer settings for font, size, language, direction and script. With full, also clears
the font cache.
$hb->set_font( font filename [ , size ] )
Explicit way to set the font (and, optionally, the size) used for shaping.
The settings persist across shaper() calls. Call without arguments to remove the settings.
The font must be a TrueType or OpenType font. Font information is cached internally, after the first call
subsequent calls with the same font filename are very fast.
$hb->set_size( size )
Explicit way to set the font size used for shaping.
Note that the font size will in general affect details of the appearance, A 5 point fontsize magnified 10
times is not identical to 50 point font size.
The setting persist across shaper() calls. Call without arguments to remove the setting.
$hb->set_text( text [ , ... ] )
Sets the text to shape. Multiple arguments are concatenated.
Note that the text must be Perl strings.
The setting persist across shaper() calls. Call without arguments to remove the setting.
$hb->set_features( feat [ , ... ] )
Sets persistent features for shaping. Features are strings as described in
<https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string> and
<https://css-tricks.com/almanac/properties/f/font-feature-settings/#values>.
Multiple feature strings may be supplied.
Call without arguments to remove the persistent features.
$hb->add_features( feat [ , ... ] )
Just like set_features, but the specified features are added to the set of persistent features.
$hb->set_language( lang )
Sets the language for shaping. lang must be a string containing a valid BCP-47 language code.
The setting persist across shaper() calls. Call without arguments to remove the setting.
$hb->get_language
Returns the language currently set for this shaper, as a string.
When called after a successful shaper() call, it returns the actual value used by shaper().
$hb->set_script( script )
Sets the script (alphabet) for shaping. script must be a string containing a valid ISO-15924 script code.
For example, "Latn" for the Latin (Western European) script, or "Arab" for arabic script.
If you don't set a script, shaper() will make a guess based on the text string. This may or may not yield
desired results.
The setting persist across shaper() calls. Call without arguments to remove the setting.
$hb->get_script
Returns the script currently set for this shaper, as a string.
When called after a successful shaper() call, it returns the actual value used by shaper().
$hb->set_direction( dir )
Sets the direction for shaping. dir must be a string containing a valid direction setting: LTR (left-to-
right), RTL (right-to-left), TTB (top-to-bottom), or BTT (bottom-to-top).
If you don't set a direction, shaper() will make a guess based on the text string. This may or may not
yield desired results.
The setting persist across shaper() calls. Call without arguments to remove the setting.
$hb->get_direction
Returns the direction currently set for this shaper, as a string.
When called after a successful shaper() call, it returns the actual value used by shaper().
$info = $hb->shaper( [ ref to features ] )
Performs the actual shape operation.
features is a reference to an array of feature strings. The features will be added to the list of
features already set with set_features/add_features. If the first (or only) feature is "none" all current
features will be ignored and only subsequent features are taken into account. Changes apply to this call
only, the persistent set of featutes is not modified.
Upon completion an array of hashes is returned with one element for each glyph to be rendered.
The hash contains the following items:
ax: horizontal advance
ay: vertical advance
dx: horizontal offset
dy: vertical offset
g: glyph index in font (CId)
name: glyph name
Note that the number of glyphs does not necessarily match the number of input characters!
$info = $hb->get_extents
Get the extents of the (shaped) buffer.
Upon completion an array of hashes is returned with one element for each glyph.
The hash contains the following items:
x_bearing Distance from the x-origin to the left extremum of the glyph.
y_bearing Distance from the top extremum of the glyph to the y-origin.
width; Distance from the left extremum of the glyph to the right extremum.
height Distance from the top extremum of the glyph to the bottom extremum.
g Glyph index in font (CId)
The values are scaled to the font size as set with set_size().
Note that the number of glyphs does not necessarily match the number of input characters!
$info = $hb->get_font_extents(dir)
Get the extents of the font in the given direction.
dir may be omitted, it defaults to the direction currently set, or 'ltr' if no direction was set.
Upon completion returns a hash with the following items:
ascend The height of typographic ascenders.
descend The height of typographic ascenders.
line_gap The suggested line-spacing gap.
The values are scaled to the font size as set with set_size().
Note that typically ascender is positive and descender negative, in coordinate systems that grow up.
SEE ALSO
Text::Layout
HarfBuzz website and documentation: <https://harfbuzz.github.io/index.html>.
BUGS AND DEFICIENCIES
It probably leaks memory. We'll see.
SUPPORT AND DOCUMENTATION
Development of this module takes place on GitHub: https://github.com/sciurius/perl-HarfBuzz-Shaper.
You can find documentation for this module with the perldoc command.
perldoc HarfBuzz::Shaper
Please report any bugs or feature requests using the issue tracker on GitHub.
HarfBuzz website and documentation: <https://harfbuzz.github.io/index.html>.
COPYRIGHT AND LICENCE
Copyright (C) 2020,2025 by Johan Vromans
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
perl v5.40.0 2025-02-01 HarfBuzz::Shaper(3pm)