JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.opengl.util.awt.TextRenderer Class Reference

Renders bitmapped Java 2D text into an OpenGL window with high performance, full Unicode support, and a simple API. More...

Collaboration diagram for com.jogamp.opengl.util.awt.TextRenderer:

Classes

class  DebugListener
 
class  DefaultRenderDelegate
 
class  Glyph
 A Glyph represents either a single unicode glyph or a substring of characters to be drawn.
 
class  GlyphProducer
 
class  Manager
 
class  Pipelined_QuadRenderer
 
interface  RenderDelegate
 Class supporting more full control over the process of rendering the bitmapped text. More...
 
class  TextData
 

Public Member Functions

 TextRenderer (final Font font)
 Creates a new TextRenderer with the given font, using no antialiasing or fractional metrics, and the default RenderDelegate. More...
 
 TextRenderer (final Font font, final boolean mipmap)
 Creates a new TextRenderer with the given font, using no antialiasing or fractional metrics, and the default RenderDelegate. More...
 
 TextRenderer (final Font font, final boolean antialiased, final boolean useFractionalMetrics)
 Creates a new TextRenderer with the given Font, specified font properties, and default RenderDelegate. More...
 
 TextRenderer (final Font font, final boolean antialiased, final boolean useFractionalMetrics, final RenderDelegate renderDelegate)
 Creates a new TextRenderer with the given Font, specified font properties, and given RenderDelegate. More...
 
 TextRenderer (final Font font, final boolean antialiased, final boolean useFractionalMetrics, RenderDelegate renderDelegate, final boolean mipmap)
 Creates a new TextRenderer with the given Font, specified font properties, and given RenderDelegate. More...
 
Rectangle2D getBounds (final String str)
 Returns the bounding rectangle of the given String, assuming it was rendered at the origin. More...
 
Rectangle2D getBounds (final CharSequence str)
 Returns the bounding rectangle of the given CharSequence, assuming it was rendered at the origin. More...
 
Font getFont ()
 Returns the Font this renderer is using. More...
 
FontRenderContext getFontRenderContext ()
 Returns a FontRenderContext which can be used for external text-related size computations. More...
 
void beginRendering (final int width, final int height) throws GLException
 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. More...
 
void beginRendering (final int width, final int height, final boolean disableDepthTest) throws GLException
 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. More...
 
void begin3DRendering () throws GLException
 Begins rendering of 2D text in 3D with this TextRenderer into the current OpenGL drawable. More...
 
void setColor (final Color color) throws GLException
 Changes the current color of this TextRenderer to the supplied one. More...
 
void setColor (final float r, final float g, final float b, final float a) throws GLException
 Changes the current color of this TextRenderer to the supplied one, where each component ranges from 0.0f - 1.0f. More...
 
void draw (final CharSequence str, final int x, final int y) throws GLException
 Draws the supplied CharSequence at the desired location using the renderer's current color. More...
 
void draw (final String str, final int x, final int y) throws GLException
 Draws the supplied String at the desired location using the renderer's current color. More...
 
void draw3D (final CharSequence str, final float x, final float y, final float z, final float scaleFactor)
 Draws the supplied CharSequence at the desired 3D location using the renderer's current color. More...
 
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. More...
 
float getCharWidth (final char inChar)
 Returns the pixel width of the given character. More...
 
void flush ()
 Causes the TextRenderer to flush any internal caches it may be maintaining and draw its rendering results to the screen. More...
 
void endRendering () throws GLException
 Ends a render cycle with this TextRenderer. More...
 
void end3DRendering () throws GLException
 Ends a 3D render cycle with this TextRenderer. More...
 
void dispose () throws GLException
 Disposes of all resources this TextRenderer is using. More...
 
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. More...
 
final boolean getUseVertexArrays ()
 Indicates whether vertex arrays are being used internally for rendering, or whether text is rendered using the OpenGL immediate mode commands. More...
 
void setSmoothing (final boolean smoothing)
 Sets whether smoothing (i.e., GL_LINEAR filtering) is enabled in the backing TextureRenderer of this TextRenderer. More...
 
boolean getSmoothing ()
 Indicates whether smoothing is enabled in the backing TextureRenderer of this TextRenderer. More...
 

Detailed Description

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 "<code>TextRenderer renderer;</code>" 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.

Author
John Burkey
Kenneth Russell

Definition at line 130 of file TextRenderer.java.

Constructor & Destructor Documentation

◆ TextRenderer() [1/5]

com.jogamp.opengl.util.awt.TextRenderer.TextRenderer ( final Font  font)

Creates a new TextRenderer with the given font, using no antialiasing or fractional metrics, and the default RenderDelegate.

Equivalent to TextRenderer(font, false, false).

Parameters
fontthe font to render with

Definition at line 221 of file TextRenderer.java.

◆ TextRenderer() [2/5]

com.jogamp.opengl.util.awt.TextRenderer.TextRenderer ( final Font  font,
final boolean  mipmap 
)

Creates a new TextRenderer with the given font, using no antialiasing or fractional metrics, and the default RenderDelegate.

If mipmap is true, attempts to use OpenGL's automatic mipmap generation for better smoothing when rendering the TextureRenderer's contents at a distance. Equivalent to TextRenderer(font, false, false).

Parameters
fontthe font to render with
mipmapwhether to attempt use of automatic mipmap generation

Definition at line 235 of file TextRenderer.java.

◆ TextRenderer() [3/5]

com.jogamp.opengl.util.awt.TextRenderer.TextRenderer ( final Font  font,
final boolean  antialiased,
final boolean  useFractionalMetrics 
)

Creates a new TextRenderer with the given Font, specified font properties, and default RenderDelegate.

The antialiased and useFractionalMetrics flags provide control over the same properties at the Java 2D level. No mipmap support is requested. Equivalent to TextRenderer(font, antialiased, useFractionalMetrics, null).

Parameters
fontthe font to render with
antialiasedwhether to use antialiased fonts
useFractionalMetricswhether to use fractional font metrics at the Java 2D level

Definition at line 252 of file TextRenderer.java.

◆ TextRenderer() [4/5]

com.jogamp.opengl.util.awt.TextRenderer.TextRenderer ( final Font  font,
final boolean  antialiased,
final boolean  useFractionalMetrics,
final RenderDelegate  renderDelegate 
)

Creates a new TextRenderer with the given Font, specified font properties, and given RenderDelegate.

The antialiased and useFractionalMetrics flags provide control over the same properties at the Java 2D level. The renderDelegate provides more control over the text rendered. No mipmap support is requested.

Parameters
fontthe font to render with
antialiasedwhether to use antialiased fonts
useFractionalMetricswhether to use fractional font metrics at the Java 2D level
renderDelegatethe render delegate to use to draw the text's bitmap, or null to use the default one

Definition at line 271 of file TextRenderer.java.

◆ TextRenderer() [5/5]

com.jogamp.opengl.util.awt.TextRenderer.TextRenderer ( final Font  font,
final boolean  antialiased,
final boolean  useFractionalMetrics,
RenderDelegate  renderDelegate,
final boolean  mipmap 
)

Creates a new TextRenderer with the given Font, specified font properties, and given RenderDelegate.

The antialiased and useFractionalMetrics flags provide control over the same properties at the Java 2D level. The renderDelegate provides more control over the text rendered. If mipmap is true, attempts to use OpenGL's automatic mipmap generation for better smoothing when rendering the TextureRenderer's contents at a distance.

Parameters
fontthe font to render with
antialiasedwhether to use antialiased fonts
useFractionalMetricswhether to use fractional font metrics at the Java 2D level
renderDelegatethe render delegate to use to draw the text's bitmap, or null to use the default one
mipmapwhether to attempt use of automatic mipmap generation

Definition at line 293 of file TextRenderer.java.

Here is the call graph for this function:

Member Function Documentation

◆ begin3DRendering()

void com.jogamp.opengl.util.awt.TextRenderer.begin3DRendering ( ) throws GLException

Begins rendering of 2D text in 3D with this TextRenderer into the current OpenGL drawable.

Assumes the end user is responsible for setting up the modelview and projection matrices, and will render text using the draw3D method. This method pushes some OpenGL state bits, binds and enables the internal OpenGL texture object, sets the texture environment mode to GL_MODULATE, and changes the current color to the last color set with this TextRenderer via setColor.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 436 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ beginRendering() [1/2]

void com.jogamp.opengl.util.awt.TextRenderer.beginRendering ( final int  width,
final int  height 
) throws GLException

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.

Binds and enables the internal OpenGL texture object, sets the texture environment mode to GL_MODULATE, and changes the current color to the last color set with this TextRenderer via setColor. This method disables the depth test and is equivalent to beginRendering(width, height, true).

Parameters
widththe width of the current on-screen OpenGL drawable
heightthe height of the current on-screen OpenGL drawable
Exceptions
com.jogamp.opengl.GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 399 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ beginRendering() [2/2]

void com.jogamp.opengl.util.awt.TextRenderer.beginRendering ( final int  width,
final int  height,
final boolean  disableDepthTest 
) throws GLException

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.

Binds and enables the internal OpenGL texture object, sets the texture environment mode to GL_MODULATE, and changes the current color to the last color set with this TextRenderer via setColor. Disables the depth test if the disableDepthTest argument is true.

Parameters
widththe width of the current on-screen OpenGL drawable
heightthe height of the current on-screen OpenGL drawable
disableDepthTestwhether to disable the depth test
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 419 of file TextRenderer.java.

Here is the call graph for this function:

◆ dispose()

void com.jogamp.opengl.util.awt.TextRenderer.dispose ( ) throws GLException

Disposes of all resources this TextRenderer is using.

It is not valid to use the TextRenderer after this method is called.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 580 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ draw() [1/2]

void com.jogamp.opengl.util.awt.TextRenderer.draw ( final CharSequence  str,
final int  x,
final int  y 
) throws GLException

Draws the supplied CharSequence at the desired location using the renderer's current color.

The baseline of the leftmost character is at position (x, y) specified in OpenGL coordinates, where the origin is at the lower-left of the drawable and the Y coordinate increases in the upward direction.

Parameters
strthe string to draw
xthe x coordinate at which to draw
ythe y coordinate at which to draw
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 504 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ draw() [2/2]

void com.jogamp.opengl.util.awt.TextRenderer.draw ( final String  str,
final int  x,
final int  y 
) throws GLException

Draws the supplied String at the desired location using the renderer's current color.

See draw(CharSequence, int, int).

Definition at line 511 of file TextRenderer.java.

Here is the call graph for this function:

◆ draw3D() [1/2]

void com.jogamp.opengl.util.awt.TextRenderer.draw3D ( final CharSequence  str,
final float  x,
final float  y,
final float  z,
final float  scaleFactor 
)

Draws the supplied CharSequence at the desired 3D location using the renderer's current color.

The baseline of the leftmost character is placed at position (x, y, z) in the current coordinate system.

Parameters
strthe string to draw
xthe x coordinate at which to draw
ythe y coordinate at which to draw
zthe z coordinate at which to draw
scaleFactora uniform scale factor applied to the width and height of the drawn rectangle
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 527 of file TextRenderer.java.

Here is the caller graph for this function:

◆ draw3D() [2/2]

void com.jogamp.opengl.util.awt.TextRenderer.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.

See draw3D(CharSequence, float, float, float, float).

Definition at line 536 of file TextRenderer.java.

◆ end3DRendering()

void com.jogamp.opengl.util.awt.TextRenderer.end3DRendering ( ) throws GLException

Ends a 3D render cycle with this TextRenderer.

Restores several OpenGL state bits. Should be paired with begin3DRendering.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 571 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ endRendering()

void com.jogamp.opengl.util.awt.TextRenderer.endRendering ( ) throws GLException

Ends a render cycle with this TextRenderer.

Restores the projection and modelview matrices as well as several OpenGL state bits. Should be paired with beginRendering.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 561 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ flush()

void com.jogamp.opengl.util.awt.TextRenderer.flush ( )

Causes the TextRenderer to flush any internal caches it may be maintaining and draw its rendering results to the screen.

This should be called after each call to draw() if you are setting OpenGL state such as the modelview matrix between calls to draw().

Definition at line 550 of file TextRenderer.java.

◆ getBounds() [1/2]

Rectangle2D com.jogamp.opengl.util.awt.TextRenderer.getBounds ( final CharSequence  str)

Returns the bounding rectangle of the given CharSequence, assuming it was rendered at the origin.

The coordinate system of the returned rectangle is Java 2D's, with increasing Y coordinates in the downward direction. The relative coordinate (0, 0) in the returned rectangle corresponds to the baseline of the leftmost character of the rendered string, in similar fashion to the results returned by, for example, java.awt.font.GlyphVector#getVisualBounds. Most applications will use only the width and height of the returned Rectangle for the purposes of centering or justifying the String. It is not specified which Java 2D bounds (getVisualBounds, getPixelBounds, etc.) the returned bounds correspond to, although every effort is made to ensure an accurate bound.

Definition at line 347 of file TextRenderer.java.

Here is the call graph for this function:

◆ getBounds() [2/2]

Rectangle2D com.jogamp.opengl.util.awt.TextRenderer.getBounds ( final String  str)

Returns the bounding rectangle of the given String, assuming it was rendered at the origin.

See getBounds(CharSequence).

Definition at line 328 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getCharWidth()

float com.jogamp.opengl.util.awt.TextRenderer.getCharWidth ( final char  inChar)

Returns the pixel width of the given character.

Definition at line 541 of file TextRenderer.java.

◆ getFont()

Font com.jogamp.opengl.util.awt.TextRenderer.getFont ( )

Returns the Font this renderer is using.

Definition at line 366 of file TextRenderer.java.

◆ getFontRenderContext()

FontRenderContext com.jogamp.opengl.util.awt.TextRenderer.getFontRenderContext ( )

Returns a FontRenderContext which can be used for external text-related size computations.

This object should be considered transient and may become invalidated between beginRendering / endRendering pairs.

Definition at line 375 of file TextRenderer.java.

Here is the caller graph for this function:

◆ getSmoothing()

boolean com.jogamp.opengl.util.awt.TextRenderer.getSmoothing ( )

Indicates whether smoothing is enabled in the backing TextureRenderer of this TextRenderer.

A few graphics cards do not behave well when this is enabled, resulting in fuzzy text. Defaults to true.

Definition at line 2034 of file TextRenderer.java.

◆ getUseVertexArrays()

final boolean com.jogamp.opengl.util.awt.TextRenderer.getUseVertexArrays ( )

Indicates whether vertex arrays are being used internally for rendering, or whether text is rendered using the OpenGL immediate mode commands.

Defaults to true.

Definition at line 2013 of file TextRenderer.java.

Here is the caller graph for this function:

◆ setColor() [1/2]

void com.jogamp.opengl.util.awt.TextRenderer.setColor ( final Color  color) throws GLException

Changes the current color of this TextRenderer to the supplied one.

The default color is opaque white.

Parameters
colorthe new color to use for rendering text
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 446 of file TextRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setColor() [2/2]

void com.jogamp.opengl.util.awt.TextRenderer.setColor ( final float  r,
final float  g,
final float  b,
final float  a 
) throws GLException

Changes the current color of this TextRenderer to the supplied one, where each component ranges from 0.0f - 1.0f.

The alpha component, if used, does not need to be premultiplied into the color channels as described in the documentation for Texture, although premultiplied colors are used internally. The default color is opaque white.

Parameters
rthe red component of the new color
gthe green component of the new color
bthe blue component of the new color
athe alpha component of the new color, 0.0f = completely transparent, 1.0f = completely opaque
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 474 of file TextRenderer.java.

Here is the call graph for this function:

◆ setSmoothing()

void com.jogamp.opengl.util.awt.TextRenderer.setSmoothing ( final boolean  smoothing)

Sets whether smoothing (i.e., GL_LINEAR filtering) is enabled in the backing TextureRenderer of this TextRenderer.

A few graphics cards do not behave well when this is enabled, resulting in fuzzy text. Defaults to true.

Definition at line 2023 of file TextRenderer.java.

Here is the call graph for this function:

◆ setUseVertexArrays()

void com.jogamp.opengl.util.awt.TextRenderer.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.

This is provided as a concession for certain graphics cards which have poor vertex array performance. Defaults to true.

Definition at line 2004 of file TextRenderer.java.

Here is the caller graph for this function:

The documentation for this class was generated from the following file: