Skip to content

class HbFace

A font face is an object that represents a single face from within a font family.

More precisely, a font face represents a single face in a binary font file. Font faces are typically built from a binary blob and a face index. Font faces are used to create fonts.

Wraps hb_face_t.

Reference:

😱 Types incomplete or incorrect? 🙏 Please contribute!

methods

HbFace.new_from_blob

function HbFace.new_from_blob(
  blob: Blob {
    new = function,
    new_from_file = function,
    get_length = function,
    get_data = function,
},
  font_index: integer?
) ->  HbFace?
@param blob - Blob to read the font from.

@param font_index - index of font to read.

Constructs a new face object from the specified blob and a face index into that blob.

The face index is used for blobs of file formats such as TTC and DFont that can contain more than one face. Face indices within such collections are zero-based.

Wraps hb_face_create.

Reference:

HbFace.new

function HbFace.new(
  file: string,
  font_index: integer?
) ->  HbFace?
@param file - path to font file.

@param font_index - index of font to read.

Create a new Face from a file.

Makes a call to Face:new_from_blob after creating a Blob from the file contents.

Wraps hb_face_create.

Example:

local face = luaharfbuzz.Face.new('xxx')
print(face) -- nil

face = luaharfbuzz.Face.new(
           '/usr/share/fonts/truetype/noto/NotoSans-Regular.ttf')
if face ~= nil then
    print(face) -- harfbuzz.Face: 0x12426a8
end

Reference:

HbFace.collect_unicodes

function HbFace.collect_unicodes() ->  number[]

@return - of codepoints supported by the face.

😱 Types incomplete or incorrect? 🙏 Please contribute!

for _, char in ipairs(face:collect_unicodes()) do print(char, unicode.utf8.char(char)) end 

__Reference:__

* Corresponding C source code: [face.c#L264-L284](https://github.com/ufyTeX/luaharfbuzz/blob/b3bdf5dc7a6e3f9b674226140c3dfdc73d2970cd/src/luaharfbuzz/face.c#L264-L284)
* HarfBuzz online documentation: [hb_face_collect_unicodes](https://harfbuzz.github.io/harfbuzz-hb-face.html#hb-face-collect-unicodes)








### HbFace.get_glyph_count
---
```lua
function HbFace.get_glyph_count() -> glyph_count integer

Fetch the glyph-count value of the specified face object.

Wraps hb_face_get_glyph_count.

Reference:

HbFace.get_name

function HbFace.get_name(
  name_id: integer,
  lang: HbLanguage?
) ->  string?

local name_id = 0 local name repeat name = face:get_name(name_id) print(name_id, name) name_id = name_id + 1 until (name == nil) 

__Reference:__

* Corresponding C source code: [face.c#L54-L80](https://github.com/ufyTeX/luaharfbuzz/blob/b3bdf5dc7a6e3f9b674226140c3dfdc73d2970cd/src/luaharfbuzz/face.c#L54-L80)
* HarfBuzz online documentation: [hb_ot_name_get_utf8](https://harfbuzz.github.io/harfbuzz-hb-ot-name.html#hb-ot-name-get-utf8)








### HbFace.get_table
---
```lua
function HbFace.get_table(tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
}) ->  Blob {
    new = function,
    new_from_file = function,
    get_length = function,
    get_data = function,
}
@param tag - Tag object of the table.

@return - Blob object for the face table of tag.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Fetch a reference to the specified table within the specified face.

Wraps hb_face_reference_table.

Reference:

HbFace.get_table_tags

function HbFace.get_table_tags() ->  HbTag[]

@return - table of Tags representing face table tags.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Fetch a list of all table tags for a face, if possible. The list returned will begin at the offset provided.

Wraps hb_face_get_table_tags.

Reference:

HbFace.get_upem

function HbFace.get_upem() ->  integer

@return - The upem value of face.

😱 Types incomplete or incorrect? 🙏 Please contribute!

print('Units per em', face:get_upem()) -- 1000 

__Reference:__

* Corresponding C source code: [face.c#L286-L291](https://github.com/ufyTeX/luaharfbuzz/blob/b3bdf5dc7a6e3f9b674226140c3dfdc73d2970cd/src/luaharfbuzz/face.c#L286-L291)
* HarfBuzz online documentation: [hb_face_get_upem](https://harfbuzz.github.io/harfbuzz-hb-face.html#hb-face-get-upem)








### HbFace.ot_color_has_palettes
---
```lua
function HbFace.ot_color_has_palettes() ->  boolean

@return - true if data found, false otherwise

😱 Types incomplete or incorrect? 🙏 Please contribute!

Tests whether a face includes a CPAL color-palette table.

Wraps hb_ot_color_has_palettes.

Reference:

HbFace.ot_color_palette_get_count

function HbFace.ot_color_palette_get_count() ->  integer

@return - The number of palettes found.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Fetch the number of color palettes in a face.

Wraps hb_ot_color_palette_get_count.

Reference:

HbFace.ot_color_palette_get_colors

function HbFace.ot_color_palette_get_colors() ->  HbColor[]

Fetch a list of the colors in a color palette.

Wraps hb_ot_color_palette_get_colors.

Reference:

HbFace.ot_color_has_layers

function HbFace.ot_color_has_layers() ->  boolean

@return - true if data found, false otherwise

😱 Types incomplete or incorrect? 🙏 Please contribute!

Test whether a face includes a COLR table with data according to COLRv0.

Wraps hb_ot_color_has_layers.

Reference:

HbFace.ot_color_glyph_get_layers

function HbFace.ot_color_glyph_get_layers(glyph: integer) ->  HbGlyphColor[]
@param glyph - The glyph index to query

Fetches a list of all color layers for the specified glyph index in the specified face. The list returned will begin at the offset provided.

Wraps hb_ot_color_glyph_get_layers.

Reference:

HbFace.ot_color_has_png

function HbFace.ot_color_has_png() ->  boolean

@return - true if data found, false otherwise

😱 Types incomplete or incorrect? 🙏 Please contribute!

Test whether a face has PNG glyph images (either in CBDT or sbix tables).

Wraps hb_ot_color_has_png.

Reference:

HbFace.ot_layout_get_script_tags

function HbFace.ot_layout_get_script_tags(table_tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
}) ->  HbTag[]
@param table_tag - OpenType Glyph Substitution Table (gsub) or OpenType Glyph Positioning Table (gpos).

Fetch a list of all scripts enumerated in the specified face's GSUB table or GPOS table.

Wraps hb_ot_layout_table_get_script_tags.

Reference:

HbFace.ot_layout_get_language_tags

function HbFace.ot_layout_get_language_tags(
  table_tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
},
  script_index: integer
) ->  HbTag[]
@param table_tag - OpenType Glyph Substitution Table (gsub) or OpenType Glyph Positioning Table (gpos).

@param script_index - The index of the requested script tag

Fetch a list of language tags in the given face's GSUB or GPOS table, underneath the specified script index.

Wraps hb_ot_layout_script_get_language_tags.

Reference:

HbFace.ot_layout_get_feature_tags

function HbFace.ot_layout_get_feature_tags(
  table_tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
},
  script_index: integer,
  language_index: integer
) ->  HbTag[]
@param table_tag - OpenType Glyph Substitution Table (gsub) or OpenType Glyph Positioning Table (gpos).

@param script_index - The index of the requested script tag

@param language_index - The index of the requested language tag

@return - The array of HbTag feature tags found for the query.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Wraps hb_ot_layout_language_get_feature_tags.

Reference:

HbFace.ot_layout_find_script

function HbFace.ot_layout_find_script(
  table_tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
},
  script_tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
}
)
 -> found boolean
 -> index integer
@param table_tag - OpenType Glyph Substitution Table (gsub) or OpenType Glyph Positioning Table (gpos).

@param script_tag - The HbTag script tag requested

@return found - true if the script is found, false otherwise

@return index - The index of the requested script tag.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Fetch the index if a given script tag in the specified face's GSUB table or GPOS table.

Wraps hb_ot_layout_table_find_script.

Reference:

@deprecated Deprecated

HbFace.ot_layout_find_language

function HbFace.ot_layout_find_language(
  tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
},
  script_index: integer,
  language_tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
}
)
 -> found boolean
 -> index integer
@param tag - OpenType Glyph Substitution Table (gsub) or OpenType Glyph Positioning Table (gpos).

@param script_index - The index of the requested script tag.

@param language_tag - The HbTag of the requested language.

@return found - true if the language tag is found, false otherwise

@return index - The index of the requested language.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Fetch the index of a given language tag in the specified face's GSUB table or GPOS table, underneath the specified script tag.

Wraps hb_ot_layout_script_find_language.

Reference:

HbFace.ot_layout_find_feature

function HbFace.ot_layout_find_feature(
  tag: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
},
  script_index: integer,
  language_index: integer,
  feature: HbTag {
    new = function,
    __to_string = function,
    __eq = function,
}
)
 -> found boolean
 -> index integer
@param tag - OpenType Glyph Substitution Table (gsub) or OpenType Glyph Positioning Table (gpos).

@param script_index - The index of the requested script tag.

@param language_index - The index of the requested language tag.

@param feature - The feature tag requested.

@return found - true if the feature is found, false otherwise

@return index - The index of the requested feature.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Fetches the index of a given feature tag in the specified face's GSUB table or GPOS table, underneath the specified script and language.

Wraps hb_ot_layout_language_find_feature.

Reference: