Pango Reference Manual: FreeType Fonts and Rendering

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

## Functions

PangoFontMap * | pango_ft2_font_map_new ()
void | pango_ft2_font_map_set_resolution ()
PangoContext * | pango_ft2_font_map_create_context ()
void | (*PangoFT2SubstituteFunc) ()
void | pango_ft2_font_map_set_default_substitute ()
void | pango_ft2_font_map_substitute_changed ()
PangoContext * | pango_ft2_get_context ()
void | pango_ft2_render ()
void | pango_ft2_render_transformed ()
void | pango_ft2_render_layout_line ()
void | pango_ft2_render_layout_line_subpixel ()
void | pango_ft2_render_layout ()
void | pango_ft2_render_layout_subpixel ()
PangoGlyph | pango_ft2_get_unknown_glyph ()
int | pango_ft2_font_get_kerning ()
FT_Face | pango_ft2_font_get_face ()
PangoCoverage * | pango_ft2_font_get_coverage ()
PangoFontMap * | pango_ft2_font_map_for_display ()
void | pango_ft2_shutdown_display ()

## Types and Values

| PangoFT2FontMap
#define | PANGO_RENDER_TYPE_FT2

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

## Functions

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

fontmap | a PangoFT2FontMap |

Since 1.2

### pango_ft2_get_context ()

    PangoContext *
    pango_ft2_get_context (double dpi_x,
                           double dpi_y);

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

font | a PangoFT2Font. |
language | a language tag. |

#### Returns

a PangoCoverage.

### pango_ft2_font_map_for_display ()

    PangoFontMap *
    pango_ft2_font_map_for_display (void);

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

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

## Types and Values

### PangoFT2FontMap

    typedef struct _PangoFT2FontMap PangoFT2FontMap;

The PangoFT2FontMap is the PangoFontMap implementation for FreeType fonts.

### PANGO_RENDER_TYPE_FT2

    #define PANGO_RENDER_TYPE_FT2 "PangoRenderFT2"

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