PangoRenderer: Pango Reference Manual

## PangoRenderer PangoRenderer — Rendering driver base class |

## Functions

void | pango_renderer_draw_layout ()
void | pango_renderer_draw_layout_line ()
void | pango_renderer_draw_glyphs ()
void | pango_renderer_draw_glyph_item ()
void | pango_renderer_draw_rectangle ()
void | pango_renderer_draw_error_underline ()
void | pango_renderer_draw_trapezoid ()
void | pango_renderer_draw_glyph ()
void | pango_renderer_activate ()
void | pango_renderer_deactivate ()
void | pango_renderer_part_changed ()
void | pango_renderer_set_color ()
PangoColor * | pango_renderer_get_color ()
void | pango_renderer_set_alpha ()
guint16 | pango_renderer_get_alpha ()
void | pango_renderer_set_matrix ()
const PangoMatrix * | pango_renderer_get_matrix ()
PangoLayout * | pango_renderer_get_layout ()
PangoLayoutLine * | pango_renderer_get_layout_line ()

## Types and Values

struct | PangoRenderer
enum | PangoRenderPart
#define | PANGO_TYPE_RENDER_PART
struct | PangoRendererClass

## Object Hierarchy

        GEnum
        ╰── PangoRenderPart
        GObject
        ╰── PangoRenderer
            ╰── PangoXftRenderer

## Description

PangoRenderer is a base class that contains the necessary logic for rendering a PangoLayout or PangoLayoutLine. By subclassing PangoRenderer and overriding operations such as `draw_glyphs` and `draw_rectangle` , renderers for particular font backends and destinations can be created.

## Functions

### pango_renderer_draw_layout ()

    void
    pango_renderer_draw_layout (PangoRenderer *renderer,
                                PangoLayout *layout,
                                int x,
                                int y);

Draws `layout` with the specified PangoRenderer.

#### Parameters

renderer | a PangoRenderer |
layout | a PangoLayout |
x | X position of left edge of baseline, in user space coordinates in Pango units. |
y | Y position of left edge of baseline, in user space coordinates in Pango units. |

Since: 1.8

### pango_renderer_draw_layout_line ()

    void
    pango_renderer_draw_layout_line (PangoRenderer *renderer,
                                     PangoLayoutLine *line,
                                     int x,
                                     int y);

Draws `line` with the specified PangoRenderer.

#### Parameters

renderer | a PangoRenderer |
line | a PangoLayoutLine |
x | X position of left edge of baseline, in user space coordinates in Pango units. |
y | Y position of left edge of baseline, in user space coordinates in Pango units. |

Since: 1.8

### pango_renderer_draw_glyphs ()

    void
    pango_renderer_draw_glyphs (PangoRenderer *renderer,
                                PangoFont *font,
                                PangoGlyphString *glyphs,
                                int x,
                                int y);

Draws the glyphs in `glyphs` with the specified PangoRenderer.

#### Parameters

renderer | a PangoRenderer |
font | a PangoFont |
glyphs | a PangoGlyphString |
x | X position of left edge of baseline, in user space coordinates in Pango units. |
y | Y position of left edge of baseline, in user space coordinates in Pango units. |

Since: 1.8

### pango_renderer_draw_glyph_item ()

    void
    pango_renderer_draw_glyph_item (PangoRenderer *renderer,
                                    const char *text,
                                    PangoGlyphItem *glyph_item,
                                    int x,
                                    int y);

Draws the glyphs in `glyph_item` with the specified PangoRenderer, embedding the text associated with the glyphs in the output if the output format supports it (PDF for example).

Note that `text` is the start of the text for layout, which is then indexed by ``glyph_item->item->offset`` .

If `text` is `NULL`, this simply calls `pango_renderer_draw_glyphs()`.

The default implementation of this method simply falls back to `pango_renderer_draw_glyphs()`.

#### Parameters

renderer | a PangoRenderer |
text | the UTF-8 text that `glyph_item` refers to, or `NULL`. | [allow-none]
glyph_item | a PangoGlyphItem |
x | X position of left edge of baseline, in user space coordinates in Pango units. |
y | Y position of left edge of baseline, in user space coordinates in Pango units. |

Since: 1.22

### pango_renderer_draw_rectangle ()

    void
    pango_renderer_draw_rectangle (PangoRenderer *renderer,
                                   PangoRenderPart part,
                                   int x,
                                   int y,
                                   int width,
                                   int height);

Draws an axis-aligned rectangle in user space coordinates with the specified PangoRenderer.

This should be called while `renderer` is already active. Use `pango_renderer_activate()` to activate a renderer.

#### Parameters

renderer | a PangoRenderer |
part | type of object this rectangle is part of |
x | X position at which to draw rectangle, in user space coordinates in Pango units |
y | Y position at which to draw rectangle, in user space coordinates in Pango units |
width | width of rectangle in Pango units in user space coordinates |
height | height of rectangle in Pango units in user space coordinates |

Since: 1.8

### pango_renderer_draw_error_underline ()

    void
    pango_renderer_draw_error_underline (PangoRenderer *renderer,
                                         int x,
                                         int y,
                                         int width,
                                         int height);

Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. (The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle)

This should be called while `renderer` is already active. Use `pango_renderer_activate()` to activate a renderer.

#### Parameters

renderer | a PangoRenderer |
x | X coordinate of underline, in Pango units in user coordinate system |
y | Y coordinate of underline, in Pango units in user coordinate system |
width | width of underline, in Pango units in user coordinate system |
height | height of underline, in Pango units in user coordinate system |

Since: 1.8

### pango_renderer_draw_trapezoid ()

    void
    pango_renderer_draw_trapezoid (PangoRenderer *renderer,
                                   PangoRenderPart part,
                                   double y1_,
                                   double x11,
                                   double x21,
                                   double y2,
                                   double x12,
                                   double x22);

Draws a trapezoid with the parallel sides aligned with the X axis using the given PangoRenderer; coordinates are in device space.

#### Parameters

renderer | a PangoRenderer |
part | type of object this trapezoid is part of |
y1_ | Y coordinate of top of trapezoid |
x11 | X coordinate of left end of top of trapezoid |
x21 | X coordinate of right end of top of trapezoid |
y2 | Y coordinate of bottom of trapezoid |
x12 | X coordinate of left end of bottom of trapezoid |
x22 | X coordinate of right end of bottom of trapezoid |

Since: 1.8

### pango_renderer_draw_glyph ()

    void
    pango_renderer_draw_glyph (PangoRenderer *renderer,
                               PangoFont *font,
                               PangoGlyph glyph,
                               double x,
                               double y);

Draws a single glyph with coordinates in device space.

#### Parameters

renderer | a PangoRenderer |
font | a PangoFont |
glyph | the glyph index of a single glyph |
x | X coordinate of left edge of baseline of glyph |
y | Y coordinate of left edge of baseline of glyph |

Since: 1.8

### pango_renderer_activate ()

    void
    pango_renderer_activate (PangoRenderer *renderer);

Does initial setup before rendering operations on `renderer` . `pango_renderer_deactivate()` should be called when done drawing. Calls such as `pango_renderer_draw_layout()` automatically activate the layout before drawing on it. Calls to `pango_renderer_activate()` and `pango_renderer_deactivate()` can be nested and the renderer will only be initialized and deinitialized once.

#### Parameters

renderer | a PangoRenderer |

Since: 1.8

### pango_renderer_deactivate ()

    void
    pango_renderer_deactivate (PangoRenderer *renderer);

Cleans up after rendering operations on `renderer` . See docs for `pango_renderer_activate()`.

#### Parameters

renderer | a PangoRenderer |

Since: 1.8

### pango_renderer_part_changed ()

    void
    pango_renderer_part_changed (PangoRenderer *renderer,
                                 PangoRenderPart part);

Informs Pango that the way that the rendering is done for `part` has changed in a way that would prevent multiple pieces being joined together into one drawing call. For instance, if a subclass of PangoRenderer was to add a stipple option for drawing underlines, it needs to call

    1
    pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE);

When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for changes to colors. (See `pango_renderer_set_color()`)

#### Parameters

renderer | a PangoRenderer |
part | the part for which rendering has changed. |

Since: 1.8

### pango_renderer_set_color ()

    void
    pango_renderer_set_color (PangoRenderer *renderer,
                              PangoRenderPart part,
                              const PangoColor *color);

Sets the color for part of the rendering. Also see `pango_renderer_set_alpha()`.

#### Parameters

renderer | a PangoRenderer |
part | the part to change the color of |
color | the new color or `NULL` to unset the current color. | [allow-none]

Since: 1.8

### pango_renderer_get_color ()

    PangoColor *
    pango_renderer_get_color (PangoRenderer *renderer,
                              PangoRenderPart part);

Gets the current rendering color for the specified part.

#### Parameters

renderer | a PangoRenderer |
part | the part to get the color for |

#### Returns

the color for the specified part, or `NULL` if it hasn't been set and should be inherited from the environment.

[transfer none][nullable]

Since: 1.8

### pango_renderer_set_alpha ()

    void
    pango_renderer_set_alpha (PangoRenderer *renderer,
                              PangoRenderPart part,
                              guint16 alpha);

Sets the alpha for part of the rendering. Note that the alpha may only be used if a color is specified for `part` as well.

#### Parameters

renderer | a PangoRenderer |
part | the part to set the alpha for |
alpha | an alpha value between 1 and 65536, or 0 to unset the alpha |

Since: 1.38

### pango_renderer_get_alpha ()

    guint16
    pango_renderer_get_alpha (PangoRenderer *renderer,
                              PangoRenderPart part);

Gets the current alpha for the specified part.

#### Parameters

renderer | a PangoRenderer |
part | the part to get the alpha for |

#### Returns

the alpha for the specified part, or 0 if it hasn't been set and should be inherited from the environment.

Since: 1.38

### pango_renderer_set_matrix ()

    void
    pango_renderer_set_matrix (PangoRenderer *renderer,
                               const PangoMatrix *matrix);

Sets the transformation matrix that will be applied when rendering.

#### Parameters

renderer | a PangoRenderer |
matrix | a PangoMatrix, or `NULL` to unset any existing matrix. (No matrix set is the same as setting the identity matrix.). | [allow-none]

Since: 1.8

### pango_renderer_get_matrix ()

    const PangoMatrix *
    pango_renderer_get_matrix (PangoRenderer *renderer);

Gets the transformation matrix that will be applied when rendering. See `pango_renderer_set_matrix()`.

#### Parameters

renderer | a PangoRenderer |

#### Returns

the matrix, or `NULL` if no matrix has been set (which is the same as the identity matrix). The returned matrix is owned by Pango and must not be modified or freed.

[nullable]

Since: 1.8

### pango_renderer_get_layout ()

    PangoLayout *
    pango_renderer_get_layout (PangoRenderer *renderer);

Gets the layout currently being rendered using `renderer` . Calling this function only makes sense from inside a subclass's methods, like in its draw_shape() for example.

The returned layout should not be modified while still being rendered.

#### Parameters

renderer | a PangoRenderer |

#### Returns

the layout, or `NULL` if no layout is being rendered using `renderer` at this time.

[transfer none][nullable]

Since: 1.20

### pango_renderer_get_layout_line ()

    PangoLayoutLine *
    pango_renderer_get_layout_line (PangoRenderer *renderer);

Gets the layout line currently being rendered using `renderer` . Calling this function only makes sense from inside a subclass's methods, like in its draw_shape() for example.

The returned layout line should not be modified while still being rendered.

#### Parameters

renderer | a PangoRenderer |

#### Returns

the layout line, or `NULL` if no layout line is being rendered using `renderer` at this time.

[transfer none][nullable]

Since: 1.20

## Types and Values

### struct PangoRenderer

    struct PangoRenderer {
      PangoMatrix *matrix;		/* May be NULL */
    };

PangoRenderer is a base class for objects that are used to render Pango objects such as PangoGlyphString and PangoLayout.

#### Members

PangoMatrix *`matrix`; | the current transformation matrix for the Renderer; may be `NULL`, which should be treated the same as the identity matrix. | [nullable]

Since: 1.8

### enum PangoRenderPart

PangoRenderPart defines different items to render for such purposes as setting colors.

#### Members

PANGO_RENDER_PART_FOREGROUND | the text itself |
PANGO_RENDER_PART_BACKGROUND | the area behind the text |
PANGO_RENDER_PART_UNDERLINE | underlines |
PANGO_RENDER_PART_STRIKETHROUGH | strikethrough lines |

Since: 1.8

### PANGO_TYPE_RENDER_PART

    #define PANGO_TYPE_RENDER_PART (pango_render_part_get_type ())

### struct PangoRendererClass

    struct PangoRendererClass {
      /* All of the following have default implementations
       * and take as coordinates user coordinates in Pango units
       */
      void (*draw_glyphs) (PangoRenderer     *renderer,
    		       PangoFont         *font,
    		       PangoGlyphString  *glyphs,
    		       int                x,
    		       int                y);
      void (*draw_rectangle) (PangoRenderer     *renderer,
    			  PangoRenderPart    part,
    			  int                x,
    			  int                y,
    			  int                width,
    			  int                height);
      void (*draw_error_underline) (PangoRenderer     *renderer,
    				int                x,
    				int                y,
    				int                width,
    				int                height);

      /* Nothing is drawn for shaped glyphs unless this is implemented */
      void (*draw_shape) (PangoRenderer  *renderer,
    		      PangoAttrShape *attr,
    		      int             x,
    		      int             y);

      /* These two must be implemented and take coordinates in
       * device space as doubles.
       */
      void (*draw_trapezoid) (PangoRenderer  *renderer,
    			  PangoRenderPart part,
    			  double          y1_,
    			  double          x11,
    			  double          x21,
    			  double          y2,
    			  double          x12,
    			  double          x22);
      void (*draw_glyph) (PangoRenderer *renderer,
    		      PangoFont     *font,
    		      PangoGlyph     glyph,
    		      double         x,
    		      double         y);

      /* Notification of change in rendering attributes
       */
      void (*part_changed) (PangoRenderer   *renderer,
    			PangoRenderPart  part);

      /* Paired around drawing operations
       */
      void (*begin) (PangoRenderer *renderer);
      void (*end)   (PangoRenderer *renderer);

      /* Hooks into the details of layout rendering
       */
      void (*prepare_run) (PangoRenderer  *renderer,
    		       PangoLayoutRun *run);

      /* All of the following have default implementations
       * and take as coordinates user coordinates in Pango units
       */
      void (*draw_glyph_item) (PangoRenderer     *renderer,
    			   const char        *text,
    			   PangoGlyphItem    *glyph_item,
    			   int                x,
    			   int                y);
    };

Class structure for PangoRenderer.

#### Members

`draw_glyphs` () | draws a PangoGlyphString |
`draw_rectangle` () | draws a rectangle |
`draw_error_underline` () | draws a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. |
`draw_shape` () | draw content for a glyph shaped with PangoAttrShape. `x` , `y` are the coordinates of the left edge of the baseline, in user coordinates. |
`draw_trapezoid` () | draws a trapezoidal filled area |
`draw_glyph` () | draws a single glyph |
`part_changed` () | do renderer specific processing when rendering attributes change |
`begin` () | Do renderer-specific initialization before drawing |
`end` () | Do renderer-specific cleanup after drawing |
`prepare_run` () | updates the renderer for a new run |
`draw_glyph_item` () | draws a PangoGlyphItem |

Since: 1.8