[HarfBuzz] how to migrate from older harfbuzz to harfbuzz-ng

[Behdad Esfahbod]

Hi there,

On 11/30/10 01:27, suzuki toshiya wrote:

> Is there any document or good example showing how to migrate to harfbuzz-ng?

I should have answered earlier.  Anyway, here's the entirety of
harfbuzz-shaper.h with my inline annotations:

(Unfortunately I couldn't fix the broken lines in my email client :(.


-- 
-- typedef enum {
--         HB_Script_Common,
--         HB_Script_Greek,
--         HB_Script_Cyrillic,
...
--         HB_Script_Cuneiform = Common,
--         HB_Script_Phoenician = Common,
--         HB_Script_PhagsPa = Common,
--         */
-- } HB_Script;

hb_script_t.


-- typedef struct
-- {
--     hb_uint32 pos;
--     hb_uint32 length;
--     HB_Script script;
--     hb_uint8 bidiLevel;
-- } HB_ScriptItem;

We don't do itemization currently.  The script and bidiLevel should be set on
hb_buffer_t as script and direction.  pos and length are passed to
hb_buffer_add_utf*().


-- typedef enum {
--     HB_NoBreak,
--     HB_SoftHyphen,
--     HB_Break,
--     HB_ForcedBreak
-- } HB_LineBreakType;

We don't do line-breaking.  Doesn't belong in harfbuzz.



-- typedef struct {
--     /*HB_LineBreakType*/ unsigned lineBreakType  :2;
--     /*HB_Bool*/ unsigned whiteSpace              :1;     /* A unicode
whitespace character, except NBSP, ZWNBSP */
--     /*HB_Bool*/ unsigned charStop                :1;     /* Valid cursor
position (for left/right arrow) */
--     /*HB_Bool*/ unsigned wordBoundary            :1;
--     /*HB_Bool*/ unsigned sentenceBoundary        :1;
--     unsigned unused                  :2;
-- } HB_CharAttributes;
--
-- void HB_GetCharAttributes(const HB_UChar16 *string, hb_uint32 stringLength,
--                           const HB_ScriptItem *items, hb_uint32 numItems,
--                           HB_CharAttributes *attributes);
-- 
-- /* requires HB_GetCharAttributes to be called before */
-- void HB_GetWordBoundaries(const HB_UChar16 *string, hb_uint32 stringLength,
--                           const HB_ScriptItem *items, hb_uint32 numItems,
--                           HB_CharAttributes *attributes);
-- 
-- /* requires HB_GetCharAttributes to be called before */
-- void HB_GetSentenceBoundaries(const HB_UChar16 *string, hb_uint32 stringLength,
--                               const HB_ScriptItem *items, hb_uint32 numItems,
--                               HB_CharAttributes *attributes);

These line-breaking-related functions will not be in harfbuzz.  It's a
font-independent process.  Currently you can use pango_break() for example.
In the future I may move that logic into its own library or possibly add to
harfbuzz, but it's not currently planned.



-- typedef enum {
--     HB_LeftToRight = 0,
--     HB_RightToLeft = 1
-- } HB_StringToGlyphsFlags;

hb_direction_t.


-- typedef enum {
--     HB_ShaperFlag_Default = 0,
--     HB_ShaperFlag_NoKerning = 1,
--     HB_ShaperFlag_UseDesignMetrics = 2
-- } HB_ShaperFlag;

To turn kerning off one has to use the feature pair kern=0.  UseDesignMetrics
can be achieved by setting font ppem to 0,0.


-- /*
--    highest value means highest priority for justification. Justification is
done by first inserting kashidas
--    starting with the highest priority positions, then stretching spaces,
afterwards extending inter char
--    spacing, and last spacing between arabic words.
--    NoJustification is for example set for arabic where no Kashida can be
inserted or for diacritics.
-- */
-- typedef enum {
--     HB_NoJustification= 0,   /* Justification can't be applied after this
glyph */
--     HB_Arabic_Space   = 1,   /* This glyph represents a space inside arabic
text */
--     HB_Character      = 2,   /* Inter-character justification point follows
this glyph */
--     HB_Space          = 4,   /* This glyph represents a blank outside an
Arabic run */
--     HB_Arabic_Normal  = 7,   /* Normal Middle-Of-Word glyph that connects
to the right (begin) */
--     HB_Arabic_Waw     = 8,   /* Next character is final form of
Waw/Ain/Qaf/Fa */
--     HB_Arabic_BaRa    = 9,   /* Next two chars are Ba + Ra/Ya/AlefMaksura */
--     HB_Arabic_Alef    = 10,  /* Next character is final form of
Alef/Tah/Lam/Kaf/Gaf */
--     HB_Arabic_HaaDal  = 11,  /* Next character is final form of Haa/Dal/Taa
Marbutah */
--     HB_Arabic_Seen    = 12,  /* Initial or Medial form Of Seen/Sad */
--     HB_Arabic_Kashida = 13   /* Kashida(U+640) in middle of word */
-- } HB_JustificationClass;

We don't do justification currently.  When we do, I expect that we don't
expose these stuff publicly.



-- /* This structure is binary compatible with Uniscribe's SCRIPT_VISATTR.
Would be nice to keep
--  * it like that. If this is a problem please tell Trolltech :)
--  */
-- typedef struct {
--     unsigned justification   :4;  /* Justification class */
--     unsigned clusterStart    :1;  /* First glyph of representation of
cluster */
--     unsigned mark            :1;  /* needs to be positioned around base char */
--     unsigned zeroWidth       :1;  /* ZWJ, ZWNJ etc, with no width */
--     unsigned dontPrint       :1;
--     unsigned combiningClass  :8;
-- } HB_GlyphAttributes;

I need to add some of these to harfbuzz, but it currently doesn't exist.


-- typedef struct HB_FaceRec_ {
--     HB_Bool isSymbolFont;
-- 
--     HB_GDEF gdef;
--     HB_GSUB gsub;
--     HB_GPOS gpos;
--     HB_Bool supported_scripts[HB_ScriptCount];
--     HB_Buffer buffer;
--     HB_Script current_script;
--     int current_flags; /* HB_ShaperFlags */
--     HB_Bool has_opentype_kerning;
--     HB_Bool glyphs_substituted;
--     HB_GlyphAttributes *tmpAttributes;
--     unsigned int *tmpLogClusters;
--     int length;
--     int orig_nglyphs;
-- } HB_FaceRec;

Must of this is internal and opaque.  No need to have it publicly really.


-- typedef HB_Error (*HB_GetFontTableFunc)(void *font, HB_Tag tag, HB_Byte
*buffer, HB_UInt *length);
-- 
-- HB_Face HB_NewFace(void *font, HB_GetFontTableFunc tableFunc);
-- void HB_FreeFace(HB_Face face);

Various hb_face_* functions.


-- typedef struct {
--     HB_Fixed x, y;
--     HB_Fixed width, height;
--     HB_Fixed xOffset, yOffset;
-- } HB_GlyphMetrics;

This is confusing.  x,y are glyph position, and exist in hb_glyph_position_t.
 The rest are in hb_glyph_extents_t.


-- typedef enum {
--     HB_FontAscent
-- } HB_FontMetric;

We don't currently have this.  I'll add as needed when doing advanced fallback
shaping.  I need font ascent/descent plus font slant.


-- typedef struct {
--     HB_Bool  (*convertStringToGlyphIndices)(HB_Font font, const HB_UChar16
*string, hb_uint32 length, HB_Glyph *glyphs, hb_uint32 *numGlyphs, HB_Bool
rightToLeft);
--     void     (*getGlyphAdvances)(HB_Font font, const HB_Glyph *glyphs,
hb_uint32 numGlyphs, HB_Fixed *advances, int flags /*HB_ShaperFlag*/);
--     HB_Bool  (*canRender)(HB_Font font, const HB_UChar16 *string, hb_uint32
length);
--     /* implementation needs to make sure to load a scaled glyph, so /no/
FT_LOAD_NO_SCALE */
--     HB_Error (*getPointInOutline)(HB_Font font, HB_Glyph glyph, int flags
/*HB_ShaperFlag*/, hb_uint32 point, HB_Fixed *xpos, HB_Fixed *ypos, hb_uint32
*nPoints);
--     void     (*getGlyphMetrics)(HB_Font font, HB_Glyph glyph,
HB_GlyphMetrics *metrics);
--     HB_Fixed (*getFontMetric)(HB_Font font, HB_FontMetric metric);
-- } HB_FontClass;

hb_font_funcs_t and its accessors.


-- typedef struct HB_Font_ {
--     const HB_FontClass *klass;
-- 
--     /* Metrics */
--     HB_UShort x_ppem, y_ppem;
--     HB_16Dot16 x_scale, y_scale;
-- 
--     void *userData;
-- } HB_FontRec;

hb_font_t and its accessors.


-- typedef struct HB_ShaperItem_ HB_ShaperItem;
-- 
-- struct HB_ShaperItem_ {
--     const HB_UChar16 *string;               /* input: the Unicode UTF16
text to be shaped */
--     hb_uint32 stringLength;                 /* input: the length of the
input in 16-bit words */
--     HB_ScriptItem item;                     /* input: the current run to be
shaped: a run of text all in the same script that is a substring of <string> */
--     HB_Font font;                           /* input: the font: scale,
units and function pointers supplying glyph indices and metrics */
--     HB_Face face;                           /* input: the shaper state;
current script, access to the OpenType tables , etc. */
--     int shaperFlags;                        /* input (unused) should be set
to 0; intended to support flags defined in HB_ShaperFlag */
--     HB_Bool glyphIndicesPresent;            /* input: true if the <glyphs>
array contains glyph indices ready to be shaped */
--     hb_uint32 initialGlyphCount;            /* input: if
glyphIndicesPresent is true, the number of glyph indices in the <glyphs> array */

Various hb_shape() parameters.



--     hb_uint32 num_glyphs;                   /* input: capacity of output
arrays <glyphs>, <attributes>, <advances>, <offsets>, and <log_clusters>; */
--                                             /* output: required capacity
(may be larger than actual capacity) */
-- 
--     HB_Glyph *glyphs;                       /* output: <num_glyphs> indices
of shaped glyphs */
--     HB_GlyphAttributes *attributes;         /* output: <num_glyphs> glyph
attributes */
--     HB_Fixed *advances;                     /* output: <num_glyphs> advances */
--     HB_FixedPoint *offsets;                 /* output: <num_glyphs> offsets */
--     unsigned short *log_clusters;           /* output: for each output
glyph, the index in the input of the start of its logical cluster */

These are in hb_buffer_t.


--     /* internal */
--     HB_Bool kerning_applied;                /* output: true if kerning was
applied by the shaper */
-- };

Don't have right now.


-- HB_Bool HB_ShapeItem(HB_ShaperItem *item);

hb_shape().


Hope that helps.

behdad