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
.
TextRenderer
public TextRenderer(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)
.
font
- the font to render with
TextRenderer
public TextRenderer(Font font,
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)
.
font
- the font to render withmipmap
- whether to attempt use of automatic mipmap generation
TextRenderer
public TextRenderer(Font font,
boolean antialiased,
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)
.
font
- the font to render withantialiased
- whether to use antialiased fontsuseFractionalMetrics
- whether to use fractional font
metrics at the Java 2D level
TextRenderer
public TextRenderer(Font font,
boolean antialiased,
boolean useFractionalMetrics,
TextRenderer.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.
font
- the font to render withantialiased
- whether to use antialiased fontsuseFractionalMetrics
- whether to use fractional font
metrics at the Java 2D levelrenderDelegate
- the render delegate to use to draw the
text's bitmap, or null to use the default one
TextRenderer
public TextRenderer(Font font,
boolean antialiased,
boolean useFractionalMetrics,
TextRenderer.RenderDelegate renderDelegate,
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.
font
- the font to render withantialiased
- whether to use antialiased fontsuseFractionalMetrics
- whether to use fractional font
metrics at the Java 2D levelrenderDelegate
- the render delegate to use to draw the
text's bitmap, or null to use the default onemipmap
- whether to attempt use of automatic mipmap generation
begin3DRendering
public void 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
.
GLException
- If an OpenGL context is not current when this method is called
beginRendering
public void beginRendering(int width,
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).
width
- the width of the current on-screen OpenGL drawableheight
- the height of the current on-screen OpenGL drawable
GLException
- If an OpenGL context is not current when this method is called
beginRendering
public void beginRendering(int width,
int height,
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.
width
- the width of the current on-screen OpenGL drawableheight
- the height of the current on-screen OpenGL drawabledisableDepthTest
- whether to disable the depth test
GLException
- If an OpenGL context is not current when this method is called
dispose
public void dispose()
throws GLException
Disposes of all resources this TextRenderer is using. It is not
valid to use the TextRenderer after this method is called.
GLException
- If an OpenGL context is not current when this method is called
draw
public void draw(CharSequence str,
int x,
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.
str
- the string to drawx
- the x coordinate at which to drawy
- the y coordinate at which to draw
GLException
- If an OpenGL context is not current when this method is called
draw
public void draw(String str,
int x,
int y)
throws GLException
draw3D
public void draw3D(CharSequence str,
float x,
float y,
float z,
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.
str
- the string to drawx
- the x coordinate at which to drawy
- the y coordinate at which to drawz
- the z coordinate at which to drawscaleFactor
- a uniform scale factor applied to the width and height of the drawn rectangle
draw3D
public void draw3D(String str,
float x,
float y,
float z,
float scaleFactor)
end3DRendering
public void end3DRendering()
throws GLException
GLException
- If an OpenGL context is not current when this method is called
endRendering
public void 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
.
GLException
- If an OpenGL context is not current when this method is called
flush
public void 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().
getBounds
public Rectangle2D getBounds(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,
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.
getBounds
public Rectangle2D getBounds(String str)
Returns the bounding rectangle of the given String, assuming it
was rendered at the origin. See
getBounds(CharSequence)
.
getCharWidth
public float getCharWidth(char inChar)
Returns the pixel width of the given character.
getFont
public Font getFont()
Returns the Font this renderer is using.
getFontRenderContext
public FontRenderContext 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.
getSmoothing
public boolean 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.
getUseVertexArrays
public boolean 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.
setColor
public void setColor(Color color)
throws GLException
Changes the current color of this TextRenderer to the supplied
one. The default color is opaque white.
color
- the new color to use for rendering text
GLException
- If an OpenGL context is not current when this method is called
setColor
public void setColor(float r,
float g,
float b,
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.
r
- the red component of the new colorg
- the green component of the new colorb
- the blue component of the new colora
- the alpha component of the new color, 0.0f = completely
transparent, 1.0f = completely opaque
GLException
- If an OpenGL context is not current when this method is called
setSmoothing
public void setSmoothing(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.
setUseVertexArrays
public void setUseVertexArrays(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.