Xft Fonts and Rendering

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

Functions

Properties

gpointer display Write / Construct Only
gint screen Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ├── PangoFont
       ╰── PangoFcFont
           ╰── PangoXftFont
    ├── PangoFontMap
       ╰── PangoFcFontMap
           ╰── PangoXftFontMap
    ╰── PangoRenderer
        ╰── PangoXftRenderer

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 low-level 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 overriding the PangoXftRendererClass virtual functions 'composite_glyphs' and 'composite_trapezoids'.

Functions

pango_xft_get_context ()

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

pango_xft_get_context has been deprecated since version 1.22 and should not be used in newly-written code.

Use pango_xft_get_font_map() followed by pango_font_map_create_context() instead.

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

[skip]

Parameters

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.

Parameters

display

an X display

 

screen

the screen number of a screen within display

 

Returns

a PangoFontMap object, owned by Pango.

[transfer none]

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.

Parameters

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.

Parameters

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 substitution function will return different results for the same input pattern, you must call this function.

Parameters

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.

Parameters

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.

Parameters

font

a PangoFont.

[nullable]

Returns

the XftFont associated to font , or NULL if font is NULL.

[nullable]


pango_xft_font_get_display ()

Display *
pango_xft_font_get_display (PangoFont *font);

Returns the X display of the XftFont of a font.

Parameters

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

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.

Parameters

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

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.

Parameters

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

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.

Parameters

font

a PangoFont.

 

Since: 1.2


pango_xft_font_get_glyph ()

guint
pango_xft_font_get_glyph (PangoFont *font,
                          gunichar wc);

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.

Parameters

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

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.

Parameters

font

a PangoFont.

 

wc

the Unicode character for which a glyph is needed.

 

Returns

a glyph index into font .


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

display

an X display

 

src_picture

the source picture to draw the string with

 

dest_picture

the destination picture to draw the string 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.

Parameters

draw

an XftDraw

 

color

the color in which to draw the glyphs

 

font

the font in which to draw the string

 

matrix

a PangoMatrix, or NULL to use an identity transformation.

[nullable]

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

Parameters

draw

an XftDraw

 

color

the foreground color in which to draw the layout line (may be overridden 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

Parameters

draw

an XftDraw

 

color

the foreground color in which to draw the layout (may be overridden 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

Types and Values

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"

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.


struct PangoXftRenderer

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


struct PangoXftRendererClass

struct PangoXftRendererClass {
  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);
};

The class structure for PangoXftRenderer

Members

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

Property Details

The “display” property

  “display”                  gpointer

The display being rendered to.

Flags: Write / Construct Only


The “screen” property

  “screen”                   gint

The screen being rendered to.

Flags: Write / Construct Only

Allowed values: >= 0

Default value: 0