Skip to content

Bitmap Font

Jump to bottom
Hapaxia edited this page Jul 18, 2017 · 9 revisions

Introduction

A bitmap font resource designed for use with Selba Ward's Bitmap Text.

Usage

Declaration

sw::BitmapFont font;

Setup

The basic setup is to set (or load) the texture, set the number of tiles per row in that texture, and set the default texture rectangle.

  • setExternalTexture(const sf::Texture&)
    sets the font to use the given sf::Texture. This does not store a copy of the texture and the texture must exist as long as the font uses it

  • loadTexture(const std::string& filename)
    loads the texture at the given filename and stores it inside the font object

  • setSmooth(bool)
    sets whether the texture is smoothed or not. This only applies to an internal texture; if the font is using an external texture, this is redundant

  • setNumberOfTilePerRow(unsigned int)
    sets the number of tiles per row in the texture

  • setDefaultTextureRect(const sf::IntRect&)
    sets the default texture rectangle to be used for each glyph when a customised rectangle is not set for that specific glyph.

Exceptions

By default, a Bitmap Font will throw exceptions (of type sw::Exception - see Selba Ward Setup) following an error. This can be disabled/re-enabled by using setThrowExceptions(bool). If exceptions are disabled, errors are ignored and the code that was attempted will simply be skipped. In the case of a method that has a return value, it will simply return a default value. This may not be the expected result so enabling exceptions are recommended (during development).

Output

Bitmap Font provides ways of outputting information about the font.

There are five ways to return something from a font:

  • getThrowExceptions(bool)
    returns a boolean that is true if the font has exceptions enabled (see Exceptions above)

  • getTexture()
    returns a pointer to the sf::Texture that it is using, which could be either an external texture or its internal texture

  • getGlyph(unsigned int glyphIndex)
    returns a glyph (type BitmapFont::Glyph) copied from the glyph specified by the glyphIndex. If the parameter is omitted, the index used is zero

  • getNumberOfGlyphs()
    returns an unsigned int representing the number of glyphs in the font (currently set to 256 and unchangable)

  • getKerning(std::string)
    returns an unsigned int representing the required kerning for the given glyph pair, which is provided via an std::string with a length of two

Customising

Glyphs' texture rect, baselines, widths and starting x position can be customised per glyph. This can be done singularly or batched.

Texture Rectangles:

  • setDefaultTextureRect(const sf::IntRect&)
    as shown in the basic setup above, this sets the default texture rectangle to be used for each glyph when a customised rectangle is not set for that specific glyph.

  • setTextureRect(const sf::IntRect&, unsigned int glyphIndex)
    sets the texture rectangle for the glyph specified by the glyphIndex. If the glyphIndex is omitted, it applies to the first glyph (glyph index of zero)

  • setTextureRects(const std::vector<sf::IntRect>&, unsigned int initialGlyphIndex)
    sets the texture rectangles for the glyphs starting from initialGlyphIndex - one rectangle per glyph

  • clearTextureRect(unsigned int glyphIndex)
    clears the texture rectangle for the specified glyph. Clearing a texture rectangle causes it to remove the texture rectangle customisation and use the default rectangle instead

  • clearAllTextureRects()
    clears all texture rectangles

Resetting Glyphs:

  • setGlyphToDefault(unsigned int glyphIndex)
    sets the specified glyph to its default state, which also uses the default texture rectangle

  • setGlyphsToDefault(unsigned int numberOfGlyphs, unsigned int glyphIndex)
    sets the number of glyphs starting from the specified glyph to their default state

  • setAllGlyphsToDefault()
    set all glyphs to their default state

Glyph Attributes:

If a glyphIndex is omitted, an index of zero is used.
If a numberOfGlyphs is omitted, a number of one is used.

  • setBaseline(int baseline, unsigned int glyphIndex)
    sets the baseline for the specified glyph

  • setWidth(int width, unsigned int glyphIndex)
    sets the width of the specified glyph

  • setStartX(int startX, unsigned int glyphIndex)
    sets the starting x position of the specified glyph

Batch manipulation:

  • setBaselines(int baseline, unsigned int numberOfGlyphs, unsigned int initialGlyphIndex)
  • setWidths(int width, unsigned int numberOfGlyphs, unsigned int initialGlyphIndex)
  • setStartXs(int startX, unsigned int numberOfGlyphs, unsigned int initialGlyphIndex)

sets the attribute for the number of glyphs specified, starting from the initial index

  • setBaselines(const std::vector<int>& baselines, unsigned int initialGlyphIndex)
  • setWidths(const std::vector<int>& widths, unsigned int initialGlyphIndex)
  • setStartXs(const std::vector<int>& startXs, unsigned int initialGlyphIndex)

sets the attributes for the glyphs starting from the initial index - one attribute per glyph

  • setBaseline(int baseline, const std::string& glyphs)
  • setWidth(int width, const std::string& glyphs)
  • setStartX(int startXs, const std::string& glyphs)

sets the attribute for all glyphs represented by a character in the string

Kerning :

  • setKerning(int kerning, const std::string& glyphPairs)
    sets the kerning for the given glyph pairs (the string parameter should have a length that is a multiple of 2)

  • setKerning(int kerning, const std::vector<std::string>& glyphPairs)
    sets the kerning for the given glyph pairs (each string in the vector must have a length of 2)

Displaying

This is a font class, not a text class, so it cannot be drawn directly. It returns a pointer to the texture that it is set up to use and returns information about its glyphs. You can use this information to display the correct part of the texture based on the text you would like to display.
Selba Ward also includes Bitmap Text that is a drawable text class that uses a Bitmap Font to provide the font.

Simple Example

#include <SFML/Graphics.hpp>
#include <SelbaWard/BitmapText.hpp>
#include <iostream>
int main()
{
    sf::RenderWindow window(sf::VideoMode(250, 40), "Bitmap Font/Bitmap Text simple example");
    sw::BitmapFont font;
    sw::BitmapText text;
    sf::Texture fontTexture;
    if (!fontTexture.loadFromFile("resources/Selba Ward Bitmap Font 0001.png")) // available from https://github.com/Hapaxia/SelbaWard/tree/master/examples/resources
    {
        std::cout << "Could not load font texture." << std::endl;
        return EXIT_FAILURE;
    }
    font.setExternalTexture(fontTexture);
    font.setNumberOfTilesPerRow(16);
    font.setDefaultTextureRect({ 0, 0, 8, 8 });
    text.setBitmapFont(font);
    text.setString("This is a bitmap font.");
    text.setPosition({ 10, 20 });
    while (window.isOpen())
    {
        sf::Event event;
        while (window.pollEvent(event))
        {
            if (event.type == sf::Event::Closed)
                window.close();
        }
        window.clear();
        window.draw(text);
        window.display();
    }
    return EXIT_SUCCESS;
}

The code above displays a single string displayed using a bitmap font:
Simple Example

Note: the texture for this example is available, along with more examples, in the examples folder, although you can use your own images.

(Bitmap Font v1.1)

Clone this wiki locally