Class BitmapFont

  • All Implemented Interfaces:
    com.badlogic.gdx.utils.Disposable

    public class BitmapFont
    extends java.lang.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! :)

    • 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

      All Methods Instance Methods Concrete Methods 
      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, java.lang.CharSequence str, float x, float y)
      Draws text at the specified position.
      GlyphLayout draw​(ExtBatch batch, java.lang.CharSequence str, float x, float y, float targetWidth, int halign, boolean wrap)
      Draws text at the specified position.
      GlyphLayout draw​(ExtBatch batch, java.lang.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, java.lang.CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap, java.lang.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​(java.lang.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.
      java.lang.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 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 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 Detail

      • 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​(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.
      • 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
      • 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object