## FreeType Fonts and Rendering

FreeType Fonts and Rendering — Functions for shape engines to manipulate FreeType fonts

## Synopsis

    struct      PangoFT2FontMap;
    #define     PANGO_RENDER_TYPE_FT2
    PangoFontMap* pango_ft2_font_map_new        (void);
    void        pango_ft2_font_map_set_resolution
                                                (PangoFT2FontMap *fontmap,
                                                 double dpi_x,
                                                 double dpi_y);
    PangoContext* pango_ft2_font_map_create_context
                                                (PangoFT2FontMap *fontmap);
    void        (*PangoFT2SubstituteFunc)       (FcPattern *pattern,
                                                 gpointer data);
    void        pango_ft2_font_map_set_default_substitute
                                                (PangoFT2FontMap *fontmap,
                                                 PangoFT2SubstituteFunc func,
                                                 gpointer data,
                                                 GDestroyNotify notify);
    void        pango_ft2_font_map_substitute_changed
                                                (PangoFT2FontMap *fontmap);
    PangoContext* pango_ft2_get_context         (double dpi_x,
                                                 double dpi_y);
    void        pango_ft2_render                (FT_Bitmap *bitmap,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 gint x,
                                                 gint y);
    void        pango_ft2_render_transformed    (FT_Bitmap *bitmap,
                                                 const PangoMatrix *matrix,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 int x,
                                                 int y);
    void        pango_ft2_render_layout_line    (FT_Bitmap *bitmap,
                                                 PangoLayoutLine *line,
                                                 int x,
                                                 int y);
    void        pango_ft2_render_layout_line_subpixel
                                                (FT_Bitmap *bitmap,
                                                 PangoLayoutLine *line,
                                                 int x,
                                                 int y);
    void        pango_ft2_render_layout         (FT_Bitmap *bitmap,
                                                 PangoLayout *layout,
                                                 int x,
                                                 int y);
    void        pango_ft2_render_layout_subpixel
                                                (FT_Bitmap *bitmap,
                                                 PangoLayout *layout,
                                                 int x,
                                                 int y);
    PangoGlyph  pango_ft2_get_unknown_glyph     (PangoFont *font);
    int         pango_ft2_font_get_kerning      (PangoFont *font,
                                                 PangoGlyph left,
                                                 PangoGlyph right);
    FT_Face     pango_ft2_font_get_face         (PangoFont *font);
    PangoCoverage* pango_ft2_font_get_coverage  (PangoFont *font,
                                                 PangoLanguage *language);
    PangoFontMap* pango_ft2_font_map_for_display
                                                (void);
    void        pango_ft2_shutdown_display      (void);

## Object Hierarchy

      GObject
       +----PangoFontMap
             +----PangoFcFontMap
                   +----PangoFT2FontMap

## Description

## Details

### struct PangoFT2FontMap

    struct PangoFT2FontMap;

The PangoFT2FontMap is the PangoFontMap implementation for FreeType fonts.

### PANGO_RENDER_TYPE_FT2

    #define PANGO_RENDER_TYPE_FT2 "PangoRenderFT2"

A string constant that was used to identify shape engines that work with the FreeType backend. See `PANGO_RENDER_TYPE_FC` for the replacement.

### pango_ft2_font_map_new ()

    PangoFontMap* pango_ft2_font_map_new        (void);

Create a new PangoFT2FontMap object; a fontmap is used to cache information about available fonts, and holds certain global parameters such as the resolution and the default substitute function (see `pango_ft2_font_map_set_default_substitute()`).

Returns : | the newly created fontmap object. Unref with `g_object_unref()` when you are finished with it.

Since 1.2

### pango_ft2_font_map_set_resolution ()

    void        pango_ft2_font_map_set_resolution
                                                (PangoFT2FontMap *fontmap,
                                                 double dpi_x,
                                                 double dpi_y);

Sets the horizontal and vertical resolutions for the fontmap.

`fontmap` : | a PangoFT2Fontmap
`dpi_x` : | dots per inch in the X direction
`dpi_y` : | dots per inch in the Y direction

### pango_ft2_font_map_create_context ()

    PangoContext* pango_ft2_font_map_create_context
                                                (PangoFT2FontMap *fontmap);

Create a PangoContext for the given fontmap.

`fontmap` : | a PangoFT2Fontmap
Returns : | the newly created context; free with `g_object_unref()`.

Since 1.2

### PangoFT2SubstituteFunc ()

    void        (*PangoFT2SubstituteFunc)       (FcPattern *pattern,
                                                 gpointer data);

Function type for doing final config tweaking on prepared FcPatterns.

`pattern` : | the FcPattern to tweak.
`data` : | user data.

### pango_ft2_font_map_set_default_substitute ()

    void        pango_ft2_font_map_set_default_substitute
                                                (PangoFT2FontMap *fontmap,
                                                 PangoFT2SubstituteFunc func,
                                                 gpointer data,
                                                 GDestroyNotify notify);

Sets a function that will be called to do final configuration substitution on a FcPattern before it is used to load the font. This function can be used to do things like set hinting and antialiasing options.

`fontmap` : | a PangoFT2FontMap
`func` : | function to call to to do final config tweaking on FcPattern objects.
`data` : | data to pass to `func`
`notify` : | function to call when `data` is no longer used.

Since 1.2

### pango_ft2_font_map_substitute_changed ()

    void        pango_ft2_font_map_substitute_changed
                                                (PangoFT2FontMap *fontmap);

Call this function any time the results of the default substitution function set with `pango_ft2_font_map_set_default_substitute()` change. That is, if your subsitution function will return different results for the same input pattern, you must call this function.

`fontmap` : | a PangoFT2Fontmap

Since 1.2

### pango_ft2_get_context ()

    PangoContext* pango_ft2_get_context         (double dpi_x,
                                                 double dpi_y);

Retrieves a PangoContext for the default PangoFT2 fontmap (see `pango_ft2_fontmap_get_for_display()`) and sets the resolution for the default fontmap to `dpi_x` by `dpi_y`.

Use of this function is deprecated; see `pango_ft2_fontmap_create_context()` instead.

`dpi_x` : | the horizontal dpi of the target device
`dpi_y` : | the vertical dpi of the target device
Returns : | the new PangoContext

### pango_ft2_render ()

    void        pango_ft2_render                (FT_Bitmap *bitmap,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 gint x,
                                                 gint y);

Renders a PangoGlyphString onto a FreeType2 bitmap.

`bitmap` : | the FreeType2 bitmap onto which to draw the string
`font` : | the font in which to draw the string
`glyphs` : | the glyph string to draw
`x` : | the x position of the start of the string (in pixels)
`y` : | the y position of the baseline (in pixels)

### pango_ft2_render_transformed ()

    void        pango_ft2_render_transformed    (FT_Bitmap *bitmap,
                                                 const PangoMatrix *matrix,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 int x,
                                                 int y);

Renders a PangoGlyphString onto a FreeType2 bitmap, possibly transforming the layed-out coordinates through a transformation matrix. Note that the transformation matrix for `font` is not changed, so to produce correct rendering results, the `font` must have been loaded using a PangoContext with an identical transformation matrix to that passed in to this function.

`bitmap` : | the FreeType2 bitmap onto which to draw the string
`matrix` : | a PangoMatrix, or `NULL` to use an identity transformation
`font` : | the font in which to draw the string
`glyphs` : | the glyph string to draw
`x` : | the x position of the start of the string (in Pango units in user space coordinates)
`y` : | the y position of the baseline (in Pango units in user space coordinates)

Since 1.6

### pango_ft2_render_layout_line ()

    void        pango_ft2_render_layout_line    (FT_Bitmap *bitmap,
                                                 PangoLayoutLine *line,
                                                 int x,
                                                 int y);

Render a PangoLayoutLine onto a FreeType2 bitmap

`bitmap` : | a FT_Bitmap to render the line onto
`line` : | a PangoLayoutLine
`x` : | the x position of start of string (in pixels)
`y` : | the y position of baseline (in pixels)

### pango_ft2_render_layout_line_subpixel ()

    void        pango_ft2_render_layout_line_subpixel
                                                (FT_Bitmap *bitmap,
                                                 PangoLayoutLine *line,
                                                 int x,
                                                 int y);

Render a PangoLayoutLine onto a FreeType2 bitmap, with he location specified in fixed-point pango units rather than pixels. (Using this will avoid extra inaccuracies from rounding to integer pixels multiple times, even if the final glyph positions are integers.)

`bitmap` : | a FT_Bitmap to render the line onto
`line` : | a PangoLayoutLine
`x` : | the x position of start of string (in pango units)
`y` : | the y position of baseline (in pango units)

Since 1.6

### pango_ft2_render_layout ()

    void        pango_ft2_render_layout         (FT_Bitmap *bitmap,
                                                 PangoLayout *layout,
                                                 int x,
                                                 int y);

Render a PangoLayout onto a FreeType2 bitmap

`bitmap` : | a FT_Bitmap to render the layout onto
`layout` : | a PangoLayout
`x` : | the X position of the left of the layout (in pixels)
`y` : | the Y position of the top of the layout (in pixels)

### pango_ft2_render_layout_subpixel ()

    void        pango_ft2_render_layout_subpixel
                                                (FT_Bitmap *bitmap,
                                                 PangoLayout *layout,
                                                 int x,
                                                 int y);

Render a PangoLayout onto a FreeType2 bitmap, with he location specified in fixed-point pango units rather than pixels. (Using this will avoid extra inaccuracies from rounding to integer pixels multiple times, even if the final glyph positions are integers.)

`bitmap` : | a FT_Bitmap to render the layout onto
`layout` : | a PangoLayout
`x` : | the X position of the left of the layout (in Pango units)
`y` : | the Y position of the top of the layout (in Pango units)

Since 1.6

### pango_ft2_get_unknown_glyph ()

    PangoGlyph  pango_ft2_get_unknown_glyph     (PangoFont *font);

Return the index of a glyph suitable for drawing unknown characters.

Use `pango_fc_font_get_unknown_glyph()` instead.

`font` : | a PangoFont
Returns : | a glyph index into `font`

### pango_ft2_font_get_kerning ()

    int         pango_ft2_font_get_kerning      (PangoFont *font,
                                                 PangoGlyph left,
                                                 PangoGlyph right);

Retrieves kerning information for a combination of two glyphs.

Use `pango_fc_font_kern_glyphs()` instead.

`font` : | a PangoFont
`left` : | the left PangoGlyph
`right` : | the right PangoGlyph
Returns : | The amount of kerning (in Pango units) to apply for the given combination of glyphs.

### pango_ft2_font_get_face ()

    FT_Face     pango_ft2_font_get_face         (PangoFont *font);

Returns the native FreeType2 FT_Face structure used for this PangoFont. This may be useful if you want to use FreeType2 functions directly.

Use `pango_fc_font_lock_face()` instead; when you are done with a face from `pango_fc_font_lock_face()` you must call `pango_fc_font_unlock_face()`.

`font` : | a PangoFont
Returns : | a pointer to a FT_Face structure, with the size set correctly

### pango_ft2_font_get_coverage ()

    PangoCoverage* pango_ft2_font_get_coverage  (PangoFont *font,
                                                 PangoLanguage *language);

Gets the PangoCoverage for a PangoFT2Font. Use `pango_font_get_coverage()` instead.

`font` : | a PangoFT2Font.
`language` : | a language tag.
Returns : | a PangoCoverage.

### pango_ft2_font_map_for_display ()

    PangoFontMap* pango_ft2_font_map_for_display
                                                (void);

Returns a PangoFT2FontMap. This font map is cached and should not be freed. If the font map is no longer needed, it can be released with `pango_ft2_shutdown_display()`. Use of the global PangoFT2 fontmap is deprecated; use `pango_ft2_font_map_new()` instead.

Returns : | a PangoFT2FontMap.

### pango_ft2_shutdown_display ()

    void        pango_ft2_shutdown_display      (void);

Free the global fontmap. (See `pango_ft2_font_map_for_display()`) Use of the global PangoFT2 fontmap is deprecated.