org.newdawn.slick
Class UnicodeFont

java.lang.Object
  extended by 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


Copyright © 2006 New Dawn Software. All Rights Reserved.