package harfbuzz
Import Path
github.com/go-text/typesetting/harfbuzz (on go.dev)
Dependency Relation
imports 13 packages, and imported by 2 packages
Involved Source Files
aat_layout.go
aat_layout_kerx.go
aat_layout_morx.go
aat_layout_trak.go
aat_map.go
buffer.go
caches.go
font.go
glyph.go
Package harfbuzz provides advanced text layout for various scripts and languages,
with font-aware substitutions and positionning.
Given a font and an input specified as runes, the package shapes this input
and returns a slice of positionned glyphs, identified by their index in the font.
See `Buffer` and its methods for more details.
This package is a direct port of the C/C++ library.
intset.go
ot_kern.go
ot_language.go
ot_language_table.go
ot_layout.go
ot_layout_gpos.go
ot_layout_gsub.go
ot_layout_gsubgpos.go
ot_map.go
ot_shape.go
ot_shape_arabic.go
ot_shape_arabic_table.go
ot_shape_arabic_win1256.go
ot_shape_complex.go
ot_shape_fallback.go
ot_shape_hangul.go
ot_shape_hebrew.go
ot_shape_indic.go
ot_shape_indic_machine.go
ot_shape_indic_table.go
ot_shape_khmer.go
ot_shape_khmer_machine.go
ot_shape_myanmar.go
ot_shape_myanmar_machine.go
ot_shape_normalize.go
ot_shape_thai.go
ot_shape_use.go
ot_shape_use_machine.go
ot_shape_use_machine_defs.go
ot_shape_use_table.go
ot_shape_vowels_constraints.go
ot_tag.go
set_digest.go
shape.go
unicode.go
Package-Level Type Names (total 14)
Buffer is the main structure holding the input text segment and its properties before shaping,
and output glyphs and their information after shaping.
Precise the cluster handling behavior.
Information about how the text in the buffer should be treated.
Info is used as internal storage during the shaping,
and also exposes the result: the glyph to display
and its original Cluster value.
Glyph that replaces invisible characters in
the shaping result. If set to zero (default), the glyph for the
U+0020 SPACE character is used. Otherwise, this value is used
verbatim.
Glyph that replaces characters not found in the font during shaping.
The not-found glyph defaults to zero, sometimes known as the
".notdef" glyph.
Pos gives the position of the glyphs resulting from the shapping
It has the same length has `Info`.
Props is required to correctly interpret the input runes.
AddRune appends a character with the Unicode value of `codepoint` to `b`, and
gives it the initial cluster value of `cluster`. Clusters can be any thing
the client wants, they are usually used to refer to the index of the
character in the input text stream and are output in the
`GlyphInfo.Cluster` field.
This also clears the posterior context (see `AddRunes`).
AddRunes appends characters from `text` array to `b`. `itemOffset` is the
position of the first character from `text` that will be appended, and
`itemLength` is the number of character to add (-1 means the end of the slice).
When shaping part of a larger text (e.g. a run of text from a paragraph),
instead of passing just the substring
corresponding to the run, it is preferable to pass the whole
paragraph and specify the run start and length as `itemOffset` and
`itemLength`, respectively, to give HarfBuzz the full context to be able,
for example, to do cross-run Arabic shaping or properly handle combining
marks at start of run.
The cluster value attributed to each rune is the index in the `text` slice.
Clear resets `b` to its initial empty state (including user settings).
This method should be used to reuse the allocated memory.
GuessSegmentProperties fills unset buffer segment properties based on buffer Unicode
contents and can be used when no other information is available.
If buffer `Props.Script` is zero, it
will be set to the Unicode script of the first character in
the buffer that has a script other than Common,
Inherited, and Unknown.
Next, if buffer `Props.Direction` is zero,
it will be set to the natural horizontal direction of the
buffer script, defaulting to `LeftToRight`.
Finally, if buffer Props.Language is empty,
it will be set to the process's default language.
Reverse reverses buffer contents, that is the order of the `Info` and `Pos` slices.
Shape shapes the buffer using `font`, turning its Unicode characters content to
positioned glyphs. If `features` is not empty, it will be used to control the
features applied during shaping. If two features have the same tag but
overlapping ranges the value of the feature with the higher index takes
precedence.
The shapping plan depends on the font capabilities. See `NewFont` and `Face` and
its extension interfaces for more details.
It also depends on the properties of the segment of text : the `Props`
field of the buffer must be set before calling `Shape`.
func NewBuffer() *Buffer
ClusterLevel allows selecting more fine-grained Cluster handling.
It defaults to `MonotoneGraphemes`.
( ClusterLevel) String() string
ClusterLevel : expvar.Var
ClusterLevel : fmt.Stringer
const Characters
const MonotoneCharacters
const MonotoneGraphemes
Direction is the text direction.
The zero value is the initial, unset, invalid direction.
Reverses a text direction. Requires that the direction
is valid.
func Direction.Reverse() Direction
func github.com/go-text/typesetting/di.Direction.Harfbuzz() Direction
func (*Font).ExtentsForDirection(direction Direction) font.FontExtents
func (*Font).GetOTLigatureCarets(direction Direction, glyph GID) []Position
func (*Font).GlyphAdvanceForDirection(glyph GID, dir Direction) (x, y Position)
const BottomToTop
const LeftToRight
const RightToLeft
const TopToBottom
Feature holds information about requested
feature application. The feature will be applied with the given value to all
glyphs which are in clusters between `start` (inclusive) and `end` (exclusive).
Setting start to `FeatureGlobalStart` and end to `FeatureGlobalEnd`
specifies that the feature always applies to the entire buffer.
The cluster to End applying this feature setting (exclusive)
The cluster to Start applying this feature setting (inclusive)
Tag ot.Tag
Value of the feature: 0 disables the feature, non-zero (usually
1) enables the feature. For features implemented as lookup type 3 (like
'salt') `Value` is a one-based index into the alternates.
func ParseFeature(feature string) (Feature, error)
func (*Buffer).Shape(font *Font, features []Feature)
Font is used internally as a wrapper around the provided Face.
Font are constructed with `NewFont` and adjusted by accessing the fields
Ptem, XScale, YScale.
Fonts private fields only depend on the provided [*font.Font], so a Font object is suitable for caching.
Point size of the font. Set to zero to unset.
This is used in AAT layout, when applying 'trak' table.
Horizontal and vertical scale of the font.
The font scale is a number related to, but not the same as,
font size. Typically the client establishes a scale factor
to be used between the two. For example, 64, or 256, which
would be the fractional-precision part of the font scale.
This is necessary because [Position] values are integer
types and you need to leave room for fractional values
in there.
For example, to set the font size to 20, with 64
levels of fractional precision you would use a scale of
20 * 64.
In the example above, even what font size 20 means is up to
you. It might be 20 pixels, or 20 points, or 20 millimeters.
HarfBuzz does not care about that. You can set the point
size of the font using [Ptem], and the pixel
size using [Face.Ppem]
The choice of scale is yours but needs to be consistent between
what you set here, and what you expect out of [Position]
as well has draw / paint API output values.
Fonts default to a scale equal to the UPEM value of their face.
A font with this setting is sometimes called an "unscaled" font.
The resulting positions are computed with: fontUnit * Scale / faceUpem,
where faceUpem is given by the face.
Given a device resolution (in dpi) and a point size, the scale to
get result in pixels is given by : pointSize * dpi / 72
Horizontal and vertical scale of the font.
The font scale is a number related to, but not the same as,
font size. Typically the client establishes a scale factor
to be used between the two. For example, 64, or 256, which
would be the fractional-precision part of the font scale.
This is necessary because [Position] values are integer
types and you need to leave room for fractional values
in there.
For example, to set the font size to 20, with 64
levels of fractional precision you would use a scale of
20 * 64.
In the example above, even what font size 20 means is up to
you. It might be 20 pixels, or 20 points, or 20 millimeters.
HarfBuzz does not care about that. You can set the point
size of the font using [Ptem], and the pixel
size using [Face.Ppem]
The choice of scale is yours but needs to be consistent between
what you set here, and what you expect out of [Position]
as well has draw / paint API output values.
Fonts default to a scale equal to the UPEM value of their face.
A font with this setting is sometimes called an "unscaled" font.
The resulting positions are computed with: fontUnit * Scale / faceUpem,
where faceUpem is given by the face.
Given a device resolution (in dpi) and a point size, the scale to
get result in pixels is given by : pointSize * dpi / 72
ExtentsForDirection fetches the extents for a font in a text segment of the
specified direction, applying the scaling.
Calls the appropriate direction-specific variant (horizontal
or vertical) depending on the value of `direction`.
Face returns the underlying face.
Note that field is readonly, since some caching may happen
in the `NewFont` constructor.
GetOTLigatureCarets fetches a list of the caret positions defined for a ligature glyph in the GDEF
table of the font (or nil if not found).
GlyphAdvanceForDirection fetches the advance for a glyph ID from the specified font,
in a text segment of the specified direction.
Calls the appropriate direction-specific variant (horizontal
or vertical) depending on the value of `dir`.
GlyphExtents fetches the GlyphExtents data for a glyph ID
in the specified font, or false if not found
GlyphHAdvance fetches the advance for a glyph ID in the font,
for horizontal text segments.
SetVarCoordsDesign applies a list of variation coordinates, in design-space units,
to the font.
func NewFont(face Face) *Font
func (*Buffer).Shape(font *Font, features []Feature)
GlyphExtents is the same as fonts.GlyphExtents but with int type
Height int32
Width int32
XBearing int32
YBearing int32
func (*Font).GlyphExtents(glyph GID) (out GlyphExtents, ok bool)
GlyphInfo holds information about the
glyphs and their relation to input text.
They are internally created from user input,
and the shapping sets the `Glyph` field.
Cluster is the index of the character in the original text that corresponds
to this `GlyphInfo`, or whatever the client passes to `Buffer.Add()`.
More than one glyph can have the same `Cluster` value,
if they resulted from the same character (e.g. one to many glyph substitution),
and when more than one character gets merged in the same glyph (e.g. many to one glyph substitution)
the glyph will have the smallest Cluster value of them.
By default some characters are merged into the same Cluster
(e.g. combining marks have the same Cluster as their bases)
even if they are separate glyphs.
See Buffer.ClusterLevel for more fine-grained Cluster handling.
Glyph is the result of the selection of concrete glyph
after shaping, and refers to the font used.
Mask exposes glyph attributes (see the constants).
It is also used internally during the shaping.
String returns a simple description of the glyph of the form Glyph=Cluster(mask)
GlyphInfo : expvar.Var
GlyphInfo : fmt.Stringer
GlyphPosition holds the positions of the
glyph in both horizontal and vertical directions.
All positions are relative to the current point.
How much the line advances after drawing this glyph when setting
text in horizontal direction.
How much the glyph moves on the X-axis before drawing it, this
should not affect how much the line advances.
How much the line advances after drawing this glyph when setting
text in vertical direction.
How much the glyph moves on the Y-axis before drawing it, this
should not affect how much the line advances.
Position stores a position, scaled according to the `Font`
scale parameters.
SegmentProperties holds various text properties of a `Buffer`.
Direction is the text flow direction of the buffer. No shaping can happen without
setting direction, and it controls the visual direction for the
output glyphs; for RTL direction the glyphs will be reversed. Many layout
features depend on the proper setting of the direction, for example,
reversing RTL text before shaping, then shaping with LTR direction is not
the same as keeping the text in logical order and shaping with RTL
direction.
Languages are crucial for selecting which OpenType feature to apply to the
buffer which can result in applying language-specific behaviour. Languages
are orthogonal to the scripts, and though they are related, they are
different concepts and should not be confused with each other.
Script is crucial for choosing the proper shaping behaviour for scripts that
require it (e.g. Arabic) and the OpenType features defined in the font
to be applied.
See the package language for predefined values.
ShappingOptions controls some fine tunning of the shaping
(see the constants).
const Bot
const DoNotinsertDottedCircle
const Eot
const PreserveDefaultIgnorables
const ProduceSafeToInsertTatweel
const ProduceUnsafeToConcat
const RemoveDefaultIgnorables
Package-Level Functions (total 5)
IsDefaultIgnorable returns `true` for
codepoints with the Default_Ignorable property
(as defined in unicode data DerivedCoreProperties.txt)
NewBuffer allocate a storage with default options.
It should then be populated with `AddRunes` and shapped with `Shape`.
NewFont constructs a new font object from the specified face.
The scale is set to the face Upem, meaning that by default
the output results will be expressed in font units.
The `face` object should not be modified after this call.
ParseFeature parses one feature string (usually coming from a comma-separated list of font features).
Features can be enabled or disabled, either globally or limited to
specific character ranges. The format for specifying feature settings
follows. All valid CSS font-feature-settings values other than 'normal'
and the global values are also accepted, though not documented below.
CSS string escapes are not supported.
The range indices refer to the positions between Unicode characters,
unless the --utf8-clusters is provided, in which case range indices
refer to UTF-8 byte indices. The position before the first character
is always 0.
The format is Python-esque. Here is how it all works:
Syntax: Value: Start: End:
Setting value:
"kern" 1 0 ∞ // Turn feature on
"+kern" 1 0 ∞ // Turn feature on
"-kern" 0 0 ∞ // Turn feature off
"kern=0" 0 0 ∞ // Turn feature off
"kern=1" 1 0 ∞ // Turn feature on
"aalt=2" 2 0 ∞ // Choose 2nd alternate
Setting index:
"kern[]" 1 0 ∞ // Turn feature on
"kern[:]" 1 0 ∞ // Turn feature on
"kern[5:]" 1 5 ∞ // Turn feature on, partial
"kern[:5]" 1 0 5 // Turn feature on, partial
"kern[3:5]" 1 3 5 // Turn feature on, range
"kern[3]" 1 3 3+1 // Turn feature on, single char
Mixing it all:
"aalt[3:5]=2" 2 3 5 // Turn 2nd alternate on for range
ParseVariation parse the string representation of a variation
of the form tag=value
Package-Level Constants (total 22)
Flag indicating that special handling of the beginning
of text paragraph can be applied to this buffer. Should usually
be set, unless you are passing to the buffer only part
of the text without the full context.
const BottomToTop Direction = 7 // Text is set vertically from bottom to top.
Don't group cluster values.
Non-base characters are assigned their
own cluster values, which are not merged into preceding base clusters. Moreover,
the cluster values are not merged into monotone order. This is the most granular
cluster level, and it is useful for clients that need to know the exact cluster
values of each character, but is harder to use for clients, since clusters
might appear in any order.
Special value for language index indicating default or unsupported language.
Flag indicating that a dotted circle should
not be inserted in the rendering of incorrect
character sequences (such at <0905 093E>).
Flag indicating that special handling of the end of text
paragraph can be applied to this buffer, similar to
`Bot`.
Special setting for `Feature.End` to apply the feature from to the end
of the buffer.
Special setting for `Feature.Start` to apply the feature from the start
of the buffer.
In scripts that use elongation (Arabic, Mongolian, Syriac, etc.), this flag signifies
that it is safe to insert a U+0640 TATWEEL character before this cluster for elongation.
This flag does not determine the script-specific elongation places, but only
when it is safe to do the elongation without interrupting text shaping.
Indicates that if input text is broken at the beginning of the cluster this glyph is part of,
then both sides need to be re-shaped, as the result might be different.
On the flip side, it means that when this flag is not present,
then it's safe to break the glyph-run at the beginning of this cluster,
and the two sides represent the exact same result one would get
if breaking input text at the beginning of this cluster and shaping the two sides
separately.
This can be used to optimize paragraph layout, by avoiding re-shaping
of each line after line-breaking.
Indicates that if input text is changed on one side of the beginning of the cluster this glyph
is part of, then the shaping results for the other side might change.
Note that the absence of this flag will NOT by itself mean that it IS safe to concat text.
Only two pieces of text both of which clear of this flag can be concatenated safely.
This can be used to optimize paragraph layout, by avoiding re-shaping of each line
after line-breaking, by limiting the reshaping to a small piece around the
breaking position only, even if the breaking position carries the
[GlyphUnsafeToBreak] or when hyphenation or other text transformation
happens at line-break position, in the following way:
1. Iterate back from the line-break position until the first cluster start position that is
NOT unsafe-to-concat,
2. Shape the segment from there till the end of line,
3. Check whether the resulting glyph-run also is clear of the unsafe-to-concat at its start-of-text position;
if it is, just splice it into place and the line is shaped; If not, move on to a position further
back that is clear of unsafe-to-concat and retry from there, and repeat.
At the start of next line a similar algorithm can be implemented. That is:
1. Iterate forward from the line-break position until the first cluster start position that is NOT unsafe-to-concat,
2. Shape the segment from beginning of the line to that position,
3. Check whether the resulting glyph-run also is clear of the unsafe-to-concat at its end-of-text position;
if it is, just splice it into place and the beginning is shaped; If not, move on to a position further forward that is clear
of unsafe-to-concat and retry up to there, and repeat.
A slight complication will arise in the implementation of the algorithm above, because while our buffer API has a way to
return flags for position corresponding to start-of-text, there is currently no position
corresponding to end-of-text. This limitation can be alleviated by shaping more text than needed
and looking for unsafe-to-concat flag within text clusters.
The [GlyphUnsafeToBreak] flag will always imply this flag.
To use this flag, you must enable the buffer flag [ProduceUnsafeToConcat] during
shaping, otherwise the buffer flag will not be reliably produced.
const LeftToRight Direction = 4 // Text is set horizontally from left to right.
Return cluster values grouped into monotone order.
Non-base characters are initially
assigned their own cluster values, which are not merged into preceding base
clusters. This allows HarfBuzz to perform additional operations like reorder
sequences of adjacent marks. The output is still monotone, but the cluster
values are more granular.
Return cluster values grouped by graphemes into monotone order.
Non-base characters are merged into the cluster of the base character that precedes them.
There is also cluster merging every time the clusters will otherwise become non-monotone.
Special value for feature index indicating unsupported feature.
Special value for script index indicating unsupported script.
Flag indication that character with Default_Ignorable
Unicode property should use the corresponding glyph
from the font, instead of hiding them (done by
replacing them with the space glyph and zeroing the
advance width.) This flag takes precedence over
`RemoveDefaultIgnorables`.
Flag indicating that the [GlyphSafeToInsertTatweel]
glyph-flag should be produced by the shaper. By default
it will not be produced.
Flag indicating that the [GlyphUnsafeToConcat]
glyph-flag should be produced by the shaper. By default
it will not be produced since it incurs a cost.
Flag indication that character with Default_Ignorable
Unicode property should be removed from glyph string
instead of hiding them (done by replacing them with the
space glyph and zeroing the advance width.)
`PreserveDefaultIgnorables` takes
precedence over this flag.
const RightToLeft Direction = 5 // Text is set horizontally from right to left. const TopToBottom Direction = 6 // Text is set vertically from top to bottom. |
The pages are generated with Golds v0.8.7. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds. |