Gets the foreground pattern of the glyph currently being
rendered. A #cairo_user_scaled_font_render_glyph_func_t function
that has been set with
cairo.global.userFontFaceSetRenderColorGlyphFunc may call this
function to retrieve the current foreground pattern for the glyph
being rendered. The function should not be called outside of a
cairo.global.userFontFaceSetRenderColorGlyphFunc callback.
The foreground marker pattern contains an internal marker to
indicate that it is to be substituted with the current source when
rendered to a surface. Querying the foreground marker will reveal a
solid black color, however this is not representative of the color
that will actually be used. Similarly, setting a solid black color
will render black, not the foreground pattern when the glyph is
painted to a surface. Using the foreground marker as the source
instead of cairo.global.userScaledFontGetForegroundSource in a
color render callback has the following benefits:
1. Cairo only needs to call the render callback once as it can
cache the recording. Cairo will substitute the actual foreground
color when rendering the recording.
2. On backends that have the concept of a foreground color in fonts such as
PDF, PostScript, and SVG, cairo can generate more optimal
output. The glyph can be included in an embedded font.
The one drawback of the using foreground marker is the render
callback can not access the color components of the pattern as the
actual foreground pattern is not available at the time the render
callback is invoked. If the render callback needs to query the
foreground pattern, use
cairo.global.userScaledFontGetForegroundSource.
the current foreground source marker pattern. This
object is owned by cairo. This object must not be modified or used
outside of a color render callback. To keep a reference to it,
you must call cairo.pattern.Pattern.reference.
Gets the foreground pattern of the glyph currently being rendered. A #cairo_user_scaled_font_render_glyph_func_t function that has been set with cairo.global.userFontFaceSetRenderColorGlyphFunc may call this function to retrieve the current foreground pattern for the glyph being rendered. The function should not be called outside of a cairo.global.userFontFaceSetRenderColorGlyphFunc callback.
The foreground marker pattern contains an internal marker to indicate that it is to be substituted with the current source when rendered to a surface. Querying the foreground marker will reveal a solid black color, however this is not representative of the color that will actually be used. Similarly, setting a solid black color will render black, not the foreground pattern when the glyph is painted to a surface. Using the foreground marker as the source instead of cairo.global.userScaledFontGetForegroundSource in a color render callback has the following benefits:
1. Cairo only needs to call the render callback once as it can cache the recording. Cairo will substitute the actual foreground color when rendering the recording.
2. On backends that have the concept of a foreground color in fonts such as PDF, PostScript, and SVG, cairo can generate more optimal output. The glyph can be included in an embedded font.
The one drawback of the using foreground marker is the render callback can not access the color components of the pattern as the actual foreground pattern is not available at the time the render callback is invoked. If the render callback needs to query the foreground pattern, use cairo.global.userScaledFontGetForegroundSource.
If the render callback simply wants to call cairo.context.Context.setSource with the foreground pattern, cairo.global.userScaledFontGetForegroundMarker is the preferred function to use as it results in better performance than cairo.global.userScaledFontGetForegroundSource.