org.newdawn.slick
Class UnicodeFont

java.lang.Object
  org.newdawn.slick.UnicodeFont

All Implemented Interfaces:

Font

public class UnicodeFont
extends java.lang.Object
implements Font

A Slick bitmap font that can display unicode glyphs from a TrueTypeFont. For efficiency, glyphs are packed on to textures. Glyphs can be loaded to the textures on the fly, when they are first needed for display. However, it is best to load the glyphs that are known to be needed at startup.

Author:

Nathan Sweet

Nested Class Summary

static class

UnicodeFont.DisplayList A simple descriptor for display lists cached within this font

Constructor Summary

UnicodeFont(java.awt.Font font)
Creates a new UnicodeFont.

UnicodeFont(java.awt.Font font, HieroSettings settings)
Creates a new UnicodeFont.

UnicodeFont(java.awt.Font font, int size, boolean bold, boolean italic)
Creates a new UnicodeFont.

UnicodeFont(java.awt.Font font, java.lang.String hieroFileRef)
Creates a new UnicodeFont.

UnicodeFont(java.lang.String ttfFileRef, HieroSettings settings)
Create a new unicode font based on a TTF file and a set of heiro configuration

UnicodeFont(java.lang.String ttfFileRef, int size, boolean bold, boolean italic)
Create a new unicode font based on a TTF file alone

UnicodeFont(java.lang.String ttfFileRef, java.lang.String hieroFileRef)
Create a new unicode font based on a TTF file

Method Summary

void	addAsciiGlyphs() Queues the glyphs in the ASCII character set (codepoints 32 through 255) to be loaded.
void	addGlyphs(int startCodePoint, int endCodePoint) Queues the glyphs in the specified codepoint range (inclusive) to be loaded.
void	addGlyphs(java.lang.String text) Queues the glyphs in the specified text to be loaded.
void	addNeheGlyphs() Queues the glyphs in the NEHE character set (codepoints 32 through 128) to be loaded.
void	clearGlyphs() Clears all loaded and queued glyphs.
void	destroy() Releases all resources used by this UnicodeFont.
UnicodeFont.DisplayList	drawDisplayList(float x, float y, java.lang.String text, Color color, int startIndex, int endIndex) Identical to drawString(float, float, String, Color, int, int) but returns a DisplayList which provides access to the width and height of the text drawn.
void	drawString(float x, float y, java.lang.String text) Draw a string to the screen
void	drawString(float x, float y, java.lang.String text, Color col) Draw a string to the screen
void	drawString(float x, float y, java.lang.String text, Color color, int startIndex, int endIndex) Draw part of a string to the screen.
int	getAscent() Gets the distance from the baseline to the y drawing location.
int	getDescent() Gets the distance from the baseline to the bottom of most alphanumeric characters with descenders.
java.util.List	getEffects() Returns a list of Effects that will be applied to the glyphs.
java.awt.Font	getFont() Returns the TrueTypeFont for this UnicodeFont.
java.lang.String	getFontFile() Returns the path to the TTF file for this UnicodeFont, or null.
int	getGlyphPageHeight() Returns the height of the backing textures.
java.util.List	getGlyphPages() Returns the GlyphPages for this UnicodeFont.
int	getGlyphPageWidth() Returns the width of the backing textures.
int	getHeight(java.lang.String text) Get the height of the given string
int	getLeading() Gets the extra distance between the descent of one line of text to the ascent of the next.
int	getLineHeight() Returns the distance from one line of text to the next.
int	getPaddingAdvanceX() Gets the additional amount to offset glyphs on the x axis.
int	getPaddingAdvanceY() Gets the additional amount to offset a line of text on the y axis.
int	getPaddingBottom() Returns the padding below a glyph on the GlyphPage to allow for effects to be drawn.
int	getPaddingLeft() Returns the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.
int	getPaddingRight() Returns the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.
int	getPaddingTop() Returns the padding above a glyph on the GlyphPage to allow for effects to be drawn.
int	getSpaceWidth() Returns the width of the space character.
int	getWidth(java.lang.String text) Get the width of the given string
int	getYOffset(java.lang.String text) Returns the distance from the y drawing location to the top most pixel of the specified text.
boolean	isCaching() Returns true if this UnicodeFont caches the glyph drawing instructions to improve performance.
boolean	loadGlyphs() Loads all queued glyphs to the backing textures.
boolean	loadGlyphs(int maxGlyphsToLoad) Loads up to the specified number of queued glyphs to the backing textures.
void	setDisplayListCaching(boolean displayListCaching) Sets if this UnicodeFont caches the glyph drawing instructions to improve performance.
void	setGlyphPageHeight(int glyphPageHeight) Sets the height of the backing textures.
void	setGlyphPageWidth(int glyphPageWidth) Sets the width of the backing textures.
void	setPaddingAdvanceX(int paddingAdvanceX) Sets the additional amount to offset glyphs on the x axis.
void	setPaddingAdvanceY(int paddingAdvanceY) Sets the additional amount to offset a line of text on the y axis.
void	setPaddingBottom(int paddingBottom) Sets the padding below a glyph on the GlyphPage to allow for effects to be drawn.
void	setPaddingLeft(int paddingLeft) Sets the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.
void	setPaddingRight(int paddingRight) Sets the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.
void	setPaddingTop(int paddingTop) Sets the padding above a glyph on the GlyphPage to allow for effects to be drawn.

Methods inherited from class java.lang.Object

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

Constructor Detail

UnicodeFont

public UnicodeFont(java.lang.String ttfFileRef,
                   java.lang.String hieroFileRef)
            throws SlickException

Create a new unicode font based on a TTF file

Parameters:

ttfFileRef - The file system or classpath location of the TrueTypeFont file.

hieroFileRef - The file system or classpath location of the Hiero settings file.

Throws:

SlickException - if the UnicodeFont could not be initialized.

UnicodeFont

public UnicodeFont(java.lang.String ttfFileRef,
                   HieroSettings settings)
            throws SlickException

Create a new unicode font based on a TTF file and a set of heiro configuration

Parameters:

ttfFileRef - The file system or classpath location of the TrueTypeFont file.

settings - The settings configured via the Hiero tool

Throws:

SlickException - if the UnicodeFont could not be initialized.

UnicodeFont

public UnicodeFont(java.lang.String ttfFileRef,
                   int size,
                   boolean bold,
                   boolean italic)
            throws SlickException

Create a new unicode font based on a TTF file alone

Parameters:

ttfFileRef - The file system or classpath location of the TrueTypeFont file.

size - The point size of the font to generated

bold - True if the font should be rendered in bold typeface

italic - True if the font should be rendered in bold typeface

Throws:

SlickException - if the UnicodeFont could not be initialized.

UnicodeFont

public UnicodeFont(java.awt.Font font,
                   java.lang.String hieroFileRef)
            throws SlickException

Creates a new UnicodeFont.

Parameters:

font - The AWT font to render

hieroFileRef - The file system or classpath location of the Hiero settings file.

Throws:

SlickException - if the UnicodeFont could not be initialized.

UnicodeFont

public UnicodeFont(java.awt.Font font,
                   HieroSettings settings)

Creates a new UnicodeFont.

Parameters:

font - The AWT font to render

settings - The settings configured via the Hiero tool

UnicodeFont

public UnicodeFont(java.awt.Font font)

Creates a new UnicodeFont.

Parameters:

font - The AWT font to render

UnicodeFont

public UnicodeFont(java.awt.Font font,
                   int size,
                   boolean bold,
                   boolean italic)

Creates a new UnicodeFont.

Parameters:

font - The AWT font to render

size - The point size of the font to generated

bold - True if the font should be rendered in bold typeface

italic - True if the font should be rendered in bold typeface

Method Detail

addGlyphs

public void addGlyphs(int startCodePoint,
                      int endCodePoint)

Queues the glyphs in the specified codepoint range (inclusive) to be loaded. Note that the glyphs are not actually loaded until loadGlyphs() is called. Some characters like combining marks and non-spacing marks can only be rendered with the context of other glyphs. In this case, use addGlyphs(String).

Parameters:

startCodePoint - The code point of the first glyph to add

endCodePoint - The code point of the last glyph to add

addGlyphs

public void addGlyphs(java.lang.String text)

Queues the glyphs in the specified text to be loaded. Note that the glyphs are not actually loaded until loadGlyphs() is called.

Parameters:

text - The text containing the glyphs to be added

addAsciiGlyphs

public void addAsciiGlyphs()

Queues the glyphs in the ASCII character set (codepoints 32 through 255) to be loaded. Note that the glyphs are not actually loaded until loadGlyphs() is called.

addNeheGlyphs

public void addNeheGlyphs()

Queues the glyphs in the NEHE character set (codepoints 32 through 128) to be loaded. Note that the glyphs are not actually loaded until loadGlyphs() is called.

loadGlyphs

public boolean loadGlyphs()
                   throws SlickException

Loads all queued glyphs to the backing textures. Glyphs that are typically displayed together should be added and loaded at the same time so that they are stored on the same backing texture. This reduces the number of backing texture binds required to draw glyphs.

Returns:

True if the glyphs were loaded entirely

Throws:

SlickException - if the glyphs could not be loaded.

loadGlyphs

public boolean loadGlyphs(int maxGlyphsToLoad)
                   throws SlickException

Loads up to the specified number of queued glyphs to the backing textures. This is typically called from the game loop to load glyphs on the fly that were requested for display but have not yet been loaded.

Parameters:

maxGlyphsToLoad - The maximum number of glyphs to be loaded this time

Returns:

True if the glyphs were loaded entirely

Throws:

SlickException - if the glyphs could not be loaded.

clearGlyphs

public void clearGlyphs()

Clears all loaded and queued glyphs.

destroy

public void destroy()

Releases all resources used by this UnicodeFont. This method should be called when this UnicodeFont instance is no longer needed.

drawDisplayList

public UnicodeFont.DisplayList drawDisplayList(float x,
                                               float y,
                                               java.lang.String text,
                                               Color color,
                                               int startIndex,
                                               int endIndex)

Identical to drawString(float, float, String, Color, int, int) but returns a DisplayList which provides access to the width and height of the text drawn.

Parameters:

text - The text to render

x - The horizontal location to render at

y - The vertical location to render at

color - The colour to apply as a filter on the text

startIndex - The start index into the string to start rendering at

endIndex - The end index into the string to render to

Returns:

The reference to the display list that was drawn and potentiall ygenerated

drawString

public void drawString(float x,
                       float y,
                       java.lang.String text,
                       Color color,
                       int startIndex,
                       int endIndex)

Description copied from interface: Font

Draw part of a string to the screen. Note that this will still position the text as though it's part of the bigger string.

Specified by:

drawString in interface Font

Parameters:

x - The x location at which to draw the string

y - The y location at which to draw the string

text - The text to be displayed

color - The colour to draw with

startIndex - The index of the first character to draw

endIndex - The index of the last character from the string to draw

drawString

public void drawString(float x,
                       float y,
                       java.lang.String text)

Description copied from interface: Font

Draw a string to the screen

Specified by:

drawString in interface Font

Parameters:

x - The x location at which to draw the string

y - The y location at which to draw the string

text - The text to be displayed

drawString

public void drawString(float x,
                       float y,
                       java.lang.String text,
                       Color col)

Description copied from interface: Font

Draw a string to the screen

Specified by:

drawString in interface Font

Parameters:

x - The x location at which to draw the string

y - The y location at which to draw the string

text - The text to be displayed

col - The colour to draw with

getSpaceWidth

public int getSpaceWidth()

Returns the width of the space character.

getWidth

public int getWidth(java.lang.String text)

Description copied from interface: Font

Get the width of the given string

Specified by:

getWidth in interface Font

Parameters:

text - The string to obtain the rendered with of

Returns:

The width of the given string

See Also:

Font.getWidth(java.lang.String)

getHeight

public int getHeight(java.lang.String text)

Description copied from interface: Font

Get the height of the given string

Specified by:

getHeight in interface Font

Parameters:

text - The string to obtain the rendered with of

Returns:

The width of the given string

See Also:

Font.getHeight(java.lang.String)

getYOffset

public int getYOffset(java.lang.String text)

Returns the distance from the y drawing location to the top most pixel of the specified text.

Parameters:

text - The text to analyse

Returns:

The distance fro the y drawing location ot the top most pixel of the specified text

getFont

public java.awt.Font getFont()

Returns the TrueTypeFont for this UnicodeFont.

Returns:

The AWT Font being rendered

getPaddingTop

public int getPaddingTop()

Returns the padding above a glyph on the GlyphPage to allow for effects to be drawn.

Returns:

The padding at the top of the glyphs when drawn

setPaddingTop

public void setPaddingTop(int paddingTop)

Sets the padding above a glyph on the GlyphPage to allow for effects to be drawn.

Parameters:

paddingTop - The padding at the top of the glyphs when drawn

getPaddingLeft

public int getPaddingLeft()

Returns the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.

Returns:

The padding at the left of the glyphs when drawn

setPaddingLeft

public void setPaddingLeft(int paddingLeft)

Sets the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.

Parameters:

paddingLeft - The padding at the left of the glyphs when drawn

getPaddingBottom

public int getPaddingBottom()

Returns the padding below a glyph on the GlyphPage to allow for effects to be drawn.

Returns:

The padding at the bottom of the glyphs when drawn

setPaddingBottom

public void setPaddingBottom(int paddingBottom)

Sets the padding below a glyph on the GlyphPage to allow for effects to be drawn.

Parameters:

paddingBottom - The padding at the bottom of the glyphs when drawn

getPaddingRight

public int getPaddingRight()

Returns the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.

Returns:

The padding at the right of the glyphs when drawn

setPaddingRight

public void setPaddingRight(int paddingRight)

Sets the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.

Parameters:

paddingRight - The padding at the right of the glyphs when drawn

getPaddingAdvanceX

public int getPaddingAdvanceX()

Gets the additional amount to offset glyphs on the x axis.

Returns:

The padding applied for each horizontal advance (i.e. when a glyph is rendered)

setPaddingAdvanceX

public void setPaddingAdvanceX(int paddingAdvanceX)

Sets the additional amount to offset glyphs on the x axis. This is typically set to a negative number when left or right padding is used so that glyphs are not spaced too far apart.

Parameters:

paddingAdvanceX - The padding applied for each horizontal advance (i.e. when a glyph is rendered)

getPaddingAdvanceY

public int getPaddingAdvanceY()

Gets the additional amount to offset a line of text on the y axis.

Returns:

The padding applied for each vertical advance (i.e. when a glyph is rendered)

setPaddingAdvanceY

public void setPaddingAdvanceY(int paddingAdvanceY)

Sets the additional amount to offset a line of text on the y axis. This is typically set to a negative number when top or bottom padding is used so that lines of text are not spaced too far apart.

Parameters:

paddingAdvanceY - The padding applied for each vertical advance (i.e. when a glyph is rendered)

getLineHeight

public int getLineHeight()

Returns the distance from one line of text to the next. This is the sum of the descent, ascent, leading, padding top, padding bottom, and padding advance y. To change the line height, use setPaddingAdvanceY(int).

Specified by:

getLineHeight in interface Font

Returns:

The maxium height of any line drawn by this font

getAscent

public int getAscent()

Gets the distance from the baseline to the y drawing location.

Returns:

The ascent of this font

getDescent

public int getDescent()

Gets the distance from the baseline to the bottom of most alphanumeric characters with descenders.

Returns:

The distance from the baseline to the bottom of the font

getLeading

public int getLeading()

Gets the extra distance between the descent of one line of text to the ascent of the next.

Returns:

The leading edge of the font

getGlyphPageWidth

public int getGlyphPageWidth()

Returns the width of the backing textures.

Returns:

The width of the glyph pages in this font

setGlyphPageWidth

public void setGlyphPageWidth(int glyphPageWidth)

Sets the width of the backing textures. Default is 512.

Parameters:

glyphPageWidth - The width of the glyph pages in this font

getGlyphPageHeight

public int getGlyphPageHeight()

Returns the height of the backing textures.

Returns:

The height of the glyph pages in this font

setGlyphPageHeight

public void setGlyphPageHeight(int glyphPageHeight)

Sets the height of the backing textures. Default is 512.

Parameters:

glyphPageHeight - The width of the glyph pages in this font

getGlyphPages

public java.util.List getGlyphPages()

Returns the GlyphPages for this UnicodeFont.

Returns:

The glyph pages that have been loaded into this font

getEffects

public java.util.List getEffects()

Returns a list of Effects that will be applied to the glyphs.

Returns:

The list of effects to be applied to the font

isCaching

public boolean isCaching()

Returns true if this UnicodeFont caches the glyph drawing instructions to improve performance.

Returns:

True if caching is turned on

setDisplayListCaching

public void setDisplayListCaching(boolean displayListCaching)

Sets if this UnicodeFont caches the glyph drawing instructions to improve performance. Default is true. Text rendering is very slow without display list caching.

Parameters:

displayListCaching - True if caching should be turned on

getFontFile

public java.lang.String getFontFile()

Returns the path to the TTF file for this UnicodeFont, or null. If this UnicodeFont was created without specifying the TTF file, it will try to determine the path using Sun classes. If this fails, null is returned.

Returns:

The reference to the font file that the kerning was loaded from