Xft Fonts and Rendering

## Xft Fonts and Rendering Xft Fonts and Rendering — Font handling and rendering with the Xft backend |

## Synopsis

                PangoXftFont;
                PangoXftFontMap;
    #define     PANGO_RENDER_TYPE_XFT
    PangoContext* pango_xft_get_context         (Display *display,
                                                 int screen);
    PangoFontMap* pango_xft_get_font_map        (Display *display,
                                                 int screen);
    void        pango_xft_set_default_substitute
                                                (Display *display,
                                                 int screen,
                                                 PangoXftSubstituteFunc func,
                                                 gpointer data,
                                                 GDestroyNotify notify);
    void        (*PangoXftSubstituteFunc)       (FcPattern *pattern,
                                                 gpointer data);
    void        pango_xft_substitute_changed    (Display *display,
                                                 int screen);
    void        pango_xft_shutdown_display      (Display *display,
                                                 int screen);
    XftFont*    pango_xft_font_get_font         (PangoFont *font);
    Display*    pango_xft_font_get_display      (PangoFont *font);
    gboolean    pango_xft_font_has_char         (PangoFont *font,
                                                 gunichar wc);
    FT_Face     pango_xft_font_lock_face        (PangoFont *font);
    void        pango_xft_font_unlock_face      (PangoFont *font);
    guint       pango_xft_font_get_glyph        (PangoFont *font,
                                                 gunichar wc);
    PangoGlyph  pango_xft_font_get_unknown_glyph
                                                (PangoFont *font,
                                                 gunichar wc);
                PangoXftRenderer;
                PangoXftRendererClass;
    PangoRenderer* pango_xft_renderer_new       (Display *display,
                                                 int screen);
    void        pango_xft_renderer_set_draw     (PangoXftRenderer *xftrenderer,
                                                 XftDraw *draw);
    void        pango_xft_renderer_set_default_color
                                                (PangoXftRenderer *xftrenderer,
                                                 PangoColor *default_color);
    void        pango_xft_render                (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 gint x,
                                                 gint y);
    void        pango_xft_picture_render        (Display *display,
                                                 Picture src_picture,
                                                 Picture dest_picture,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 gint x,
                                                 gint y);
    void        pango_xft_render_transformed    (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoMatrix *matrix,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 int x,
                                                 int y);
    void        pango_xft_render_layout_line    (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoLayoutLine *line,
                                                 int x,
                                                 int y);
    void        pango_xft_render_layout         (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoLayout *layout,
                                                 int x,
                                                 int y);

## Object Hierarchy

      GObject
       +----PangoFont
             +----PangoFcFont
                   +----PangoXftFont

## Description

The Xft library is a library for displaying fonts on the X window system; internally it uses the fontconfig library to locate font files, and the FreeType library to load and render fonts. The Xft backend is the recommended Pango font backend for screen display with X. (The Cairo back end is another possibility.)

Using the Xft backend is generally straightforward; `pango_xft_get_context()` creates a context for a specified display and screen. You can then create a PangoLayout with that context and render it with `pango_xft_render_layout()`. At a more advanced level, the lowlevel fontconfig options used for rendering fonts can be affected using `pango_xft_set_default_substitute()`, and `pango_xft_substitute_changed()`.

A range of functions for drawing pieces of a layout, such as individual layout lines and glyphs strings are provided. You can also directly create a PangoXftRenderer. Finally, in some advanced cases, it is useful to derive from PangoXftRenderer. Deriving from PangoXftRenderer is useful for two reasons. One reason is be to support custom attributes by overriding PangoRendererClass virtual functions like 'prepare_run' or 'draw_shape'. The reason is to customize exactly how the final bits are drawn to the destination by overring the PangoXftRendererClass virtual functions 'composite_glyphs' and 'composite_trapezoids'.

## Details

### PangoXftFont

    typedef struct _PangoXftFont PangoXftFont;

PangoXftFont is an implementation of PangoFcFont using the Xft library for rendering. It is used in conjunction with PangoXftFontMap.

### PangoXftFontMap

    typedef struct _PangoXftFontMap PangoXftFontMap;

PangoXftFontMap is an implementation of PangoFcFontMap suitable for the Xft library as the renderer. It is used in to create fonts of type PangoXftFont.

### PANGO_RENDER_TYPE_XFT

    #define PANGO_RENDER_TYPE_XFT "PangoRenderXft"

### Warning

`PANGO_RENDER_TYPE_XFT` 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 Xft backend. See `PANGO_RENDER_TYPE_FC` for the replacement.

### pango_xft_get_context ()

    PangoContext* pango_xft_get_context         (Display *display,
                                                 int screen);

Retrieves a PangoContext appropriate for rendering with Xft fonts on the given screen of the given display.

`display` : | an X display.
`screen` : | an X screen.
Returns : | the new PangoContext.

### pango_xft_get_font_map ()

    PangoFontMap* pango_xft_get_font_map        (Display *display,
                                                 int screen);

Returns the PangoXftFontmap for the given display and screen. The fontmap is owned by Pango and will be valid until the display is closed.

`display` : | an X display
`screen` : | the screen number of a screen within `display`
Returns : | a PangoFontMap object, owned by Pango.

Since 1.2

### pango_xft_set_default_substitute ()

    void        pango_xft_set_default_substitute
                                                (Display *display,
                                                 int screen,
                                                 PangoXftSubstituteFunc 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.

`display` : | an X Display
`screen` : | the screen number of a screen within `display`
`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

### PangoXftSubstituteFunc ()

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

Function type for doing final config tweaking on prepared FcPatterns.

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

### pango_xft_substitute_changed ()

    void        pango_xft_substitute_changed    (Display *display,
                                                 int screen);

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

`display` : | an X Display
`screen` : | the screen number of a screen within `display`

Since 1.2

### pango_xft_shutdown_display ()

    void        pango_xft_shutdown_display      (Display *display,
                                                 int screen);

Release any resources that have been cached for the combination of `display` and `screen`. Note that when the X display is closed, resources are released automatically, without needing to call this function.

`display` : | an X display
`screen` : | the screen number of a screen within `display`

Since 1.2

### pango_xft_font_get_font ()

    XftFont*    pango_xft_font_get_font         (PangoFont *font);

Returns the XftFont of a font.

`font` : | a PangoFont.
Returns : | the XftFont associated to `font`.

### pango_xft_font_get_display ()

    Display*    pango_xft_font_get_display      (PangoFont *font);

Returns the X display of the XftFont of a font.

`font` : | a PangoFont.
Returns : | the X display of the XftFont associated to `font`.

### pango_xft_font_has_char ()

    gboolean    pango_xft_font_has_char         (PangoFont *font,
                                                 gunichar wc);

### Warning

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

Determines whether `font` has a glyph for the codepoint `wc`.

Use `pango_fc_font_has_char()` instead.

`font` : | a PangoFont for the Xft backend
`wc` : | Unicode codepoint to look up
Returns : | `TRUE` if `font` has the requested codepoint.

Since 1.2

### pango_xft_font_lock_face ()

    FT_Face     pango_xft_font_lock_face        (PangoFont *font);

### Warning

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

Gets the FreeType FT_Face associated with a font, This face will be kept around until you call `pango_xft_font_unlock_face()`.

Use `pango_fc_font_lock_face()` instead.

`font` : | a PangoFont.
Returns : | the FreeType FT_Face associated with `font`.

Since 1.2

### pango_xft_font_unlock_face ()

    void        pango_xft_font_unlock_face      (PangoFont *font);

### Warning

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

Releases a font previously obtained with `pango_xft_font_lock_face()`.

Use `pango_fc_font_unlock_face()` instead.

`font` : | a PangoFont.

Since 1.2

### pango_xft_font_get_glyph ()

    guint       pango_xft_font_get_glyph        (PangoFont *font,
                                                 gunichar wc);

### Warning

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

Gets the glyph index for a given Unicode character for `font`. If you only want to determine whether the font has the glyph, use `pango_xft_font_has_char()`.

Use `pango_fc_font_get_glyph()` instead.

`font` : | a PangoFont for the Xft backend
`wc` : | Unicode codepoint to look up
Returns : | the glyph index, or 0, if the Unicode character does not exist in the font.

Since 1.2

### pango_xft_font_get_unknown_glyph ()

    PangoGlyph  pango_xft_font_get_unknown_glyph
                                                (PangoFont *font,
                                                 gunichar wc);

### Warning

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

Returns the index of a glyph suitable for drawing `wc` as an unknown character.

Use `PANGO_GET_UNKNOWN_GLYPH()` instead.

`font` : | a PangoFont.
`wc` : | the Unicode character for which a glyph is needed.
Returns : | a glyph index into `font`.

### PangoXftRenderer

    typedef struct {
    } PangoXftRenderer;

PangoXftRenderer is a subclass of PangoRenderer used for rendering with Pango's Xft backend. It can be used directly, or it can be further subclassed to modify exactly how drawing of individual elements occurs.

Since 1.8

### PangoXftRendererClass

    typedef struct {
      void (*composite_trapezoids) (PangoXftRenderer *xftrenderer,
    				PangoRenderPart   part,
    				XTrapezoid       *trapezoids,
    				int               n_trapezoids);
      void (*composite_glyphs)     (PangoXftRenderer *xftrenderer,
    				XftFont          *xft_font,
    				XftGlyphSpec     *glyphs,
    				int               n_glyphs);
    } PangoXftRendererClass;

The class structure for PangoXftRenderer

`composite_trapezoids` () | draw the specified trapezoids using the current color and other attributes for `part`
`composite_glyphs` () | draw the specified glyphs using the current foreground color and other foreground attributes

Since 1.8

### pango_xft_renderer_new ()

    PangoRenderer* pango_xft_renderer_new       (Display *display,
                                                 int screen);

Create a new PangoXftRenderer to allow rendering Pango objects with the Xft library. You must call `pango_xft_renderer_set_draw()` before using the renderer.

`display` : | an X display
`screen` : | the index of the screen for `display` to which rendering will be done
Returns : | the newly created PangoXftRenderer, which should be freed with `g_object_unref()`.

Since 1.8

### pango_xft_renderer_set_draw ()

    void        pango_xft_renderer_set_draw     (PangoXftRenderer *xftrenderer,
                                                 XftDraw *draw);

Sets the XftDraw object that the renderer is drawing to. The renderer must not be currently active.

`xftrenderer` : | a PangoXftRenderer
`draw` : | a XftDraw

Since 1.8

### pango_xft_renderer_set_default_color ()

    void        pango_xft_renderer_set_default_color
                                                (PangoXftRenderer *xftrenderer,
                                                 PangoColor *default_color);

Sets the default foreground color for a XftRenderer.

`xftrenderer` : | a XftRenderer
`default_color` : | the default foreground color

Since 1.8

### pango_xft_render ()

    void        pango_xft_render                (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 gint x,
                                                 gint y);

Renders a PangoGlyphString onto an XftDraw object wrapping an X drawable.

`draw` : | the XftDraw object.
`color` : | the color in 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 start of string (in pixels)
`y` : | the y position of baseline (in pixels)

### pango_xft_picture_render ()

    void        pango_xft_picture_render        (Display *display,
                                                 Picture src_picture,
                                                 Picture dest_picture,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 gint x,
                                                 gint y);

Renders a PangoGlyphString onto an Xrender Picture object.

`display` : | an X display
`src_picture` : | the source picture to draw the string with
`dest_picture` : | the destination picture to draw the strign onto
`font` : | the font in which to draw the string
`glyphs` : | the glyph string to draw
`x` : | the x position of start of string (in pixels)
`y` : | the y position of baseline (in pixels)

### pango_xft_render_transformed ()

    void        pango_xft_render_transformed    (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoMatrix *matrix,
                                                 PangoFont *font,
                                                 PangoGlyphString *glyphs,
                                                 int x,
                                                 int y);

Renders a PangoGlyphString onto a XftDraw, 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.

`draw` : | an XftDraw
`color` : | the color in which to draw the glyphs
`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.8

### pango_xft_render_layout_line ()

    void        pango_xft_render_layout_line    (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoLayoutLine *line,
                                                 int x,
                                                 int y);

Render a PangoLayoutLine onto a XftDraw

`draw` : | an XftDraw
`color` : | the foreground color in which to draw the layout line (may be overriden by color attributes)
`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.8

### pango_xft_render_layout ()

    void        pango_xft_render_layout         (XftDraw *draw,
                                                 XftColor *color,
                                                 PangoLayout *layout,
                                                 int x,
                                                 int y);

Render a PangoLayout onto a XftDraw

`draw` : | an XftDraw
`color` : | the foreground color in which to draw the layout (may be overriden by color attributes)
`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.8