org.lwjgl.stb

Class STBEasyFont

java.lang.Object

org.lwjgl.stb.STBEasyFont

public class STBEasyFont
extends java.lang.Object

Native bindings to stb_easy_font.h from the stb library.

Bitmap font for use in 3D APIs:

• Easy-to-deploy
• reasonably compact
• extremely inefficient performance-wise
• crappy-looking
• ASCII-only

Intended for when you just want to get some text displaying in a 3D app as quickly as possible.

Doesn't use any textures, instead builds characters out of quads.

SAMPLE CODE

Here's sample code for old OpenGL; it's a lot more complicated to make work on modern APIs, and that's your problem.

 void print_string(float x, float y, char *text, float r, float g, float b)
 {
     static char buffer[99999]; // ~500 chars
     int num_quads;
 
     num_quads = stb_easy_font_print(x, y, text, NULL, buffer, sizeof(buffer));
 
     glColor3f(r,g,b);
     glEnableClientState(GL_VERTEX_ARRAY);
     glVertexPointer(2, GL_FLOAT, 16, buffer);
     glDrawArrays(GL_QUADS, 0, num_quads*4);
     glDisableClientState(GL_VERTEX_ARRAY);
 }

Method Summary

Modifier and Type	Method and Description
static int	nstb_easy_font_height(long text) Unsafe version of: easy_font_height
static int	nstb_easy_font_print(float x, float y, long text, long color, long vertex_buffer, int vbuf_size) Unsafe version of: easy_font_print
static int	nstb_easy_font_width(long text) Unsafe version of: easy_font_width
static int	stb_easy_font_height(java.nio.ByteBuffer text) Takes a string and returns the vertical size (which can vary if text has newlines).
static int	stb_easy_font_height(java.lang.CharSequence text) Takes a string and returns the vertical size (which can vary if text has newlines).
static int	stb_easy_font_print(float x, float y, java.nio.ByteBuffer text, java.nio.ByteBuffer color, java.nio.ByteBuffer vertex_buffer) Takes a string (which can contain '\n') and fills out a vertex buffer with renderable data to draw the string.
static int	stb_easy_font_print(float x, float y, java.lang.CharSequence text, java.nio.ByteBuffer color, java.nio.ByteBuffer vertex_buffer) Takes a string (which can contain '\n') and fills out a vertex buffer with renderable data to draw the string.
static void	stb_easy_font_spacing(float spacing) Use positive values to expand the space between characters, and small negative values (no smaller than -1.5) to contract the space between characters.
static int	stb_easy_font_width(java.nio.ByteBuffer text) Takes a string and returns the horizontal size.
static int	stb_easy_font_width(java.lang.CharSequence text) Takes a string and returns the horizontal size.

Methods inherited from class java.lang.Object

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

Method Detail

nstb_easy_font_width

public static int nstb_easy_font_width(long text)

Unsafe version of: easy_font_width

stb_easy_font_width

public static int stb_easy_font_width(java.nio.ByteBuffer text)

Takes a string and returns the horizontal size.

Parameters:

text - an ASCII string

Returns:

the horizontal size, in pixels

stb_easy_font_width

public static int stb_easy_font_width(java.lang.CharSequence text)

Takes a string and returns the horizontal size.

Parameters:

text - an ASCII string

Returns:

the horizontal size, in pixels

nstb_easy_font_height

public static int nstb_easy_font_height(long text)

Unsafe version of: easy_font_height

stb_easy_font_height

public static int stb_easy_font_height(java.nio.ByteBuffer text)

Takes a string and returns the vertical size (which can vary if text has newlines).

Parameters:

text - an ASCII string

Returns:

the vertical size, in pixels

stb_easy_font_height

public static int stb_easy_font_height(java.lang.CharSequence text)

Takes a string and returns the vertical size (which can vary if text has newlines).

Parameters:

text - an ASCII string

Returns:

the vertical size, in pixels

nstb_easy_font_print

public static int nstb_easy_font_print(float x,
                                       float y,
                                       long text,
                                       long color,
                                       long vertex_buffer,
                                       int vbuf_size)

Unsafe version of: easy_font_print

Parameters:

vbuf_size - the vertex_buffer size, in bytes

stb_easy_font_print

public static int stb_easy_font_print(float x,
                                      float y,
                                      java.nio.ByteBuffer text,
                                      @Nullable
                                      java.nio.ByteBuffer color,
                                      java.nio.ByteBuffer vertex_buffer)

Takes a string (which can contain '\n') and fills out a vertex buffer with renderable data to draw the string. Output data assumes increasing x is rightwards, increasing y is downwards.

The vertex data is divided into quads, i.e. there are four vertices in the vertex buffer for each quad.

The vertices are stored in an interleaved format:

 x:float
 y:float
 z:float
 color:uint8[4]

You can ignore z and color if you get them from elsewhere. This format was chosen in the hopes it would make it easier for you to reuse existing buffer-drawing code.

If you pass in NULL for color, it becomes 255,255,255,255.

If the buffer isn't large enough, it will truncate. Expect it to use an average of ~270 bytes per character.

If your API doesn't draw quads, build a reusable index list that allows you to render quads as indexed triangles.

Parameters:

x - the x offset

y - the y offset

text - an ASCII string

color - the text color, in RGBA (4 bytes)

vertex_buffer - a pointer to memory in which to store the vertex data

Returns:

the number of quads

stb_easy_font_print

public static int stb_easy_font_print(float x,
                                      float y,
                                      java.lang.CharSequence text,
                                      @Nullable
                                      java.nio.ByteBuffer color,
                                      java.nio.ByteBuffer vertex_buffer)

Takes a string (which can contain '\n') and fills out a vertex buffer with renderable data to draw the string. Output data assumes increasing x is rightwards, increasing y is downwards.

The vertex data is divided into quads, i.e. there are four vertices in the vertex buffer for each quad.

The vertices are stored in an interleaved format:

 x:float
 y:float
 z:float
 color:uint8[4]

You can ignore z and color if you get them from elsewhere. This format was chosen in the hopes it would make it easier for you to reuse existing buffer-drawing code.

If you pass in NULL for color, it becomes 255,255,255,255.

If the buffer isn't large enough, it will truncate. Expect it to use an average of ~270 bytes per character.

If your API doesn't draw quads, build a reusable index list that allows you to render quads as indexed triangles.

Parameters:

x - the x offset

y - the y offset

text - an ASCII string

color - the text color, in RGBA (4 bytes)

vertex_buffer - a pointer to memory in which to store the vertex data

Returns:

the number of quads

stb_easy_font_spacing

public static void stb_easy_font_spacing(float spacing)

Use positive values to expand the space between characters, and small negative values (no smaller than -1.5) to contract the space between characters.

E.g. spacing = 1 adds one "pixel" of spacing between the characters. spacing = -1 is reasonable but feels a bit too compact to me; -0.5 is a reasonable compromise as long as you're scaling the font up.

Parameters:

spacing - the font spacing