Provided by: libfont-freetype-perl_0.16-3build3_amd64 bug

NAME

       Font::FreeType::Face - font typefaces loaded from Font::FreeType

SYNOPSIS

           use Font::FreeType;

           my $freetype = Font::FreeType->new;
           my $face = $freetype->face('Vera.ttf');

DESCRIPTION

       This class represents a font face (or typeface) loaded from a font file.  Usually a face
       represents all the information in the font file (such as a TTF file), although it is
       possible to have multiple faces in a single file.

       Never 'use' this module directly; the class is loaded automatically from Font::FreeType.
       Use the "Font::FreeType->face()" method to create a new Font::FreeType::Face object from a
       filename.

METHODS

       Unless otherwise stated, all methods will die if there is an error.

       ascender()
           The height above the baseline of the 'top' of the font's glyphs, scaled to the current
           size of the face.

       attach_file(filename)
           Informs FreeType of an ancillary file needed for reading the font.  Hasn't been tested
           yet.

       current_face_index()
           The index number of the current font face.  Usually this will be zero, which is the
           default.  See "Font::FreeType->face()" for how to load other faces from the same file.

       descender()
           The depth below the baseline of the 'bottom' of the font's glyphs, scaled to the
           current size of the face.  Actually represents the distance moving up from the
           baseline, so usually negative.

       family_name()
           A string containing the name of the family this font claims to be from.

       fixed_sizes()
           In scalar context returns the number of fixed sizes (of embedded bitmaps) available in
           the font.  In list context returns a list of hashes which detail those sizes.  Each
           hash can contain the following keys, but they will be absent if the information isn't
           available:

           size
               Size of the glyphs in points.  Only available with Freetype 2.1.5 or newer.

           height
               Height of the bitmaps in pixels.

           width
               Width of the bitmaps in pixels.

           x_res_dpi, y_res_dpi
               Resolution the bitmaps were designed for, in dots per inch.  Only available with
               Freetype 2.1.5 or newer.

           x_res_ppem, y_res_ppem
               Resolution the bitmaps were designed for, in pixels per em.  Only available with
               Freetype 2.1.5 or newer.

       foreach_char(code-ref)
           Iterates through all the characters in the font, and calls code-ref for each of them
           in turn.  Glyphs which don't correspond to Unicode characters are ignored.

           Each time your callback code is called, $_ will be set to a Font::FreeType::Glyph
           object for the current glyph.  For an example see the program list-characters.pl
           provided in the distribution.

       foreach_glyph(code-ref)
           Iterates through all the glyphs in the font, and calls code-ref for each of them in
           turn.

           Each time your callback code is called, $_ will be set to a Font::FreeType::Glyph
           object for the current glyph.

       glyph_from_char(character, fallback = 0)
           Returns a Font::FreeType::Glyph object for the glyph corresponding to the first
           character in the string provided.  Note that currently non-ASCII characters are not
           likely to work with this, so you might be better using the glyph_from_char_code()
           method below and the Perl "ord" function.

           Returns undef if the glyph is not available in the font and fallback isn't defined;
           otherwise, i.e. if fallback = true returns fonts missing glyph.

       glyph_from_char_code(char-code, fallback = 0)
           Returns a Font::FreeType::Glyph object for the glyph corresponding to Unicode
           character char-code.  FreeType supports using other character sets, but this module
           doesn't yet.

           Returns undef if the glyph is not available in the font and fallback isn't defined;
           otherwise, i.e. if fallback = true returns fonts missing glyph.

       get_name_index(name)
           Looks up a glyph by name and returns the index for that glyph in the font. Returns 0
           if the name is not found.

       glyph_from_index(index)
           Returns a Font::FreeType::Glyph object for the glyph at the given index.

       glyph_from_name(name, fallback = 0)
           Looks up a glyph by name and returns a Font::FreeType::Glyph object.

           Returns undef if the glyph is not available in the font and fallback isn't defined;
           otherwise, i.e. if fallback = true returns fonts missing glyph.

       has_glyph_names()
           True if individual glyphs have names.  If so, the names can be retrieved with the
           name() method on Font::FreeType::Glyph objects.

           See also has_reliable_glyph_names() below.

       has_horizontal_metrics()
       has_vertical_metrics()
           These return true if the font contains metrics for the corresponding directional
           layout.  Most fonts will contain horizontal metrics, describing (for example) how the
           characters should be spaced out across a page when being written horizontally like
           English.  Some fonts, such as Chinese ones, may contain vertical metrics as well,
           allowing typesetting down the page.

       has_kerning()
           True if the font provides kerning information.  See the kerning() method below.

       has_reliable_glyph_names()
           True if the font contains reliable PostScript glyph names.  Some Some fonts contain
           bad glyph names.  This method always returns false when used with Freetype versions
           earlier than 2.1.1.

           See also has_glyph_names() above.

       height()
           The line height of the text, i.e. distance between baselines of two lines of text.

       is_bold()
           True if the font claims to be in a bold style.

       is_fixed_width()
           True if all the characters in the font are the same width.  Will be true for
           monospaced fonts like Courier.

       is_italic()
           Returns true if the font claims to be in an italic style.

       is_scalable()
           True if the font has a scalable outline, meaning it can be rendered nicely at
           virtually any size.  Returns false for bitmap fonts.

       is_sfnt()
           True if the font file is in the 'sfnt' format, meaning it is either TrueType or
           OpenType.  This isn't much use yet, but future versions of this library might provide
           access to extra information about sfnt fonts.

       kerning(left-glyph-index, right-glyph-index, [mode])
           Returns the suggested kerning adjustment between two glyphs.  When called in scalar
           context returns a single value, which should be added to the position of the second
           glyph on the x axis for horizontal layouts, or the y axis for vertical layouts.

           Note: currently always returns the x axis kerning, but this will be fixed when
           vertical layouts are handled properly.

           For example, assuming $left and $right are two Font::FreeType::Glyph objects:

               my $kern_distance = $face->kerning($left->index, $right->index);

           In list context this returns two values corresponding to the x and y axes, which
           should be treated in the same way.

           The "mode" argument controls how the kerning is calculated, with the following options
           available:

           FT_KERNING_DEFAULT
               Grid-fitting (hinting) and scaling are done.  Use this when rendering glyphs to
               bitmaps to make the kerning take the resolution of the output in to account.

           FT_KERNING_UNFITTED
               Scaling is done, but not hinting.  Use this when extracting the outlines of
               glyphs.  If you used the "FT_LOAD_NO_HINTING" option when creating the face then
               use this when calculating the kerning.

           FT_KERNING_UNSCALED
               Leave the measurements in font units, without scaling, and without hinting.

       load_flags()
           Retrieve the load_flags option used.

       load_flags(load_flags)
           Setting the load_flags option. Returns the newly set value.

       number_of_faces()
           The number of faces contained in the file from which this one was created.  Usually
           there is only one.  See "Font::FreeType->face()" for how to load the others if there
           are more.

       number_of_glyphs()
           The number of glyphs in the font face.

       postscript_name()
           A string containing the PostScript name of the font, or undef if it doesn't have one.

       set_char_size(width, height, x_res, y_res)
           Set the size at which glyphs should be rendered.  Metrics are also scaled to match.
           The width and height will usually be the same, and are in points.  The resolution is
           in dots-per-inch.

           When generating PostScript outlines a resolution of 72 will scale to PostScript
           points.

       set_pixel_size(width, height)
           Set the size at which bitmapped fonts will be loaded.  Bitmap fonts are automatically
           set to the first available standard size, so this usually isn't needed.

       style_name()
           A string describing the style of the font, such as 'Roman' or 'Demi Bold'.  Most
           TrueType fonts are just 'Regular'.

       underline_position()
       underline_thickness()
           The suggested position and thickness of underlining for the font, or undef if the
           information isn't provided.  Currently in font units, but this is likely to be changed
           in a future version.

       units_per_em()
           The size of the em square used by the font designer.  This can be used to scale font-
           specific measurements to the right size, although that's usually done for you by
           FreeType.  Usually this is 2048 for TrueType fonts.

       charmap()
           The current active charmap for this face.

       charmaps()
           An array of the charmaps of the face.

       bounding_box()
           The outline's bounding box for this face.

SEE ALSO

       Font::FreeType, Font::FreeType::Glyph Font::FreeType::CharMap

AUTHOR

       Geoff Richards <qef@laxan.com>

COPYRIGHT

       Copyright 2004, Geoff Richards.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.