Package org.lazywizard.lazylib.ui

Class LazyFont

Object

LazyFont

public class LazyFont
extends Object

An efficiently drawable bitmap font implementation. May not be a pixel-perfect match to Starsector's implementation.

Basic Usage:

• Load a font with loadFont(String). This can be kept around safely without worrying about memory usage - the underlying texture makes up the bulk of the size, and that is only loaded once per unique font and stored in a global cache. LazyFont itself only contains font metadata used for rendering, and is relatively lightweight.
• Using said font object, create a LazyFont.DrawableString with createText(String, Color, float, float, float). This methods arguments determine how the text will appear and any size restrictions the block of text should be given. These can all be changed later by calling methods directly on the returned LazyFont.DrawableString.
• Draw the text where you need it with LazyFont.DrawableString.draw(float, float) once per frame.
• That's it! So long as you keep a reference to the LazyFont.DrawableString, you can re-draw the text extremely efficiently, or edit/append the text at will. Editing the LazyFont.DrawableString in any way will cause a full rebuild of its GPU-buffered data the next time you call LazyFont.DrawableString.draw(float, float), though the performance impact should be minimal even with extremely long text blocks.
• When finished using the LazyFont.DrawableString, optionally call LazyFont.DrawableString.dispose() to ensure its underlying OpenGL resources are cleaned up immediately. Ensure you don't call LazyFont.DrawableString.draw(float, float) after calling LazyFont.DrawableString.dispose() or your game will crash!

Example Usage:

 package data.scripts.plugins;

 import com.fs.starfarer.api.Global;
 import com.fs.starfarer.api.combat.BaseEveryFrameCombatPlugin;
 import com.fs.starfarer.api.combat.CombatEngineAPI;
 import com.fs.starfarer.api.combat.ViewportAPI;
 import org.lazywizard.lazylib.ui.FontException;
 import org.lazywizard.lazylib.ui.LazyFont;
 import org.lwjgl.input.Mouse;

 import java.awt.*;

 public class LazyFontExample extends BaseEveryFrameCombatPlugin
 {
     private LazyFont.DrawableString toDraw;

     // Set up the font and the DrawableString; only has to be done once
     @Override
     public void init(CombatEngineAPI engine)
     {
         // Load the chosen .fnt file
         // Fonts are cached globally, so it's acceptable for each class using the same
         // font to request their own copy of it - they will all share the underlying data
         final LazyFont font;
         try
         {
             font = LazyFont.loadFont("graphics/fonts/insignia15LTaa.fnt");
         }
         // FontException is thrown if the .fnt file does not exist or has malformed data
         catch (FontException ex)
         {
             Global.getLogger(this.getClass()).error("Failed to load font", ex);
             engine.removePlugin(this);
             return;
         }

         // Create a renderable block of text
         // In this case, the text will font size 15, and default to yellow text
         toDraw = font.createText("This is some sample text.", Color.YELLOW, 15f);

         // Enable line wrapping when text reaches 400 pixels wide
         toDraw.setMaxWidth(400f);

         // If you need to add text to the DrawableString, do so like this:
         toDraw.append("\nThis is a second line of sample text. It will be drawn orange.", Color.ORANGE);
         toDraw.append("\nThis is a third line of sample text that shows off the automatic" +
                 " word wrapping when a line of text reaches the maximum width you've chosen.\n" +
                 "Since this append doesn't have a color attached, it will return to the original yellow.);
         toDraw.append("You can also chain appends,").append(" like this," Color.BLUE)
                 .append(" to make writing text easier.");
     }

     @Override
     public void renderInUICoords(ViewportAPI view)
     {
         // Call draw() once per frame to render the text
         // In this case, draw the text slightly below the mouse cursor
         // The draw point is the top left corner of the textbox, so we adjust the X
         // position to center the text horizontally below the mouse cursor
         if (toDraw != null) // Needed to work around a vanilla combat plugin bug when loading the campaign
         {
             toDraw.draw(Mouse.getX() - (toDraw.getWidth() / 2f), Mouse.getY() - 30f);
         }
     }
 }
 

Since:

2.3

Author:

LazyWizard

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	LazyFont.DrawableString	Represents an efficiently redrawable block of text.
class	LazyFont.LazyChar	Keeps track of the metadata for each supported character in a font.
static enum	LazyFont.TextAlignment	Represents the alignment of text within a LazyFont.DrawableString's render area.
static enum	LazyFont.TextAnchor	Represents the origin of drawing for LazyFont.DrawableStrings.

Method Summary

Modifier and Type	Method	Description
String	buildUntilLimit(String rawLine, float fontSize, float maxWidth)	Returns the longest String that will fit within a single line, given the space limits passed in.
float	calcWidth(String rawLine, float fontSize)	Returns the raw width of a String at a specific font size, without taking into account word wrapping.
LazyFont.DrawableString	createText()	Create a LazyFont.DrawableString with no text, ready for appending.
LazyFont.DrawableString	createText(String text)	Create a LazyFont.DrawableString with the specified initial text.
LazyFont.DrawableString	createText(String text, Color baseColor)	Create a LazyFont.DrawableString with the specified initial text and color.
LazyFont.DrawableString	createText(String text, Color baseColor, float size)	Create a LazyFont.DrawableString with the specified initial text, color, and font size, with no text wrapping.
LazyFont.DrawableString	createText(String text, Color baseColor, float size, float maxWidth)	Create a LazyFont.DrawableString with the specified initial text, color, and font size, with text wrapping.
LazyFont.DrawableString	createText(String text, Color baseColor, float size, float maxWidth, float maxHeight)	Create a LazyFont.DrawableString with the specified initial text, color, and font size, with text wrapping and a max height - any appended text past that limit will be discarded.
float	getBaseHeight()	Returns the base height of the underlying font.
LazyFont.LazyChar	getChar(char character)	Returns font metadata for a specific character.
String	getFontName()	Returns the name of the font, as defined in its .fnt file.
float	getTextureHeight()	Returns the height of the font's underlying texture atlas.
int	getTextureId()	Returns the ID of the font's underlying texture atlas.
float	getTextureWidth()	Returns the width of the font's underlying texture atlas.
static LazyFont	loadFont(String fontPath)	Loads a bitmap font and returns the LazyFont representation.
String	wrapString(String toWrap, float fontSize, float maxWidth)	Returns the word-wrapping that would be done to a block of text to fit it within a specific area at a specific font size.
String	wrapString(String toWrap, float fontSize, float maxWidth, float maxHeight)	Returns the word-wrapping that would be done to a block of text to fit it within a specific area at a specific font size.
String	wrapString(String toWrap, float fontSize, float maxWidth, float maxHeight, int indent)	Returns the word-wrapping that would be done to a block of text to fit it within a specific area at a specific font size.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

loadFont

@NotNull
public static LazyFont loadFont(String fontPath)
                         throws FontException

Loads a bitmap font and returns the LazyFont representation. This method caches loaded fonts, so only one LazyFont will exist for each font file loaded, and subsequent calls will be near instantaneous.

Parameters:

fontPath - The relative path to the .fnt file (ex: "graphics/fonts/insignia15LTaa.fnt").

Returns:

A LazyFont representation of the bitmap font at fontPath.

Throws:

FontException - If there's no font found at fontPath or the data in the font is malformed.

Since:

2.3

buildUntilLimit

@NotNull
public String buildUntilLimit(String rawLine,
 float fontSize,
 float maxWidth)

Returns the longest String that will fit within a single line, given the space limits passed in. This can and will return a String ending with a partial word. For proper word-wrapping, use wrapString(String, float, float, float) instead.

Parameters:

rawLine - The text to be measured. This should be a single line of text with no newlines.

fontSize - The font size the text would be rendered at.

maxWidth - The max width of the text area. Text will be cut off at the last character that fit within this width.

Returns:

The longest substring of rawLine that will fit within a single line of up to maxWidth width.

Since:

3.0

wrapString

@NotNull
public String wrapString(String toWrap,
 float fontSize,
 float maxWidth,
 float maxHeight,
 int indent)

Returns the word-wrapping that would be done to a block of text to fit it within a specific area at a specific font size. Can be used alongside calcWidth(String, float) to determine the size of a block of rendered text without needing the expense of building a LazyFont.DrawableString first.

Parameters:

toWrap - The text to be word-wrapped.

fontSize - The font size the text would be rendered at.

maxWidth - The max width of the text area. Text will be wrapped at the last word that fit within this width.

maxHeight - The max height of the text area. Text beyond this will be discarded.

indent - The number of empty spaces at the start of each line. Used by LazyFont.DrawableString.appendIndented(String, int) and LazyFont.DrawableString.appendIndented(String, Color, int).

Returns:

toWrap, wrapped to fit within the area specified by maxWidth and maxHeight.

Since:

2.3

wrapString

@NotNull
public String wrapString(String toWrap,
 float fontSize,
 float maxWidth,
 float maxHeight)

Returns the word-wrapping that would be done to a block of text to fit it within a specific area at a specific font size. Can be used alongside calcWidth(String, float) to determine the size of a block of rendered text without needing the expense of building a LazyFont.DrawableString first.

Parameters:

toWrap - The text to be word-wrapped.

fontSize - The font size the text would be rendered at.

maxWidth - The max width of the text area. Text will be wrapped at the last word that fit within this width.

maxHeight - The max height of the text area. Text beyond this will be discarded.

Returns:

toWrap, wrapped to fit within the area specified by maxWidth and maxHeight.

Since:

2.3

wrapString

@NotNull
public String wrapString(String toWrap,
 float fontSize,
 float maxWidth)

Returns the word-wrapping that would be done to a block of text to fit it within a specific area at a specific font size. Can be used alongside calcWidth(String, float) to determine the size of a block of rendered text without needing the expense of building a LazyFont.DrawableString first.

Parameters:

toWrap - The text to be word-wrapped.

fontSize - The font size the text would be rendered at.

maxWidth - The max width of the text area. Text will be wrapped at the last word that fit within this width.

Returns:

toWrap, wrapped to fit within the area specified by maxWidth.

Since:

2.3

getBaseHeight

public float getBaseHeight()

Returns the base height of the underlying font. Rendered text will look best when drawn at an evenly divisible ratio of this value.

Returns:

The base height of the font, in pixels.

Since:

2.3

getTextureHeight

public float getTextureHeight()

Returns the height of the font's underlying texture atlas.

Returns:

The height of the underlying texture atlas, in pixels.

Since:

2.3

getTextureWidth

public float getTextureWidth()

Returns the width of the font's underlying texture atlas.

Returns:

The width of the underlying texture atlas, in pixels.

Since:

2.3

getTextureId

public int getTextureId()

Returns the ID of the font's underlying texture atlas. Equivalent to calling SpriteAPI.getTextureId().

Returns:

The ID of the underlying texture atlas.

Since:

2.3

calcWidth

public float calcWidth(String rawLine,
 float fontSize)

Returns the raw width of a String at a specific font size, without taking into account word wrapping.

Parameters:

rawLine - The String to measure.

fontSize - The font size the String would be rendered at.

Returns:

The width of rawLine if drawn with size fontSize, not taking word wrapping into account.

Since:

2.3

getFontName

@NotNull
public String getFontName()

Returns the name of the font, as defined in its .fnt file.

Returns:

The name of the loaded font.

Since:

2.5b

getChar

@NotNull
public LazyFont.LazyChar getChar(char character)

Returns font metadata for a specific character. If the font does not support the character, data for '?' is returned instead.

Parameters:

character - The character to look up.

Returns:

A LazyFont.LazyChar containing metadata for how the font handles character, or metadata for '?' if that character is not supported by the font.

Since:

2.3

createText

@NotNull
public LazyFont.DrawableString createText(String text,
 Color baseColor,
 float size,
 float maxWidth,
 float maxHeight)

Create a LazyFont.DrawableString with the specified initial text, color, and font size, with text wrapping and a max height - any appended text past that limit will be discarded.

Parameters:

text - The initial text to be drawn. You can modify it later using the returned LazyFont.DrawableString.

baseColor - The base color of the drawn text (color of appended text that doesn't have its own color argument passed in).

size - The font size of the drawn text. For best results, this should be evenly divisible by getBaseHeight(). Other values may cause slight blurriness or jaggedness.

maxWidth - The maximum width of the drawn text before further text will be wrapped to a new line.

maxHeight - The maximum height of the drawn text. All further text past this point will be discarded.

Returns:

A LazyFont.DrawableString with the specified text, color, and font size, with text wrapping at maxWidth, and a max height of maxHeight.

Since:

2.3

createText

@NotNull
public LazyFont.DrawableString createText(String text,
 Color baseColor,
 float size,
 float maxWidth)

Create a LazyFont.DrawableString with the specified initial text, color, and font size, with text wrapping.

Parameters:

text - The initial text to be drawn. You can modify it later using the returned LazyFont.DrawableString.

baseColor - The base color of the drawn text (color of appended text that doesn't have its own color argument passed in).

size - The font size of the drawn text. For best results, this should be evenly divisible by getBaseHeight(). Other values may cause slight blurriness or jaggedness.

maxWidth - The maximum width of the drawn text before further text will be wrapped to a new line.

Returns:

A LazyFont.DrawableString with the specified text, color, and font size, with text wrapping at maxWidth.

Since:

2.3

See Also:

• createText(String, Color, float, float, float)

createText

@NotNull
public LazyFont.DrawableString createText(String text,
 Color baseColor,
 float size)

Create a LazyFont.DrawableString with the specified initial text, color, and font size, with no text wrapping.

Parameters:

text - The initial text to be drawn. You can modify it later using the returned LazyFont.DrawableString.

baseColor - The base color of the drawn text (color of appended text that doesn't have its own color argument passed in).

size - The font size of the drawn text. For best results, this should be evenly divisible by getBaseHeight(). Other values may cause slight blurriness or jaggedness.

Returns:

A LazyFont.DrawableString with the specified text, color, and font size, with no text wrapping.

Since:

2.3

See Also:

• createText(String, Color, float, float, float)

createText

@NotNull
public LazyFont.DrawableString createText(String text,
 Color baseColor)

Create a LazyFont.DrawableString with the specified initial text and color. Defaults to the base font size, and no text wrapping.

Parameters:

text - The initial text to be drawn. You can modify it later using the returned LazyFont.DrawableString.

baseColor - The base color of the drawn text (color of appended text that doesn't have its own color argument passed in).

Returns:

A LazyFont.DrawableString with the specified text and color, the base font size, and no text wrapping.

Since:

2.3

See Also:

• createText(String, Color, float, float, float)

createText

@NotNull
public LazyFont.DrawableString createText(String text)

Create a LazyFont.DrawableString with the specified initial text. Defaults to white text, the base font size, and no text wrapping.

Parameters:

text - The initial text to be drawn. You can modify it later using the returned LazyFont.DrawableString.

Returns:

A LazyFont.DrawableString with the specified text, white color, the base font size, and no text wrapping.

Since:

2.3

See Also:

• createText(String, Color, float, float, float)

createText

@NotNull
public LazyFont.DrawableString createText()

Create a LazyFont.DrawableString with no text, ready for appending. Defaults to white text, the base font size, and no text wrapping.

Returns:

An empty LazyFont.DrawableString with white text, the base font size, and no text wrapping.

Since:

2.3

See Also:

• createText(String, Color, float, float, float)