libgdx API

com.badlogic.gdx.graphics.g2d
Class BitmapFont

java.lang.Object
  extended by com.badlogic.gdx.graphics.g2d.BitmapFont
All Implemented Interfaces:
Disposable

public class BitmapFont
extends java.lang.Object
implements Disposable

Renders bitmap fonts. The font consists of 2 files: an image file or TextureRegion containing the glyphs and a file in the AngleCode BMFont text format that describes where each glyph is on the image. Currently only a single image of glyphs is supported.

Text is drawn using a SpriteBatch. Text can be cached in a BitmapFontCache for faster rendering of static text, which saves needing to compute the location of each glyph each frame.

* The texture for a BitmapFont loaded from a file is managed. dispose() must be called to free the texture when no longer needed. A BitmapFont loaded using a TextureRegion is managed if the region's texture is managed. Disposing the BitmapFont disposes the region's texture, which may not be desirable if the texture is still being used elsewhere.

The code is based on Matthias Mann's TWL BitmapFont class. Thanks for sharing, Matthias! :)

Author:
Nathan Sweet, Matthias Mann

Nested Class Summary
static class BitmapFont.BitmapFontData
           
static class BitmapFont.HAlignment
           
static class BitmapFont.TextBounds
           
 
Constructor Summary
BitmapFont()
          Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file.
BitmapFont(BitmapFont.BitmapFontData data, TextureRegion region, boolean integer)
           
BitmapFont(boolean flip)
          Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file.
BitmapFont(FileHandle fontFile, boolean flip)
          Creates a BitmapFont from a BMFont file.
BitmapFont(FileHandle fontFile, FileHandle imageFile, boolean flip)
          Creates a BitmapFont from a BMFont file, using the specified image for glyphs.
BitmapFont(FileHandle fontFile, FileHandle imageFile, boolean flip, boolean integer)
          Creates a BitmapFont from a BMFont file, using the specified image for glyphs.
BitmapFont(FileHandle fontFile, TextureRegion region, boolean flip)
          Creates a BitmapFont with the glyphs relative to the specified region.
 
Method Summary
 void computeGlyphAdvancesAndPositions(java.lang.CharSequence str, FloatArray glyphAdvances, FloatArray glyphPositions)
          Computes the glyph advances for the given character sequence and stores them in the provided FloatArray.
 int computeVisibleGlyphs(java.lang.CharSequence str, int start, int end, float availableWidth)
          Returns the number of glyphs from the substring that can be rendered in the specified width.
 boolean containsCharacter(char character)
           
 void dispose()
          Disposes the texture used by this BitmapFont's region.
 BitmapFont.TextBounds draw(SpriteBatch spriteBatch, java.lang.CharSequence str, float x, float y)
          Draws a string at the specified position.
 BitmapFont.TextBounds draw(SpriteBatch spriteBatch, java.lang.CharSequence str, float x, float y, int start, int end)
          Draws a substring at the specified position.
 BitmapFont.TextBounds drawMultiLine(SpriteBatch spriteBatch, java.lang.CharSequence str, float x, float y)
          Draws a string, which may contain newlines (\n), at the specified position.
 BitmapFont.TextBounds drawMultiLine(SpriteBatch spriteBatch, java.lang.CharSequence str, float x, float y, float alignmentWidth, BitmapFont.HAlignment alignment)
          Draws a string, which may contain newlines (\n), at the specified position and alignment.
 BitmapFont.TextBounds drawWrapped(SpriteBatch spriteBatch, java.lang.CharSequence str, float x, float y, float wrapWidth)
          Draws a string, which may contain newlines (\n), with the specified position.
 BitmapFont.TextBounds drawWrapped(SpriteBatch spriteBatch, java.lang.CharSequence str, float x, float y, float wrapWidth, BitmapFont.HAlignment alignment)
          Draws a string, which may contain newlines (\n), with the specified position.
 float getAscent()
          Returns the ascent, which is the distance from the cap height to the top of the tallest glyph.
 BitmapFont.TextBounds getBounds(java.lang.CharSequence str)
          Returns the size of the specified string.
 BitmapFont.TextBounds getBounds(java.lang.CharSequence str, int start, int end)
          Returns the size of the specified substring.
 float getCapHeight()
          Returns the cap height, which is the distance from the top of most uppercase characters to the baseline.
 Color getColor()
          Returns the color of this font.
 BitmapFont.BitmapFontData getData()
           
 float getDescent()
          Returns the descent, which is the distance from the bottom of the glyph that extends the lowest to the baseline.
 float getLineHeight()
          Returns the line height, which is the distance from one line of text to the next.
 BitmapFont.TextBounds getMultiLineBounds(java.lang.CharSequence str)
          Returns the size of the specified string, which may contain newlines.
 TextureRegion getRegion()
           
 float getScaleX()
           
 float getScaleY()
           
 float getSpaceWidth()
          Returns the width of the space character.
 BitmapFont.TextBounds getWrappedBounds(java.lang.CharSequence str, float wrapWidth)
          Returns the size of the specified string, which may contain newlines and is wrapped to keep it within a rectangle of the specified width.
 float getXHeight()
          Returns the x-height, which is the distance from the top of most lowercase characters to the baseline.
 boolean isFlipped()
          Returns true if this BitmapFont has been flipped for use with a y-down coordinate system.
 void scale(float amount)
          Sets the font's scale relative to the current scale.
 void setColor(Color tint)
           
 void setColor(float color)
           
 void setColor(float r, float g, float b, float a)
           
 void setFixedWidthGlyphs(java.lang.CharSequence glyphs)
          Makes the specified glyphs fixed width.
 void setScale(float scaleXY)
          Scales the font by the specified amount in both directions.

Note that smoother scaling can be achieved if the texture backing the BitmapFont is using Texture.TextureFilter.Linear.
 void setScale(float scaleX, float scaleY)
           
 void setUseIntegerPositions(boolean use)
          Specifies whether to use integer positions or not.
 boolean usesIntegerPositions()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BitmapFont

public BitmapFont()
Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file. This is convenient to easily display text without bothering with generating a bitmap font.


BitmapFont

public BitmapFont(boolean flip)
Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file. This is convenient to easily display text without bothering with generating a bitmap font.

Parameters:
flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

BitmapFont

public BitmapFont(FileHandle fontFile,
                  TextureRegion region,
                  boolean flip)
Creates a BitmapFont with the glyphs relative to the specified region.

Parameters:
region - The texture region containing the glyphs. The glyphs must be relative to the lower left corner (ie, the region should not be flipped).
flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

BitmapFont

public BitmapFont(FileHandle fontFile,
                  boolean flip)
Creates a BitmapFont from a BMFont file. The image file name is read from the BMFont file and the image is loaded from the same directory.

Parameters:
flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

BitmapFont

public BitmapFont(FileHandle fontFile,
                  FileHandle imageFile,
                  boolean flip)
Creates a BitmapFont from a BMFont file, using the specified image for glyphs. Any image specified in the BMFont file is ignored.

Parameters:
flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

BitmapFont

public BitmapFont(FileHandle fontFile,
                  FileHandle imageFile,
                  boolean flip,
                  boolean integer)
Creates a BitmapFont from a BMFont file, using the specified image for glyphs. Any image specified in the BMFont file is ignored.

Parameters:
flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.
integer - If true, rendering positions will be at integer values to avoid filtering artifacts.s

BitmapFont

public BitmapFont(BitmapFont.BitmapFontData data,
                  TextureRegion region,
                  boolean integer)
Method Detail

draw

public BitmapFont.TextBounds draw(SpriteBatch spriteBatch,
                                  java.lang.CharSequence str,
                                  float x,
                                  float y)
Draws a string at the specified position.

Parameters:
x - The x position for the left most character.
y - The y position for the top of most capital letters in the font (the cap height).
Returns:
The bounds of the rendered string (the height is the distance from y to the baseline). Note the same TextBounds instance is used for all methods that return TextBounds.

draw

public BitmapFont.TextBounds draw(SpriteBatch spriteBatch,
                                  java.lang.CharSequence str,
                                  float x,
                                  float y,
                                  int start,
                                  int end)
Draws a substring at the specified position.

Parameters:
x - The x position for the left most character.
y - The y position for the top of most capital letters in the font (the cap height).
start - The first character of the string to draw.
end - The last character of the string to draw (exclusive).
Returns:
The bounds of the rendered string (the height is the distance from y to the baseline). Note the same TextBounds instance is used for all methods that return TextBounds.

drawMultiLine

public BitmapFont.TextBounds drawMultiLine(SpriteBatch spriteBatch,
                                           java.lang.CharSequence str,
                                           float x,
                                           float y)
Draws a string, which may contain newlines (\n), at the specified position.

Parameters:
x - The x position for the left most character.
y - The y position for the top of most capital letters in the font (the cap height).
Returns:
The bounds of the rendered string (the height is the distance from y to the baseline of the last line). Note the same TextBounds instance is used for all methods that return TextBounds.

drawMultiLine

public BitmapFont.TextBounds drawMultiLine(SpriteBatch spriteBatch,
                                           java.lang.CharSequence str,
                                           float x,
                                           float y,
                                           float alignmentWidth,
                                           BitmapFont.HAlignment alignment)
Draws a string, which may contain newlines (\n), at the specified position and alignment. Each line is aligned horizontally within a rectangle of the specified width.

Parameters:
x - The x position for the left most character.
y - The y position for the top of most capital letters in the font (the cap height).
Returns:
The bounds of the rendered string (the height is the distance from y to the baseline of the last line). Note the same TextBounds instance is used for all methods that return TextBounds.

drawWrapped

public BitmapFont.TextBounds drawWrapped(SpriteBatch spriteBatch,
                                         java.lang.CharSequence str,
                                         float x,
                                         float y,
                                         float wrapWidth)
Draws a string, which may contain newlines (\n), with the specified position. Each line is automatically wrapped to keep it within a rectangle of the specified width.

Parameters:
x - The x position for the left most character.
y - The y position for the top of most capital letters in the font (the cap height).
Returns:
The bounds of the rendered string (the height is the distance from y to the baseline of the last line). Note the same TextBounds instance is used for all methods that return TextBounds.

drawWrapped

public BitmapFont.TextBounds drawWrapped(SpriteBatch spriteBatch,
                                         java.lang.CharSequence str,
                                         float x,
                                         float y,
                                         float wrapWidth,
                                         BitmapFont.HAlignment alignment)
Draws a string, which may contain newlines (\n), with the specified position. Each line is automatically wrapped to keep it within a rectangle of the specified width, and aligned horizontally within that rectangle.

Parameters:
x - The x position for the left most character.
y - The y position for the top of most capital letters in the font (the cap height).
Returns:
The bounds of the rendered string (the height is the distance from y to the baseline of the last line). Note the same TextBounds instance is used for all methods that return TextBounds.

getBounds

public BitmapFont.TextBounds getBounds(java.lang.CharSequence str)
Returns the size of the specified string. The height is the distance from the top of most capital letters in the font (the cap height) to the baseline. Note the same TextBounds instance is used for all methods that return TextBounds.


getBounds

public BitmapFont.TextBounds getBounds(java.lang.CharSequence str,
                                       int start,
                                       int end)
Returns the size of the specified substring. The height is the distance from the top of most capital letters in the font (the cap height) to the baseline. Note the same TextBounds instance is used for all methods that return TextBounds.

Parameters:
start - The first character of the string.
end - The last character of the string (exclusive).

getMultiLineBounds

public BitmapFont.TextBounds getMultiLineBounds(java.lang.CharSequence str)
Returns the size of the specified string, which may contain newlines. The height is the distance from the top of most capital letters in the font (the cap height) to the baseline of the last line of text. Note the same TextBounds instance is used for all methods that return TextBounds.


getWrappedBounds

public BitmapFont.TextBounds getWrappedBounds(java.lang.CharSequence str,
                                              float wrapWidth)
Returns the size of the specified string, which may contain newlines and is wrapped to keep it within a rectangle of the specified width. The height is the distance from the top of most capital letters in the font (the cap height) to the baseline of the last line of text. Note the same TextBounds instance is used for all methods that return TextBounds.


computeGlyphAdvancesAndPositions

public void computeGlyphAdvancesAndPositions(java.lang.CharSequence str,
                                             FloatArray glyphAdvances,
                                             FloatArray glyphPositions)
Computes the glyph advances for the given character sequence and stores them in the provided FloatArray. The FloatArray is cleared. This will add an additional element at the end.

Parameters:
str - the character sequence
glyphAdvances - the glyph advances output array.
glyphPositions - the glyph positions output array.

computeVisibleGlyphs

public int computeVisibleGlyphs(java.lang.CharSequence str,
                                int start,
                                int end,
                                float availableWidth)
Returns the number of glyphs from the substring that can be rendered in the specified width.

Parameters:
start - The first character of the string.
end - The last character of the string (exclusive).

setColor

public void setColor(float color)

setColor

public void setColor(Color tint)

setColor

public void setColor(float r,
                     float g,
                     float b,
                     float a)

getColor

public Color getColor()
Returns the color of this font. Changing the returned color will have no affect, setColor(Color) or setColor(float, float, float, float) must be used.


setScale

public void setScale(float scaleX,
                     float scaleY)

setScale

public void setScale(float scaleXY)
Scales the font by the specified amount in both directions.

Note that smoother scaling can be achieved if the texture backing the BitmapFont is using Texture.TextureFilter.Linear. The default is Nearest, so use a BitmapFont constructor that takes a TextureRegion.


scale

public void scale(float amount)
Sets the font's scale relative to the current scale.


getScaleX

public float getScaleX()

getScaleY

public float getScaleY()

getRegion

public TextureRegion getRegion()

getLineHeight

public float getLineHeight()
Returns the line height, which is the distance from one line of text to the next.


getSpaceWidth

public float getSpaceWidth()
Returns the width of the space character.


getXHeight

public float getXHeight()
Returns the x-height, which is the distance from the top of most lowercase characters to the baseline.


getCapHeight

public float getCapHeight()
Returns the cap height, which is the distance from the top of most uppercase characters to the baseline. Since the drawing position is the cap height of the first line, the cap height can be used to get the location of the baseline.


getAscent

public float getAscent()
Returns the ascent, which is the distance from the cap height to the top of the tallest glyph.


getDescent

public float getDescent()
Returns the descent, which is the distance from the bottom of the glyph that extends the lowest to the baseline. This number is negative.


isFlipped

public boolean isFlipped()
Returns true if this BitmapFont has been flipped for use with a y-down coordinate system.


dispose

public void dispose()
Disposes the texture used by this BitmapFont's region.

Specified by:
dispose in interface Disposable

setFixedWidthGlyphs

public void setFixedWidthGlyphs(java.lang.CharSequence glyphs)
Makes the specified glyphs fixed width. This can be useful to make the numbers in a font fixed width. Eg, when horizontally centering a score or loading percentage text, it will not jump around as different numbers are shown.


containsCharacter

public boolean containsCharacter(char character)
Parameters:
character -
Returns:
whether the given character is contained in this font.

setUseIntegerPositions

public void setUseIntegerPositions(boolean use)
Specifies whether to use integer positions or not. Default is to use them so filtering doesn't kick in as badly.

Parameters:
use -

usesIntegerPositions

public boolean usesIntegerPositions()
Returns:
whether this font uses integer positions for drawing.

getData

public BitmapFont.BitmapFontData getData()

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)