userScaledFontGetForegroundMarker

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.

1. 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].