X Fonts and Rendering

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

Synopsis




#define     PANGO_RENDER_TYPE_X
PangoContext* pango_x_get_context           (Display *display);
void        pango_x_context_set_funcs       (PangoContext *context,
                                             PangoGetGCFunc get_gc_func,
                                             PangoFreeGCFunc free_gc_func);
GC          (*PangoGetGCFunc)               (PangoContext *context,
                                             PangoColor *color,
                                             GC base_gc);
void        (*PangoFreeGCFunc)              (PangoContext *context,
                                             GC gc);
void        pango_x_render                  (Display *display,
                                             Drawable d,
                                             GC gc,
                                             PangoFont *font,
                                             PangoGlyphString *glyphs,
                                             gint x,
                                             gint y);
void        pango_x_render_layout_line      (Display *display,
                                             Drawable drawable,
                                             GC gc,
                                             PangoLayoutLine *line,
                                             int x,
                                             int y);
void        pango_x_render_layout           (Display *display,
                                             Drawable drawable,
                                             GC gc,
                                             PangoLayout *layout,
                                             int x,
                                             int y);
typedef     PangoXSubfont;
#define     PANGO_X_MAKE_GLYPH              (subfont,index_)
#define     PANGO_X_GLYPH_SUBFONT           (glyph)
#define     PANGO_X_GLYPH_INDEX             (glyph)
PangoFont*  pango_x_load_font               (Display *display,
                                             const gchar *spec);
PangoGlyph  pango_x_get_unknown_glyph       (PangoFont *font);
gboolean    pango_x_has_glyph               (PangoFont *font,
                                             PangoGlyph glyph);
int         pango_x_list_subfonts           (PangoFont *font,
                                             char **charsets,
                                             int n_charsets,
                                             PangoXSubfont **subfont_ids,
                                             int **subfont_charsets);
PangoFontMap* pango_x_font_map_for_display  (Display *display);
void        pango_x_shutdown_display        (Display *display);
PangoXFontCache* pango_x_font_map_get_font_cache
                                            (PangoFontMap *font_map);
char*       pango_x_font_subfont_xlfd       (PangoFont *font,
                                             PangoXSubfont subfont_id);
gboolean    pango_x_find_first_subfont      (PangoFont *font,
                                             char **charsets,
                                             int n_charsets,
                                             PangoXSubfont *rfont);
PangoGlyph  pango_x_font_get_unknown_glyph  (PangoFont *font,
                                             gunichar wc);
gboolean    pango_x_apply_ligatures         (PangoFont *font,
                                             PangoXSubfont subfont,
                                             gunichar **glyphs,
                                             int *n_glyphs,
                                             int **clusters);
void        pango_x_fallback_shape          (PangoFont *font,
                                             PangoGlyphString *glyphs,
                                             const char *text,
                                             int n_chars);
struct      PangoXFontCache;
PangoXFontCache* pango_x_font_cache_new     (Display *display);
void        pango_x_font_cache_free         (PangoXFontCache *cache);
XFontStruct* pango_x_font_cache_load        (PangoXFontCache *cache,
                                             const char *xlfd);
void        pango_x_font_cache_unload       (PangoXFontCache *cache,
                                             XFontStruct *fs);

Description

The functions and macros in this section are used by shape engines to look up glyphs for particular character sets within an PangoFont for the X rendering system.

Details

PANGO_RENDER_TYPE_X

#define PANGO_RENDER_TYPE_X "PangoRenderX"

A string constant identifying the X renderer. The associated quark (see g_quark_from_string()) is used to identify the renderer in pango_find_map().

pango_x_get_context ()

PangoContext* pango_x_get_context           (Display *display);

Retrieves a PangoContext appropriate for rendering with X fonts on the given display.

`display` :	an X display (As returned by `XOpenDisplay()`.)
Returns :	the new PangoContext.

pango_x_context_set_funcs ()

void        pango_x_context_set_funcs       (PangoContext *context,
                                             PangoGetGCFunc get_gc_func,
                                             PangoFreeGCFunc free_gc_func);

Sets the functions that will be used to get GC's in various colors when rendering layouts with this context.

`context` :	a PangoContext.
`get_gc_func` :	function called to create a new GC for a given color.
`free_gc_func` :	function called to free a GC created with `get_gc_func`.

PangoGetGCFunc ()

GC          (*PangoGetGCFunc)               (PangoContext *context,
                                             PangoColor *color,
                                             GC base_gc);

Specifies the type of the function used to create a new GC for a given color.

`context` :	a PangoContext.
`color` :	the color to create a new GC for.
`base_gc` :	the GC to base the new GC on.
Returns :	the new GC.

PangoFreeGCFunc ()

void        (*PangoFreeGCFunc)              (PangoContext *context,
                                             GC gc);

Specifies the type of the function used to free a GC created with the corresponding PangoGetGCFunc function.

`context` :	a PangoContext.
`gc` :	the GC to free.

pango_x_render ()

void        pango_x_render                  (Display *display,
                                             Drawable d,
                                             GC gc,
                                             PangoFont *font,
                                             PangoGlyphString *glyphs,
                                             gint x,
                                             gint y);

Renders a PangoGlyphString onto an X drawable.

`display` :	the X display.
`d` :	the drawable on which to draw string.
`gc` :	the graphics context.
`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_x_render_layout_line ()

void        pango_x_render_layout_line      (Display *display,
                                             Drawable drawable,
                                             GC gc,
                                             PangoLayoutLine *line,
                                             int x,
                                             int y);

Renders a PangoLayoutLine onto an X drawable.

`display` :	the X display.
`drawable` :	the drawable on which to draw.
`gc` :	GC to use for uncolored drawing.
`line` :	a PangoLayoutLine.
`x` :	the x position of start of string (in pixels).
`y` :	the y position of baseline (in pixels).

pango_x_render_layout ()

void        pango_x_render_layout           (Display *display,
                                             Drawable drawable,
                                             GC gc,
                                             PangoLayout *layout,
                                             int x,
                                             int y);

Renders a PangoLayoutLine onto an X drawable.

`display` :	the X display.
`drawable` :	the drawable on which to draw.
`gc` :	GC to use for uncolored drawing.
`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).

PangoXSubfont

typedef guint16 PangoXSubfont;

The PangoXSubFont type is an integer ID that identifies one particular X font within the fonts referenced in a PangoFont.

PANGO_X_MAKE_GLYPH()

#define PANGO_X_MAKE_GLYPH(subfont,index_) ((subfont)<<16 | (index_))

Make a glyph index from a PangoXSubFont index and a index of a character with the corresponding X font.

`subfont` :	a PangoXSubfont index
`index_` :	the index of a character within an X font.

PANGO_X_GLYPH_SUBFONT()

#define PANGO_X_GLYPH_SUBFONT(glyph) ((glyph)>>16)

Extract the subfont index from a glyph index.

glyph : a PangoGlyphIndex

PANGO_X_GLYPH_INDEX()

#define PANGO_X_GLYPH_INDEX(glyph) ((glyph) & 0xffff)

Extract the character index within the X font from a glyph index.

glyph : a PangoGlyphIndex

pango_x_load_font ()

PangoFont*  pango_x_load_font               (Display *display,
                                             const gchar *spec);

Loads up a logical font based on a "fontset" style text specification. This is not remotely useful (Pango API's generally work in terms of PangoFontDescription) and the result may not work correctly in all circumstances. Use of this function should be avoided.

`display` :	the X display.
`spec` :	a comma-separated list of XLFD's.
Returns :	a new PangoFont.

pango_x_get_unknown_glyph ()

PangoGlyph  pango_x_get_unknown_glyph       (PangoFont *font);

Returns the index of a glyph suitable for drawing unknown characters; you should generally use pango_x_font_get_unknown_glyph_instead, since that may return a glyph that provides a better representation of a particular char. (E.g., by showing hex digits, or a glyph representive of a certain Unicode range.)

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

pango_x_has_glyph ()

gboolean    pango_x_has_glyph               (PangoFont *font,
                                             PangoGlyph glyph);

Checks if the given glyph is present in a X font.

`font` :	a PangoFont which must be from the X backend.
`glyph` :	the index of a glyph in the font. (Formed using the PANGO_X_MAKE_GLYPH macro)
Returns :	`TRUE` if the glyph is present.

pango_x_list_subfonts ()

int         pango_x_list_subfonts           (PangoFont *font,
                                             char **charsets,
                                             int n_charsets,
                                             PangoXSubfont **subfont_ids,
                                             int **subfont_charsets);

Lists the subfonts of a given font. The result is ordered first by charset, and then within each charset, by the order of fonts in the font specification.

`font` :	a PangoFont.
`charsets` :	the charsets to list subfonts for.
`n_charsets` :	the number of charsets in `charsets`.
`subfont_ids` :	location to store a pointer to an array of subfont IDs for each found subfont; the result must be freed using `g_free()`.
`subfont_charsets` :	location to store a pointer to an array of subfont IDs for each found subfont; the result must be freed using `g_free()`.
Returns :	length of the arrays stored in `subfont_ids` and `subfont_charsets`.

pango_x_font_map_for_display ()

PangoFontMap* pango_x_font_map_for_display  (Display *display);

Returns a PangoXFontMap for display. Font maps are cached and should not be freed. If the font map for a display is no longer needed, it can be released with pango_x_shutdown_display().

`display` :	an X Display.
Returns :	a PangoXFontMap for `display`.

pango_x_shutdown_display ()

void        pango_x_shutdown_display        (Display *display);

Free cached resources for the given X display structure.

display : an X Display

pango_x_font_map_get_font_cache ()

PangoXFontCache* pango_x_font_map_get_font_cache
                                            (PangoFontMap *font_map);

Obtains the font cache associated with the given font map.

`font_map` :	a PangoXFontMap.
Returns :	the PangoXFontCache of `font_map`.

pango_x_font_subfont_xlfd ()

char*       pango_x_font_subfont_xlfd       (PangoFont *font,
                                             PangoXSubfont subfont_id);

Determines the X Logical Font Description for the specified subfont.

`font` :	a PangoFont which must be from the X backend.
`subfont_id` :	the id of a subfont within the font.
Returns :	A newly-allocated string containing the XLFD for the subfont. This string must be freed with `g_free()`.

pango_x_find_first_subfont ()

gboolean    pango_x_find_first_subfont      (PangoFont *font,
                                             char **charsets,
                                             int n_charsets,
                                             PangoXSubfont *rfont);

Looks for subfonts with the charset charset, in font, and puts the first one in *rfont.

`font` :	A PangoFont.
`charsets` :	An array of charsets.
`n_charsets` :	The number of charsets in `charsets`.
`rfont` :	A pointer to a PangoXSubfont.
Returns :	`TRUE` if *`rfont` now contains a font.

pango_x_font_get_unknown_glyph ()

PangoGlyph  pango_x_font_get_unknown_glyph  (PangoFont *font,
                                             gunichar wc);

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

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

pango_x_apply_ligatures ()

gboolean    pango_x_apply_ligatures         (PangoFont *font,
                                             PangoXSubfont subfont,
                                             gunichar **glyphs,
                                             int *n_glyphs,
                                             int **clusters);

Previously did subfont-specific ligation. Now a no-op.

`font` :	unused
`subfont` :	unused
`glyphs` :	unused
`n_glyphs` :	unused
`clusters` :	unused
Returns :	`FALSE`, always.

pango_x_fallback_shape ()

void        pango_x_fallback_shape          (PangoFont *font,
                                             PangoGlyphString *glyphs,
                                             const char *text,
                                             int n_chars);

This is a simple fallback shaper, that can be used if no subfont that supports a given script is found. For every character in text, it puts the Unknown glyph.

`font` :	A PangoFont.
`glyphs` :	A pointer to a PangoGlyphString.
`text` :	UTF-8 string.
`n_chars` :	Number of UTF-8 seqs in `text`.

struct PangoXFontCache

struct PangoXFontCache;

A PangoXFontCache caches XFontStructs for a single display by their XLFD name.

pango_x_font_cache_new ()

PangoXFontCache* pango_x_font_cache_new     (Display *display);

Creates a font cache for the specified display.

`display` :	an X display.
Returns :	The new font cache. This must be freed with `pango_x_font_cache_free()`.

pango_x_font_cache_free ()

void        pango_x_font_cache_free         (PangoXFontCache *cache);

Frees a PangoXFontCache and all associated memory. All fonts loaded through this font cache will be freed along with the cache.

cache : a PangoXFontCache

pango_x_font_cache_load ()

XFontStruct* pango_x_font_cache_load        (PangoXFontCache *cache,
                                             const char *xlfd);

Loads a XFontStruct from a X Logical Font Description. The result may be newly loaded, or it may have been previously stored.

`cache` :	a PangoXFontCache
`xlfd` :	the X Logical Font Description to load.
Returns :	The font structure, or `NULL` if the font could not be loaded. In order to free this structure, you must call `pango_x_font_cache_unload()`.

pango_x_font_cache_unload ()

void        pango_x_font_cache_unload       (PangoXFontCache *cache,
                                             XFontStruct *fs);

Frees a font structure previously loaded with pango_x_font_cache_load().

`cache` :	a PangoXFontCache
`fs` :	the font structure to unload