Pango Reference Manual: FreeType Fonts and Rendering

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

## Synopsis

                        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

The macros and functions in this section are used to access fonts and render text to bitmaps using the FreeType 2 library.

## Details

### PangoFT2FontMap

    typedef struct _PangoFT2FontMap PangoFT2FontMap;

The PangoFT2FontMap is the PangoFontMap implementation for FreeType fonts.

### PANGO_RENDER_TYPE_FT2

    #define PANGO_RENDER_TYPE_FT2 "PangoRenderFT2"

### Warning

`PANGO_RENDER_TYPE_FT2` is deprecated and should not be used in newly-written code.

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

Since 1.2

### pango_ft2_font_map_create_context ()

    PangoContext *      pango_ft2_font_map_create_context   (PangoFT2FontMap *fontmap);

### Warning

`pango_ft2_font_map_create_context` has been deprecated since version 1.22 and should not be used in newly-written code. Use `pango_font_map_create_context()` instead.

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 substitution 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);

### Warning

`pango_ft2_get_context` has been deprecated since version 1.22 and should not be used in newly-written code. Use `pango_font_map_create_context()` instead.

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

`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
`font` : | the font in which to draw the string
`matrix` : | a PangoMatrix, or `NULL` to use an identity transformation
`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);

### Warning

`pango_ft2_get_unknown_glyph` is deprecated and should not be used in newly-written code.

Return the index of a glyph suitable for drawing unknown characters with `font`, or `PANGO_GLYPH_EMPTY` if no suitable glyph found.

If you want to draw an unknown-box for a character that is not covered by the font, use `PANGO_GET_UNKNOWN_GLYPH()` instead.

`font` : | a PangoFont
Returns : | a glyph index into `font`, or `PANGO_GLYPH_EMPTY`

### pango_ft2_font_get_kerning ()

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

### Warning

`pango_ft2_font_get_kerning` is deprecated and should not be used in newly-written code.

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

### Warning

`pango_ft2_font_get_face` is deprecated and should not be used in newly-written code.

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, or `NULL` if `font` is `NULL`.

### pango_ft2_font_get_coverage ()

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

### Warning

`pango_ft2_font_get_coverage` is deprecated and should not be used in newly-written code.

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

### Warning

`pango_ft2_font_map_for_display` is deprecated and should not be used in newly-written code.

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

### Warning

`pango_ft2_shutdown_display` is deprecated and should not be used in newly-written code.

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