com.badlogic.gdx.graphics.g2d
Class BitmapFont

java.lang.Object
  com.badlogic.gdx.graphics.g2d.BitmapFont

All Implemented Interfaces:

Disposable

public class BitmapFont
extends 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 Batch. 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 was originally based on Matthias Mann's TWL BitmapFont class. Thanks for sharing, Matthias! :)

Author:

Nathan Sweet, Matthias Mann

Nested Class Summary

static class	BitmapFont.BitmapFontData Backing data for a BitmapFont.
static class	BitmapFont.Glyph Represents a single character in a font page.
static class	BitmapFont.HAlignment Defines possible horizontal alignments.
static class	BitmapFont.TextBounds Arbitrarily definable text boundary

Field Summary

static char[]	capChars
static char[]	xChars

Constructor Summary

BitmapFont()
Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file.

BitmapFont(BitmapFont.BitmapFontData data, TextureRegion[] regions, boolean integer)
Constructs a new BitmapFont from the given BitmapFont.BitmapFontData and array of TextureRegion.

BitmapFont(BitmapFont.BitmapFontData data, TextureRegion region, boolean integer)
Constructs a new BitmapFont from the given BitmapFont.BitmapFontData and TextureRegion.

BitmapFont(boolean flip)
Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file.

BitmapFont(FileHandle fontFile)
Creates a BitmapFont from a BMFont 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)
Creates a BitmapFont with the glyphs relative to the specified region.

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

Method Summary

void	computeGlyphAdvancesAndPositions(CharSequence str, FloatArray glyphAdvances, FloatArray glyphPositions) Computes the glyph advances for the given character sequence and stores them in the provided FloatArray.
int	computeVisibleGlyphs(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) Checks whether this BitmapFont data contains a given character.
void	dispose() Disposes the texture used by this BitmapFont's region IF this BitmapFont created the texture.
BitmapFont.TextBounds	draw(Batch batch, CharSequence str, float x, float y) Draws a string at the specified position.
BitmapFont.TextBounds	draw(Batch batch, CharSequence str, float x, float y, int start, int end) Draws a string at the specified position.
BitmapFont.TextBounds	drawMultiLine(Batch batch, CharSequence str, float x, float y) Draws a string, which may contain newlines (\n), at the specified position.
BitmapFont.TextBounds	drawMultiLine(Batch batch, CharSequence str, float x, float y, float alignmentWidth, BitmapFont.HAlignment alignment) Draws a string, which may contain newlines (\n), at the specified position.
BitmapFont.TextBounds	drawWrapped(Batch batch, CharSequence str, float x, float y, float wrapWidth) Draws a string, which may contain newlines (\n), with the specified position.
BitmapFont.TextBounds	drawWrapped(Batch batch, 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(CharSequence str) Returns the bounds of the specified text.
BitmapFont.TextBounds	getBounds(CharSequence str, BitmapFont.TextBounds textBounds) Returns the bounds of the specified text.
BitmapFont.TextBounds	getBounds(CharSequence str, int start, int end) Returns the bounds of the specified text.
BitmapFont.TextBounds	getBounds(CharSequence str, int start, int end, BitmapFont.TextBounds textBounds) Returns the size of the specified string.
BitmapFontCache	getCache() For expert usage -- returns the BitmapFontCache used by this font, for rendering to a sprite batch.
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() Gets the underlying BitmapFont.BitmapFontData for this BitmapFont.
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(CharSequence str) Returns the bounds of the specified text, which may contain newlines.
BitmapFont.TextBounds	getMultiLineBounds(CharSequence str, BitmapFont.TextBounds textBounds) Returns the bounds of the specified text, which may contain newlines.
TextureRegion	getRegion() Returns the first texture region.
TextureRegion	getRegion(int index) Returns the texture page at the given index.
TextureRegion[]	getRegions() Returns the array of TextureRegions that represents each texture page of glyphs.
float	getScaleX()
float	getScaleY()
float	getSpaceWidth() Returns the width of the space character.
BitmapFont.TextBounds	getWrappedBounds(CharSequence str, float wrapWidth) Returns the bounds of the specified text, which may contain newlines and is wrapped within the specified width.
BitmapFont.TextBounds	getWrappedBounds(CharSequence str, float wrapWidth, BitmapFont.TextBounds textBounds) Returns the bounds of the specified text, which may contain newlines and is wrapped within 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.
boolean	ownsTexture()
void	scale(float amount) Sets the font's scale relative to the current scale.
void	setColor(Color color)
void	setColor(float color)
void	setColor(float r, float g, float b, float a)
void	setFixedWidthGlyphs(CharSequence glyphs) Makes the specified glyphs fixed width.
void	setOwnsTexture(boolean ownsTexture) Sets whether the font owns the texture or not.
void	setScale(float scaleXY) Scales the font by the specified amount in both directions.
void	setScale(float scaleX, float scaleY) Scales the font by the specified amounts on both axes Note that smoother scaling can be achieved if the texture backing the BitmapFont is using Texture.TextureFilter.Linear.
void	setUseIntegerPositions(boolean integer) Specifies whether to use integer positions or not.
boolean	usesIntegerPositions() Checks whether this font uses integer positions for drawing.

Methods inherited from class java.lang.Object

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

Field Detail

xChars

public static final char[] xChars

capChars

public static final char[] capChars

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)

Creates a BitmapFont with the glyphs relative to the specified region. If the region is null, the glyph textures are loaded from the image file given in the font file. The dispose() method will not dispose the region's texture in this case! The font data is not flipped.

Parameters:

fontFile - the font definition file

region - The texture region containing the glyphs. The glyphs must be relative to the lower left corner (ie, the region should not be flipped). If the region is null the glyph images are loaded from the image path in the font file.

BitmapFont

public BitmapFont(FileHandle fontFile,
                  TextureRegion region,
                  boolean flip)

Creates a BitmapFont with the glyphs relative to the specified region. If the region is null, the glyph textures are loaded from the image file given in the font file. The dispose() method will not dispose the region's texture in this case!

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). If the region is null the glyph images are loaded from the image path in the font file.

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)

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. The font data is not flipped.

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.

BitmapFont

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

Constructs a new BitmapFont from the given BitmapFont.BitmapFontData and TextureRegion. If the TextureRegion is null, the image path(s) will be read from the BitmapFontData. The dispose() method will not dispose the texture of the region(s) if the region is != null. Passing a single TextureRegion assumes that your font only needs a single texture page. If you need to support multiple pages, either let the Font read the images themselves (by specifying null as the TextureRegion), or by specifying each page manually with the TextureRegion[] constructor.

Parameters:

integer - If true, rendering positions will be at integer values to avoid filtering artifacts.

BitmapFont

public BitmapFont(BitmapFont.BitmapFontData data,
                  TextureRegion[] regions,
                  boolean integer)

Constructs a new BitmapFont from the given BitmapFont.BitmapFontData and array of TextureRegion. If the TextureRegion is null or empty, the image path(s) will be read from the BitmapFontData. The dispose() method will not dispose the texture of the region(s) if the regions array is != null and not empty.

Parameters:

integer - If true, rendering positions will be at integer values to avoid filtering artifacts.

Method Detail

draw

public BitmapFont.TextBounds draw(Batch batch,
                                  CharSequence str,
                                  float x,
                                  float y)

Draws a string at the specified position.

See Also:

BitmapFontCache.addText(CharSequence, float, float, int, int)

draw

public BitmapFont.TextBounds draw(Batch batch,
                                  CharSequence str,
                                  float x,
                                  float y,
                                  int start,
                                  int end)

Draws a string at the specified position.

See Also:

BitmapFontCache.addText(CharSequence, float, float, int, int)

drawMultiLine

public BitmapFont.TextBounds drawMultiLine(Batch batch,
                                           CharSequence str,
                                           float x,
                                           float y)

Draws a string, which may contain newlines (\n), at the specified position.

See Also:

BitmapFontCache#addMultiLineText(CharSequence, float, float, float, HAlignment)

drawMultiLine

public BitmapFont.TextBounds drawMultiLine(Batch batch,
                                           CharSequence str,
                                           float x,
                                           float y,
                                           float alignmentWidth,
                                           BitmapFont.HAlignment alignment)

Draws a string, which may contain newlines (\n), at the specified position.

See Also:

BitmapFontCache#addMultiLineText(CharSequence, float, float, float, HAlignment)

drawWrapped

public BitmapFont.TextBounds drawWrapped(Batch batch,
                                         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 within the specified width.

See Also:

BitmapFontCache#addWrappedText(CharSequence, float, float, float, HAlignment)

drawWrapped

public BitmapFont.TextBounds drawWrapped(Batch batch,
                                         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 within the specified width.

See Also:

BitmapFontCache#addWrappedText(CharSequence, float, float, float, HAlignment)

getBounds

public BitmapFont.TextBounds getBounds(CharSequence str)

Returns the bounds of the specified text. Note the returned TextBounds instance is reused.

See Also:

getBounds(CharSequence, int, int, TextBounds)

getBounds

public BitmapFont.TextBounds getBounds(CharSequence str,
                                       BitmapFont.TextBounds textBounds)

Returns the bounds of the specified text.

See Also:

getBounds(CharSequence, int, int, TextBounds)

getBounds

public BitmapFont.TextBounds getBounds(CharSequence str,
                                       int start,
                                       int end)

Returns the bounds of the specified text. Note the returned TextBounds instance is reused.

See Also:

getBounds(CharSequence, int, int, TextBounds)

getBounds

public BitmapFont.TextBounds getBounds(CharSequence str,
                                       int start,
                                       int end,
                                       BitmapFont.TextBounds textBounds)

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.

Parameters:

start - The first character of the string.

end - The last character of the string (exclusive).

getMultiLineBounds

public BitmapFont.TextBounds getMultiLineBounds(CharSequence str)

Returns the bounds of the specified text, which may contain newlines.

See Also:

getMultiLineBounds(CharSequence, TextBounds)

getMultiLineBounds

public BitmapFont.TextBounds getMultiLineBounds(CharSequence str,
                                                BitmapFont.TextBounds textBounds)

Returns the bounds of the specified text, 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.

getWrappedBounds

public BitmapFont.TextBounds getWrappedBounds(CharSequence str,
                                              float wrapWidth)

Returns the bounds of the specified text, which may contain newlines and is wrapped within the specified width.

See Also:

getWrappedBounds(CharSequence, float, TextBounds)

getWrappedBounds

public BitmapFont.TextBounds getWrappedBounds(CharSequence str,
                                              float wrapWidth,
                                              BitmapFont.TextBounds textBounds)

Returns the bounds of the specified text, which may contain newlines and is wrapped within 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.

Parameters:

wrapWidth - Width to wrap the bounds within.

computeGlyphAdvancesAndPositions

public void computeGlyphAdvancesAndPositions(CharSequence str,
                                             FloatArray glyphAdvances,
                                             FloatArray glyphPositions)

Computes the glyph advances for the given character sequence and stores them in the provided FloatArray. The float arrays are cleared. An additional element is added at the end.

Parameters:

glyphAdvances - the glyph advances output array.

glyphPositions - the glyph positions output array.

computeVisibleGlyphs

public int computeVisibleGlyphs(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 color)

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)

Scales the font by the specified amounts on both axes

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.

Throws:

IllegalArgumentException - When scaleXY is zero

setScale

public void setScale(float scaleXY)

Scales the font by the specified amount in both directions.

Throws:

IllegalArgumentException - When scaleXY is zero

See Also:

setScale(float, float)

scale

public void scale(float amount)

Sets the font's scale relative to the current scale.

Throws:

IllegalArgumentException - When resulting scale is zero

See Also:

setScale(float, float)

getScaleX

public float getScaleX()

getScaleY

public float getScaleY()

getRegion

public TextureRegion getRegion()

Returns the first texture region. This is included for backwards-compatibility, and for convenience since most fonts only use one texture page. For multi-page fonts, use getRegions().

Returns:

the first texture region

getRegions

public TextureRegion[] getRegions()

Returns the array of TextureRegions that represents each texture page of glyphs.

Returns:

the array of texture regions; modifying it may produce undesirable results

getRegion

public TextureRegion getRegion(int index)

Returns the texture page at the given index.

Returns:

the texture page at the given index

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 IF this BitmapFont created the texture.

Specified by:

dispose in interface Disposable

setFixedWidthGlyphs

public void setFixedWidthGlyphs(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)

Checks whether this BitmapFont data contains a given character.

setUseIntegerPositions

public void setUseIntegerPositions(boolean integer)

Specifies whether to use integer positions or not. Default is to use them so filtering doesn't kick in as badly.

usesIntegerPositions

public boolean usesIntegerPositions()

Checks whether this font uses integer positions for drawing.

getCache

public BitmapFontCache getCache()

For expert usage -- returns the BitmapFontCache used by this font, for rendering to a sprite batch. This can be used, for example, to manipulate glyph colors within a specific index.

Returns:

the bitmap font cache used by this font

getData

public BitmapFont.BitmapFontData getData()

Gets the underlying BitmapFont.BitmapFontData for this BitmapFont.

ownsTexture

public boolean ownsTexture()

Returns:

whether the texture is owned by the font, font disposes the texture itself if true

setOwnsTexture

public void setOwnsTexture(boolean ownsTexture)

Sets whether the font owns the texture or not. In case it does, the font will also dispose of the texture when dispose() is called. Use with care!

Parameters:

ownsTexture - whether the font owns the texture