Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class UserScaledFont

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.ScaledFont

org.freedesktop.cairo.UserScaledFont

public class UserScaledFont
extends ScaledFont

Provides a ScaledFont from the User font backend.

The user-font feature allows the cairo user to provide drawings for glyphs in a font. This is most useful in implementing fonts in non-standard formats, like SVG fonts and Flash fonts, but can also be used by games and other application to draw "funky" fonts.

Since:

1.8

Constructor Summary

Constructors

Constructor	Description
UserScaledFont(MemorySegment address)	Constructor used internally to instantiate a java UserScaledFont object for a native cairo_scaled_font_t instance

Method Summary

Modifier and Type	Method	Description
Pattern	getForegroundMarker()	Gets the foreground pattern of the glyph currently being rendered.
Pattern	getForegroundSource()	Gets the foreground pattern of the glyph currently being rendered.

Methods inherited from class org.freedesktop.cairo.ScaledFont

create, destroy, extents, getCTM, getFontFace, getFontMatrix, getFontOptions, getFontType, getScaleMatrix, getType, getUserData, glyphExtents, setUserData, status, textExtents, textToGlyphs

Methods inherited from class io.github.jwharm.cairobindings.Proxy

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

UserScaledFont

public UserScaledFont(MemorySegment address)

Constructor used internally to instantiate a java UserScaledFont object for a native cairo_scaled_font_t instance

Parameters:

address - the memory address of the native cairo_scaled_font_t instance

Method Details

getForegroundMarker

public Pattern getForegroundMarker()

Gets the foreground pattern of the glyph currently being rendered. A UserScaledFontRenderGlyphFunc function that has been set with UserFontFace.setRenderColorGlyphFunc(org.freedesktop.cairo.UserScaledFontRenderGlyphFunc) may call this function to retrieve the current foreground pattern for the glyph being rendered. The function should not be called outside of a UserFontFace.setRenderColorGlyphFunc(UserScaledFontRenderGlyphFunc) 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 getForegroundSource() 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 getForegroundSource().

If the render callback simply wants to call Context.getSource() with the foreground pattern, getForegroundMarker is the preferred function to use as it results in better performance than getForegroundSource().

Returns:

the current foreground source marker pattern. This object must not be modified or used outside of a color render callback.

Since:

1.18

getForegroundSource

public Pattern getForegroundSource()

Gets the foreground pattern of the glyph currently being rendered. A UserScaledFontRenderGlyphFunc function that has been set with UserFontFace.setRenderColorGlyphFunc(org.freedesktop.cairo.UserScaledFontRenderGlyphFunc) may call this function to retrieve the current foreground pattern for the glyph being rendered. The function should not be called outside of a UserFontFace.setRenderColorGlyphFunc(UserScaledFontRenderGlyphFunc) callback.

This function returns the current source at the time the glyph is rendered. Compared with getForegroundMarker(), this function returns the actual source pattern that will be used to render the glyph. The render callback is free to query the pattern and extract color components or other pattern data. For example if the render callback wants to create a gradient stop based on colors in the foreground source pattern, it will need to use this function in order to be able to query the colors in the foreground pattern.

While this function does not have the restrictions on using the pattern that getForegroundMarker() has, it does incur a performance penalty. If a render callback calls this function:

1. Cairo will call the render callback whenever the current pattern of the context in which the glyph is rendered changes.
2. On backends that support font embedding (PDF, PostScript, and SVG), cairo can not embed this glyph in a font. Instead the glyph will be emitted as an image or sequence of drawing operations each time it is used.

Returns:

the current foreground source pattern.

Since:

1.18