bmfont_rs

2 unstable releases

0.2.0	Jun 24, 2022
0.1.0	Sep 10, 2021

#1941 in Parser implementations

33 downloads per month

MIT/Apache

150KB
3.5K SLoC

BMFont font descriptor parsing library.

Manipulate, import and export BMFont descriptor files in text, binary, XML formats and more.

Overview

This crate provides building, manipulation, import, and export functions for BMFont descriptor files.

The core data object is the Font. This struct holds, in its entirety, the data contained within a BMFont descriptor file. When paired with the associated texture bitmap file/s, we have the information required to render the font in question.

Due to the numerous graphics backends and usage requirements, this crate does not attempt to offer a universal rendering solution.

This crate contains no unsafe code. Also, unless specified by compilation switches, it doesn't pull in any external dependencies.

Basic usage

The modules are organized around the core BMFont file formats:

text : text format
binary : binary format
xml : XML format, requires: --features xml

Each module is provides a number of import from_... and export: to_... functions.

To use:

Select the desired BMFont format you want to work with.
Select the appropriate from/ to methods based on the data structures you want to work with.

Example: import a BMFont text format file.

use std::io;
use std::io::prelude::*;
use std::fs;

fn main() -> bmfont_rs::Result<()> {
    let mut buf = fs::read("font.fnt")?;
    let font = bmfont_rs::text::from_bytes(&buf)?;
    println!("{:?}", font);
    Ok(())
}

Example: export a BMFont text format file.

use std::io;
use std::io::prelude::*;
use std::fs::File;

fn main() -> bmfont_rs::Result<()> {
    let font = bmfont_rs::Font::default();
    let mut writer = File::create("font.fnt")?;
    bmfont_rs::text::to_writer(&mut writer, &font)?;
    Ok(())
}

Advanced usage - broken files

Unfortunately, there exist several BMFont tools that output broken files. Either they do not comply with the BMFont standard as written or contain other errors. When attempting to load these files, bmfont_rs will emit an error describing the problem.

We may be able to work around or ignore some of these problems using the LoadSettings struct. Simply build the LoadSettings instance using the desired behavior switches and pass it into the ext form of the load function.

If you encounter a BMFont file that appears to work with other tools, but not bmfont_rs then kindly open a ticket. It may be possible to add the correct behavior switch in future versions of bmfont_rs.

Example: import a BMFont text file with incorrect character counts.

use std::io;
use std::io::prelude::*;
use std::fs;

fn main() -> bmfont_rs::Result<()> {
    let src = fs::read_to_string("font.txt")?;
    let settings = bmfont_rs::LoadSettings::default().ignore_counts();
    let font = bmfont_rs::text::from_str_ext(&src, &settings)?;
    println!("{:?}", font);
}

Examples: render

Alt text

The above text was generated with the render.rs example.

If you are uncertain how one might use a BMFont descriptor to render output, this example would be worth studying. Substituting your own graphics backend should not be too difficult.

Due to the numerous graphics backends and usage requirements, this crate makes no attempt at offering a universal rendering solution.