cairo_user_scaled_font_render_glyph_func_t

cairo_user_scaled_font_render_glyph_func_t is the type of function which is called when a user scaled-font needs to render a glyph.

The callback is mandatory, and expected to draw the glyph with code glyph to the cairo context cr. cr is prepared such that the glyph drawing is done in font space. That is, the matrix set on cr is the scale matrix of scaled_font, The extents argument is where the user font sets the font extents for scaled_font. However, if user prefers to draw in user space, they can achieve that by changing the matrix on cr. All cairo rendering operations to cr are permitted, however, the result is undefined if any source other than the default source on cr is used. That means, glyph bitmaps should be rendered using cairo_mask() instead of cairo_paint().

Other non-default settings on cr include a font size of 1.0 (given that it is set up to be in font space), and font options corresponding to scaled_font.

The extents argument is preset to have x_bearing, width, and y_advance of zero, y_bearing set to -font_extents.ascent, height to font_extents.ascent+font_extents.descent, and x_advance to font_extents.max_x_advance. The only field user needs to set in majority of cases is x_advance. If the width field is zero upon the callback returning (which is its preset value), the glyph extents are automatically computed based on the drawings done to cr. This is in most cases exactly what the desired behavior is. However, if for any reason the callback sets the extents, it must be ink extents, and include the extents of all drawing done to cr in the callback.