Package gaiasky.util.gdx.g2d

Class BitmapFont

java.lang.Object
gaiasky.util.gdx.g2d.BitmapFont
All Implemented Interfaces:
com.badlogic.gdx.utils.Disposable
public class BitmapFont extends Object implements com.badlogic.gdx.utils.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.

Text is drawn using a ExtBatch. 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! :)

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    BitmapFont.BitmapFontData
    Backing data for a BitmapFont.
    static class 
    BitmapFont.Glyph
    Represents a single character in a font page.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BitmapFont()
    Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file.
    BitmapFont​(boolean flip)
    Creates a BitmapFont using the default 15pt Arial font included in the libgdx JAR file.
    BitmapFont​(com.badlogic.gdx.files.FileHandle fontFile)
    Creates a BitmapFont from a BMFont file.
    BitmapFont​(com.badlogic.gdx.files.FileHandle fontFile, boolean flip)
    Creates a BitmapFont from a BMFont file.
    BitmapFont​(com.badlogic.gdx.files.FileHandle fontFile, com.badlogic.gdx.files.FileHandle imageFile, boolean flip)
    Creates a BitmapFont from a BMFont file, using the specified image for glyphs.
    BitmapFont​(com.badlogic.gdx.files.FileHandle fontFile, com.badlogic.gdx.files.FileHandle imageFile, boolean flip, boolean integer)
    Creates a BitmapFont from a BMFont file, using the specified image for glyphs.
    BitmapFont​(com.badlogic.gdx.files.FileHandle fontFile, TextureRegion region)
    Creates a BitmapFont with the glyphs relative to the specified region.
    BitmapFont​(com.badlogic.gdx.files.FileHandle fontFile, TextureRegion region, boolean flip)
    Creates a BitmapFont with the glyphs relative to the specified region.
    BitmapFont​(BitmapFont.BitmapFontData data, com.badlogic.gdx.utils.Array<TextureRegion> pageRegions, 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dispose()
    Disposes the texture used by this BitmapFont's region IF this BitmapFont created the texture.
    void
    draw​(ExtBatch batch, GlyphLayout layout, float x, float y)
    Draws text at the specified position.
    GlyphLayout
    draw​(ExtBatch batch, CharSequence str, float x, float y)
    Draws text at the specified position.
    GlyphLayout
    draw​(ExtBatch batch, CharSequence str, float x, float y, float targetWidth, int halign, boolean wrap)
    Draws text at the specified position.
    GlyphLayout
    draw​(ExtBatch batch, CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap)
    Draws text at the specified position.
    GlyphLayout
    draw​(ExtBatch batch, CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap, String truncate)
    Draws text at the specified position.
    float
    getAscent()
    Returns the ascent, which is the distance from the cap height to the top of the tallest glyph.
    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.
    com.badlogic.gdx.graphics.Color
    getColor()
    Returns the color of text drawn with 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.
    TextureRegion
    getRegion()
    Returns the first texture region.
    TextureRegion
    getRegion​(int index)
    Returns the texture page at the given index.
    com.badlogic.gdx.utils.Array<TextureRegion>
    getRegions()
    Returns the array of TextureRegions that represents each texture page of glyphs.
    float
    getScaleX()
     
    float
    getScaleY()
     
    float
    getSpaceXadvance()
    Returns the x-advance of the space character.
    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.
    protected void
    load​(BitmapFont.BitmapFontData data)
     
    BitmapFontCache
    newFontCache()
    Creates a new BitmapFontCache for this font.
    boolean
    ownsTexture()
     
    void
    setColor​(float r, float g, float b, float a)
    A convenience method for setting the font color.
    void
    setColor​(com.badlogic.gdx.graphics.Color color)
    A convenience method for setting the font color.
    void
    setFixedWidthGlyphs​(CharSequence glyphs)
    Makes the specified glyphs fixed width.
    void
    setOwnsTexture​(boolean ownsTexture)
    Sets whether the font owns the texture.
    void
    setUseIntegerPositions​(boolean integer)
    Specifies whether to use integer positions.
    String
    toString()
     
    boolean
    usesIntegerPositions()
    Checks whether this font uses integer positions for drawing.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • 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 without generating a bitmap font yourself.

    • 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 without generating a bitmap font yourself.
      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​(com.badlogic.gdx.files.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​(com.badlogic.gdx.files.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​(com.badlogic.gdx.files.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​(com.badlogic.gdx.files.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​(com.badlogic.gdx.files.FileHandle fontFile, com.badlogic.gdx.files.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​(com.badlogic.gdx.files.FileHandle fontFile, com.badlogic.gdx.files.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, com.badlogic.gdx.utils.Array<TextureRegion> pageRegions, 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 Details

    • load

      protected void load​(BitmapFont.BitmapFontData data)

    • draw

      public GlyphLayout draw​(ExtBatch batch, CharSequence str, float x, float y)
      Draws text at the specified position.
      See Also:
      BitmapFontCache.addText(CharSequence, float, float)

    • draw

      public GlyphLayout draw​(ExtBatch batch, CharSequence str, float x, float y, float targetWidth, int halign, boolean wrap)
      Draws text at the specified position.
      See Also:
      BitmapFontCache.addText(CharSequence, float, float, int, int, float, int, boolean, String)

    • draw

      public GlyphLayout draw​(ExtBatch batch, CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap)
      Draws text at the specified position.
      See Also:
      BitmapFontCache.addText(CharSequence, float, float, int, int, float, int, boolean, String)

    • draw

      public GlyphLayout draw​(ExtBatch batch, CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap, String truncate)
      Draws text at the specified position.
      See Also:
      BitmapFontCache.addText(CharSequence, float, float, int, int, float, int, boolean, String)

    • draw

      public void draw​(ExtBatch batch, GlyphLayout layout, float x, float y)
      Draws text at the specified position.
      See Also:
      BitmapFontCache.addText(CharSequence, float, float, int, int, float, int, boolean, String)

    • getColor

      public com.badlogic.gdx.graphics.Color getColor()
      Returns the color of text drawn with this font.

    • setColor

      public void setColor​(com.badlogic.gdx.graphics.Color color)
      A convenience method for setting the font color. The color can also be set by modifying getColor().

    • setColor

      public void setColor​(float r, float g, float b, float a)
      A convenience method for setting the font color. The color can also be set by modifying getColor().

    • 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 com.badlogic.gdx.utils.Array<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.

    • getSpaceXadvance

      public float getSpaceXadvance()
      Returns the x-advance 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 com.badlogic.gdx.utils.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.

    • setUseIntegerPositions

      public void setUseIntegerPositions​(boolean integer)
      Specifies whether to use integer positions. 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. 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

    • newFontCache

      public BitmapFontCache newFontCache()
      Creates a new BitmapFontCache for this font. Using this method allows the font to provide the BitmapFontCache implementation to customize rendering.

      Note this method is called by the BitmapFont constructors. If a subclass overrides this method, it will be called before the subclass constructors.

    • toString

      public String toString()
      Overrides:
      toString in class Object