Package com.metsci.glimpse.jogamp.opengl.util.awt.text

Class GlyphCache

java.lang.Object

com.metsci.glimpse.jogamp.opengl.util.awt.text.GlyphCache

public final class GlyphCache
extends Object

Storage of glyphs in an OpenGL texture.

GlyphCache andles storing glyphs in a 2D texture and retrieving their coordinates.

The first step in using a GlyphCache is to make sure it's set up by calling beginRendering(GL). Then glyphs can be added using upload(Glyph). Each glyph will be packed efficiently into the texture with a small amount of space around it using RectanglePacker. When all glyphs have been added, be sure to call update(GL) or endRendering(GL) before trying to render with the texture, as the glyphs are not actually drawn into the texture right away in order to increase performance. Texture coordinates of individual glyphs can be determined with find(Glyph). When reusing the glyph cache, contains(Glyph) should be called to make sure a glyph is not already stored.

Events fired when:

• A glyph has not been used recently (CLEAN, glyph);
• The backing store is going to be flushed.

GlyphCache is compatible with GL2 or GL3.

See Also:

TextureBackingStore

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	GlyphCache.EventListener	Object that wants to be notified of cache events.
static class	GlyphCache.EventType	Type of event fired from the cache.

Method Summary

Modifier and Type	Method	Description
void	addListener(GlyphCache.EventListener listener)	Registers an GlyphCache.EventListener with this GlyphCache.
void	beginRendering(com.jogamp.opengl.GL gl)	Sets up the cache for rendering.
void	dispose(com.jogamp.opengl.GL gl)	Destroys resources used by this GlyphCache.
void	endRendering(com.jogamp.opengl.GL gl)	Finishes setting up the cache for rendering.
com.jogamp.opengl.util.texture.TextureCoords	find(Glyph glyph)	Determines the texture coordinates of a glyph in the cache.
FontRenderContext	getFontRenderContext()	Returns the font render context used for text size computations by this GlyphCache.
boolean	getUseSmoothing()	Checks if this GlyphCache is interpolating when sampling.
static GlyphCache	newInstance(Font font, TextRenderer.RenderDelegate rd, boolean antialias, boolean subpixel, boolean mipmap)	Creates a new GlyphCache.
void	onBackingStoreEvent(com.metsci.glimpse.jogamp.opengl.util.awt.text.TextureBackingStore.EventType type)	Responds to an event from the backing store.
void	setUseSmoothing(boolean useSmoothing)	Changes whether this GlyphCache's texture should interpolate when sampling.
void	update(com.jogamp.opengl.GL gl)	Forces the cache to update the underlying OpenGL texture.
void	upload(Glyph glyph)	Stores a glyph in the cache.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addListener

public void addListener(GlyphCache.EventListener listener)

Registers an GlyphCache.EventListener with this GlyphCache.

Parameters:

listener - Listener to register

Throws:

NullPointerException - if listener is null

beginRendering

public void beginRendering(com.jogamp.opengl.GL gl)

Sets up the cache for rendering.

After calling this method the texture storing the glyphs will be bound.

Parameters:

gl - Current OpenGL context

Throws:

NullPointerException - if context is null

dispose

public void dispose(com.jogamp.opengl.GL gl)

Destroys resources used by this GlyphCache.

Parameters:

gl - Current OpenGL context

Throws:

NullPointerException - if context is null

endRendering

public void endRendering(com.jogamp.opengl.GL gl)

Finishes setting up the cache for rendering.

After calling this method, all uploaded glyphs will be guaranteed to be present in the underlying OpenGL texture.

Parameters:

gl - Current OpenGL context

Throws:

NullPointerException - if context is null

find

public com.jogamp.opengl.util.texture.TextureCoords find(Glyph glyph)

Determines the texture coordinates of a glyph in the cache.

Notes:

• Texture coordinates are in the range 0 to 1
• Automatically marks the glyph as being used recently
• If cache has been resized, coordinates are recalculated

Parameters:

glyph - Glyph already in cache

Returns:

Texture coordinates of glyph in the cache, not null

Throws:

NullPointerException - if glyph is null

getFontRenderContext

public FontRenderContext getFontRenderContext()

Returns the font render context used for text size computations by this GlyphCache.

This object should be considered transient and may become invalidated between beginRendering(com.jogamp.opengl.GL) and endRendering(com.jogamp.opengl.GL) pairs.

Returns:

Font render context used for text size computations, not null

getUseSmoothing

public boolean getUseSmoothing()

Checks if this GlyphCache is interpolating when sampling.

Returns:

True if this glyph cache is interpolating when it samples

newInstance

public static GlyphCache newInstance(Font font,
                                     TextRenderer.RenderDelegate rd,
                                     boolean antialias,
                                     boolean subpixel,
                                     boolean mipmap)

Creates a new GlyphCache.

Parameters:

font - Font that was used to create glyphs that will be stored

rd - Controller of rendering bitmapped text

antialias - Whether to render glyphs with smooth edges

subpixel - Whether to consider subpixel positioning

mipmap - Whether to create multiple sizes for texture

Returns:

New glyph cache instance, not null

Throws:

NullPointerException - if font or render delegate is null

IllegalArgumentException - if render delegate wants full color

onBackingStoreEvent

public void onBackingStoreEvent(com.metsci.glimpse.jogamp.opengl.util.awt.text.TextureBackingStore.EventType type)

Responds to an event from the backing store.

Parameters:

type - Kind of backing store event

Throws:

NullPointerException - if type is null

setUseSmoothing

public void setUseSmoothing(boolean useSmoothing)

Changes whether this GlyphCache's texture should interpolate when sampling.

Parameters:

useSmoothing - True to use linear interpolation

update

public void update(com.jogamp.opengl.GL gl)

Forces the cache to update the underlying OpenGL texture.

After calling this method, all uploaded glyphs will be guaranteed to be present in the underlying OpenGL texture.

Parameters:

gl - Current OpenGL context

Throws:

NullPointerException - if context is null

upload

public void upload(Glyph glyph)

Stores a glyph in the cache.

Determines a place to put the glyph in the underlying OpenGL texture, computes the glyph's texture coordinates for that position, and requests the glyph be drawn into the texture. (Note however that to increase performance the glyph is not guaranteed to actually be in the texture until update(GL) or endRendering(GL) is called.)

Parameters:

glyph - Glyph not already stored in cache

Throws:

NullPointerException - if glyph is null