JOGL 2.3.2 · com.jogamp.opengl.util.awt.TextRenderer

Renders bitmapped Java 2D text into an OpenGL window with high performance, full Unicode support, and a simple API. Performs appropriate caching of text rendering results in an OpenGL texture internally to avoid repeated font rasterization. The caching is completely automatic, does not require any user intervention, and has no visible controls in the public API.

Using the TextRenderer is simple. Add a "TextRenderer renderer;" field to your GLEventListener. In your init method, add:

renderer = new TextRenderer(new Font("SansSerif", Font.BOLD, 36));

In the display method of your GLEventListener, add:

renderer.beginRendering(drawable.getWidth(), drawable.getHeight());
// optionally set the color
renderer.setColor(1.0f, 0.2f, 0.2f, 0.8f);
renderer.draw("Text to draw", xPosition, yPosition);
// ... more draw commands, color changes, etc.
renderer.endRendering();

Unless you are sharing textures and display lists between OpenGL contexts, you do not need to call the dispose method of the TextRenderer; the OpenGL resources it uses internally will be cleaned up automatically when the OpenGL context is destroyed.

Note

that the TextRenderer may cause the vertex and texture coordinate array buffer bindings to change, or to be unbound. This is important to note if you are using Vertex Buffer Objects (VBOs) in your application.

Internally, the renderer uses a rectangle packing algorithm to pack both glyphs and full Strings' rendering results (which are variable size) onto a larger OpenGL texture. The internal backing store is maintained using a TextureRenderer. A least recently used (LRU) algorithm is used to discard previously rendered strings; the specific algorithm is undefined, but is currently implemented by flushing unused Strings' rendering results every few hundred rendering cycles, where a rendering cycle is defined as a pair of calls to beginRendering / endRendering.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	TextRenderer.CharacterCache
private static class	TextRenderer.CharSequenceIterator
pack-priv class	TextRenderer.DebugListener
public static class	TextRenderer.DefaultRenderDelegate
pack-priv class	TextRenderer.Glyph A Glyph represents either a single unicode glyph or a substring of characters to be drawn.
pack-priv class	TextRenderer.GlyphProducer
pack-priv class	TextRenderer.Manager
pack-priv class	TextRenderer.Pipelined_QuadRenderer
public static interface	TextRenderer.RenderDelegate Class supporting more full control over the process of rendering the bitmapped text.
pack-priv static class	TextRenderer.TextData

Field Summary

Modifier and Type	Field and Description
private final boolean	antialiased
private boolean	beginRenderingDepthTestDisabled
private int	beginRenderingHeight
private int	beginRenderingWidth
private float	cachedA
private float	cachedB
private TextureRenderer	cachedBackingStore
private Color	cachedColor
private FontRenderContext	cachedFontRenderContext
private float	cachedG
private Graphics2D	cachedGraphics
private float	cachedR
private boolean	checkFor_isExtensionAvailable_GL_VERSION_1_5
private static final int	CYCLES_PER_FLUSH
private Frame	dbgFrame
private static final boolean	DEBUG
private boolean	debugged
private static final boolean	DISABLE_GLYPH_CACHE
private static final boolean	DRAW_BBOXES
private final Font	font
private boolean	haveCachedColor
private boolean	haveMaxSize
private boolean	inBeginEndPair
private boolean	isExtensionAvailable_GL_VERSION_1_5
private boolean	isOrthoMode
pack-priv static final int	kCoordsPerVertTex
pack-priv static final int	kCoordsPerVertVerts
pack-priv static final int	kQuadsPerBuffer
pack-priv static final int	kSize
pack-priv static final int	kSizeInBytes_OneVertices_TexData
pack-priv static final int	kSizeInBytes_OneVertices_VertexData
pack-priv static final int	kTotalBufferSizeBytesTex
pack-priv static final int	kTotalBufferSizeBytesVerts
pack-priv static final int	kTotalBufferSizeCoordsTex
pack-priv static final int	kTotalBufferSizeCoordsVerts
pack-priv static final int	kTotalBufferSizeVerts
pack-priv static final int	kVertsPerQuad
private static final float	MAX_VERTICAL_FRAGMENTATION
private final TextRenderer.GlyphProducer	mGlyphProducer
private boolean	mipmap
pack-priv TextRenderer.Pipelined_QuadRenderer	mPipelinedQuadRenderer
private boolean	needToResetColor
private int	numRenderCycles
private RectanglePacker	packer
private final TextRenderer.RenderDelegate	renderDelegate
private final char[]	singleUnicode
private boolean	smoothing
private final Map<String, Rect>	stringLocations
private final boolean	useFractionalMetrics
private boolean	useVertexArrays

Constructor Summary

Access	Constructor and Description
public	TextRenderer(final Font the font to render with font) Creates a new TextRenderer with the given font, using no antialiasing or fractional metrics, and the default RenderDelegate.
public	TextRenderer(final Font the font to render with font, final boolean whether to attempt use of automatic mipmap generation mipmap) Creates a new TextRenderer with the given font, using no antialiasing or fractional metrics, and the default RenderDelegate.
public	TextRenderer(final Font the font to render with font, final boolean whether to use antialiased fonts antialiased, final boolean whether to use fractional font metrics at the Java 2D level useFractionalMetrics) Creates a new TextRenderer with the given Font, specified font properties, and default RenderDelegate.
public	TextRenderer(final Font the font to render with font, final boolean whether to use antialiased fonts antialiased, final boolean whether to use fractional font metrics at the Java 2D level useFractionalMetrics, final TextRenderer.RenderDelegate the render delegate to use to draw the text's bitmap, or null to use the default one renderDelegate) Creates a new TextRenderer with the given Font, specified font properties, and given RenderDelegate.
public	TextRenderer(final Font the font to render with font, final boolean whether to use antialiased fonts antialiased, final boolean whether to use fractional font metrics at the Java 2D level useFractionalMetrics, TextRenderer.RenderDelegate the render delegate to use to draw the text's bitmap, or null to use the default one renderDelegate, final boolean whether to attempt use of automatic mipmap generation mipmap) Creates a new TextRenderer with the given Font, specified font properties, and given RenderDelegate.

Method Summary

Modifier and Type	Method and Description
public void	begin3DRendering() Begins rendering of 2D text in 3D with this `TextRenderer` into the current OpenGL drawable.
public void	beginRendering(final int the width of the current on-screen OpenGL drawable width, final int the height of the current on-screen OpenGL drawable height) Begins rendering with this `TextRenderer` into the current OpenGL drawable, pushing the projection and modelview matrices and some state bits and setting up a two-dimensional orthographic projection with (0, 0) as the lower-left coordinate and (width, height) as the upper-right coordinate.
public void	beginRendering(final int the width of the current on-screen OpenGL drawable width, final int the height of the current on-screen OpenGL drawable height, final boolean whether to disable the depth test disableDepthTest) Begins rendering with this `TextRenderer` into the current OpenGL drawable, pushing the projection and modelview matrices and some state bits and setting up a two-dimensional orthographic projection with (0, 0) as the lower-left coordinate and (width, height) as the upper-right coordinate.
private void	beginRendering(final boolean ortho, final int width, final int height, final boolean disableDepthTestForOrtho)
private void	clearUnusedEntries()
private void	debug(final GL gl)
public void	dispose() Disposes of all resources this TextRenderer is using.
public void	draw(final CharSequence the string to draw str, final int the x coordinate at which to draw x, final int the y coordinate at which to draw y) Draws the supplied CharSequence at the desired location using the renderer's current color.
public void	draw(final String str, final int x, final int y) Draws the supplied String at the desired location using the renderer's current color.
public void	draw3D(final CharSequence the string to draw str, final float the x coordinate at which to draw x, final float the y coordinate at which to draw y, final float the z coordinate at which to draw z, final float a uniform scale factor applied to the width and height of the drawn rectangle scaleFactor) Draws the supplied CharSequence at the desired 3D location using the renderer's current color.
public void	draw3D(final String str, final float x, final float y, final float z, final float scaleFactor) Draws the supplied String at the desired 3D location using the renderer's current color.
private void	draw3D_ROBUST(final CharSequence str, final float x, final float y, final float z, final float scaleFactor)
public void	end3DRendering() Ends a 3D render cycle with this `TextRenderer`.
public void	endRendering() Ends a render cycle with this `TextRenderer`.
private void	endRendering(final boolean ortho) emzic: here the call to glBindBuffer crashes on certain graphicscard/driver combinations this is why the ugly try-catch block has been added, which falls back to the old textrenderer
public void	flush() Causes the TextRenderer to flush any internal caches it may be maintaining and draw its rendering results to the screen.
private void	flushGlyphPipeline()
private TextureRenderer	getBackingStore()
public Rectangle2D	getBounds(final String str) Returns the bounding rectangle of the given String, assuming it was rendered at the origin.
public Rectangle2D	getBounds(final CharSequence str) Returns the bounding rectangle of the given CharSequence, assuming it was rendered at the origin.
public float	getCharWidth(final char inChar) Returns the pixel width of the given character.
public Font	getFont() Returns the Font this renderer is using.
public FontRenderContext	getFontRenderContext() Returns a FontRenderContext which can be used for external text-related size computations.
private Graphics2D	getGraphics2D()
public boolean	getSmoothing() Indicates whether smoothing is enabled in the backing TextureRenderer of this TextRenderer.
public final boolean	getUseVertexArrays() Indicates whether vertex arrays are being used internally for rendering, or whether text is rendered using the OpenGL immediate mode commands.
private void	internal_draw3D(final CharSequence str, float x, final float y, final float z, final float scaleFactor)
private final boolean	is15Available(final GL gl)
private Rectangle2D	normalize(final Rectangle2D src)
private static Rectangle2D	preNormalize(final Rectangle2D src)
public void	setColor(final Color the new color to use for rendering text color) Changes the current color of this TextRenderer to the supplied one.
public void	setColor(final float the red component of the new color r, final float the green component of the new color g, final float the blue component of the new color b, final float the alpha component of the new color, 0.0f = completely transparent, 1.0f = completely opaque a) Changes the current color of this TextRenderer to the supplied one, where each component ranges from 0.0f - 1.0f.
public void	setSmoothing(final boolean smoothing) Sets whether smoothing (i.e., GL_LINEAR filtering) is enabled in the backing TextureRenderer of this TextRenderer.
public void	setUseVertexArrays(final boolean useVertexArrays) Sets whether vertex arrays are being used internally for rendering, or whether text is rendered using the OpenGL immediate mode commands.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public Class TextRenderer

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary