#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.
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 <literal>x_bearing</literal>,
<literal>width</literal>, and <literal>y_advance</literal> of zero,
<literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>,
<literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>,
and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>.
The only field user needs to set in majority of cases is
<literal>x_advance</literal>.
If the <literal>width</literal> 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.
#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, when this callback is set with cairo.global.userFontFaceSetRenderGlyphFunc, 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.context.Context.mask instead of cairo.context.Context.paint.
When this callback is set with cairo.global.userFontFaceSetRenderColorGlyphFunc, the default source is black. Setting the source is a valid operation. cairo.global.userScaledFontGetForegroundMarker or cairo.global.userScaledFontGetForegroundSource may be called to obtain the current source at the time the glyph is rendered.
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 <literal>x_bearing</literal>, <literal>width</literal>, and <literal>y_advance</literal> of zero, <literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>, <literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>, and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>. The only field user needs to set in majority of cases is <literal>x_advance</literal>. If the <literal>width</literal> 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.
Where both color and non-color callbacks has been set using cairo.global.userFontFaceSetRenderColorGlyphFunc, and cairo.global.userFontFaceSetRenderGlyphFunc, the color glyph callback will be called first. If the color glyph callback returns cairo.types.Status.UserFontNotImplemented, any drawing operations are discarded and the non-color callback will be called. This is the only case in which the cairo.types.Status.UserFontNotImplemented may be returned from a render callback. This fallback sequence allows a user font face to contain a combination of both color and non-color glyphs.