Module org.freedesktop.cairo

Package org.freedesktop.cairo

Interface UserScaledFontTextToGlyphsFunc

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 UserScaledFontTextToGlyphsFunc

UserScaledFontTextToGlyphsFunc is the type of function which is called to convert input text to an array of glyphs. This is used by the Context.showText(java.lang.String) operation.

Using this callback the user-font has full control on glyphs and their positions. That means, it allows for features like ligatures and kerning, as well as complex shaping required for scripts like Arabic and Indic.

In the Glyphs object, the numGlyphs field is preset to the number of glyph entries available in the glyphsPointer buffer. If the glyphs buffer is null, the value of numGlyphs will be zero. If the provided glyph array is too short for the conversion (or for convenience), a new glyph array may be allocated using Glyphs.allocateGlyphs(int) and placed in glyphsPointer. Upon return, numGlyphs should contain the number of generated glyphs. If the value glyphsPointer points at has changed after the call, the caller will free the allocated glyph array using cairo_glyph_free(). (If the caller is using these bindings, this will happen automatically.) The caller will also free the original value of glyphsPointer, so the callback shouldn't do so. The callback should populate the glyph indices and positions (in font space) assuming that the text is to be shown at the origin.

If clustersPointer is not MemorySegment.NULL, numClusters and clusterFlags are also non-NULL, and cluster mapping should be computed. The semantics of how cluster array allocation works is similar to the glyph array. That is, if clustersPointer initially points to a non-NULL value, that array may be used as a cluster buffer, and numClusters points to the number of cluster entries available there. If the provided cluster array is too short for the conversion (or for convenience), a new cluster array may be allocated using Glyphs.allocateClusters(int) and placed in clustersPointer. In this case, the original value of clustersPointer will still be freed by the caller. Upon return, numClusters should contain the number of generated clusters. If the value clusters points at has changed after the call, the caller will free the allocated cluster array using cairo_text_cluster_free(). (If the caller is using these bindings, this will happen automatically.)

The callback is optional. If the numGlyphs field in the Glyphs object is negative upon the callback returning or the callback throws UnsupportedOperationException, the unicode_to_glyph callback is tried. See UserScaledFontUnicodeToGlyphFunc.

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
void	textToGlyphs(UserScaledFont scaledFont, String string, Glyphs glyphs)	Called to convert input text to an array of glyphs.
default MemorySegment	toCallback(Arena arena)	Generates an upcall stub, a C function pointer that will call upcall(java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, int, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment).
default int	upcall(MemorySegment scaledFont, MemorySegment utf8, int utf8Len, MemorySegment glyphsPtr, MemorySegment numGlyphsPtr, MemorySegment clustersPtr, MemorySegment numClustersPtr, MemorySegment clusterFlagsPtr)	The callback that is executed by native code.

Method Details

textToGlyphs

void textToGlyphs(UserScaledFont scaledFont,
 String string,
 Glyphs glyphs)
           throws UnsupportedOperationException,
Exception

Called to convert input text to an array of glyphs.

Parameters:

scaledFont - the scaled-font being created

string - a string of text encoded in UTF-8

glyphs - a Glyphs object with a pointer to the array of glyphs to fill and its initial length, a pointer to the array of text clusters to fill and its initial length, and the initial TextClusterFlags. These fields are expected to be replaced with the results.

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,
 MemorySegment utf8,
 int utf8Len,
 MemorySegment glyphsPtr,
 MemorySegment numGlyphsPtr,
 MemorySegment clustersPtr,
 MemorySegment numClustersPtr,
 MemorySegment clusterFlagsPtr)

The callback that is executed by native code. This method marshals the parameters and calls textToGlyphs(org.freedesktop.cairo.UserScaledFont, java.lang.String, org.freedesktop.cairo.Glyphs).

Parameters:

scaledFont - the scaled-font being created

utf8 - a string of text encoded in UTF-8

utf8Len - length of utf8 in bytes

glyphsPtr - pointer to array of glyphs to fill, in font space

numGlyphsPtr - pointer to number of glyphs

clustersPtr - pointer to array of cluster mapping information to fill, or MemorySegment.NULL

numClustersPtr - pointer to number of clusters

clusterFlagsPtr - pointer to location to store cluster flags corresponding to the output clustersPtr

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, java.lang.foreign.MemorySegment, int, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, 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