Module org.freedesktop.cairo

Package org.freedesktop.cairo

Interface UserScaledFontRenderGlyphFunc

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface UserScaledFontRenderGlyphFunc

UserScaledFontRenderGlyphFunc 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 scaledFont. The extents argument is where the user font sets the font extents for scaledFont. 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 UserFontFace.setRenderGlyphFunc(org.freedesktop.cairo.UserScaledFontRenderGlyphFunc), the result is undefined if any source other than the default source on cr is used. That means, glyph bitmaps should be rendered using Context.mask(Pattern) instead of Context.paint().

When this callback is set with UserFontFace.setRenderColorGlyphFunc(org.freedesktop.cairo.UserScaledFontRenderGlyphFunc), the default source is black. Setting the source is a valid operation. UserScaledFont.getForegroundMarker() or UserScaledFont.getForegroundSource() 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 scaledFont.

The extents argument is preset to have xBearing, width, and yAdvance of zero, yBearing set to -extents.ascent, height to extents.ascent+extents.descent, and xAdvance to extents.maxXAdvance. The only field a user needs to set in the majority of cases is xAdvance. 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.

Where both color and non-color callbacks has been set using UserFontFace.setRenderGlyphFunc(org.freedesktop.cairo.UserScaledFontRenderGlyphFunc), and UserFontFace.setRenderColorGlyphFunc(org.freedesktop.cairo.UserScaledFontRenderGlyphFunc), the color glyph callback will be called first. If the color glyph callback throws UnsupportedOperationException, any drawing operations are discarded and the non-color callback will be called. This fallback sequence allows a user font face to contain a combination of both color and non-color glyphs.

Since:

1.8

Method Summary

Modifier and Type	Method	Description
void	renderGlyph(UserScaledFont scaledFont, long glyph, Context cr, FontExtents extents)	called when a user scaled-font needs to render a glyph.
default MemorySegment	toCallback(Arena arena)	Generates an upcall stub, a C function pointer that will call upcall(java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment).
default int	upcall(MemorySegment scaledFont, long glyph, MemorySegment cr, MemorySegment extents)	The callback that is executed by native code.

Method Details

renderGlyph

void renderGlyph(UserScaledFont scaledFont,
 long glyph,
 Context cr,
 FontExtents extents)
          throws UnsupportedOperationException,
Exception

called when a user scaled-font needs to render a glyph.

Parameters:

scaledFont - user scaled-font

glyph - glyph code to render

cr - cairo context to draw to, in font space

extents - glyph extents to fill in, in font space

Throws:

UnsupportedOperationException - when fallback options should be tried

Exception - when an error occurs. Throwing an exception will trigger a Status.USER_FONT_ERROR return value to native code.

Since:

1.8

upcall

default int upcall(MemorySegment scaledFont,
 long glyph,
 MemorySegment cr,
 MemorySegment extents)

The callback that is executed by native code. This method marshals the parameters and calls renderGlyph(org.freedesktop.cairo.UserScaledFont, long, org.freedesktop.cairo.Context, org.freedesktop.cairo.FontExtents).

Parameters:

scaledFont - user scaled-font

glyph - glyph code to render

cr - cairo context to draw to, in font space

extents - glyph extents to fill in, in font space

Returns:

Status.SUCCESS upon success, Status.USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, or Status.USER_FONT_ERROR if an exception was thrown.

Since:

1.8

toCallback

default MemorySegment toCallback(Arena arena)

Generates an upcall stub, a C function pointer that will call upcall(java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment).

Parameters:

arena - the arena in which the upcall stub will be allocated

Returns:

the function pointer of the upcall stub

Since:

1.8