public class BitmapFont extends Object implements Disposable
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! :)
Modifier and Type | Class and Description |
---|---|
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
|
Modifier and Type | Field and Description |
---|---|
static char[] |
capChars |
static char[] |
xChars |
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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 |
isBreakChar(char c) |
boolean |
isFlipped()
Returns true if this BitmapFont has been flipped for use with a y-down coordinate system.
|
boolean |
isMarkupEnabled()
Returns true if color markup is enabled for this BitmapFont
|
boolean |
ownsTexture() |
void |
scale(float amount)
Sets the font's scale relative to the current scale.
|
void |
setBreakChars(char[] breakChars)
Provide any additional characters that should act as break characters when the label is wrapped.
|
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 |
setMarkupEnabled(boolean markupEnabled)
Sets color markup on/off for this BitmapFont
|
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
|
void |
setUseIntegerPositions(boolean integer)
Specifies whether to use integer positions or not.
|
String |
toString() |
boolean |
usesIntegerPositions()
Checks whether this font uses integer positions for drawing.
|
public BitmapFont()
public BitmapFont(boolean flip)
flip
- If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.public BitmapFont(FileHandle fontFile, TextureRegion region)
dispose()
method will not dispose the region's texture in this
case!
The font data is not flipped.
fontFile
- the font definition fileregion
- 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.public BitmapFont(FileHandle fontFile, TextureRegion region, boolean flip)
dispose()
method will not dispose the region's texture in this
case!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.public BitmapFont(FileHandle fontFile)
public BitmapFont(FileHandle fontFile, boolean flip)
flip
- If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.public BitmapFont(FileHandle fontFile, FileHandle imageFile, boolean flip)
flip
- If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.public BitmapFont(FileHandle fontFile, FileHandle imageFile, boolean flip, boolean integer)
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.public BitmapFont(BitmapFont.BitmapFontData data, TextureRegion region, boolean integer)
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.
integer
- If true, rendering positions will be at integer values to avoid filtering artifacts.public BitmapFont(BitmapFont.BitmapFontData data, TextureRegion[] regions, boolean integer)
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.integer
- If true, rendering positions will be at integer values to avoid filtering artifacts.public BitmapFont.TextBounds draw(Batch batch, CharSequence str, float x, float y)
public BitmapFont.TextBounds draw(Batch batch, CharSequence str, float x, float y, int start, int end)
public BitmapFont.TextBounds drawMultiLine(Batch batch, CharSequence str, float x, float y)
BitmapFontCache#addMultiLineText(CharSequence, float, float, float, HAlignment)
public BitmapFont.TextBounds drawMultiLine(Batch batch, CharSequence str, float x, float y, float alignmentWidth, BitmapFont.HAlignment alignment)
BitmapFontCache#addMultiLineText(CharSequence, float, float, float, HAlignment)
public BitmapFont.TextBounds drawWrapped(Batch batch, CharSequence str, float x, float y, float wrapWidth)
BitmapFontCache#addWrappedText(CharSequence, float, float, float, HAlignment)
public BitmapFont.TextBounds drawWrapped(Batch batch, CharSequence str, float x, float y, float wrapWidth, BitmapFont.HAlignment alignment)
BitmapFontCache#addWrappedText(CharSequence, float, float, float, HAlignment)
public BitmapFont.TextBounds getBounds(CharSequence str)
public BitmapFont.TextBounds getBounds(CharSequence str, BitmapFont.TextBounds textBounds)
public BitmapFont.TextBounds getBounds(CharSequence str, int start, int end)
public BitmapFont.TextBounds getBounds(CharSequence str, int start, int end, BitmapFont.TextBounds textBounds)
cap height
) to the baseline.start
- The first character of the string.end
- The last character of the string (exclusive).public BitmapFont.TextBounds getMultiLineBounds(CharSequence str)
public BitmapFont.TextBounds getMultiLineBounds(CharSequence str, BitmapFont.TextBounds textBounds)
cap height
) to the baseline of the last line of text.public BitmapFont.TextBounds getWrappedBounds(CharSequence str, float wrapWidth)
public BitmapFont.TextBounds getWrappedBounds(CharSequence str, float wrapWidth, BitmapFont.TextBounds textBounds)
cap height
) to the baseline of
the last line of text.wrapWidth
- Width to wrap the bounds within.public void computeGlyphAdvancesAndPositions(CharSequence str, FloatArray glyphAdvances, FloatArray glyphPositions)
FloatArray
. The float
arrays are cleared. An additional element is added at the end.glyphAdvances
- the glyph advances output array.glyphPositions
- the glyph positions output array.public int computeVisibleGlyphs(CharSequence str, int start, int end, float availableWidth)
start
- The first character of the string.end
- The last character of the string (exclusive).public void setColor(float color)
public void setColor(Color color)
public void setColor(float r, float g, float b, float a)
public Color getColor()
setColor(Color)
or
setColor(float, float, float, float)
must be used.public void setScale(float scaleX, float scaleY)
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
.
IllegalArgumentException
- if scaleX or scaleY is zero.public void setScale(float scaleXY)
IllegalArgumentException
- if scaleX or scaleY is zero.setScale(float, float)
public void scale(float amount)
IllegalArgumentException
- if the resulting scale is zero.setScale(float, float)
public float getScaleX()
public float getScaleY()
public TextureRegion getRegion()
public TextureRegion[] getRegions()
public TextureRegion getRegion(int index)
public float getLineHeight()
public float getSpaceWidth()
public float getXHeight()
public float getCapHeight()
public float getAscent()
public float getDescent()
public boolean isFlipped()
public boolean isMarkupEnabled()
public void setMarkupEnabled(boolean markupEnabled)
public void dispose()
dispose
in interface Disposable
public void setFixedWidthGlyphs(CharSequence glyphs)
public boolean containsCharacter(char character)
public void setUseIntegerPositions(boolean integer)
public boolean usesIntegerPositions()
public BitmapFontCache getCache()
public BitmapFont.BitmapFontData getData()
BitmapFont.BitmapFontData
for this BitmapFont.public boolean ownsTexture()
public void setOwnsTexture(boolean ownsTexture)
dispose()
is called. Use with care!ownsTexture
- whether the font owns the texturepublic void setBreakChars(char[] breakChars)
public boolean isBreakChar(char c)
Copyright © 2015. All rights reserved.