Class: FT2::Face

Inherits:
Object
  • Object
show all
Defined in:
ext/ft2-ruby/ft2.c

Constant Summary collapse

SCALABLE = 
INT2FIX(FT_FACE_FLAG_SCALABLE)
FIXED_SIZES = 
INT2FIX(FT_FACE_FLAG_FIXED_SIZES)
FIXED_WIDTH = 
INT2FIX(FT_FACE_FLAG_FIXED_WIDTH)
FIXED_HORIZONTAL = 
INT2FIX(FT_FACE_FLAG_HORIZONTAL)
FIXED_VERTICAL = 
INT2FIX(FT_FACE_FLAG_VERTICAL)
SFNT = 
INT2FIX(FT_FACE_FLAG_SFNT)
KERNING = 
INT2FIX(FT_FACE_FLAG_KERNING)
MULTIPLE_MASTERS = 
INT2FIX(FT_FACE_FLAG_MULTIPLE_MASTERS)
GLYPH_NAMES = 
INT2FIX(FT_FACE_FLAG_GLYPH_NAMES)
EXTERNAL_STREAM = 
INT2FIX(FT_FACE_FLAG_EXTERNAL_STREAM)
FAST_GLYPHS = 
INT2FIX(FT_FACE_FLAG_FAST_GLYPHS)
BOLD = 
INT2FIX(FT_STYLE_FLAG_BOLD)
ITALIC = 
INT2FIX(FT_STYLE_FLAG_ITALIC)

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.initialize ⇒ Object

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).



442
443
444
 
# File 'ext/ft2-ruby/ft2.c', line 442

static VALUE ft_face_init(VALUE self) {
  return self;
}

.load(*args) ⇒ Object

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



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'ext/ft2-ruby/ft2.c', line 317

VALUE ft_face_new(int argc, VALUE *argv, VALUE klass) {
  VALUE self, path;
  FT_Library *lib;
  FT_Face *face;
  FT_Error err;
  FT_Long face_index;

  lib = &library;
  switch (argc) {
    case 1:
      path = argv[0];
      face_index = 0;
      break;
    case 2:
      if (rb_obj_is_kind_of(argv[0], rb_cString)) {
        path = argv[0];
        face_index = NUM2INT(argv[1]);
      } else if (rb_obj_is_kind_of(argv[0], cLibrary)) {
        Data_Get_Struct(argv[0], FT_Library, lib);
        path = argv[0];
        face_index = 0;
      } else {
        rb_raise(rb_eArgError, "Invalid first argument.");
      }
      break;
    case 3:
      Data_Get_Struct(argv[0], FT_Library, lib);
      path = argv[1];
      face_index = NUM2INT(argv[1]);
      break;
    default:
      rb_raise(rb_eArgError, "Invalid argument count: %d.", argc);
  }

  face = malloc(sizeof(FT_Face));
  err = FT_New_Face(*lib, RSTRING_PTR(path), face_index, face);
  if (err != FT_Err_Ok)
    handle_error(err);

  self = Data_Wrap_Struct(klass, 0, face_free, face);
  rb_obj_call_init(self, 0, NULL);

  return self;
}

.new(*args) ⇒ Object

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



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'ext/ft2-ruby/ft2.c', line 317

VALUE ft_face_new(int argc, VALUE *argv, VALUE klass) {
  VALUE self, path;
  FT_Library *lib;
  FT_Face *face;
  FT_Error err;
  FT_Long face_index;

  lib = &library;
  switch (argc) {
    case 1:
      path = argv[0];
      face_index = 0;
      break;
    case 2:
      if (rb_obj_is_kind_of(argv[0], rb_cString)) {
        path = argv[0];
        face_index = NUM2INT(argv[1]);
      } else if (rb_obj_is_kind_of(argv[0], cLibrary)) {
        Data_Get_Struct(argv[0], FT_Library, lib);
        path = argv[0];
        face_index = 0;
      } else {
        rb_raise(rb_eArgError, "Invalid first argument.");
      }
      break;
    case 3:
      Data_Get_Struct(argv[0], FT_Library, lib);
      path = argv[1];
      face_index = NUM2INT(argv[1]);
      break;
    default:
      rb_raise(rb_eArgError, "Invalid argument count: %d.", argc);
  }

  face = malloc(sizeof(FT_Face));
  err = FT_New_Face(*lib, RSTRING_PTR(path), face_index, face);
  if (err != FT_Err_Ok)
    handle_error(err);

  self = Data_Wrap_Struct(klass, 0, face_free, face);
  rb_obj_call_init(self, 0, NULL);

  return self;
}

.new_from_memory(*args) ⇒ Object

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



383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'ext/ft2-ruby/ft2.c', line 383

VALUE ft_face_new_from_memory(int argc, VALUE *argv, VALUE klass) {
  VALUE self;
  FT_Library *lib;
  FT_Face *face;
  FT_Error err;
  FT_Long face_index;
  void *mem;
  int len;

  lib = &library;
  switch (argc) {
    case 2:
      mem = RSTRING_PTR(argv[0]);
      len = NUM2INT(argv[1]);
      face_index = 0;
      break;
    case 3:
      if (rb_obj_is_kind_of(argv[0], rb_cString)) {
        mem = RSTRING_PTR(argv[0]);
        len = NUM2INT(argv[1]);
        face_index = NUM2INT(argv[2]);
      } else if (rb_obj_is_kind_of(argv[0], cLibrary)) {
        Data_Get_Struct(argv[0], FT_Library, lib);
        mem = RSTRING_PTR(argv[1]);
        len = NUM2INT(argv[2]);
        face_index = 0;
      } else {
        rb_raise(rb_eArgError, "Invalid first argument.");
      }
      break;
    case 4:
      Data_Get_Struct(argv[0], FT_Library, lib);
      mem = RSTRING_PTR(argv[1]);
      len = NUM2INT(argv[2]);
      face_index = NUM2INT(argv[3]);
      break;
    default:
      rb_raise(rb_eArgError, "Invalid argument count: %d.", argc);
  }

  face = malloc(sizeof(FT_Face));
  err = FT_New_Memory_Face(*lib, mem, len, face_index, face);
  if (err != FT_Err_Ok)
    handle_error(err);

  self = Data_Wrap_Struct(klass, 0, face_free, face);
  rb_obj_call_init(self, 0, NULL);

  return self;
}

Instance Method Details

#ascender ⇒ Object

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



898
899
900
901
902
 
# File 'ext/ft2-ruby/ft2.c', line 898

static VALUE ft_face_ascender(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->ascender);
}

#attach(path) ⇒ Object Also known as: attach_file

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



1088
1089
1090
1091
1092
1093
1094
1095
 
# File 'ext/ft2-ruby/ft2.c', line 1088

static VALUE ft_face_attach(VALUE self, VALUE path) {
  FT_Face *face;
  FT_Error err;
  Data_Get_Struct(self, FT_Face, face);
  if ((err = FT_Attach_File(*face, RSTRING_PTR(path))) != FT_Err_Ok)
    handle_error(err);
  return self;
}

#available_sizes ⇒ Object Also known as: num_available_sizes

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

Note:

This method does not currently work..

Examples:

face.available_sizesdflksjaflksdjf FIXME



803
804
805
806
807
808
 
# File 'ext/ft2-ruby/ft2.c', line 803

static VALUE ft_face_available_sizes(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  /* FIXME!! */
  return INT2FIX((*face)->available_sizes);
}

#bbox ⇒ Object

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

Note:

This method is not currently implemented (FIXME).

Examples:

FIXME



858
859
860
861
862
863
 
# File 'ext/ft2-ruby/ft2.c', line 858

static VALUE ft_face_bbox(VALUE self) {
  UNUSED(self);
  /* FIXME */
  rb_bug("not implemented yet");
  return Qnil;
}

#bold? ⇒ Boolean

Is this a bold FT2::Face?

Examples:

puts "bold face" if face.bold?

Returns:

  • (Boolean) 


697
698
699
700
701
 
# File 'ext/ft2-ruby/ft2.c', line 697

static VALUE ft_face_flag_bold(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->style_flags & FT_STYLE_FLAG_BOLD) ? Qtrue : Qfalse;
}

#char_index(char_code) ⇒ Object

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



1354
1355
1356
1357
1358
 
# File 'ext/ft2-ruby/ft2.c', line 1354

static VALUE ft_face_char_index(VALUE self, VALUE char_code) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX(FT_Get_Char_Index(*face, NUM2INT(char_code)));
}

#charmap ⇒ Object

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

Examples:

size = face.size



1058
1059
1060
1061
1062
1063
1064
1065
1066
 
# File 'ext/ft2-ruby/ft2.c', line 1058

static VALUE ft_face_charmap(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);

  if ((*face)->charmap)
    return Data_Wrap_Struct(cCharMap, 0, dont_free, (*face)->charmap);
  else
    return Qnil;
}

#charmaps ⇒ Object

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 }



833
834
835
836
837
838
839
840
841
842
843
844
845
846
 
# File 'ext/ft2-ruby/ft2.c', line 833

static VALUE ft_face_charmaps(VALUE self) {
  FT_Face *face;
  VALUE ary;
  int i;
  Data_Get_Struct(self, FT_Face, face);

  /* FIXME */
  rb_bug("not implemented yet");
  ary = rb_ary_new();
  for (i = 0; i < (*face)->num_charmaps; i++)
    rb_ary_push(ary, INT2FIX(i));

  return ary;
}

#current_charmap ⇒ Object

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 = face.charmap



1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
 
# File 'ext/ft2-ruby/ft2.c', line 1604

static VALUE ft_face_current_charmap(VALUE self) {
  FT_Face *face;
  FT_ULong c_code;
  FT_UInt g_idx;
  VALUE rtn;

  rtn = Qnil;
  Data_Get_Struct(self, FT_Face, face);

  c_code = FT_Get_First_Char(*face, &g_idx);
  if (!g_idx || !c_code)
    return rtn;

  rtn = rb_hash_new();
  while (c_code != 0) {
    rb_hash_aset(rtn, UINT2NUM(c_code), UINT2NUM(g_idx));
    c_code = FT_Get_Next_Char(*face, c_code, &g_idx);
  }

  return rtn;
}

#descender ⇒ Object

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



916
917
918
919
920
 
# File 'ext/ft2-ruby/ft2.c', line 916

static VALUE ft_face_descender(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->descender);
}

#external_stream? ⇒ Boolean

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

Examples:

puts "face loaded from external stream" if face.external_stream?

Returns:

  • (Boolean) 


639
640
641
642
643
 
# File 'ext/ft2-ruby/ft2.c', line 639

static VALUE ft_face_flag_external_stream(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_EXTERNAL_STREAM) ? Qtrue : Qfalse;
}

#faces ⇒ Object Also known as: num_faces

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

Aliases:

FT2::Face#num_faces

Examples:

num_faces = face.faces



456
457
458
459
460
 
# File 'ext/ft2-ruby/ft2.c', line 456

static VALUE ft_face_faces(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->num_faces);
}

#family ⇒ Object

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



747
748
749
750
751
 
# File 'ext/ft2-ruby/ft2.c', line 747

static VALUE ft_face_family(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return rb_str_new2((*face)->family_name);
}

#fast_glyphs? ⇒ Boolean

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?

Returns:

  • (Boolean) 


655
656
657
658
659
 
# File 'ext/ft2-ruby/ft2.c', line 655

static VALUE ft_face_flag_fast_glyphs(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_FAST_GLYPHS) ? Qtrue : Qfalse;
}

#first_char ⇒ Object

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



1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
 
# File 'ext/ft2-ruby/ft2.c', line 1544

static VALUE ft_face_first_char(VALUE self) {
  FT_Face *face;
  VALUE ary;
  FT_ULong char_code;
  FT_UInt  glyph_index;
  Data_Get_Struct(self, FT_Face, face);
  ary = rb_ary_new();

  char_code = FT_Get_First_Char(*face, &glyph_index);
  rb_ary_push(ary, UINT2NUM(char_code));
  rb_ary_push(ary, UINT2NUM(glyph_index));

  return ary;
}

#fixed_sizes ⇒ Object Also known as: num_fixed_sizes

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



787
788
789
790
791
 
# File 'ext/ft2-ruby/ft2.c', line 787

static VALUE ft_face_fixed_sizes(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->num_fixed_sizes);
}

#fixed_sizes? ⇒ Boolean

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

Examples:

puts "contains fixed sized glyphs" if face.fixed_sizes?

Returns:

  • (Boolean) 


551
552
553
554
555
 
# File 'ext/ft2-ruby/ft2.c', line 551

static VALUE ft_face_flag_fixed_sizes(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_FIXED_SIZES) ? Qtrue : Qfalse;
}

#fixed_width? ⇒ Boolean

Does this FT2::Face contain fixed with characters?

Examples:

puts "contains fixed width characters" if face.fixed_width?

Returns:

  • (Boolean) 


564
565
566
567
568
 
# File 'ext/ft2-ruby/ft2.c', line 564

static VALUE ft_face_flag_fixed_width(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_FIXED_WIDTH) ? Qtrue : Qfalse;
}

#flags ⇒ Object Also known as: face_flags

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



525
526
527
528
529
 
# File 'ext/ft2-ruby/ft2.c', line 525

static VALUE ft_face_flags(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->face_flags);
}

#glyph ⇒ Object

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



1024
1025
1026
1027
1028
1029
1030
1031
1032
 
# File 'ext/ft2-ruby/ft2.c', line 1024

static VALUE ft_face_glyph(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);

  if ((*face)->glyph)
    return Data_Wrap_Struct(cGlyphSlot, 0, dont_free, &((*face)->glyph));
  else
    return Qnil;
}

#glyph_name(glyph_index) ⇒ Object

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



1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
 
# File 'ext/ft2-ruby/ft2.c', line 1444

static VALUE ft_face_glyph_name(VALUE self, VALUE glyph_index) {
  FT_Face *face;
  FT_Error err;
  char buf[1024];
  Data_Get_Struct(self, FT_Face, face);
  err = FT_Get_Glyph_Name(*face, NUM2INT(glyph_index), buf, sizeof(buf));
  if (err != FT_Err_Ok)
    handle_error(err);

  return (buf && strlen(buf)) ? rb_str_new2(buf) : Qnil;
}

#glyphs ⇒ Object Also known as: num_glyphs

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"



727
728
729
730
731
 
# File 'ext/ft2-ruby/ft2.c', line 727

static VALUE ft_face_glyphs(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->num_glyphs);
}

#height ⇒ Object

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



935
936
937
938
939
 
# File 'ext/ft2-ruby/ft2.c', line 935

static VALUE ft_face_height(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->height);
}

#horizontal? ⇒ Boolean

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?

Returns:

  • (Boolean) 


580
581
582
583
584
 
# File 'ext/ft2-ruby/ft2.c', line 580

static VALUE ft_face_flag_horizontal(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_HORIZONTAL) ? Qtrue : Qfalse;
}

#index ⇒ Object Also known as: face_index

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



475
476
477
478
479
 
# File 'ext/ft2-ruby/ft2.c', line 475

static VALUE ft_face_index(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->face_index);
}

#italic? ⇒ Boolean

Is this an italic FT2::Face?

Examples:

puts "italic face" if face.italic?

Returns:

  • (Boolean) 


710
711
712
713
714
 
# File 'ext/ft2-ruby/ft2.c', line 710

static VALUE ft_face_flag_italic(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->style_flags & FT_STYLE_FLAG_ITALIC) ? Qtrue : Qfalse;
}

#kerning(left_glyph, right_glyph, kern_mode) ⇒ Object Also known as: get_kerning

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



1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
 
# File 'ext/ft2-ruby/ft2.c', line 1409

static VALUE ft_face_kerning(VALUE self, VALUE left_glyph, VALUE right_glyph, VALUE kern_mode) {
  FT_Face *face;
  FT_Error err;
  FT_Vector v;
  VALUE ary;

  Data_Get_Struct(self, FT_Face, face);
  ary = rb_ary_new();

  if (kern_mode == Qnil)
    kern_mode = NUM2INT(ft_kerning_default);

  err = FT_Get_Kerning(*face, NUM2INT(left_glyph), NUM2INT(right_glyph), NUM2INT(kern_mode), &v);
  if (err != FT_Err_Ok)
    handle_error(err);

  rb_ary_push(ary, INT2FIX(v.x));
  rb_ary_push(ary, INT2FIX(v.y));

  return ary;
}

#kerning? ⇒ Boolean

Does this FT2::Face contain kerning information?

Examples:

puts "face contains kerning information" if face.kerning?

Returns:

  • (Boolean) 


626
627
628
629
630
 
# File 'ext/ft2-ruby/ft2.c', line 626

static VALUE ft_face_flag_kerning(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_KERNING) ? Qtrue : Qfalse;
}

#load_char(char_code, flags) ⇒ Object

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



1326
1327
1328
1329
1330
1331
1332
1333
1334
 
# File 'ext/ft2-ruby/ft2.c', line 1326

static VALUE ft_face_load_char(VALUE self, VALUE char_code, VALUE flags) {
  FT_Face *face;
  FT_Error err;
  Data_Get_Struct(self, FT_Face, face);
  err = FT_Load_Char(*face, NUM2INT(char_code), NUM2INT(flags));
  if (err != FT_Err_Ok)
    handle_error(err);
  return self;
}

#load_glyph(glyph_index, flags) ⇒ Object

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



1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
 
# File 'ext/ft2-ruby/ft2.c', line 1264

static VALUE ft_face_load_glyph(VALUE self, VALUE glyph_index, VALUE flags) {
  FT_Face *face;
  FT_Error err;

  Data_Get_Struct(self, FT_Face, face);
  if (flags == Qnil)
    flags = INT2FIX(FT_LOAD_DEFAULT);

  err = FT_Load_Glyph(*face, NUM2INT(glyph_index), NUM2INT(flags));
  if (err != FT_Err_Ok)
    handle_error(err);

  return self;
}

#max_advance_height ⇒ Object

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



971
972
973
974
975
 
# File 'ext/ft2-ruby/ft2.c', line 971

static VALUE ft_face_max_advance_height(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->max_advance_height);
}

#max_advance_width ⇒ Object

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



953
954
955
956
957
 
# File 'ext/ft2-ruby/ft2.c', line 953

static VALUE ft_face_max_advance_width(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->max_advance_width);
}

#name_index(glyph_name) ⇒ Object

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



1372
1373
1374
1375
1376
 
# File 'ext/ft2-ruby/ft2.c', line 1372

static VALUE ft_face_name_index(VALUE self, VALUE glyph_name) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX(FT_Get_Name_Index(*face, RSTRING_PTR(glyph_name)));
}

#next_char(char_code) ⇒ Object

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



1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
 
# File 'ext/ft2-ruby/ft2.c', line 1579

static VALUE ft_face_next_char(VALUE self, VALUE char_code) {
  FT_Face *face;
  VALUE ary;
  FT_ULong ret_char_code;
  FT_UInt  glyph_index;
  Data_Get_Struct(self, FT_Face, face);
  ary = rb_ary_new();

  ret_char_code = FT_Get_Next_Char(*face, char_code, &glyph_index);
  rb_ary_push(ary, UINT2NUM(ret_char_code));
  rb_ary_push(ary, UINT2NUM(glyph_index));

  return ary;
}

#num_charmaps ⇒ Object

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

Examples:

puts 'number of charmaps: ' << face.num_charmaps



817
818
819
820
821
 
# File 'ext/ft2-ruby/ft2.c', line 817

static VALUE ft_face_num_charmaps(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->num_charmaps);
}

#postscript_name ⇒ Object Also known as: name

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



1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
 
# File 'ext/ft2-ruby/ft2.c', line 1468

static VALUE ft_face_ps_name(VALUE self) {
  FT_Face *face;
  const char *str;
  Data_Get_Struct(self, FT_Face, face);

  if ((str = FT_Get_Postscript_Name(*face)) != NULL)
    return rb_str_new2(str);
  else
    return Qnil;
}

#scalable? ⇒ Boolean

Is this FT2::Face scalable?

Examples:

puts "is scalable" if face.scalable?

Returns:

  • (Boolean) 


538
539
540
541
542
 
# File 'ext/ft2-ruby/ft2.c', line 538

static VALUE ft_face_flag_scalable(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_SCALABLE) ? Qtrue : Qfalse;
}

#select_charmap(encoding) ⇒ Object

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



1492
1493
1494
1495
1496
1497
1498
1499
1500
 
# File 'ext/ft2-ruby/ft2.c', line 1492

static VALUE ft_face_select_charmap(VALUE self, VALUE encoding) {
  FT_Face *face;
  FT_Error err;
  Data_Get_Struct(self, FT_Face, face);
  err = FT_Select_Charmap(*face, NUM2INT(encoding));
  if (err != FT_Err_Ok)
    handle_error(err);
  return self;
}

#set_char_size(c_w, c_h, h_r, v_r) ⇒ Object

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



1116
1117
1118
1119
1120
1121
1122
1123
1124
 
# File 'ext/ft2-ruby/ft2.c', line 1116

static VALUE ft_face_set_char_size(VALUE self, VALUE c_w, VALUE c_h, VALUE h_r, VALUE v_r) {
  FT_Face *face;
  FT_Error err;
  Data_Get_Struct(self, FT_Face, face);
  err = FT_Set_Char_Size(*face, NUM2DBL(c_w), NUM2DBL(c_h), NUM2INT(h_r), NUM2INT(v_r));
  if (err != FT_Err_Ok)
    handle_error(err);
  return self;
}

#set_charmap(charmap) ⇒ Object Also known as: 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



1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
 
# File 'ext/ft2-ruby/ft2.c', line 1513

static VALUE ft_face_set_charmap(VALUE self, VALUE charmap) {
  FT_Face *face;
  FT_CharMap *cm;
  FT_Error err;
  Data_Get_Struct(self, FT_Face, face);
  Data_Get_Struct(charmap, FT_CharMap, cm);
  err = FT_Set_Charmap(*face, *cm);
  if (err != FT_Err_Ok)
    handle_error(err);
  return self;
}

#set_pixel_sizes(pixel_w, pixel_h) ⇒ Object

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



1152
1153
1154
1155
1156
1157
1158
1159
1160
 
# File 'ext/ft2-ruby/ft2.c', line 1152

static VALUE ft_face_set_pixel_sizes(VALUE self, VALUE pixel_w, VALUE pixel_h) {
  FT_Face *face;
  FT_Error err;
  Data_Get_Struct(self, FT_Face, face);
  err = FT_Set_Pixel_Sizes(*face, NUM2INT(pixel_w), NUM2INT(pixel_h));
  if (err != FT_Err_Ok)
    handle_error(err);
  return self;
}

#set_transform(matrix, delta) ⇒ Object

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



1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
 
# File 'ext/ft2-ruby/ft2.c', line 1189

static VALUE ft_face_set_transform(VALUE self, VALUE matrix, VALUE delta) {
  FT_Face *face;
  FT_Matrix m;
  FT_Vector v;

  Data_Get_Struct(self, FT_Face, face);

  if (matrix != Qnil) {
    /* FIXME: do I have these reversed? */
    m.xx = DBL2FTFIX(NUM2DBL(rb_ary_entry(rb_ary_entry(matrix, 0), 0)));
    m.xy = DBL2FTFIX(NUM2DBL(rb_ary_entry(rb_ary_entry(matrix, 1), 0)));
    m.yx = DBL2FTFIX(NUM2DBL(rb_ary_entry(rb_ary_entry(matrix, 0), 1)));
    m.yy = DBL2FTFIX(NUM2DBL(rb_ary_entry(rb_ary_entry(matrix, 1), 1)));
  }

  if (delta != Qnil) {
    v.x = NUM2INT(rb_ary_entry(delta, 0));
    v.y = NUM2INT(rb_ary_entry(delta, 1));
  }

  if (matrix != Qnil && delta != Qnil)
    FT_Set_Transform(*face, &m, &v);
  else if (matrix == Qnil && delta != Qnil)
    FT_Set_Transform(*face, NULL, &v);
  else if (matrix != Qnil && delta == Qnil)
    FT_Set_Transform(*face, &m, NULL);
  else
    FT_Set_Transform(*face, NULL, NULL);

  return self;
}

#sfnt? ⇒ Boolean

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?

Returns:

  • (Boolean) 


613
614
615
616
617
 
# File 'ext/ft2-ruby/ft2.c', line 613

static VALUE ft_face_flag_sfnt(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_SFNT) ? Qtrue : Qfalse;
}

#size ⇒ Object

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

Examples:

size = face.size



1041
1042
1043
1044
1045
1046
1047
1048
1049
 
# File 'ext/ft2-ruby/ft2.c', line 1041

static VALUE ft_face_size(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);

  if ((*face)->size)
    return Data_Wrap_Struct(cSize, 0, dont_free, (*face)->size);
  else
    return Qnil;
}

#style ⇒ Object

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



765
766
767
768
769
770
771
 
# File 'ext/ft2-ruby/ft2.c', line 765

static VALUE ft_face_style(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  if (!(*face)->style_name)
    return Qnil;
  return rb_str_new2((*face)->style_name);
}

#style_flags ⇒ Object

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



684
685
686
687
688
 
# File 'ext/ft2-ruby/ft2.c', line 684

static VALUE ft_face_style_flags(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->style_flags);
}

#underline_position ⇒ Object

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



989
990
991
992
993
 
# File 'ext/ft2-ruby/ft2.c', line 989

static VALUE ft_face_underline_position(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->underline_position);
}

#underline_thickness ⇒ Object

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



1006
1007
1008
1009
1010
 
# File 'ext/ft2-ruby/ft2.c', line 1006

static VALUE ft_face_underline_thickness(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->underline_thickness);
}

#units_per_em ⇒ Object Also known as: units_per_EM

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



880
881
882
883
884
 
# File 'ext/ft2-ruby/ft2.c', line 880

static VALUE ft_face_units_per_em(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return INT2FIX((int) (*face)->units_per_EM);
}

#vertical? ⇒ Boolean

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?

Returns:

  • (Boolean) 


597
598
599
600
601
 
# File 'ext/ft2-ruby/ft2.c', line 597

static VALUE ft_face_flag_vertical(VALUE self) {
  FT_Face *face;
  Data_Get_Struct(self, FT_Face, face);
  return ((*face)->face_flags & FT_FACE_FLAG_VERTICAL) ? Qtrue : Qfalse;
}