Module org.freedesktop.cairo

Package org.freedesktop.cairo

Interface UserScaledFontUnicodeToGlyphFunc

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 UserScaledFontUnicodeToGlyphFunc

UserScaledFontUnicodeToGlyphFunc is the type of function which is called to convert an input Unicode character to a single glyph. This is used by the Context.showText(String) operation.

This callback is used to provide the same functionality as the text_to_glyphs callback does (see UserScaledFontTextToGlyphsFunc) but has much less control on the output, in exchange for increased ease of use. The inherent assumption to using this callback is that each character maps to one glyph, and that the mapping is context independent. It also assumes that glyphs are positioned according to their advance width. These mean no ligatures, kerning, or complex scripts can be implemented using this callback.

The callback is optional, and only used if text_to_glyphs callback is not set or fails to return glyphs. If this callback is not set, an identity mapping from Unicode code-points to glyph indices is assumed.

Note: While cairo does not impose any limitation on glyph indices, some applications may assume that a glyph index fits in a 16-bit unsigned integer. As such, it is advised that user-fonts keep their glyphs in the 0 to 65535 range. Furthermore, some applications may assume that glyph 0 is a special glyph-not-found glyph. User-fonts are advised to use glyph 0 for such purposes and do not use that glyph value for other purposes.

Since:

1.8

Method Summary

Modifier and Type	Method	Description
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).
long	unicodeToGlyph(UserScaledFont scaledFont, long unicode)	Called to convert an input Unicode character to a single glyph.
default int	upcall(MemorySegment scaledFont, long unicode, MemorySegment glyphIndex)	The callback that is executed by native code.

Method Details

unicodeToGlyph

long unicodeToGlyph(UserScaledFont scaledFont,
 long unicode)
             throws UnsupportedOperationException,
Exception

Called to convert an input Unicode character to a single glyph.

Parameters:

scaledFont - the scaled-font being created

unicode - input unicode character code-point

Returns:

output glyph index

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 unicode,
 MemorySegment glyphIndex)

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

Parameters:

scaledFont - the scaled-font being created

unicode - input unicode character code-point

glyphIndex - output glyph index

Returns:

Status.SUCCESS upon success, Status.USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, or Status.USER_FONT_ERROR or any other error status on error.

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).

Parameters:

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

Returns:

the function pointer of the upcall stub

Since:

1.8