Class FT2::Face
In: ./ft2.c
Parent: Object
Methods
ascender    attach    available_sizes    bbox    bold?    char_index    charmap    charmaps    current_charmap    descender    external_stream?    faces    family    fast_glyphs?    first_char    fixed_sizes    fixed_sizes?    fixed_width?    flags    glyph    glyph_name    glyphs    height    horizontal?    index    initialize    italic?    kerning    kerning?    load    load_char    load_glyph    max_advance_height    max_advance_width    name_index    new    new_from_memory    next_char    num_charmaps    postscript_name    scalable?    select_charmap    set_char_size    set_charmap    set_pixel_sizes    set_transform    sfnt?    size    style    style_flags    underline_position    underline_thickness    units_per_em    vertical?   
Public Class methods
new(int argc, VALUE *argv, VALUE klass)

Allocate and initialize a new FT2::Face object.

Note: 

  FreeType2-Ruby creates a new (hidden) FT2::Library instance at
  runtime, which FT2::Face objects are automatically initialized with
  if an a library is not specified.

Aliases: 

  FT2::Face.load

Examples: 

  # load font from file "yudit.ttf"
  face = FT2::Face.new 'yudit.ttf'

  # load second face from from file "yudit.ttf"
  face = FT2::Face.new 'yudit.ttf', 1

  # load font from file "yudit.ttf" under FT2::Library instance lib
  face = FT2::Face.new lib, 'yudit.ttf'

  # load second face from file "yudit.ttf" under FT2::Library instance lib
  face = FT2::Face.new lib, 'yudit.ttf', 1
load(int argc, VALUE *argv, VALUE klass)

Allocate and initialize a new FT2::Face object.

Note: 

  FreeType2-Ruby creates a new (hidden) FT2::Library instance at
  runtime, which FT2::Face objects are automatically initialized with
  if an a library is not specified.

Aliases: 

  FT2::Face.load

Examples: 

  # load font from file "yudit.ttf"
  face = FT2::Face.new 'yudit.ttf'

  # load second face from from file "yudit.ttf"
  face = FT2::Face.new 'yudit.ttf', 1

  # load font from file "yudit.ttf" under FT2::Library instance lib
  face = FT2::Face.new lib, 'yudit.ttf'

  # load second face from file "yudit.ttf" under FT2::Library instance lib
  face = FT2::Face.new lib, 'yudit.ttf', 1
new_from_memory(int argc, VALUE *argv, VALUE klass)

Allocate and initialize a new FT2::Face object from in-memory buffer.

Note: 

  FreeType2-Ruby creates a new (hidden) FT2::Library instance at
  runtime, which FT2::Face objects are automatically initialized with
  if an a library is not specified.

Examples: 

  # load font from string _buffer_
  face = FT2::Face.new buffer, buffer_size

  # load second face from string _buffer_
  face = FT2::Face.new buffer, buffer_size, 1

  # load font from string _buffer_ under FT2::Library instance _lib_
  face = FT2::Face.new lib, buffer, buffer_size

  # load second face from string _buffer_ under FT2::Library instance _lib_
  face = FT2::Face.new lib, buffer, buffer_size, 1
initialize(VALUE self)

Constructor for FT2::Face.

This method is currently empty. You should never call this method directly unless you're instantiating a derived class (ie, you know what you're doing).

Public Instance methods
faces(VALUE self)

Return the number of faces in an FT2::Face object.

Aliases: 

  FT2::Face#num_faces

Examples: 

  num_faces = face.faces
index(VALUE self)

Return the index of an FT2::Face object in its font file.

Note: 

  This is almost always zero.

Aliases: 

  FT2::Face#face_index

Examples: 

  index = face.index
flags(VALUE self)

Return the face flags of an FT2::Face object.

You can binary OR this with any of the following values to obtain the value of that flag (note that this is returned as an Integer and not as a boolean value; eg non-zero for true and zero for false).

Face Flags: 

  FT2::Face::SCALABLE
  FT2::Face::FIXED_SIZES
  FT2::Face::FIXED_WIDTH
  FT2::Face::FIXED_HORIZONTAL
  FT2::Face::FIXED_VERTICAL
  FT2::Face::SFNT
  FT2::Face::KERNING
  FT2::Face::MULTIPLE_MASTERS
  FT2::Face::GLYPH_NAMES
  FT2::Face::EXTERNAL_STREAM
  FT2::Face::FAST_GLYPHS

Alternatively, if you're only checking one flag, it's slightly faster (and arguably more concise), to use the following flag methods, which DO return true or false.

Individual Flag Methods: 

  FT2::Face#scalable?
  FT2::Face#fixed_sizes?
  FT2::Face#fixed_width?
  FT2::Face#horizontal?
  FT2::Face#vertical?
  FT2::Face#sfnt?
  FT2::Face#kerning?
  FT2::Face#external_stream?
  FT2::Face#fast_glyphs?

Aliases: 

  FT2::Face#face_flags

Examples: 

  if (face.flags & (FT2::Face::FAST_GLYPHS | FT2::Face::KERNING) != 0)
    puts 'face contains fast glyphs and kerning information'
  end
scalable?(VALUE self)

Is this FT2::Face scalable?

Examples: 

  puts "is scalable" if face.scalable?
fixed_sizes?(VALUE self)

Does this FT2::Face contain bitmap strikes for some pixel sizes?

Examples: 

  puts "contains fixed sized glyphs" if face.fixed_sizes?
fixed_width?(VALUE self)

Does this FT2::Face contain fixed with characters?

Examples: 

  puts "contains fixed width characters" if face.fixed_width?
horizontal?(VALUE self)

Does this FT2::Face contain horizontal glyph metrics?

Note: 

  This flag is true for virtually all fonts.

Examples: 

  puts "contains horizontal glyph metrics" if face.horizontal?
vertical?(VALUE self)

Does this FT2::Face contain vertical glyph metrics?

Note: 

  If this flag is not set, the glyph loader will synthesize vertical
  metrics itself.

Examples: 

  puts "contains vertical glyph metrics" if face.vertical?
sfnt?(VALUE self)

Is this FT2::Face stored in the 'sfnt' storage format?

Note: 

  This currently means the file was either TrueType or OpenType.

Examples: 

  puts "sfnt format font" if face.sfnt?
kerning?(VALUE self)

Does this FT2::Face contain kerning information?

Examples: 

  puts "face contains kerning information" if face.kerning?
external_stream?(VALUE self)

Was this FT2::Face loaded from an external stream?

Examples: 

  puts "face loaded from external stream" if face.external_stream?
fast_glyphs?(VALUE self)

Does this FT2::Face contain fast glyphs?

Note: 

  This flag is usually set for fixed-size formats like FNT.

Examples: 

  puts "face contains fast glyphs" if face.fast_glyphs?
style_flags(VALUE self)

Return the style flags of an FT2::Face object.

You can binary OR this with any of the following values to obtain the value of that style flag (note that this is returned as an Integer and not as a boolean value; eg non-zero for true and zero for false).

Style Flags: 

  FT2::Face::BOLD
  FT2::Face::ITALIC

Alternatively, if you're only checking one style flag, it's slightly faster (and arguably more concise), to use the following style flag methods, which DO return true or false.

Individual Style Flag Methods: 

  FT2::Face#bold?
  FT2::Face#italic?

Examples: 

  style = face.style_flags
bold?(VALUE self)

Is this a bold FT2::Face?

Examples: 

  puts "bold face" if face.bold?
italic?(VALUE self)

Is this an italic FT2::Face?

Examples: 

  puts "italic face" if face.italic?
glyphs(VALUE self)

Return the number of glyphs in an FT2::Face object.

Aliases: 

  FT2::Face#num_glyphs

Examples: 

  count = face.glyphs
  puts "face has #{count.to_str} glyphs"
family(VALUE self)

Return the family name of an FT2::Face object.

Description: 

  This is an ASCII string, usually in English, which describes the
  FT2::Face object's family (eg "Times New Roman" or "Geneva"). Some
  formats (eg Truetype and OpenType) provide localized and Unicode
  versions of this string, which are accessable via the format specific
  interfaces.

Examples: 

  puts 'family: ' << face.family
style(VALUE self)

Return the style name of an FT2::Face object.

Description: 

  This is an ASCII string, usually in English, which describes the
  FT2::Face object's style (eg "Bold", "Italic", "Condensed", etc).
  This field is optional and may be set to nil.

Examples: 

  puts 'style: ' << face.style if face.style
fixed_sizes(VALUE self)

Return the number of fixed sizes in an FT2::Face object.

Note: 

  This should be set to 0 for scalable fonts, unless the FT2::Face
  object contains a complete set of glyphs for the specified size.

Aliases: 

  FT2::Face#num_fixed_sizes

Examples: 

  puts 'fized sizes count: ' << face.fixed_sizes
available_sizes(VALUE self)

Return an array of sizes in an FT2::Face object.

Note: 

  This method does not currently work..

Examples: 

  face.available_sizesdflksjaflksdjf FIXME
num_charmaps(VALUE self)

Return the number of charmaps in an FT2::Face object.

Examples: 

  puts 'number of charmaps: ' << face.num_charmaps
charmaps(VALUE self)

Return an array of charmaps in an FT2::Face object.

Note: 

  This method may not work correctly at the moment (FIXME).

Examples: 

  face.charmaps.each { |map| puts map.to_str }
bbox(VALUE self)

Return the bounding box of an FT2::Face object.

Note: 

  This method is not currently implemented (FIXME).

Examples: 

  FIXME
units_per_em(VALUE self)

Return the number of font units per EM for this FT2::Face object.

Description: 

  This value is typically 2048 for TrueType fonts, 1000 for Type1
  fonts, and should be set to the (unrealistic) value 1 for
  fixed-size fonts.

Aliases: 

  FT2::Face#units_per_EM

Examples: 

  em = face.units_per_em
ascender(VALUE self)

Return the ascender for this FT2::Face object.

Description: 

  An FT2::Face object's ascender is the vertical distance, in font
  units, from the baseline to the topmost point of any glyph in the
  face.

Examples: 

  asc = face.ascender
descender(VALUE self)

Return the descender for this FT2::Face object.

Description: 

  An FT2::Face object's descender is the vertical distance, in font
  units, from the baseline to the bottommost point of any glyph in
  the face.

Examples: 

  asc = face.descender
height(VALUE self)

Return the height of this FT2::Face object.

Description: 

  An FT2::Face object's height is the vertical distance, in font
  units, from the baseline of one line to the baseline of the next.
  The value can be computed as 'ascender + descender + line_gap',
  where 'line_gap' is also called 'external leading'.

Examples: 

  h = face.height
max_advance_width(VALUE self)

Return the maximal advance width of this FT2::Face object.

Description: 

  The maximal advance width, in font units, for all glyphs in this
  FT2::Face object.  This can be used to make word-wrapping
  computations faster.  Only relevant for scalable formats.

Examples: 

  maw = face.max_advance_width
max_advance_height(VALUE self)

Return the maximal advance height of this FT2::Face object.

Description: 

  The maximal advance height, in font units, for all glyphs in this
  FT2::Face object.  This can be used to make word-wrapping
  computations faster.  Only relevant for scalable formats.

Examples: 

  mah = face.max_advance_height
underline_position(VALUE self)

Return the underline position of this FT2::Face object.

Description: 

  The position, in font units, of the underline line for this face.
  It's the center of the underlining stem. Only relevant for scalable
  formats.

Examples: 

  uh = face.underline_position
underline_thickness(VALUE self)

Return the underline thickness of this FT2::Face object.

Description: 

 The thickness, in font units, of the underline for this face. Only
 relevant for scalable formats.

Examples: 

  ut = face.underline_thickness
glyph(VALUE self)

Return the glyph slot associated with this FT2::Face object.

Description: 

 The face's associated glyph slot(s) (a FT2::GlyphSlot). This object
 is created automatically with a new FT2::Face object. However,
 certain kinds of applications (mainly tools like converters) can
 need more than one slot to ease their task.

Examples: 

  glyph = face.glyph
size(VALUE self)

Return the current active size of this FT2::Face object.

Examples: 

  size = face.size
charmap(VALUE self)

Return the current active FT2::CharMap of this FT2::Face object.

Examples: 

  size = face.size
attach(VALUE self, VALUE path)

Attach a font file to this FT2::Face object.

Description: 

  This is usually to read additional information for a single face
  object. For example, it is used to read the AFM files that come
  with Type 1 fonts in order to add kerning data and other metrics.
  Throws an exception if the font file could not be loaded.
  FreeType2 also supports loading from an input stream, but this
  feature is not implemented in FT2-Ruby.

Examples: 

  path = 'fonts'yudit.ttf'
  begin
    face.attach path  # attach file "fonts/yudit.ttf"
  rescue Exception
    $stderr.puts "Couldn't open font file \"#{path}\": " << $!
  end
load_glyph(VALUE self, VALUE glyph_index, VALUE flags)

Load a glyph at a given size into a glyph slot of a FT2::Face object.

Description: 

  Load a glyph at a given size into a glyph slot of a FT2::Face
  object.

  glyph_index: The index of the glyph in the font file.
  load_flags: A flag indicating what to load for this glyph. The
              FT2::Load::XXXX constants can be used to control the
              glyph loading process (e.g., whether the outline should
              be scaled, whether to load bitmaps or not, whether to
              hint the outline, etc).

Note: 

  If the glyph image is not a bitmap, and if the bit flag
  FT2::Load::IGNORE_TRANSFORM is unset, the glyph image will be
  transformed with the information passed to a previous call to
  FT2::Face#set_transform

  Note that this also transforms the `face.glyph.advance' field, but
  not the values in `face.glyph.metrics'.

Load Flags: 

  FT2::Load::DEFAULT
  FT2::Load::RENDER
  FT2::Load::MONOCHROME
  FT2::Load::LINEAR_DESIGN
  FT2::Load::NO_SCALE
  FT2::Load::NO_HINTING
  FT2::Load::NO_BITMAP
  FT2::Load::CROP_BITMAP
  FT2::Load::VERTICAL_LAYOUT
  FT2::Load::IGNORE_TRANSFORM
  FT2::Load::IGNORE_GLOBAL_ADVANCE_WIDTH
  FT2::Load::FORCE_AUTOHINT
  FT2::Load::NO_RECURSE
  FT2::Load::PEDANTIC

Examples: 

  face.load_glyph 5, FT2::Load::DEFAULT
load_char(VALUE self, VALUE char_code, VALUE flags)

Load a glyph at a given size into a glyph slot of a FT2::Face object.

Description: 

  Load a glyph at a given size into a glyph slot of a FT2::Face
  object according to its character code.

  char_code: The glyph's character code, according to the current
             charmap used in the FT2::Face object.
  load_flags: A flag indicating what to load for this glyph. The
              FT2::Load::XXXX constants can be used to control the
              glyph loading process (e.g., whether the outline should
              be scaled, whether to load bitmaps or not, whether to
              hint the outline, etc).

Note: 

  If the face has no current charmap, or if the character code is not
  defined in the charmap, this function will return an error.

  If the glyph image is not a bitmap, and if the bit flag
  FT2::Load::IGNORE_TRANSFORM is unset, the glyph image will be
  transformed with the information passed to a previous call to
  FT2::Face#set_transform

  Note that this also transforms the `face.glyph.advance' field, but
  not the values in `face.glyph.metrics'.

Load Flags: 

  FT2::Load::DEFAULT
  FT2::Load::RENDER
  FT2::Load::MONOCHROME
  FT2::Load::LINEAR_DESIGN
  FT2::Load::NO_SCALE
  FT2::Load::NO_HINTING
  FT2::Load::NO_BITMAP
  FT2::Load::CROP_BITMAP
  FT2::Load::VERTICAL_LAYOUT
  FT2::Load::IGNORE_TRANSFORM
  FT2::Load::IGNORE_GLOBAL_ADVANCE_WIDTH
  FT2::Load::FORCE_AUTOHINT
  FT2::Load::NO_RECURSE
  FT2::Load::PEDANTIC

Examples: 

  face.load_char 5, FT2::Load::DEFAULT
char_index(VALUE self, VALUE char_code)

Get the glyph index of a character code.

Note: 

  This function uses a charmap object in order to do the translation.

  FreeType computes its own glyph indices which are not necessarily
  the same as used in the font in case the font is based on glyph
  indices. Reason for this behaviour is to assure that index 0 is
  never used, representing the missing glyph.

  A return value of 0 means `undefined character code'.

Examples: 

  index = face.char_index 65
  puts 'undefined character code' if index == 0
name_index(VALUE self, VALUE glyph_name)

Get the glyph index of a given glyph name.

Note: 

  This method uses driver specific objects to do the translation.

  A return value of 0 means `undefined character code'.

Examples: 

  index = face.name_index glyph_name
kerning(VALUE self, VALUE left_glyph, VALUE right_glyph, VALUE kern_mode)

Get the kerning vector between two glyphs of a FT2::Face object.

Description: 

  Get the kerning vector between two glyphs of a FT2::Face object.

  left_glyph: The index of the left glyph in the kern pair.
  right_glyph: The index of the right glyph in the kern pair.
  kern_mode: One of the FT2::KerningMode::XXXX constants. Determines
             the scale/dimension of the returned kerning vector.

  Passing kern_mode == nil is the same as FT2::KerningMode::DEFAULT.

  Returns a kerning vector (actually a two-element array). This is in
  font units for scalable formats, and in pixels for fixed-sizes
  formats.

Kerning Modes: 

  FT2::KerningMode::DEFAULT
  FT2::KerningMode::UNFITTED
  FT2::KerningMode::UNSCALED

Examples: 

  left_glyph = 10
  left_glyph = 11
  k_v = face.kerning left_glyph, right_glyph, nil

  # another example, w/o default options
  k_v = face.get_kerning 12, 13, FT2::KerningMode::UNFITTED
glyph_name(VALUE self, VALUE glyph_index)

Get the ASCII name of a glyph in a FT2::Face object.

Note: 

  If the face doesn't provide glyph names or if the glyph index is
  invalid, nil is returned.  The glyph name is truncated if it is
  longer than 1024 characters.

Examples: 

  glyph_index = 45
  glyph_name = face.glyph_name glyph_index
postscript_name(VALUE self)

Get the ASCII Postscript name of a FT2::Face object.

Note: 

  This should only work with Postscript and TrueType fonts. If the
  PostScript name is un-avaialble, nil is returned.

Examples: 

  ps_name = face.postscript_name
  name = face.name
select_charmap(VALUE self, VALUE encoding)

Select a FT2::Face object's charmap by its encoding tag.

Encoding Tags: 

  FT2::Encoding::NONE
  FT2::Encoding::SYMBOL
  FT2::Encoding::UNICODE
  FT2::Encoding::LATIN_1

Examples: 

  face.select_charmap FT2::Encoding::UNICODE
set_charmap(VALUE self, VALUE charmap)

Select the FT2::Face object's charmap for character code to glyph index decoding.

Examples: 

  charmap = face.charmaps[0]
  face.set_charmap charmap

  charmap = face.charmaps[0]
  face.charmap = charmap
first_char(VALUE self)

Return the first character code of the selected charmap and corresponding glyph index of a FT2::Face object.

Note: 

  Using this with FT2::Face#next_char will allow you to iterate
  through the charmap => glyph index mapping for the selected
  charmap.

  You should probably use the method FT2::Face#current_charmap
  instead.

Examples: 

  c_code, g_idx = face.first_char
  while g_idx != 0
    puts "#{c_code} => #{g_idx}"
    c_code, g_idx = face.next_char
  end
next_char(VALUE self, VALUE char_code)

Return the next character code of the selected charmap and corresponding glyph index of a FT2::Face object.

Note: 

  Using this with FT2::Face#first_char will allow you to iterate
  through the charmap => glyph index mapping for the selected
  charmap.  Returns 0 if the charmap is empty, or if there are no
  more codes in the charmap.

  You should probably use the method FT2::Face#current_charmap
  instead.

Examples: 

  c_code, g_idx = face.first_char
  while g_idx != 0
    puts "#{c_code} => #{g_idx}"
    c_code, g_idx = face.next_char
  end
current_charmap(VALUE self)

Return the character code to glyph index map of the selected charmap of a FT2::Face object.

Note: 

  Returns nil if the selected charmap is empty.

Examples: 

  mapping =
set_char_size(VALUE self, VALUE c_w, VALUE c_h, VALUE h_r, VALUE v_r)

Set the character dimensions of this FT2::Face object.

Description: 

  Sets the character dimensions of a FT2::Face object. The
  `char_width' and `char_height' values are used for the width and
  height, respectively, expressed in 26.6 fractional points.

  If the horizontal or vertical resolution values are zero, a default
  value of 72dpi is used. Similarly, if one of the character
  dimensions is zero, its value is set equal to the other.

  When dealing with fixed-size faces (i.e., non-scalable formats),
  use the function FT2::Face#set_pixel_sizes .

Examples: 

  face.set_char_size char_width, char_height, horiz_res, vert_res
set_pixel_sizes(VALUE self, VALUE pixel_w, VALUE pixel_h)

Set the character dimensions of this FT2::Face object.

Description: 

  Sets the character dimensions of a FT2::Face object. The width and
  height are expressed in integer pixels.

  If one of the character dimensions is zero, its value is set equal
  to the other.

  The values of `pixel_width' and `pixel_height' correspond to the
  pixel values of the typographic character size, which are NOT
  necessarily the same as the dimensions of the glyph `bitmap cells'.

  The `character size' is really the size of an abstract square
  called the `EM', used to design the font. However, depending on the
  font design, glyphs will be smaller or greater than the EM.

  This means that setting the pixel size to, say, 8x8 doesn't
  guarantee in any way that you will get glyph bitmaps that all fit
  within an 8x8 cell (sometimes even far from it).

Examples: 

  face.set_pixel_sizes pixel_width, pixel_height
set_transform(VALUE self, VALUE matrix, VALUE delta)

Set the pre-render transoformation matrix and vector of a FT2::Face object.

Description: 

  Used to set the transformation that is applied to glyph images just
  before they are converted to bitmaps in a FT2::GlyphSlot when
  FT2::GlyphSlot#render is called.

  matrix: The transformation's 2x2 matrix. Use nil for the identity
          matrix.
  delta: The translation vector. Use nil for the null vector.

Note: 

  The transformation is only applied to scalable image formats after
  the glyph has been loaded. It means that hinting is unaltered by
  the transformation and is performed on the character size given in
  the last call to FT2::Face#set_char_sizes or
  FT2::Face#set_pixel_sizes.

Examples: 

  matrix = [[0, 1],
            [0, 1]]
  vector = nil

  face.set_transform matrix, vector