Package org.lwjgl.stb

Class 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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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.lang.CharSequence text)
      Takes a string and returns the vertical size (which can vary if text has newlines).
      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_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 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 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.lang.CharSequence text)
      Takes a string and returns the horizontal size.
      static int stb_easy_font_width​(java.nio.ByteBuffer 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)
        
        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)
        
        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)
        
        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