Struct tetra::graphics::text::BmFontBuilder

pub struct BmFontBuilder { /* fields omitted */ }

A builder for fonts stored in the AngelCode BMFont format.

Currently, only the text format is supported. Support for the binary file format may be added in the future.

Font::bmfont provides a simpler API for loading vector fonts, if you don’t need all of the functionality of this struct.

Exporting from BMFont

For best results, follow these guidelines when exporting from BMFont:

Font Settings

• For the sizing to match the TTF version of the same font, tick ‘match char height’.

Export Options

• Unless you are using a custom shader, choose the ‘white text with alpha’ preset.
• Export using the ‘text’ font descriptor format.
• Make sure the corresponding Tetra feature flag is enabled for your texture’s file format.

Performance

Creating or cloning a BmFontBuilder can be expensive, depending on how many images you load into it.

The data is not internally reference-counted (unlike some other Tetra structs like VectorFontBuilder), as you’ll generally only use a BmFontBuilder once. This allows the builder’s buffers to be re-used by the created Font.

Implementations

impl BmFontBuilder

pub fn new<P>(path: P) -> Result<BmFontBuilder> where
    P: AsRef<Path>, 

Loads a BMFont from the given file.

By default, the image directory will be set to the same directory as the font itself.

Errors

• TetraError::FailedToLoadAsset will be returned if the file could not be loaded.

pub fn from_file_data<D>(data: D) -> BmFontBuilder where
    D: Into<String>, 

Loads a BMFont from a string.

As a BMFont only contains relative paths, you will need to specify an image directory and/or page data in order for the font to successfully build.

pub fn with_image_dir<P>(self, path: P) -> BmFontBuilder where
    P: Into<PathBuf>, 

Sets the directory to search for the font’s image files.

This will automatically be set if the builder was created via new, but can be overridden.

If all of the font’s pages are manually loaded via the other builder methods, this path will be ignored.

pub fn with_page<P>(self, id: u32, path: P) -> Result<BmFontBuilder> where
    P: AsRef<Path>, 

Loads an image for the specified page of the font.

This will override the path specified in the font itself.

Errors

• TetraError::FailedToLoadAsset will be returned if a file could not be loaded.
• TetraError::InvalidTexture will be returned if some of the image data was invalid.

pub fn with_page_file_data(self, id: u32, data: &[u8]) -> Result<BmFontBuilder>

Sets the image for the specified page of the font, using data encoded in one of Tetra’s supported image file formats.

The format of the data will be determined based on the ‘magic bytes’ at the beginning of the data. Note that TGA files do not have recognizable magic bytes, so this function will not recognize them.

This will override the path specified in the font itself.

Errors

• TetraError::InvalidTexture will be returned if the image data was invalid.

pub fn with_page_image_data(self, id: u32, data: ImageData) -> BmFontBuilder

Sets the image for the specified page of the font, using decoded image data.

This will override the path specified in the font itself.

pub fn with_page_rgba<D>(
    self,
    id: u32,
    width: i32,
    height: i32,
    data: D
) -> Result<BmFontBuilder> where
    D: Into<Vec<u8>>, 

Sets the image for the specified page of the font, using RGBA data.

This will override the path specified in the font itself.

Errors

• TetraError::NotEnoughData will be returned if not enough data is provided to fill the texture.

pub fn build(self, ctx: &mut Context) -> Result<Font>

Builds the font.

Any pages that have not had their images manually set will be loaded from the path specified by with_image_dir.

Errors

• TetraError::FailedToLoadAsset will be returned if a file could not be loaded.
• TetraError::InvalidTexture will be returned if some of the image data was invalid.
• TetraError::InvalidFont will be returned if the font definition was invalid, or if there was no path specified for one of the image files.
• TetraError::PlatformError will be returned if the GPU cache for the font could not be created.

Trait Implementations

impl Clone for BmFontBuilder

fn clone(&self) -> BmFontBuilder

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BmFontBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.