__init__.py

# -*- coding: utf-8 -*-
# -----------------------------------------------------------------------------
#
#  FreeType high-level python API - Copyright 2011-2015 Nicolas P. Rougier
#  Distributed under the terms of the new BSD license.
#
# -----------------------------------------------------------------------------
'''
FreeType high-level python API

This the bindings for the high-level API of FreeType (that must be installed
somewhere on your system).

Note: C Library will be searched using the ctypes.util.find_library. However,
      this search might fail. In such a case (or for other reasons), you may
      have to specify an explicit path below.
'''
import io
import sys
from ctypes import *
import ctypes.util
import struct

from freetype.raw import *

# Hack to get unicode class in python3
PY3 = sys.version_info[0] == 3
if PY3: unicode = str


def unmake_tag(i):
    # roughly opposite of FT_MAKE_TAG, converts 32-bit int to Python string
    # could do with .to_bytes if limited to Python 3.2 or higher...
    b = struct.pack('>I', i)
    return b.decode('ascii', errors='replace')

_handle = None


FT_Library_filename = filename

class _FT_Library_Wrapper(FT_Library):
    '''Subclass of FT_Library to help with calling FT_Done_FreeType'''
    # for some reason this doesn't get carried over and ctypes complains
    _type_ = FT_Library._type_

    # Store ref to FT_Done_FreeType otherwise it will be deleted before needed.
    _ft_done_freetype = FT_Done_FreeType

    def __del__(self):
        # call FT_Done_FreeType
        # This does not work properly (seg fault on sime system (OSX))
        # self._ft_done_freetype(self)
        pass
    

def _init_freetype():
    global _handle

    _handle = _FT_Library_Wrapper()
    error = FT_Init_FreeType( byref(_handle) )

    if error: raise FT_Exception(error)

    try:
        set_lcd_filter( FT_LCD_FILTER_DEFAULT )
    except:
        pass

# -----------------------------------------------------------------------------
# High-level API of FreeType 2
# -----------------------------------------------------------------------------


def get_handle():
    '''
    Get unique FT_Library handle
    '''

    if not _handle:
        _init_freetype()

    return _handle

def version():
    '''
    Return the version of the FreeType library being used as a tuple of
    ( major version number, minor version number, patch version number )
    '''
    amajor = FT_Int()
    aminor = FT_Int()
    apatch = FT_Int()

    library = get_handle()
    FT_Library_Version(library, byref(amajor), byref(aminor), byref(apatch))
    return (amajor.value, aminor.value, apatch.value)


# -----------------------------------------------------------------------------
#  Stand alone functions
# -----------------------------------------------------------------------------
def set_lcd_filter(filt):
    '''
    This function is used to apply color filtering to LCD decimated bitmaps,
    like the ones used when calling FT_Render_Glyph with FT_RENDER_MODE_LCD or
    FT_RENDER_MODE_LCD_V.

    **Note**

    This feature is always disabled by default. Clients must make an explicit
    call to this function with a 'filter' value other than FT_LCD_FILTER_NONE
    in order to enable it.

    Due to PATENTS covering subpixel rendering, this function doesn't do
    anything except returning 'FT_Err_Unimplemented_Feature' if the
    configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not defined in
    your build of the library, which should correspond to all default builds of
    FreeType.

    The filter affects glyph bitmaps rendered through FT_Render_Glyph,
    FT_Outline_Get_Bitmap, FT_Load_Glyph, and FT_Load_Char.

    It does not affect the output of FT_Outline_Render and
    FT_Outline_Get_Bitmap.

    If this feature is activated, the dimensions of LCD glyph bitmaps are
    either larger or taller than the dimensions of the corresponding outline
    with regards to the pixel grid. For example, for FT_RENDER_MODE_LCD, the
    filter adds up to 3 pixels to the left, and up to 3 pixels to the right.

    The bitmap offset values are adjusted correctly, so clients shouldn't need
    to modify their layout and glyph positioning code when enabling the filter.
    '''
    library = get_handle()
    error = FT_Library_SetLcdFilter(library, filt)
    if error: raise FT_Exception(error)



def set_lcd_filter_weights(a,b,c,d,e):
    '''
    Use this function to override the filter weights selected by
    FT_Library_SetLcdFilter. By default, FreeType uses the quintuple (0x00,
    0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10, 0x40, 0x70,
    0x40, 0x10) for FT_LCD_FILTER_DEFAULT and FT_LCD_FILTER_LEGACY.

    **Note**

    Only available if version > 2.4.0
    '''
    if version()>=(2,4,0):
        library = get_handle()
        weights = FT_Char(5)(a,b,c,d,e)
        error = FT_Library_SetLcdFilterWeights(library, weights)
        if error: raise FT_Exception(error)
    else:
        raise RuntimeError(
              'set_lcd_filter_weights require freetype > 2.4.0')


def _encode_filename(filename):
    encoded = filename.encode(sys.getfilesystemencoding())
    if "?" not in filename and b"?" in encoded:
        # A bug, decoding mbcs always ignore exception, still isn't fixed in Python 2,
        # view http://bugs.python.org/issue850997 for detail
        raise UnicodeError()
    return encoded



# -----------------------------------------------------------------------------
#  Direct wrapper (simple renaming)
# -----------------------------------------------------------------------------
Vector = FT_Vector
Matrix = FT_Matrix


# -----------------------------------------------------------------------------
# Handling for FT_Done_MM_Var, which was added in FreeType 2.9. Prior to that,
# we need to import libc and use libc free on the memory allocated for the
# FT_MM_Var data structure. See Face.get_variation_info().
# -----------------------------------------------------------------------------
if version() < (2,9,1):
    if platform.system() == "Windows":
        libcpath = ctypes.util.find_library("msvcrt")
    else:
        libcpath = ctypes.util.find_library("c")
    libc = CDLL(libcpath)
    libc.free.argtypes = [c_void_p]
    libc.free.restype = None

    def FT_Done_MM_Var_func(p):
        libc.free(p)
else:
    def FT_Done_MM_Var_func(p):
        error = FT_Done_MM_Var(get_handle(), p)
        if error:
            raise FT_Exception("Failure calling FT_Done_MM_Var")


# -----------------------------------------------------------------------------
class BBox( object ):
    '''
    FT_BBox wrapper.

    A structure used to hold an outline's bounding box, i.e., the coordinates
    of its extrema in the horizontal and vertical directions.

    **Note**

    The bounding box is specified with the coordinates of the lower left and
    the upper right corner. In PostScript, those values are often called
    (llx,lly) and (urx,ury), respectively.

    If 'yMin' is negative, this value gives the glyph's descender. Otherwise,
    the glyph doesn't descend below the baseline. Similarly, if 'ymax' is
    positive, this value gives the glyph's ascender.

    'xMin' gives the horizontal distance from the glyph's origin to the left
    edge of the glyph's bounding box. If 'xMin' is negative, the glyph
    extends to the left of the origin.
    '''

    def __init__(self, bbox):
        '''
        Create a new BBox object.

        :param bbox: a FT_BBox or a tuple of 4 values
        '''
        if type(bbox) is FT_BBox:
            self._FT_BBox = bbox
        else:
            self._FT_BBox = FT_BBox(*bbox)

    xMin = property(lambda self: self._FT_BBox.xMin,
                    doc = 'The horizontal minimum (left-most).')

    yMin = property(lambda self: self._FT_BBox.yMin,
                    doc = 'The vertical minimum (bottom-most).')

    xMax = property(lambda self: self._FT_BBox.xMax,
                    doc = 'The horizontal maximum (right-most).')

    yMax = property(lambda self: self._FT_BBox.yMax,
                    doc = 'The vertical maximum (top-most).')





# -----------------------------------------------------------------------------
class GlyphMetrics( object ):
    '''

    A structure used to model the metrics of a single glyph. The values are
    expressed in 26.6 fractional pixel format; if the flag FT_LOAD_NO_SCALE has
    been used while loading the glyph, values are expressed in font units
    instead.

    **Note**

    If not disabled with FT_LOAD_NO_HINTING, the values represent dimensions of
    the hinted glyph (in case hinting is applicable).

    Stroking a glyph with an outside border does not increase ‘horiAdvance’ or
    ‘vertAdvance’; you have to manually adjust these values to account for the
    added width and height.
    '''

    def __init__(self, metrics ):
        '''
        Create a new GlyphMetrics object.

        :param metrics: a FT_Glyph_Metrics
        '''
        self._FT_Glyph_Metrics = metrics

    width = property( lambda self: self._FT_Glyph_Metrics.width,
       doc = '''The glyph's width.''' )

    height = property( lambda self: self._FT_Glyph_Metrics.height,
       doc = '''The glyph's height.''' )

    horiBearingX = property( lambda self: self._FT_Glyph_Metrics.horiBearingX,
       doc = '''Left side bearing for horizontal layout.''' )

    horiBearingY = property( lambda self: self._FT_Glyph_Metrics.horiBearingY,
       doc = '''Top side bearing for horizontal layout.''' )

    horiAdvance = property( lambda self: self._FT_Glyph_Metrics.horiAdvance,
       doc = '''Advance width for horizontal layout.''' )

    vertBearingX = property( lambda self: self._FT_Glyph_Metrics.vertBearingX,
       doc = '''Left side bearing for vertical layout.''' )

    vertBearingY = property( lambda self: self._FT_Glyph_Metrics.vertBearingY,
       doc = '''Top side bearing for vertical layout. Larger positive values
                mean further below the vertical glyph origin.''' )

    vertAdvance = property( lambda self: self._FT_Glyph_Metrics.vertAdvance,
       doc = '''Advance height for vertical layout. Positive values mean the
                glyph has a positive advance downward.''' )


# -----------------------------------------------------------------------------
class SizeMetrics( object ):
    '''
    The size metrics structure gives the metrics of a size object.

    **Note**

    The scaling values, if relevant, are determined first during a size
    changing operation. The remaining fields are then set by the driver. For
    scalable formats, they are usually set to scaled values of the
    corresponding fields in Face.

    Note that due to glyph hinting, these values might not be exact for certain
    fonts. Thus they must be treated as unreliable with an error margin of at
    least one pixel!

    Indeed, the only way to get the exact metrics is to render all glyphs. As
    this would be a definite performance hit, it is up to client applications
    to perform such computations.

    The SizeMetrics structure is valid for bitmap fonts also.
    '''

    def __init__(self, metrics ):
        '''
        Create a new SizeMetrics object.

        :param metrics: a FT_SizeMetrics
        '''
        self._FT_Size_Metrics = metrics

    x_ppem = property( lambda self: self._FT_Size_Metrics.x_ppem,
       doc = '''The width of the scaled EM square in pixels, hence the term
                'ppem' (pixels per EM). It is also referred to as 'nominal
                width'.''' )

    y_ppem = property( lambda self: self._FT_Size_Metrics.y_ppem,
       doc = '''The height of the scaled EM square in pixels, hence the term
                'ppem' (pixels per EM). It is also referred to as 'nominal
                height'.''' )

    x_scale = property( lambda self: self._FT_Size_Metrics.x_scale,
        doc = '''A 16.16 fractional scaling value used to convert horizontal
                 metrics from font units to 26.6 fractional pixels. Only
                 relevant for scalable font formats.''' )

    y_scale = property( lambda self: self._FT_Size_Metrics.y_scale,
        doc = '''A 16.16 fractional scaling value used to convert vertical
                 metrics from font units to 26.6 fractional pixels. Only
                 relevant for scalable font formats.''' )

    ascender = property( lambda self: self._FT_Size_Metrics.ascender,
         doc = '''The ascender in 26.6 fractional pixels. See Face for the
                  details.''' )

    descender = property( lambda self: self._FT_Size_Metrics.descender,
          doc = '''The descender in 26.6 fractional pixels. See Face for the
                    details.''' )

    height = property( lambda self: self._FT_Size_Metrics.height,
       doc = '''The height in 26.6 fractional pixels. See Face for the details.''' )

    max_advance = property(lambda self: self._FT_Size_Metrics.max_advance,
            doc = '''The maximal advance width in 26.6 fractional pixels. See
                      Face for the details.''' )



# -----------------------------------------------------------------------------
class BitmapSize( object ):
    '''
    FT_Bitmap_Size wrapper

    This structure models the metrics of a bitmap strike (i.e., a set of glyphs
    for a given point size and resolution) in a bitmap font. It is used for the
    'available_sizes' field of Face.

    **Note**

    Windows FNT: The nominal size given in a FNT font is not reliable. Thus
    when the driver finds it incorrect, it sets 'size' to some calculated
    values and sets 'x_ppem' and 'y_ppem' to the pixel width and height given
    in the font, respectively.

    TrueType embedded bitmaps: 'size', 'width', and 'height' values are not
    contained in the bitmap strike itself. They are computed from the global
    font parameters.
    '''
    def __init__(self, size ):
        '''
        Create a new SizeMetrics object.

        :param size: a FT_Bitmap_Size
        '''
        self._FT_Bitmap_Size = size

    height = property( lambda self: self._FT_Bitmap_Size.height,
       doc = '''The vertical distance, in pixels, between two consecutive
                baselines. It is always positive.''')

    width = property( lambda self: self._FT_Bitmap_Size.width,
      doc = '''The average width, in pixels, of all glyphs in the strike.''')

    size = property( lambda self: self._FT_Bitmap_Size.size,
     doc = '''The nominal size of the strike in 26.6 fractional points. This
              field is not very useful.''')

    x_ppem = property( lambda self: self._FT_Bitmap_Size.x_ppem,
       doc = '''The horizontal ppem (nominal width) in 26.6 fractional
                pixels.''')

    y_ppem = property( lambda self: self._FT_Bitmap_Size.y_ppem,
       doc = '''The vertical ppem (nominal width) in 26.6 fractional
                pixels.''')


# -----------------------------------------------------------------------------
class Bitmap(object):
    '''
    FT_Bitmap wrapper

    A structure used to describe a bitmap or pixmap to the raster. Note that we
    now manage pixmaps of various depths through the 'pixel_mode' field.

    *Note*:

      For now, the only pixel modes supported by FreeType are mono and
      grays. However, drivers might be added in the future to support more
      'colorful' options.
    '''
    def __init__(self, bitmap):
        '''
        Create a new Bitmap object.

        :param bitmap: a FT_Bitmap
        '''
        self._FT_Bitmap = bitmap

    rows = property(lambda self: self._FT_Bitmap.rows,
     doc = '''The number of bitmap rows.''')

    width = property(lambda self: self._FT_Bitmap.width,
      doc = '''The number of pixels in bitmap row.''')

    pitch = property(lambda self: self._FT_Bitmap.pitch,
      doc = '''The pitch's absolute value is the number of bytes taken by one
               bitmap row, including padding. However, the pitch is positive
               when the bitmap has a 'down' flow, and negative when it has an
               'up' flow. In all cases, the pitch is an offset to add to a
               bitmap pointer in order to go down one row.

               Note that 'padding' means the alignment of a bitmap to a byte
               border, and FreeType functions normally align to the smallest
               possible integer value.

               For the B/W rasterizer, 'pitch' is always an even number.

               To change the pitch of a bitmap (say, to make it a multiple of
               4), use FT_Bitmap_Convert. Alternatively, you might use callback
               functions to directly render to the application's surface; see
               the file 'example2.py' in the tutorial for a demonstration.''')

    def _get_buffer(self):
        data = [self._FT_Bitmap.buffer[i] for i in range(self.rows*self.pitch)]
        return data
    buffer = property(_get_buffer,
       doc = '''A typeless pointer to the bitmap buffer. This value should be
                aligned on 32-bit boundaries in most cases.''')

    num_grays = property(lambda self: self._FT_Bitmap.num_grays,
          doc = '''This field is only used with FT_PIXEL_MODE_GRAY; it gives
                   the number of gray levels used in the bitmap.''')

    pixel_mode = property(lambda self: self._FT_Bitmap.pixel_mode,
           doc = '''The pixel mode, i.e., how pixel bits are stored. See
                    FT_Pixel_Mode for possible values.''')

    palette_mode = property(lambda self: self._FT_Bitmap.palette_mode,
             doc ='''This field is intended for paletted pixel modes; it
                     indicates how the palette is stored. Not used currently.''')

    palette = property(lambda self: self._FT_Bitmap.palette,
        doc = '''A typeless pointer to the bitmap palette; this field is
                 intended for paletted pixel modes. Not used currently.''')




# -----------------------------------------------------------------------------
class Charmap( object ):
    '''
    FT_Charmap wrapper.

    A handle to a given character map. A charmap is used to translate character
    codes in a given encoding into glyph indexes for its parent's face. Some
    font formats may provide several charmaps per font.

    Each face object owns zero or more charmaps, but only one of them can be
    'active' and used by FT_Get_Char_Index or FT_Load_Char.

    The list of available charmaps in a face is available through the
    'face.num_charmaps' and 'face.charmaps' fields of FT_FaceRec.

    The currently active charmap is available as 'face.charmap'. You should
    call FT_Set_Charmap to change it.

    **Note**:

      When a new face is created (either through FT_New_Face or FT_Open_Face),
      the library looks for a Unicode charmap within the list and automatically
      activates it.

    **See also**:

      See FT_CharMapRec for the publicly accessible fields of a given character
      map.
    '''

    def __init__( self, charmap ):
        '''
        Create a new Charmap object.

        Parameters:
        -----------
        charmap : a FT_Charmap
        '''
        self._FT_Charmap = charmap

    encoding = property( lambda self: self._FT_Charmap.contents.encoding,
         doc = '''An FT_Encoding tag identifying the charmap. Use this with
                  FT_Select_Charmap.''')

    platform_id = property( lambda self: self._FT_Charmap.contents.platform_id,
            doc = '''An ID number describing the platform for the following
                     encoding ID. This comes directly from the TrueType
                     specification and should be emulated for other
                     formats.''')

    encoding_id = property( lambda self: self._FT_Charmap.contents.encoding_id,
            doc = '''A platform specific encoding number. This also comes from
                     the TrueType specification and should be emulated
                     similarly.''')

    def _get_encoding_name(self):
        encoding = self.encoding
        for key,value in FT_ENCODINGS.items():
            if encoding == value:
                return key
        return 'Unknown encoding'
    encoding_name = property( _get_encoding_name,
              doc = '''A platform specific encoding name. This also comes from
                     the TrueType specification and should be emulated
                     similarly.''')

    def _get_index( self ):
        return FT_Get_Charmap_Index( self._FT_Charmap )
    index = property( _get_index,
      doc = '''The index into the array of character maps within the face to
               which 'charmap' belongs. If an error occurs, -1 is returned.''')

    def _get_cmap_language_id( self ):
        return FT_Get_CMap_Language_ID( self._FT_Charmap )
    cmap_language_id = property( _get_cmap_language_id,
                 doc = '''The language ID of 'charmap'. If 'charmap' doesn't
                          belong to a TrueType/sfnt face, just return 0 as the
                          default value.''')

    def _get_cmap_format( self ):
        return FT_Get_CMap_Format( self._FT_Charmap )
    cmap_format = property( _get_cmap_format,
            doc = '''The format of 'charmap'. If 'charmap' doesn't belong to a
                     TrueType/sfnt face, return -1.''')



# -----------------------------------------------------------------------------
class Outline( object ):
    '''
    FT_Outline wrapper.

    This structure is used to describe an outline to the scan-line converter.
    '''
    def __init__( self, outline ):
        '''
        Create a new Outline object.

        :param charmap: a FT_Outline
        '''
        self._FT_Outline = outline

    n_contours = property(lambda self: self._FT_Outline.n_contours)
    def _get_contours(self):
        n = self._FT_Outline.n_contours
        data = [self._FT_Outline.contours[i] for i in range(n)]
        return data
    contours = property(_get_contours,
         doc = '''The number of contours in the outline.''')

    n_points = property(lambda self: self._FT_Outline.n_points)
    def _get_points(self):
        n = self._FT_Outline.n_points
        data = []
        for i in range(n):
            v = self._FT_Outline.points[i]
            data.append( (v.x,v.y) )
        return data
    points = property( _get_points,
       doc = '''The number of points in the outline.''')

    def _get_tags(self):
        n = self._FT_Outline.n_points
        data = [self._FT_Outline.tags[i] for i in range(n)]
        return data
    tags = property(_get_tags,
     doc = '''A list of 'n_points' chars, giving each outline point's type.

              If bit 0 is unset, the point is 'off' the curve, i.e., a Bezier
              control point, while it is 'on' if set.

              Bit 1 is meaningful for 'off' points only. If set, it indicates a
              third-order Bezier arc control point; and a second-order control
              point if unset.

              If bit 2 is set, bits 5-7 contain the drop-out mode (as defined
              in the OpenType specification; the value is the same as the
              argument to the SCANMODE instruction).

              Bits 3 and 4 are reserved for internal purposes.''')

    flags = property(lambda self: self._FT_Outline.flags,
      doc = '''A set of bit flags used to characterize the outline and give
               hints to the scan-converter and hinter on how to
               convert/grid-fit it. See FT_OUTLINE_FLAGS.''')

    def get_inside_border( self ):
        '''
        Retrieve the FT_StrokerBorder value corresponding to the 'inside'
        borders of a given outline.

        :return: The border index. FT_STROKER_BORDER_RIGHT for empty or invalid
                 outlines.
        '''
        return FT_Outline_GetInsideBorder( byref(self._FT_Outline) )

    def get_outside_border( self ):
        '''
        Retrieve the FT_StrokerBorder value corresponding to the 'outside'
        borders of a given outline.

        :return: The border index. FT_STROKER_BORDER_RIGHT for empty or invalid
                 outlines.
        '''
        return FT_Outline_GetOutsideBorder( byref(self._FT_Outline) )

    def get_bbox(self):
        '''
        Compute the exact bounding box of an outline. This is slower than
        computing the control box. However, it uses an advanced algorithm which
        returns very quickly when the two boxes coincide. Otherwise, the
        outline Bezier arcs are traversed to extract their extrema.
        '''
        bbox = FT_BBox()
        error = FT_Outline_Get_BBox(byref(self._FT_Outline), byref(bbox))
        if error: raise FT_Exception(error)
        return BBox(bbox)

    def get_cbox(self):
        '''
        Return an outline's 'control box'. The control box encloses all the
        outline's points, including Bezier control points. Though it coincides
        with the exact bounding box for most glyphs, it can be slightly larger
        in some situations (like when rotating an outline which contains Bezier
        outside arcs).

        Computing the control box is very fast, while getting the bounding box
        can take much more time as it needs to walk over all segments and arcs
        in the outline. To get the latter, you can use the 'ftbbox' component
        which is dedicated to this single task.
        '''
        bbox = FT_BBox()
        FT_Outline_Get_CBox(byref(self._FT_Outline), byref(bbox))
        return BBox(bbox)

    _od_move_to_noop = FT_Outline_MoveToFunc(lambda a, b: 0)
    def _od_move_to_builder(self, cb):
        if cb is None:
            return self._od_move_to_noop
        def move_to(a, b):
            return cb(a[0], b) or 0
        return FT_Outline_MoveToFunc(move_to)

    _od_line_to_noop = FT_Outline_LineToFunc(lambda a, b: 0)
    def _od_line_to_builder(self, cb):
        if cb is None:
            return self._od_line_to_noop
        def line_to(a, b):
            return cb(a[0], b) or 0
        return FT_Outline_LineToFunc(line_to)

    _od_conic_to_noop = FT_Outline_ConicToFunc(lambda a, b, c: 0)
    def _od_conic_to_builder(self, cb):
        if cb is None:
            return self._od_conic_to_noop
        def conic_to(a, b, c):
            return cb(a[0], b[0], c) or 0
        return FT_Outline_ConicToFunc(conic_to)

    _od_cubic_to_noop = FT_Outline_CubicToFunc(lambda a, b, c, d: 0)
    def _od_cubic_to_builder(self, cb):
        if cb is None:
            return self._od_cubic_to_noop
        def cubic_to(a, b, c, d):
            return cb(a[0], b[0], c[0], d) or 0
        return FT_Outline_CubicToFunc(cubic_to)

    def decompose(self, context=None, move_to=None, line_to=None, conic_to=None, cubic_to=None, shift=0, delta=0):
        '''
        Decompose the outline into a sequence of move, line, conic, and
        cubic segments.

        :param context: Arbitrary contextual object which will be passed as
                        the last parameter of all callbacks. Typically an
                        object to be drawn to, but can be anything.

        :param move_to: Callback which will be passed an `FT_Vector`
                        control point and the context. Called when outline
                        needs to jump to a new path component.

        :param line_to: Callback which will be passed an `FT_Vector`
                        control point and the context. Called to draw a
                        straight line from the current position to the
                        control point.

        :param conic_to: Callback which will be passed two `FT_Vector`
                         control points and the context. Called to draw a
                         second-order Bézier curve from the current
                         position using the passed control points.

        :param curve_to: Callback which will be passed three `FT_Vector`
                         control points and the context. Called to draw a
                         third-order Bézier curve from the current position
                         using the passed control points.

        :param shift: Passed to FreeType which will transform vectors via
                      `x = (x << shift) - delta` and `y = (y << shift) - delta`

        :param delta: Passed to FreeType which will transform vectors via
                      `x = (x << shift) - delta` and `y = (y << shift) - delta`

        :since: 1.3
        '''
        func = FT_Outline_Funcs(
            move_to = self._od_move_to_builder(move_to),
            line_to = self._od_line_to_builder(line_to),
            conic_to = self._od_conic_to_builder(conic_to),
            cubic_to = self._od_cubic_to_builder(cubic_to),
            shift = shift,
            delta = FT_Pos(delta),
        )

        error = FT_Outline_Decompose( byref(self._FT_Outline), byref(func), py_object(context) )
        if error: raise FT_Exception( error )



# -----------------------------------------------------------------------------
class Glyph( object ):
    '''
    FT_Glyph wrapper.

    The root glyph structure contains a given glyph image plus its advance
    width in 16.16 fixed float format.
    '''
    def __init__( self, glyph ):
        '''
        Create Glyph object from an FT glyph.

        :param glyph: valid FT_Glyph object
        '''
        self._FT_Glyph = glyph

    def __del__( self ):
        '''
        Destroy glyph.
        '''
        FT_Done_Glyph( self._FT_Glyph )

    def _get_format( self ):
        return self._FT_Glyph.contents.format
    format = property( _get_format,
       doc = '''The format of the glyph's image.''')


    def stroke( self, stroker, destroy=False ):
        '''
        Stroke a given outline glyph object with a given stroker.

        :param stroker: A stroker handle.

        :param destroy: A Boolean. If 1, the source glyph object is destroyed on
                        success.

        **Note**:

          The source glyph is untouched in case of error.
        '''
        error = FT_Glyph_Stroke( byref(self._FT_Glyph),
                                 stroker._FT_Stroker, destroy )
        if error: raise FT_Exception( error )

    def to_bitmap( self, mode, origin, destroy=False ):
        '''
        Convert a given glyph object to a bitmap glyph object.

        :param mode: An enumeration that describes how the data is rendered.

        :param origin: A pointer to a vector used to translate the glyph image
                       before rendering. Can be 0 (if no translation). The origin is
                       expressed in 26.6 pixels.

                       We also detect a plain vector and make a pointer out of it,
                       if that's the case.

        :param destroy: A boolean that indicates that the original glyph image
                        should be destroyed by this function. It is never destroyed
                        in case of error.

        **Note**:

          This function does nothing if the glyph format isn't scalable.

          The glyph image is translated with the 'origin' vector before
          rendering.

          The first parameter is a pointer to an FT_Glyph handle, that will be
          replaced by this function (with newly allocated data). Typically, you
          would use (omitting error handling):
        '''
        if ( type(origin) == FT_Vector ):
            error = FT_Glyph_To_Bitmap( byref(self._FT_Glyph),
                                        mode, byref(origin), destroy )
        else:
            error = FT_Glyph_To_Bitmap( byref(self._FT_Glyph),
                                        mode, origin, destroy )

        if error: raise FT_Exception( error )
        return BitmapGlyph( self._FT_Glyph )

    def get_cbox(self, bbox_mode):
        '''
        Return an outline's 'control box'. The control box encloses all the
        outline's points, including Bezier control points. Though it coincides
        with the exact bounding box for most glyphs, it can be slightly larger
        in some situations (like when rotating an outline which contains Bezier
        outside arcs).

        Computing the control box is very fast, while getting the bounding box
        can take much more time as it needs to walk over all segments and arcs
        in the outline. To get the latter, you can use the 'ftbbox' component
        which is dedicated to this single task.

        :param mode: The mode which indicates how to interpret the returned
                     bounding box values.

        **Note**:

          Coordinates are relative to the glyph origin, using the y upwards
          convention.

          If the glyph has been loaded with FT_LOAD_NO_SCALE, 'bbox_mode' must be
          set to FT_GLYPH_BBOX_UNSCALED to get unscaled font units in 26.6 pixel
          format. The value FT_GLYPH_BBOX_SUBPIXELS is another name for this
          constant.

          Note that the maximum coordinates are exclusive, which means that one
          can compute the width and height of the glyph image (be it in integer
          or 26.6 pixels) as:

          width  = bbox.xMax - bbox.xMin;
          height = bbox.yMax - bbox.yMin;

          Note also that for 26.6 coordinates, if 'bbox_mode' is set to
          FT_GLYPH_BBOX_GRIDFIT, the coordinates will also be grid-fitted, which
          corresponds to:

          bbox.xMin = FLOOR(bbox.xMin);
          bbox.yMin = FLOOR(bbox.yMin);
          bbox.xMax = CEILING(bbox.xMax);
          bbox.yMax = CEILING(bbox.yMax);

          To get the bbox in pixel coordinates, set 'bbox_mode' to
          FT_GLYPH_BBOX_TRUNCATE.

          To get the bbox in grid-fitted pixel coordinates, set 'bbox_mode' to
          FT_GLYPH_BBOX_PIXELS.
        '''
        bbox = FT_BBox()
        FT_Glyph_Get_CBox(byref(self._FT_Glyph.contents), bbox_mode, byref(bbox))
        return BBox(bbox)



# -----------------------------------------------------------------------------
class BitmapGlyph( object ):
    '''
    FT_BitmapGlyph wrapper.

    A structure used for bitmap glyph images. This really is a 'sub-class' of
    FT_GlyphRec.
    '''
    def __init__( self, glyph ):
        '''
        Create Glyph object from an FT glyph.

        Parameters:
        -----------
          glyph: valid FT_Glyph object
        '''
        self._FT_BitmapGlyph = cast(glyph, FT_BitmapGlyph)

    # def __del__( self ):
    #     '''
    #     Destroy glyph.
    #     '''
    #     FT_Done_Glyph( cast(self._FT_BitmapGlyph, FT_Glyph) )


    def _get_format( self ):
        return self._FT_BitmapGlyph.contents.format
    format = property( _get_format,
       doc = '''The format of the glyph's image.''')


    def _get_bitmap( self ):
        return Bitmap( self._FT_BitmapGlyph.contents.bitmap )
    bitmap = property( _get_bitmap,
       doc = '''A descriptor for the bitmap.''')


    def _get_left( self ):
        return self._FT_BitmapGlyph.contents.left
    left = property( _get_left,
     doc = '''The left-side bearing, i.e., the horizontal distance from the
              current pen position to the left border of the glyph bitmap.''')


    def _get_top( self ):
        return self._FT_BitmapGlyph.contents.top
    top = property( _get_top,
    doc = '''The top-side bearing, i.e., the vertical distance from the
             current pen position to the top border of the glyph bitmap.
             This distance is positive for upwards y!''')


# -----------------------------------------------------------------------------
class GlyphSlot( object ):
    '''
    FT_GlyphSlot wrapper.

    FreeType root glyph slot class structure. A glyph slot is a container where
    individual glyphs can be loaded, be they in outline or bitmap format.
    '''

    def __init__( self, slot ):
        '''
        Create GlyphSlot object from an FT glyph slot.

        Parameters:
        -----------
          glyph: valid FT_GlyphSlot object
        '''
        self._FT_GlyphSlot = slot
        
    def render( self, render_mode ):
        '''
        Convert a given glyph image to a bitmap. It does so by inspecting the
        glyph image format, finding the relevant renderer, and invoking it.
        
        :param render_mode: The render mode used to render the glyph image into
                            a bitmap. See FT_Render_Mode for a list of possible
                            values.
                            
                            If FT_RENDER_MODE_NORMAL is used, a previous call
                            of FT_Load_Glyph with flag FT_LOAD_COLOR makes
                            FT_Render_Glyph provide a default blending of
                            colored glyph layers associated with the current
                            glyph slot (provided the font contains such layers)
                            instead of rendering the glyph slot's outline.
                            This is an experimental feature; see FT_LOAD_COLOR
                            for more information.
                            
        **Note**:
        
          To get meaningful results, font scaling values must be set with
          functions like FT_Set_Char_Size before calling FT_Render_Glyph.

          When FreeType outputs a bitmap of a glyph, it really outputs an alpha
          coverage map. If a pixel is completely covered by a filled-in
          outline, the bitmap contains 0xFF at that pixel, meaning that
          0xFF/0xFF fraction of that pixel is covered, meaning the pixel is
          100% black (or 0% bright). If a pixel is only 50% covered
          (value 0x80), the pixel is made 50% black (50% bright or a middle
          shade of grey). 0% covered means 0% black (100% bright or white).

          On high-DPI screens like on smartphones and tablets, the pixels are
          so small that their chance of being completely covered and therefore
          completely black are fairly good. On the low-DPI screens, however,
          the situation is different. The pixels are too large for most of the
          details of a glyph and shades of gray are the norm rather than the
          exception.

          This is relevant because all our screens have a second problem: they
          are not linear. 1 + 1 is not 2. Twice the value does not result in
          twice the brightness. When a pixel is only 50% covered, the coverage
          map says 50% black, and this translates to a pixel value of 128 when
          you use 8 bits per channel (0-255). However, this does not translate
          to 50% brightness for that pixel on our sRGB and gamma 2.2 screens.
          Due to their non-linearity, they dwell longer in the darks and only a
          pixel value of about 186 results in 50% brightness – 128 ends up too
          dark on both bright and dark backgrounds. The net result is that dark
          text looks burnt-out, pixely and blotchy on bright background, bright
          text too frail on dark backgrounds, and colored text on colored
          background (for example, red on green) seems to have dark halos or
          ‘dirt’ around it. The situation is especially ugly for diagonal stems
          like in ‘w’ glyph shapes where the quality of FreeType's
          anti-aliasing depends on the correct display of grays. On high-DPI
          screens where smaller, fully black pixels reign supreme, this doesn't
          matter, but on our low-DPI screens with all the gray shades, it does.
          0% and 100% brightness are the same things in linear and non-linear
          space, just all the shades in-between aren't.

          The blending function for placing text over a background is

          dst = alpha * src + (1 - alpha) * dst

          which is known as the OVER operator.

          To correctly composite an anti-aliased pixel of a glyph onto a
          surface, take the foreground and background colors (e.g., in sRGB
          space) and apply gamma to get them in a linear space, use OVER to
          blend the two linear colors using the glyph pixel as the alpha value
          (remember, the glyph bitmap is an alpha coverage bitmap), and apply
          inverse gamma to the blended pixel and write it back to the image.

          Internal testing at Adobe found that a target inverse gamma of 1.8
          for step 3 gives good results across a wide range of displays with
          an sRGB gamma curve or a similar one.

          This process can cost performance. There is an approximation that
          does not need to know about the background color; see
          https://bel.fi/alankila/lcd/ and
          https://bel.fi/alankila/lcd/alpcor.html for details.

          **ATTENTION:** Linear blending is even more important when dealing
          with subpixel-rendered glyphs to prevent color-fringing! A
          subpixel-rendered glyph must first be filtered with a filter that
          gives equal weight to the three color primaries and does not exceed a
          sum of 0x100, see section ‘Subpixel Rendering’. Then the only
          difference to gray linear blending is that subpixel-rendered linear
          blending is done 3 times per pixel: red foreground subpixel to red
          background subpixel and so on for green and blue.
        '''
        error = FT_Render_Glyph( self._FT_GlyphSlot, render_mode )
        if error: raise FT_Exception( error )

    def get_glyph( self ):
        '''
        A function used to extract a glyph image from a slot. Note that the
        created FT_Glyph object must be released with FT_Done_Glyph.
        '''
        aglyph = FT_Glyph()
        error = FT_Get_Glyph( self._FT_GlyphSlot, byref(aglyph) )
        if error: raise FT_Exception( error )
        return Glyph( aglyph )

    def _get_bitmap( self ):
        return Bitmap( self._FT_GlyphSlot.contents.bitmap )
    bitmap = property( _get_bitmap,
       doc = '''This field is used as a bitmap descriptor when the slot format
                is FT_GLYPH_FORMAT_BITMAP. Note that the address and content of
                the bitmap buffer can change between calls of FT_Load_Glyph and
                a few other functions.''')

    def _get_metrics( self ):
        return GlyphMetrics( self._FT_GlyphSlot.contents.metrics )
    metrics = property( _get_metrics,
       doc = '''The metrics of the last loaded glyph in the slot. The returned
       values depend on the last load flags (see the FT_Load_Glyph API
       function) and can be expressed either in 26.6 fractional pixels or font
       units. Note that even when the glyph image is transformed, the metrics
       are not.''')

    def _get_next( self ):
        return GlyphSlot( self._FT_GlyphSlot.contents.next )
    next = property( _get_next,
     doc = '''In some cases (like some font tools), several glyph slots per
              face object can be a good thing. As this is rare, the glyph slots
              are listed through a direct, single-linked list using its 'next'
              field.''')

    advance = property( lambda self: self._FT_GlyphSlot.contents.advance,
        doc = '''This shorthand is, depending on FT_LOAD_IGNORE_TRANSFORM, the
                 transformed advance width for the glyph (in 26.6 fractional
                 pixel format). As specified with FT_LOAD_VERTICAL_LAYOUT, it
                 uses either the 'horiAdvance' or the 'vertAdvance' value of
                 'metrics' field.''')

    def _get_outline( self ):
        return Outline( self._FT_GlyphSlot.contents.outline )
    outline = property( _get_outline,
        doc = '''The outline descriptor for the current glyph image if its
                 format is FT_GLYPH_FORMAT_OUTLINE. Once a glyph is loaded,
                 'outline' can be transformed, distorted, embolded,
                 etc. However, it must not be freed.''')

    format = property( lambda self: self._FT_GlyphSlot.contents.format,
       doc = '''This field indicates the format of the image contained in the
                glyph slot. Typically FT_GLYPH_FORMAT_BITMAP,
                FT_GLYPH_FORMAT_OUTLINE, or FT_GLYPH_FORMAT_COMPOSITE, but
                others are possible.''')

    bitmap_top  = property( lambda self:
                             self._FT_GlyphSlot.contents.bitmap_top,
            doc = '''This is the bitmap's top bearing expressed in integer
                     pixels. Remember that this is the distance from the
                     baseline to the top-most glyph scanline, upwards y
                     coordinates being positive.''')

    bitmap_left = property( lambda self:
                            self._FT_GlyphSlot.contents.bitmap_left,
            doc = '''This is the bitmap's left bearing expressed in integer
                     pixels. Of course, this is only valid if the format is
                     FT_GLYPH_FORMAT_BITMAP.''')

    linearHoriAdvance = property( lambda self:
                                  self._FT_GlyphSlot.contents.linearHoriAdvance,
                  doc = '''The advance width of the unhinted glyph. Its value
                           is expressed in 16.16 fractional pixels, unless
                           FT_LOAD_LINEAR_DESIGN is set when loading the glyph.
                           This field can be important to perform correct
                           WYSIWYG layout. Only relevant for outline glyphs.''')

    linearVertAdvance = property( lambda self:
                                  self._FT_GlyphSlot.contents.linearVertAdvance,
                  doc = '''The advance height of the unhinted glyph. Its value
                           is expressed in 16.16 fractional pixels, unless
                           FT_LOAD_LINEAR_DESIGN is set when loading the glyph.
                           This field can be important to perform correct
                           WYSIWYG layout. Only relevant for outline glyphs.''')


# -----------------------------------------------------------------------------
#  Face wrapper
# -----------------------------------------------------------------------------
class Face( object ):
    '''
    FT_Face wrapper

    FreeType root face class structure. A face object models a typeface in a
    font file.
    '''
    def __init__( self, path_or_stream, index = 0 ):
        '''
        Build a new Face

        :param Union[str, typing.BinaryIO] path_or_stream:
            A path to the font file or an io.BytesIO stream.

        :param int index:
               The index of the face within the font.
               The first face has index 0.
        '''
        library = get_handle( )
        face = FT_Face( )
        self._FT_Face = None
        #error = FT_New_Face( library, path_or_stream, 0, byref(face) )
        self._filebodys = []
        if hasattr(path_or_stream, "read"):
            error = self._init_from_memory(library, face, index, path_or_stream.read())
        else:
            try:
                error = self._init_from_file(library, face, index, path_or_stream)
            except UnicodeError:
                with open(path_or_stream, mode="rb") as f:
                    filebody = f.read()
                error = self._init_from_memory(library, face, index, filebody)
        if error:
            raise FT_Exception(error)
        self._index = index
        self._FT_Face = face
        self._name_strings = dict()

    def _init_from_file(self, library, face, index, path):
        u_filename = c_char_p(_encode_filename(path))
        error = FT_New_Face(library, u_filename, index, byref(face))
        return error

    def _init_from_memory(self, library, face, index, byte_stream):
        error = FT_New_Memory_Face(
            library, byte_stream, len(byte_stream), index, byref(face)
        )
        self._filebodys.append(byte_stream)  # prevent gc
        return error

    def _init_name_string_map(self):
        # build map of (nID, pID, eID, lID) keys to name string bytes
        self._name_strings = dict()

        for nidx in range(self._get_sfnt_name_count()):
            namerec = self.get_sfnt_name(nidx)
            nk = (namerec.name_id,
                    namerec.platform_id,
                    namerec.encoding_id,
                    namerec.language_id)

            self._name_strings[nk] = namerec.string

    @classmethod
    def from_bytes(cls, bytes_, index=0):
         return cls(io.BytesIO(bytes_), index)

    def __del__( self ):
        '''
        Discard  face object, as well as all of its child slots and sizes.
        '''
        # We check FT_Done_Face because by the time we're called it
        # may already be gone (see #44 and discussion in #169)
        if FT_Done_Face is not None and self._FT_Face is not None:
            FT_Done_Face( self._FT_Face )


    def attach_file( self, filename ):
        '''
        Attach data to a face object. Normally, this is used to read
        additional information for the face object. For example, you can attach
        an AFM file that comes with a Type 1 font to get the kerning values and
        other metrics.

        :param filename: Filename to attach

        **Note**

        The meaning of the 'attach' (i.e., what really happens when the new
        file is read) is not fixed by FreeType itself. It really depends on the
        font format (and thus the font driver).

        Client applications are expected to know what they are doing when
        invoking this function. Most drivers simply do not implement file
        attachments.
        '''

        try:
            u_filename = c_char_p(_encode_filename(filename))
            error = FT_Attach_File( self._FT_Face, u_filename )
        except UnicodeError:
            with open(filename, mode='rb') as f:
                filebody = f.read()
            parameters = FT_Open_Args()
            parameters.flags = FT_OPEN_MEMORY
            parameters.memory_base = filebody
            parameters.memory_size = len(filebody)
            parameters.stream = None
            error = FT_Attach_Stream( self._FT_Face, parameters )
            self._filebodys.append(filebody)  # prevent gc
        if error: raise FT_Exception( error)


    def set_char_size( self, width=0, height=0, hres=72, vres=72 ):
        '''
        This function calls FT_Request_Size to request the nominal size (in
        points).

        :param float width: The nominal width, in 26.6 fractional points.

        :param float height: The nominal height, in 26.6 fractional points.

        :param float hres: The horizontal resolution in dpi.

        :param float vres: The vertical resolution in dpi.

        **Note**

        If either the character width or height is zero, it is set equal to the
        other value.

        If either the horizontal or vertical resolution is zero, it is set
        equal to the other value.

        A character width or height smaller than 1pt is set to 1pt; if both
        resolution values are zero, they are set to 72dpi.

        Don't use this function if you are using the FreeType cache API.
        '''
        error = FT_Set_Char_Size( self._FT_Face, width, height, hres, vres )
        if error: raise FT_Exception( error)

    def set_pixel_sizes( self, width, height ):
        '''
        This function calls FT_Request_Size to request the nominal size (in
        pixels).

        :param width: The nominal width, in pixels.

        :param height: The nominal height, in pixels.
        '''
        error = FT_Set_Pixel_Sizes( self._FT_Face, width, height )
        if error: raise FT_Exception(error)

    def select_charmap( self, encoding ):
        '''
        Select a given charmap by its encoding tag (as listed in 'freetype.h').

        **Note**:

          This function returns an error if no charmap in the face corresponds to
          the encoding queried here.

          Because many fonts contain more than a single cmap for Unicode
          encoding, this function has some special code to select the one which
          covers Unicode best ('best' in the sense that a UCS-4 cmap is preferred
          to a UCS-2 cmap). It is thus preferable to FT_Set_Charmap in this case.
        '''
        error = FT_Select_Charmap( self._FT_Face, encoding )
        if error: raise FT_Exception(error)

    def set_charmap( self, charmap ):
        '''
        Select a given charmap for character code to glyph index mapping.

        :param charmap: A handle to the selected charmap, or an index to face->charmaps[]
        '''
        if ( type(charmap) == Charmap ):
            error = FT_Set_Charmap( self._FT_Face, charmap._FT_Charmap )
            # Type 14 is allowed to fail, to match ft2demo's behavior.
            if ( charmap.cmap_format == 14 ):
                error = 0
        else:
            # Treat "charmap" as plain number
            error = FT_Set_Charmap( self._FT_Face, self._FT_Face.contents.charmaps[charmap] )
        if error : raise FT_Exception(error)

    def get_char_index( self, charcode ):
        '''
        Return the glyph index of a given character code. This function uses a
        charmap object to do the mapping.

        :param charcode: The character code.

        **Note**:

          If you use FreeType to manipulate the contents of font files directly,
          be aware that the glyph index returned by this function doesn't always
          correspond to the internal indices used within the file. This is done
          to ensure that value 0 always corresponds to the 'missing glyph'.
        '''
        if isinstance(charcode, (str,unicode)):
            charcode = ord(charcode)
        return FT_Get_Char_Index( self._FT_Face, charcode )

    def get_glyph_name(self, agindex, buffer_max=64):
        '''
        This function is used to return the glyph name for the given charcode.

        :param agindex: The glyph index.

        :param buffer_max: The maximum number of bytes to use to store the
            glyph name.

        :param glyph_name: The glyph name, possibly truncated.

        '''
        buff = create_string_buffer(buffer_max)
        error = FT_Get_Glyph_Name(self._FT_Face, FT_UInt(agindex), byref(buff),
                                  FT_UInt(buffer_max))
        if error: raise FT_Exception(error)
        return buff.value

    def get_chars( self ):
        '''
        This generator function is used to return all unicode character
        codes in the current charmap of a given face. For each character it
        also returns the corresponding glyph index.

        :return: character code, glyph index

        **Note**:
          Note that 'agindex' is set to 0 if the charmap is empty. The
          character code itself can be 0 in two cases: if the charmap is empty
          or if the value 0 is the first valid character code.
        '''
        charcode, agindex = self.get_first_char()
        yield charcode, agindex
        while agindex != 0:
            charcode, agindex = self.get_next_char(charcode, 0)
            yield charcode, agindex

    def get_first_char( self ):
        '''
        This function is used to return the first character code in the current
        charmap of a given face. It also returns the corresponding glyph index.

        :return: Glyph index of first character code. 0 if charmap is empty.

        **Note**:

          You should use this function with get_next_char to be able to parse
          all character codes available in a given charmap. The code should look
          like this:

          Note that 'agindex' is set to 0 if the charmap is empty. The result
          itself can be 0 in two cases: if the charmap is empty or if the value 0
          is the first valid character code.
        '''
        agindex = FT_UInt()
        charcode = FT_Get_First_Char( self._FT_Face, byref(agindex) )
        return charcode, agindex.value

    def get_next_char( self, charcode, agindex ):
        '''
        This function is used to return the next character code in the current
        charmap of a given face following the value 'charcode', as well as the
        corresponding glyph index.

        :param charcode: The starting character code.

        :param agindex: Glyph index of next character code. 0 if charmap is empty.

        **Note**:

          You should use this function with FT_Get_First_Char to walk over all
          character codes available in a given charmap. See the note for this
          function for a simple code example.

          Note that 'agindex' is set to 0 when there are no more codes in the
          charmap.
        '''
        agindex = FT_UInt( 0 ) #agindex )
        charcode = FT_Get_Next_Char( self._FT_Face, charcode, byref(agindex) )
        return charcode, agindex.value

    def get_name_index( self, name ):
        '''
        Return the glyph index of a given glyph name. This function uses driver
        specific objects to do the translation.

        :param name: The glyph name.
        '''
        if not isinstance(name, bytes):
            raise FT_Exception(0x06, "FT_Get_Name_Index() expects a binary "
                               "string for the name parameter.")
        return FT_Get_Name_Index( self._FT_Face, name )

    def set_transform( self, matrix, delta ):
        '''
        A function used to set the transformation that is applied to glyph
        images when they are loaded into a glyph slot through FT_Load_Glyph.

        :param matrix: A pointer to the transformation's 2x2 matrix.
                       Use 0 for the identity matrix.

        :parm delta: A pointer to the translation vector.
                     Use 0 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 FT_Set_Char_Size or FT_Set_Pixel_Sizes.

          Note that this also transforms the 'face.glyph.advance' field, but
          not the values in 'face.glyph.metrics'.
        '''
        FT_Set_Transform( self._FT_Face,
                          byref(matrix), byref(delta) )

    def select_size( self, strike_index ):
        '''
        Select a bitmap strike.

        :param strike_index: The index of the bitmap strike in the
                             'available_sizes' field of Face object.
        '''
        error = FT_Select_Size( self._FT_Face, strike_index )
        if error: raise FT_Exception( error )

    def load_glyph( self, index, flags = FT_LOAD_RENDER ):
        '''
        A function used to load a single glyph into the glyph slot of a face
        object.

        :param index: The index of the glyph in the font file. For CID-keyed
                      fonts (either in PS or in CFF format) this argument
                      specifies the CID value.

        :param flags: A flag indicating what to load for this glyph. The FT_LOAD_XXX
                      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**:

          The loaded glyph may be transformed. See FT_Set_Transform for the
          details.

          For subsetted CID-keyed fonts, 'FT_Err_Invalid_Argument' is returned
          for invalid CID values (this is, for CID values which don't have a
          corresponding glyph in the font). See the discussion of the
          FT_FACE_FLAG_CID_KEYED flag for more details.
        '''
        error = FT_Load_Glyph( self._FT_Face, index, flags )
        if error: raise FT_Exception( error )

    def load_char( self, char, flags = FT_LOAD_RENDER ):
        '''
        A function used to load a single glyph into the glyph slot of a face
        object, according to its character code.

        :param char: The glyph's character code, according to the current
                     charmap used in the face.

        :param flags: A flag indicating what to load for this glyph. The
                      FT_LOAD_XXX 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**:

          This function simply calls FT_Get_Char_Index and FT_Load_Glyph.
        '''

        # python 2 with ascii input
        if ( isinstance(char, str) and ( len(char) == 1 ) ):
            char = ord(char)
        # python 2 with utf8 string input
        if ( isinstance(char, str) and ( len(char) != 1 ) ):
            char = ord(char.decode('utf8'))
        # python 3 or python 2 with __future__.unicode_literals
        if ( isinstance(char, unicode) and ( len(char) == 1 ) ):
            char = ord(char)
        # allow bare integer to pass through
        error = FT_Load_Char( self._FT_Face, char, flags )
        if error: raise FT_Exception( error )


    def get_advance( self, gindex, flags ):
        '''
        Retrieve the advance value of a given glyph outline in an FT_Face. By
        default, the unhinted advance is returned in font units.

        :param gindex: The glyph index.

        :param flags: A set of bit flags similar to those used when calling
                      FT_Load_Glyph, used to determine what kind of advances
                      you need.

        :return: The advance value, in either font units or 16.16 format.

                 If FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical
                 advance corresponding to a vertical layout. Otherwise, it is
                 the horizontal advance in a horizontal layout.
        '''

        padvance = FT_Fixed(0)
        error = FT_Get_Advance( self._FT_Face, gindex, flags, byref(padvance) )
        if error: raise FT_Exception( error )
        return padvance.value



    def get_kerning( self, left, right, mode = FT_KERNING_DEFAULT ):
        '''
        Return the kerning vector between two glyphs of a same face.

        :param left: The index of the left glyph in the kern pair.

        :param right: The index of the right glyph in the kern pair.

        :param mode: See FT_Kerning_Mode for more information. Determines the scale
                     and dimension of the returned kerning vector.

        **Note**:

          Only horizontal layouts (left-to-right & right-to-left) are supported
          by this method. Other layouts, or more sophisticated kernings, are out
          of the scope of this API function -- they can be implemented through
          format-specific interfaces.
        '''
        left_glyph = self.get_char_index( left )
        right_glyph = self.get_char_index( right )
        kerning = FT_Vector(0,0)
        error = FT_Get_Kerning( self._FT_Face,
                                left_glyph, right_glyph, mode, byref(kerning) )
        if error: raise FT_Exception( error )
        return kerning

    def get_format(self):
        '''
        Return a string describing the format of a given face, using values
        which can be used as an X11 FONT_PROPERTY. Possible values are
        'TrueType', 'Type 1', 'BDF', ‘PCF', ‘Type 42', ‘CID Type 1', ‘CFF',
        'PFR', and ‘Windows FNT'.
        '''

        return FT_Get_X11_Font_Format( self._FT_Face )


    def get_fstype(self):
        '''
        Return the fsType flags for a font (embedding permissions).

        The return value is a tuple containing the freetype enum name
        as a string and the actual flag as an int
        '''

        flag = FT_Get_FSType_Flags( self._FT_Face )
        for k, v in FT_FSTYPES.items():
            if v == flag:
                return k, v


    def _get_sfnt_name_count(self):
        return FT_Get_Sfnt_Name_Count( self._FT_Face )
    sfnt_name_count = property(_get_sfnt_name_count,
                doc = '''Number of name strings in the SFNT 'name' table.''')

    def get_sfnt_name( self, index ):
        '''
        Retrieve a string of the SFNT 'name' table for a given index

        :param index: The index of the 'name' string.

        **Note**:

          The 'string' array returned in the 'aname' structure is not
          null-terminated. The application should deallocate it if it is no
          longer in use.

          Use FT_Get_Sfnt_Name_Count to get the total number of available
          'name' table entries, then do a loop until you get the right
          platform, encoding, and name ID.
        '''
        name = FT_SfntName( )
        error = FT_Get_Sfnt_Name( self._FT_Face, index, byref(name) )
        if error: raise FT_Exception( error )
        return SfntName( name )

    def get_best_name_string(self, nameID, default_string='', preferred_order=None):
        '''
        Retrieve a name string given nameID. Searches available font names
        matching nameID and returns the decoded bytes of the best match.
        "Best" is defined as a preferred list of platform/encoding/languageIDs
        which can be overridden by supplying a preferred_order matching the
        scheme of 'sort_order' (see below).

        The routine will attempt to decode the string's bytes to a Python str, when the
        platform/encoding[/langID] are known (Windows, Mac, or Unicode platforms).
 
        If you prefer more control over name string selection and decoding than
        this routine provides:
            - call self._init_name_string_map()
            - use (nameID, platformID, encodingID, languageID) as a key into 
              the self._name_strings dict
       '''
        if not(self._name_strings):
            self._init_name_string_map()

        sort_order = preferred_order or (
            (3, 1, 1033),  # Microsoft/Windows/US English
            (1, 0, 0),     # Mac/Roman/English
            (0, 6, 0),     # Unicode/SMP/*
            (0, 4, 0),     # Unicode/SMP/*
            (0, 3, 0),     # Unicode/BMP/*
            (0, 2, 0),     # Unicode/10646-BMP/*
            (0, 1, 0),     # Unicode/1.1/*
        )

        # get all keys matching nameID
        keys_present = [k for k in self._name_strings.keys() if k[0] == nameID]

        if keys_present:
            # sort found keys by sort_order
            key_order = {k: v for v, k in enumerate(sort_order)}
            keys_present.sort(key=lambda x: key_order.get(x[1:4]))
            best_key = keys_present[0]
            nsbytes = self._name_strings[best_key]

            if best_key[1:3] == (3, 1) or best_key[1] == 0:
                enc = "utf-16-be"
            elif best_key[1:4] == (1, 0, 0):
                enc = "mac-roman"
            else:
                enc = "unicode_escape"

            ns = nsbytes.decode(enc)

        else:
            ns = default_string

        return ns

    def get_variation_info(self):
        '''
        Retrieves variation space information for the current face.
        '''
        if version() < (2, 8, 1):
            raise NotImplementedError("freetype-py VF support requires FreeType 2.8.1 or later")

        p_amaster = pointer(FT_MM_Var())
        error = FT_Get_MM_Var(self._FT_Face, byref(p_amaster))
        
        if error:
            raise FT_Exception(error)

        vsi = VariationSpaceInfo(self, p_amaster)

        FT_Done_MM_Var_func(p_amaster)

        return vsi

    def get_var_blend_coords(self):
        '''
        Get the current blend coordinates (-1.0..+1.0)
        '''
        vsi = self.get_variation_info()
        num_coords = len(vsi.axes)
        ft_coords = (FT_Fixed * num_coords)()
        error = FT_Get_Var_Blend_Coordinates(self._FT_Face, num_coords, byref(ft_coords))

        if error:
            raise FT_Exception(error)

        coords = tuple([ft_coords[ai]/65536.0 for ai in range(num_coords)])

        return coords

    def set_var_blend_coords(self, coords, reset=False):
        '''
        Set blend coords. Using reset=True will set all axes to
        their default coordinates.
        '''
        if reset:
            error = FT_Set_Var_Blend_Coordinates(self._FT_Face, 0, 0)
        else:
            num_coords = len(coords)
            ft_coords = [int(round(c * 65536.0)) for c in coords]
            coords_array = (FT_Fixed * num_coords)(*ft_coords)
            error = FT_Set_Var_Blend_Coordinates(self._FT_Face, num_coords, byref(coords_array))

        if error:
            raise FT_Exception(error)

    def get_var_design_coords(self):
        '''
        Get the current design coordinates
        '''
        vsi = self.get_variation_info()
        num_coords = len(vsi.axes)
        ft_coords = (FT_Fixed * num_coords)()
        error = FT_Get_Var_Design_Coordinates(self._FT_Face, num_coords, byref(ft_coords))

        if error:
            raise FT_Exception(error)

        coords = tuple([ft_coords[ai]/65536.0 for ai in range(num_coords)])

        return coords

    def set_var_design_coords(self, coords, reset=False):
        '''
        Set design coords. Using reset=True will set all axes to
        their default coordinates.
        '''
        if reset:
            error = FT_Set_Var_Design_Coordinates(self._FT_Face, 0, 0)
        
        else:
            num_coords = len(coords)
            ft_coords = [int(round(c * 65536.0)) for c in coords]
            coords_array = (FT_Fixed * num_coords)(*ft_coords)
            error = FT_Set_Var_Design_Coordinates(self._FT_Face, num_coords, byref(coords_array))

        if error:
            raise FT_Exception(error)

    def set_var_named_instance(self, instance_name):
        '''
        Set instance by name. This will work with any FreeType with variable support
        (for our purposes: v2.8.1 or later). If the actual FT_Set_Named_Instance()
        function is available (v2.9.1 or later), we use it (which, despite what you might
        expect from its name, sets instances by *index*). Otherwise we just use the coords
        of the named instance (if found) and call self.set_var_design_coords.
        '''
        have_func = freetype.version() >= (2, 9, 1)
        vsi = self.get_variation_info()

        for inst_idx, inst in enumerate(vsi.instances, start=1):
            if inst.name == instance_name:
                if have_func:
                    error = FT_Set_Named_Instance(self._FT_Face, inst_idx)
                else:
                    error = self.set_var_design_coords(inst.coords)

                if error:
                    raise FT_Exception(error)

                break

        # named instance not found; do nothing

    def _get_postscript_name( self ):
        return FT_Get_Postscript_Name( self._FT_Face )
    postscript_name = property( _get_postscript_name,
                doc = '''ASCII PostScript name of face, if available. This only
                         works with PostScript and TrueType fonts.''')

    def _has_horizontal( self ):
        return bool( self.face_flags & FT_FACE_FLAG_HORIZONTAL )
    has_horizontal = property( _has_horizontal,
               doc = '''True whenever a face object contains horizontal metrics
               (this is true for all font formats though).''')

    def _has_vertical( self ):
        return bool( self.face_flags & FT_FACE_FLAG_VERTICAL )
    has_vertical = property( _has_vertical,
             doc = '''True whenever a face object contains vertical metrics.''')

    def _has_kerning( self ):
        return bool( self.face_flags & FT_FACE_FLAG_KERNING )
    has_kerning = property( _has_kerning,
            doc = '''True whenever a face object contains kerning data that can
                     be accessed with FT_Get_Kerning.''')

    def _is_scalable( self ):
        return bool( self.face_flags & FT_FACE_FLAG_SCALABLE )
    is_scalable = property( _is_scalable,
            doc = '''true whenever a face object contains a scalable font face
                     (true for TrueType, Type 1, Type 42, CID, OpenType/CFF,
                     and PFR font formats.''')

    def _is_sfnt( self ):
        return bool( self.face_flags & FT_FACE_FLAG_SFNT )
    is_sfnt = property( _is_sfnt,
        doc = '''true whenever a face object contains a font whose format is
                 based on the SFNT storage scheme. This usually means: TrueType
                 fonts, OpenType fonts, as well as SFNT-based embedded bitmap
                 fonts.

                 If this macro is true, all functions defined in
                 FT_SFNT_NAMES_H and FT_TRUETYPE_TABLES_H are available.''')

    def _is_fixed_width( self ):
        return bool( self.face_flags & FT_FACE_FLAG_FIXED_WIDTH )
    is_fixed_width = property( _is_fixed_width,
               doc = '''True whenever a face object contains a font face that
                        contains fixed-width (or 'monospace', 'fixed-pitch',
                        etc.) glyphs.''')

    def _has_fixed_sizes( self ):
        return bool( self.face_flags & FT_FACE_FLAG_FIXED_SIZES )
    has_fixed_sizes = property( _has_fixed_sizes,
                doc = '''True whenever a face object contains some embedded
                bitmaps. See the 'available_sizes' field of the FT_FaceRec
                structure.''')

    def _has_glyph_names( self ):
        return bool( self.face_flags & FT_FACE_FLAG_GLYPH_NAMES )
    has_glyph_names = property( _has_glyph_names,
                doc = '''True whenever a face object contains some glyph names
                         that can be accessed through FT_Get_Glyph_Name.''')

    def _has_multiple_masters( self ):
        return bool( self.face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS )
    has_multiple_masters = property( _has_multiple_masters,
                     doc = '''True whenever a face object contains some
                              multiple masters. The functions provided by
                              FT_MULTIPLE_MASTERS_H are then available to
                              choose the exact design you want.''')

    def _is_cid_keyed( self ):
        return bool( self.face_flags & FT_FACE_FLAG_CID_KEYED )
    is_cid_keyed = property( _is_cid_keyed,
             doc = '''True whenever a face object contains a CID-keyed
                      font. See the discussion of FT_FACE_FLAG_CID_KEYED for
                      more details.

                      If this macro is true, all functions defined in FT_CID_H
                      are available.''')

    def _is_tricky( self ):
        return bool( self.face_flags & FT_FACE_FLAG_TRICKY )
    is_tricky = property( _is_tricky,
          doc = '''True whenever a face represents a 'tricky' font. See the
                   discussion of FT_FACE_FLAG_TRICKY for more details.''')


    num_faces = property(lambda self: self._FT_Face.contents.num_faces,
          doc = '''The number of faces in the font file. Some font formats can
                   have multiple faces in a font file.''')

    face_index = property(lambda self: self._FT_Face.contents.face_index,
           doc = '''The index of the face in the font file. It is set to 0 if
                    there is only one face in the font file.''')

    face_flags = property(lambda self: self._FT_Face.contents.face_flags,
           doc = '''A set of bit flags that give important information about
                    the face; see FT_FACE_FLAG_XXX for the details.''')

    style_flags = property(lambda self: self._FT_Face.contents.style_flags,
            doc = '''A set of bit flags indicating the style of the face; see
                     FT_STYLE_FLAG_XXX for the details.''')

    num_glyphs = property(lambda self: self._FT_Face.contents.num_glyphs,
           doc = '''The number of glyphs in the face. If the face is scalable
           and has sbits (see 'num_fixed_sizes'), it is set to the number of
           outline glyphs.

           For CID-keyed fonts, this value gives the highest CID used in the
           font.''')

    family_name = property(lambda self: self._FT_Face.contents.family_name,
            doc = '''The face's family name. This is an ASCII string, usually
                     in English, which describes the typeface's family (like
                     'Times New Roman', 'Bodoni', 'Garamond', etc). This is a
                     least common denominator used to list fonts. Some formats
                     (TrueType & OpenType) provide localized and Unicode
                     versions of this string. Applications should use the
                     format specific interface to access them. Can be NULL
                     (e.g., in fonts embedded in a PDF file).''')

    style_name = property(lambda self: self._FT_Face.contents.style_name,
           doc = '''The face's style name. This is an ASCII string, usually in
                    English, which describes the typeface's style (like
                    'Italic', 'Bold', 'Condensed', etc). Not all font formats
                    provide a style name, so this field is optional, and can be
                    set to NULL. As for 'family_name', some formats provide
                    localized and Unicode versions of this string. Applications
                    should use the format specific interface to access them.''')

    num_fixed_sizes = property(lambda self: self._FT_Face.contents.num_fixed_sizes,
                doc = '''The number of bitmap strikes in the face. Even if the
                         face is scalable, there might still be bitmap strikes,
                         which are called 'sbits' in that case.''')

    def _get_available_sizes( self ):
        sizes = []
        n = self.num_fixed_sizes
        FT_sizes = self._FT_Face.contents.available_sizes
        for i in range(n):
            sizes.append( BitmapSize(FT_sizes[i]) )
        return sizes
    available_sizes = property(_get_available_sizes,
                doc = '''A list of FT_Bitmap_Size for all bitmap strikes in the
                face. It is set to NULL if there is no bitmap strike.''')

    num_charmaps = property(lambda self: self._FT_Face.contents.num_charmaps)
    def _get_charmaps( self ):
        charmaps = []
        n = self._FT_Face.contents.num_charmaps
        FT_charmaps = self._FT_Face.contents.charmaps
        for i in range(n):
            charmaps.append( Charmap(FT_charmaps[i]) )
        return charmaps
    charmaps = property(_get_charmaps,
         doc = '''A list of the charmaps of the face.''')

    #       ('generic', FT_Generic),

    def _get_bbox( self ):
        return BBox( self._FT_Face.contents.bbox )
    bbox = property( _get_bbox,
     doc = '''The font bounding box. Coordinates are expressed in font units
              (see 'units_per_EM'). The box is large enough to contain any
              glyph from the font. Thus, 'bbox.yMax' can be seen as the
              'maximal ascender', and 'bbox.yMin' as the 'minimal
              descender'. Only relevant for scalable formats.

              Note that the bounding box might be off by (at least) one pixel
              for hinted fonts. See FT_Size_Metrics for further discussion.''')

    units_per_EM = property(lambda self: self._FT_Face.contents.units_per_EM,
             doc = '''The number of font units per EM square for this
                      face. This is typically 2048 for TrueType fonts, and 1000
                      for Type 1 fonts. Only relevant for scalable formats.''')

    ascender = property(lambda self: self._FT_Face.contents.ascender,
         doc = '''The typographic ascender of the face, expressed in font
                  units. For font formats not having this information, it is
                  set to 'bbox.yMax'. Only relevant for scalable formats.''')

    descender = property(lambda self: self._FT_Face.contents.descender,
          doc = '''The typographic descender of the face, expressed in font
                   units. For font formats not having this information, it is
                   set to 'bbox.yMin'. Note that this field is usually
                   negative. Only relevant for scalable formats.''')

    height = property(lambda self: self._FT_Face.contents.height,
       doc = '''The height is the vertical distance between two consecutive
                baselines, expressed in font units. It is always positive. Only
                relevant for scalable formats.''')

    max_advance_width = property(lambda self: self._FT_Face.contents.max_advance_width,
                  doc = '''The maximal advance width, in font units, for all
                           glyphs in this face. This can be used to make word
                           wrapping computations faster. Only relevant for
                           scalable formats.''')

    max_advance_height = property(lambda self: self._FT_Face.contents.max_advance_height,
                   doc = '''The maximal advance height, in font units, for all
                            glyphs in this face. This is only relevant for
                            vertical layouts, and is set to 'height' for fonts
                            that do not provide vertical metrics. Only relevant
                            for scalable formats.''')

    underline_position = property(lambda self: self._FT_Face.contents.underline_position,
                   doc = '''The position, in font units, of the underline line
                            for this face. It is the center of the underlining
                            stem. Only relevant for scalable formats.''')

    underline_thickness = property(lambda self: self._FT_Face.contents.underline_thickness,
                    doc = '''The thickness, in font units, of the underline for
                             this face. Only relevant for scalable formats.''')


    def _get_glyph( self ):
        return GlyphSlot( self._FT_Face.contents.glyph )
    glyph = property( _get_glyph,
      doc = '''The face's associated glyph slot(s).''')

    def _get_size( self ):
        size = self._FT_Face.contents.size
        metrics = size.contents.metrics
        return SizeMetrics(metrics)
    size = property( _get_size,
     doc = '''The current active size for this face.''')

    def _get_charmap( self ):
        return Charmap( self._FT_Face.contents.charmap)
    charmap = property( _get_charmap,
        doc = '''The current active charmap for this face.''')



# -----------------------------------------------------------------------------
#  SfntName wrapper
# -----------------------------------------------------------------------------
class SfntName( object ):
    '''
    SfntName wrapper

    A structure used to model an SFNT 'name' table entry.
    '''
    def __init__(self, name):
        '''
        Create a new SfntName object.

        :param name : SFNT 'name' table entry.

        '''
        self._FT_SfntName = name

    platform_id = property(lambda self: self._FT_SfntName.platform_id,
            doc = '''The platform ID for 'string'.''')

    encoding_id = property(lambda self: self._FT_SfntName.encoding_id,
            doc = '''The encoding ID for 'string'.''')

    language_id = property(lambda self: self._FT_SfntName.language_id,
            doc = '''The language ID for 'string'.''')

    name_id = property(lambda self: self._FT_SfntName.name_id,
        doc = '''An identifier for 'string'.''')

    #string      = property(lambda self: self._FT_SfntName.string)

    string_len = property(lambda self: self._FT_SfntName.string_len,
           doc = '''The length of 'string' in bytes.''')

    def _get_string(self):
    #     #s = self._FT_SfntName
         s = string_at(self._FT_SfntName.string, self._FT_SfntName.string_len)
         return s
    #     #return s.decode('utf-16be', 'ignore')
    #     return s.decode('utf-8', 'ignore')
    #     #n = s.string_len
    #     #data = [s.string[i] for i in range(n)]
    #     #return data
    string = property(_get_string,
       doc = '''The 'name' string. Note that its format differs depending on
                the (platform,encoding) pair. It can be a Pascal String, a
                UTF-16 one, etc.

                Generally speaking, the string is not zero-terminated. Please
                refer to the TrueType specification for details.''')



# -----------------------------------------------------------------------------
class Stroker( object ):
    '''
    FT_Stroker wrapper

    This component generates stroked outlines of a given vectorial glyph. It
    also allows you to retrieve the 'outside' and/or the 'inside' borders of
    the stroke.

    This can be useful to generate 'bordered' glyph, i.e., glyphs displayed
    with a coloured (and anti-aliased) border around their shape.
    '''

    def __init__( self ):
        '''
        Create a new Stroker object.
        '''
        library = get_handle( )
        stroker = FT_Stroker( )
        error = FT_Stroker_New( library, byref(stroker) )
        if error: raise FT_Exception( error )
        self._FT_Stroker = stroker


    def __del__( self ):
        '''
        Destroy object.
        '''
        FT_Stroker_Done( self._FT_Stroker )


    def set( self, radius, line_cap, line_join, miter_limit ):
        '''
        Reset a stroker object's attributes.

        :param radius: The border radius.

        :param line_cap: The line cap style.

        :param line_join: The line join style.

        :param miter_limit: The miter limit for the FT_STROKER_LINEJOIN_MITER
                            style, expressed as 16.16 fixed point value.

        **Note**:

          The radius is expressed in the same units as the outline coordinates.
        '''
        FT_Stroker_Set( self._FT_Stroker,
                        radius, line_cap, line_join, miter_limit )


    def rewind( self ):
        '''
        Reset a stroker object without changing its attributes. You should call
        this function before beginning a new series of calls to
        FT_Stroker_BeginSubPath or FT_Stroker_EndSubPath.
        '''
        FT_Stroker_Rewind( self._FT_Stroker )


    def parse_outline( self, outline, opened ):
        '''
        A convenience function used to parse a whole outline with the
        stroker. The resulting outline(s) can be retrieved later by functions
        like FT_Stroker_GetCounts and FT_Stroker_Export.

        :param outline: The source outline.

        :pram opened: A boolean. If 1, the outline is treated as an open path
                      instead of a closed one.

        **Note**:

          If 'opened' is 0 (the default), the outline is treated as a closed
          path, and the stroker generates two distinct 'border' outlines.

          If 'opened' is 1, the outline is processed as an open path, and the
          stroker generates a single 'stroke' outline.

          This function calls 'rewind' automatically.
        '''
        error = FT_Stroker_ParseOutline( self._FT_Stroker, byref(outline._FT_Outline), opened)
        if error: raise FT_Exception( error )


    def begin_subpath( self, to, _open ):
        '''
        Start a new sub-path in the stroker.

        :param to A pointer to the start vector.

        :param _open: A boolean. If 1, the sub-path is treated as an open one.

        **Note**:

          This function is useful when you need to stroke a path that is not
          stored as an 'Outline' object.
        '''
        error = FT_Stroker_BeginSubPath( self._FT_Stroker, to, _open )
        if error: raise FT_Exception( error )


    def end_subpath( self ):
        '''
        Close the current sub-path in the stroker.

        **Note**:

          You should call this function after 'begin_subpath'. If the subpath
          was not 'opened', this function 'draws' a single line segment to the
          start position when needed.
        '''
        error = FT_Stroker_EndSubPath( self._FT_Stroker)
        if error: raise FT_Exception( error )


    def line_to( self, to ):
        '''
        'Draw' a single line segment in the stroker's current sub-path, from
        the last position.

        :param to: A pointer to the destination point.

        **Note**:

          You should call this function between 'begin_subpath' and
          'end_subpath'.
        '''
        error = FT_Stroker_LineTo( self._FT_Stroker, to )
        if error: raise FT_Exception( error )


    def conic_to( self, control, to ):
        '''
        'Draw' a single quadratic Bezier in the stroker's current sub-path,
        from the last position.

        :param control: A pointer to a Bezier control point.

        :param to: A pointer to the destination point.

        **Note**:

          You should call this function between 'begin_subpath' and
          'end_subpath'.
        '''
        error = FT_Stroker_ConicTo( self._FT_Stroker, control, to )
        if error: raise FT_Exception( error )


    def cubic_to( self, control1, control2, to ):
        '''
        'Draw' a single quadratic Bezier in the stroker's current sub-path,
        from the last position.

        :param control1: A pointer to the first Bezier control point.

        :param control2: A pointer to second Bezier control point.

        :param to: A pointer to the destination point.

        **Note**:

          You should call this function between 'begin_subpath' and
          'end_subpath'.
        '''
        error = FT_Stroker_CubicTo( self._FT_Stroker, control1, control2, to )
        if error: raise FT_Exception( error )


    def get_border_counts( self, border ):
        '''
        Call this function once you have finished parsing your paths with the
        stroker. It returns the number of points and contours necessary to
        export one of the 'border' or 'stroke' outlines generated by the
        stroker.

        :param border: The border index.

        :return: number of points, number of contours
        '''
        anum_points = FT_UInt()
        anum_contours = FT_UInt()
        error = FT_Stroker_GetBorderCounts( self._FT_Stroker, border,
                                    byref(anum_points), byref(anum_contours) )
        if error: raise FT_Exception( error )
        return anum_points.value, anum_contours.value


    def export_border( self , border, outline ):
        '''
        Call this function after 'get_border_counts' to export the
        corresponding border to your own 'Outline' structure.

        Note that this function appends the border points and contours to your
        outline, but does not try to resize its arrays.

        :param border:  The border index.

        :param outline: The target outline.

        **Note**:

          Always call this function after get_border_counts to get sure that
          there is enough room in your 'Outline' object to receive all new
          data.

          When an outline, or a sub-path, is 'closed', the stroker generates two
          independent 'border' outlines, named 'left' and 'right'

          When the outline, or a sub-path, is 'opened', the stroker merges the
          'border' outlines with caps. The 'left' border receives all points,
          while the 'right' border becomes empty.

          Use the function export instead if you want to retrieve all borders
          at once.
        '''
        FT_Stroker_ExportBorder( self._FT_Stroker, border, byref(outline._FT_Outline) )


    def get_counts( self ):
        '''
        Call this function once you have finished parsing your paths with the
        stroker. It returns the number of points and contours necessary to
        export all points/borders from the stroked outline/path.

        :return: number of points, number of contours
        '''

        anum_points = FT_UInt()
        anum_contours = FT_UInt()
        error = FT_Stroker_GetCounts( self._FT_Stroker,
                                      byref(anum_points), byref(anum_contours) )
        if error: raise FT_Exception( error )
        return anum_points.value, anum_contours.value


    def export( self, outline ):
        '''
        Call this function after get_border_counts to export all borders to
        your own 'Outline' structure.

        Note that this function appends the border points and contours to your
        outline, but does not try to resize its arrays.

        :param outline: The target outline.
        '''
        FT_Stroker_Export( self._FT_Stroker, byref(outline._FT_Outline) )


# -----------------------------------------------------------------------------
# Classes related to Variable Font support
#
class VariationAxis(object):
    tag = None
    coords = tuple()

    def __init__(self, ftvaraxis):
        self.tag = unmake_tag(ftvaraxis.tag)
        self.name = ftvaraxis.name.decode('ascii')
        self.minimum = ftvaraxis.minimum/65536.0
        self.default = ftvaraxis.default/65536.0
        self.maximum = ftvaraxis.maximum/65536.0
        self.strid = ftvaraxis.strid  # do we need this? Should be same as 'name'...

    def __repr__(self):
        return "<VariationAxis '{}' ('{}') [{}, {}, {}]>".format(
            self.tag, self.name, self.minimum, self.default, self.maximum)

class VariationInstance(object):
    def __init__(self, name, psname, coords):
        self.name = name
        self.psname = psname
        self.coords = coords

    def __repr__(self):
        return "<VariationInstance '{}' {}>".format(
            self.name, self.coords)

class VariationSpaceInfo(object):
    """
    VF info (axes & instances).
    """
    def __init__(self, face, p_ftmmvar):
        """
        Build a VariationSpaceInfo object given face (freetype.Face) and
        p_ftmmvar (pointer to FT_MM_Var).
        """
        ftmv = p_ftmmvar.contents

        axes = []
        for axidx in range(ftmv.num_axis):
            axes.append(VariationAxis(ftmv.axis[axidx]))

        self.axes = tuple(axes)

        inst = []
        for instidx in range(ftmv.num_namedstyles):
            instinfo = ftmv.namedstyle[instidx]
            nid = instinfo.strid
            name = face.get_best_name_string(nid)
            psid = instinfo.psid
            psname = face.get_best_name_string(psid)
            coords = []
            for cidx in range(len(self.axes)):
                coords.append(instinfo.coords[cidx]/65536.0)

            inst.append(VariationInstance(name, psname, tuple(coords)))

        self.instances = tuple(inst)