Expand description
BMFont parsing library.
Manipulate, import and export BMFont 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 formatbinary
: binary formatxml
: 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);
Ok(())
}
Rendering fonts
The render.rs example, demonstrates a simple way to render font text to an image. Substituting your own graphics backend should not be too difficult.
To view the example’s output and for details on how to run it, kindly refer to the repository README.
Due to the numerous graphics back-ends and usage requirements, this crate makes no attempt at offering a universal rendering solution.
Serde
Font implements Serde’s serialize
and deserialize
traits.
These are feature gated and require: --features serde
.
JSON
The json.rs example demonstrates this.
For details on how to run the example, kindly refer to the repository README.
JSON is not natively supported. However, as we do support Serde, we can easily cobble together support with Serde JSON.
By default our Serde serializers map boolean types to JSON boolean types: true
and false
.
However, at least one JSON BMFont parser expects integer boolean types: 1
and 0
.
To facilitate the latter we can pass --features serde_boolint
, which casts boolean values to
integers and vice versa.
BMFont
The BMFont homepage is here. The site includes detailed documentation, BMFont itself and source code.
I am in no way affiliated with www.angelcode.com
or BMFont.
All trademarks belong to their respective owners.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Modules
Structs
Character description.
Character texture channel description.
Common character description.
Bitmap font descriptor.
Font information.
Kerning pair.
Font import behavior settings.
Character padding.
Character spacing.
Enums
Constants
ANSI character encoding.
Arabic character encoding.
Baltic character encoding.
Big5 Chinese character encoding.
Default character encoding.
Eastern Europe character encoding.
GB 2312 Chinese character encoding.
Greek character encoding.
Hangul character encoding.
Hebrew character encoding.
Johab Korean character encoding.
Max character encoding.
OEM character encoding.
Russian character encoding.
Shift JIS character encoding.
Symbol character encoding.
Thai character encoding.
Turkish character encoding.
Vietnamese character encoding.
Type Definitions
Error Result.