com.luciad.view.lightspeed.util.opengl.texturefont

LuciadFusionClass TLspTextureFont

java.lang.Object

com.luciad.view.lightspeed.services.glcache.ALspGLResource

com.luciad.view.lightspeed.util.opengl.texturefont.TLspTextureFont

public class TLspTextureFont
extends ALspGLResource

Utility class for drawing text to a ILcdGLDrawable using a "texture font". A texture font is an image that contains all ASCII characters, allowing text to be drawn as a strip of texture-mapped quadrilaterals. This typically offers significantly better performance than other text rendering approaches.

Since:

2012.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TLspTextureFont.GlyphInfo This class contains information about a glyph.

Constructor Summary

Constructors

Constructor and Description
TLspTextureFont(Font aFont) Creates a painter for the specified font.
TLspTextureFont(Font aFont, Color aTextColor) Creates a painter for the specified font and color.
TLspTextureFont(Font aFont, Color aTextColor, Color aHaloColor) Creates a painter for the specified font and color, and with a halo in the specified color.

Method Summary

Modifier and Type	Method and Description
void	bind(ILcdGLDrawable aGLDrawable) Binds this GL resource for use with the given ILcdGLDrawable.
void	destroy(ILcdGLDrawable aGLDrawable) Destroys the OpenGL resource so that it becomes no longer available nor valid to use.
void	drawString(ILcdGLDrawable aGLDrawable, double aX, double aY, double aZ, double aSize, String aString) Draws a string at the specified location and with the given size.
void	drawString(ILcdGLDrawable aGLDrawable, double aX, double aY, double aZ, String aString) Draws a string at the specified location with the font's native size.
void	drawString(ILcdGLDrawable aGLDrawable, ILcdPoint aLocation, ILcdBounds aBounds, double aSize, String aString, TLspContext aContext) Draws a string at the specified location and with the given size.
void	drawString(ILcdGLDrawable aGLDrawable, ILcdPoint aLocation, String aString) Draws a string at the specified location with the font's native size.
void	drawStrings(ILcdGLDrawable aGLDrawable, List<ILcdPoint> aPositions, List<ILcdBounds> aBounds, double aSize, List<String> aStrings, TLspContext aContext)
Color	getBackgroundColor() Returns the color used for filling the background of the rendered text.
long	getBytes() Gets the estimated number of bytes this resource occupies in GPU memory.
Font	getFont() Returns the current font.
Color	getFrameColor() Returns the color used for a frame around the rendered text
TLspTextureFont.GlyphInfo	getGlyphInfo(char aChar, double aSize)
Color	getHaloColor() Returns the current halo color.
int	getHaloThickness() Returns the thickness of the halo around the rendered text.
int	getNativeSize() Returns the height of a single character glyph in the texture font.
int	getPadding() Returns the number of blank pixels added around each character glyph in the texture font.
double	getStringWidth(String aString) Returns the width the specified string would have if it were to be drawn with the font's native size.
double	getStringWidth(String aString, double aSize) Returns the width the specified string would have if it were to be drawn with the given size.
Color	getTextColor() Returns the current text color.
boolean	isBackgroundEnabled() Returns whether or not the background of the text is filled with the background color.
boolean	isFrameEnabled() Returns whether or not a frame is drawn around the label.
boolean	isHaloEnabled() Returns whether or not the halo effect is on.
void	setBackgroundColor(Color aBackgroundColor) Sets the color used for filling the background of the rendered text to the given color.
void	setBackgroundEnabled(boolean aBackgroundEnabled) Sets whether or not the background of the text is filled with the background color.
void	setFont(Font aFont) Sets the font to be used for text rendering.
void	setFrameColor(Color aFrameColor) Sets the color used for a frame around the rendered text
void	setFrameEnabled(boolean aFrameEnabled) Toggles the use of a frame around the rendered text.
void	setHaloColor(Color aHaloColor) Sets the color to be used for halos around rendered text.
void	setHaloEnabled(boolean aHaloEnabled) Toggles the use of a halo effect around rendered text.
void	setHaloThickness(int aHaloThickness) Sets the thickness of the halo around the rendered text.
void	setTextColor(Color aTextColor) Sets the color to be used for text rendering.
void	unbind(ILcdGLDrawable aGLDrawable) Unbinds this GL resource from the given ILcdGLDrawable.

Methods inherited from class com.luciad.view.lightspeed.services.glcache.ALspGLResource

getSourceString, isBound, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TLspTextureFont

public TLspTextureFont(Font aFont)

Creates a painter for the specified font. By default, the font color is white and the halo effect is off.

Parameters:

aFont - an AWT font

TLspTextureFont

public TLspTextureFont(Font aFont,
                       Color aTextColor)

Creates a painter for the specified font and color. By default, the halo effect is off.

Parameters:

aFont - an AWT font

aTextColor - the font color

TLspTextureFont

public TLspTextureFont(Font aFont,
                       Color aTextColor,
                       Color aHaloColor)

Creates a painter for the specified font and color, and with a halo in the specified color.

Parameters:

aFont - an AWT font

aTextColor - the font color

aHaloColor - the halo color

Method Detail

getFont

public Font getFont()

Returns the current font.

Returns:

the current font

See Also:

setFont(java.awt.Font)

setFont

public void setFont(Font aFont)

Sets the font to be used for text rendering. If this property is changed, a new texture font image will be generated the next time the painter is used, which is a costly operation. Applications should therefore avoid calling this method very frequently.

Parameters:

aFont - the new font to be used

getTextColor

public Color getTextColor()

Returns the current text color.

Returns:

the current text color

See Also:

setTextColor(java.awt.Color)

setTextColor

public void setTextColor(Color aTextColor)

Sets the color to be used for text rendering. If this property is changed, a new texture font image will be generated the next time the painter is used, which is a costly operation. Applications should therefore avoid calling this method very frequently.

Parameters:

aTextColor - the new text color to be used

getHaloColor

public Color getHaloColor()

Returns the current halo color.

Returns:

the current halo color

See Also:

setHaloColor(java.awt.Color)

setHaloColor

public void setHaloColor(Color aHaloColor)

Sets the color to be used for halos around rendered text. If this property is changed, a new texture font image will be generated the next time the painter is used, which is a costly operation. Applications should therefore avoid calling this method very frequently.

Parameters:

aHaloColor - the new halo color to be used

isHaloEnabled

public boolean isHaloEnabled()

Returns whether or not the halo effect is on.

Returns:

whether or not the halo effect is on

See Also:

setHaloEnabled(boolean)

setHaloEnabled

public void setHaloEnabled(boolean aHaloEnabled)

Toggles the use of a halo effect around rendered text. A halo is an outline of constant width around the text, which ensures that the text is clearly visible on all backgrounds. If this property is changed, a new texture font image will be generated the next time the painter is used, which is a costly operation. Applications should therefore avoid calling this method very frequently.

Parameters:

aHaloEnabled - specifies whether halos should be enabled or disabled

getHaloThickness

public int getHaloThickness()

Returns the thickness of the halo around the rendered text.

Returns:

the thickness of the halo around the rendered text.

setHaloThickness

public void setHaloThickness(int aHaloThickness)

Sets the thickness of the halo around the rendered text. If this property is changed, a new texture font image will be generated the next time the painter is used, which is a costly operation. Applications should therefore avoid calling this method very frequently.

Parameters:

aHaloThickness - the thickness of the halo around the rendered text.

isFrameEnabled

public boolean isFrameEnabled()

Returns whether or not a frame is drawn around the label.

Returns:

whether or not a frame is drawn around the label

setFrameEnabled

public void setFrameEnabled(boolean aFrameEnabled)

Toggles the use of a frame around the rendered text.

Parameters:

aFrameEnabled - a flag indicating whether a frame should be drawn or not

getFrameColor

public Color getFrameColor()

Returns the color used for a frame around the rendered text

Returns:

the color used for a frame around the rendered text

setFrameColor

public void setFrameColor(Color aFrameColor)

Sets the color used for a frame around the rendered text

Parameters:

aFrameColor - the new frame color

getBackgroundColor

public Color getBackgroundColor()

Returns the color used for filling the background of the rendered text.

Returns:

the color used for filling the background of the rendered text

setBackgroundColor

public void setBackgroundColor(Color aBackgroundColor)

Sets the color used for filling the background of the rendered text to the given color.

Parameters:

aBackgroundColor - the new background color

isBackgroundEnabled

public boolean isBackgroundEnabled()

Returns whether or not the background of the text is filled with the background color.

Returns:

whether or not the background of the text is filled with the background color

setBackgroundEnabled

public void setBackgroundEnabled(boolean aBackgroundEnabled)

Sets whether or not the background of the text is filled with the background color.

Parameters:

aBackgroundEnabled - flag indicating whether the background is filled or not

drawString

public void drawString(ILcdGLDrawable aGLDrawable,
                       ILcdPoint aLocation,
                       ILcdBounds aBounds,
                       double aSize,
                       String aString,
                       TLspContext aContext)

Draws a string at the specified location and with the given size.

Parameters:

aGLDrawable - the ILcdGLDrawable to draw the string into

aLocation - the location at which the string should be drawn

aBounds - the bounds of the text in view coordinates (used for drawing the frame around the text)

aSize - the size with which to draw the string, i.e. the height of a line of text

aString - the string to be drawn

drawString

public void drawString(ILcdGLDrawable aGLDrawable,
                       double aX,
                       double aY,
                       double aZ,
                       double aSize,
                       String aString)

Draws a string at the specified location and with the given size. The string is drawn as a strip of quadrilaterals in the XY plane; the coordinates aX, aY and aZ specify the lower left corner of the string.

Other than enabling and binding the font texture, this method does not change any OpenGL state. It is up to the application to set up any required transformations before calling this method (e.g. to ensure that the string is drawn aligned to the screen). In other words, the coordinate reference in which aX, aY, aZ and aSize are expressed, is determined by the current OpenGL state at the time this method is called.

Parameters:

aGLDrawable - the ILcdGLDrawable to draw the string into

aX - the X coordinate of the string's location

aY - the Y coordinate of the string's location

aZ - the Z coordinate of the string's location

aSize - the size with which to draw the string, i.e. the height of a line of text

aString - the string to be drawn

drawStrings

public void drawStrings(ILcdGLDrawable aGLDrawable,
                        List<ILcdPoint> aPositions,
                        List<ILcdBounds> aBounds,
                        double aSize,
                        List<String> aStrings,
                        TLspContext aContext)

bind

public void bind(ILcdGLDrawable aGLDrawable)

Description copied from class: ALspGLResource

Binds this GL resource for use with the given ILcdGLDrawable. Implementations should override this method to perform the appropriate OpenGL call, e.g. glBindTexture(). Inheriting classes must also always invoke super.bind(), as this is required for the correct behavior of ALspGLResource.isBound().

If this resource was already destroyed and the destroy implementation calls super.destroy, a runtime exception will be thrown when calling this method.

Overrides:

bind in class ALspGLResource

Parameters:

aGLDrawable - the GL drawable in which this resource is to be bound

unbind

public void unbind(ILcdGLDrawable aGLDrawable)

Description copied from class: ALspGLResource

Unbinds this GL resource from the given ILcdGLDrawable. Implementations should override this method to perform whatever OpenGL calls are needed to undo the effects of ALspGLResource.bind(com.luciad.view.opengl.binding.ILcdGLDrawable). Inheriting classes must also always invoke super.unbind(), as this is required for the correct behavior of ALspGLResource.isBound().

If this resource was already destroyed and the destroy implementation calls super.destroy, a runtime exception will be thrown when calling this method.

Overrides:

unbind in class ALspGLResource

Parameters:

aGLDrawable - the drawable from which the GL resource should be unbound

getStringWidth

public double getStringWidth(String aString,
                             double aSize)

Returns the width the specified string would have if it were to be drawn with the given size.

Parameters:

aString - the string whose width should be determined

aSize - the text size based on which the string width should be computed

Returns:

the width of the string if it were drawn with the given size

See Also:

drawString(ILcdGLDrawable, double, double, double, double, String)

drawString

public void drawString(ILcdGLDrawable aGLDrawable,
                       ILcdPoint aLocation,
                       String aString)

Draws a string at the specified location with the font's native size.

Parameters:

aGLDrawable - the ILcdGLDrawable to draw the string into

aLocation - the location at which the string should be drawn

aString - the string to be drawn

See Also:

drawString(ILcdGLDrawable, double, double, double, double, String), getNativeSize()

drawString

public void drawString(ILcdGLDrawable aGLDrawable,
                       double aX,
                       double aY,
                       double aZ,
                       String aString)

Draws a string at the specified location with the font's native size.

Parameters:

aGLDrawable - the ILcdGLDrawable to draw the string into

aX - the X coordinate of the string's location

aY - the Y coordinate of the string's location

aZ - the Z coordinate of the string's location

aString - the string to be drawn

See Also:

drawString(ILcdGLDrawable, double, double, double, double, String), getNativeSize()

getNativeSize

public int getNativeSize()

Returns the height of a single character glyph in the texture font. When drawing text in view coordinates, this value can be used as the size parameter in calls to drawString(com.luciad.view.opengl.binding.ILcdGLDrawable, com.luciad.shape.ILcdPoint, com.luciad.shape.ILcdBounds, double, String, com.luciad.view.lightspeed.TLspContext) to draw characters without scaling. Since scaling could introduce some artifacts due to texture filtering, drawing text at its native size typically improves the text's visual quality.

Returns:

the height of a single character glyph in the texture font

getStringWidth

public double getStringWidth(String aString)

Returns the width the specified string would have if it were to be drawn with the font's native size.

Parameters:

aString - the string whose width should be determined

Returns:

the width of the string if it were drawn with the font's native size

See Also:

getStringWidth(String, double), getNativeSize()

getPadding

public int getPadding()

Returns the number of blank pixels added around each character glyph in the texture font. Empty borders are added on all four sides of each glyph so that texture filtering would not cause glyphs to "bleed" into their neighbours when the glyphs are drawn strongly minified.

The drawString() method already takes this value into account when positioning successive characters in a string, but applications may, for instance, also want to use this method to determine the appropriate amount of spacing between multiple lines of text.

Returns:

the amount of padding around each character glyph

destroy

public void destroy(ILcdGLDrawable aGLDrawable)

Description copied from class: ALspGLResource

Destroys the OpenGL resource so that it becomes no longer available nor valid to use.

You should never call this yourself. The GL resource cache will automatically remove old resources. Alternatively, if you don't need the resource anymore, manually remove it from the GL resource cache.

Extensions of this class should preferably call super.destroy. Doing so will add extra error checking in the bind and unbind methods, to make sure that no destroyed resources are used during painting (this may lead to native crashes).

Overrides:

destroy in class ALspGLResource

Parameters:

aGLDrawable - the drawable this resource is used for

getBytes

public long getBytes()

Description copied from class: ALspGLResource

Gets the estimated number of bytes this resource occupies in GPU memory.

Specified by:

getBytes in class ALspGLResource

Returns:

the estimated number of bytes

getGlyphInfo

public TLspTextureFont.GlyphInfo getGlyphInfo(char aChar,
                                              double aSize)