LWJGL stb bindings

OpenGL Development
#1

The latest LWJGL 3 nightly build (#49) now features bindings to the stb collection of “single-file public domain libraries for C/C++”. Not everything is supported, only libraries that make sense in Java and are lightweight enough for LWJGL.

The main motivation for adding these bindings was to allow LWJGL users to get rid of any dependencies to AWT (e.g. for loading fonts or images). There are many other options of course, but stb is a solution that was very easy to support and should cover most needs. It is developed by Sean Barrett (works at RAD Game Tools), written in pure C, with functionality focused on game development.

LWJGL includes the following bindings (under the org.lwjgl.stb package):

STBEasyFont (demo)

A quick-and-dirty solution for getting some text rendered in the simplest possible way. It provides a function that converts an ASCII string to an array of GL_QUADS, which you can then render any way you like. It's essentially a monospaced bitmap font.

It’s obviously very inefficient, but you can cache the generated geometry.

STBTruetype (simple demo - advanced demo)

Parses .ttf files, returns font/glyph metrics and rasterizes fonts to packed textures.

The API is simple, but this is an advanced library; line metrics, glyph metrics, kerning, pixel snapping, oversampling for small test sizes, subpixel positioning, everything you need is here. Make sure to read this guide on oversampling. The “advanced demo” above is an LWJGL port of the “oversample” test in the stb repository.

STBRectPack

Can be used to pack rectangular textures into an atlas. It implements the Skyline Bottom-Left algorithm and is used internally by STBTruetype for the glyph packing.

STBImage (demo)

An image loading library. Supports the following image file formats:
  • JPEG baseline & progressive (12 bpc/arithmetic not supported, same as stock IJG lib)
  • PNG 1/2/4/8/16-bit-per-channel
  • TGA (not sure what subset, if a subset)
  • BMP non-1bpp, non-RLE
  • PSD (composited view only, no extra channels, 8/16 bit-per-channel)
  • GIF (*desired_channels always reports as 4-channel)
  • HDR (radiance rgbE format)
  • PIC (Softimage PIC)
  • PNM (PPM and PGM binary only)

STBImageResize

High-quality image resizing. It's sRGB-aware, alpha-aware, supports different edge wrap modes and a variety of filters (including cubic and Mitchell-Netrevalli).

If you’re using glGenerateMipmap or aren’t doing gamma correct mipmap generation, you really really want to use this.

STBImageWrite

Simple library for writing image files. Supports:
  • PNG
  • BMP
  • TGA
  • HDR

It is meant for saving screenshots to disk, so it is optimized for encoding speed, not compression ratio.

STBDXT

A real-time DXT1/DXT5 compressor. If you need to compress textures at runtime, this should provide better quality than the compression done by OpenGL drivers.

STBVorbis (demo)

An Ogg Vorbis audio decoder. Seeking is not properly implemented yet, only "rewind" works.

STBPerlin

Computes Perlin's revised noise function (3D input, 1D output). I'm not sure how this performs in terms of speed and quality; if anyone tests it, please post here.

General notes

Try to avoid the "filename" APIs (in STBImage, STBImageWrite and STBVorbis), they do not support unicode paths atm (on Windows). Better use standard Java IO to load the files in memory and use the corresponding APIs.

I haven’t had the time to test everything, let me know if you encounter any issues. You can see a video of some of the above here (GIF, 7.43 MB).

#2

@Spasi, all the Github links from this page are now 404’ing.

#3

Thanks, fixed.

#4

Awesome stuff. Much appreciated.

#5

The latest nightly build includes an updated font rasterizer, as described here: How the stb_truetype Anti-Aliased Software Rasterizer v2 Works

#6

Most of the examples for the TrueType usage seem to be using an outdated API that more closely resembles the C version. Also it uses the fixed pipeline for drawing the quads. Is there better documentation that I can find or better examples?

#7

[quote=“zeejfps,post:6,topic:54537”]
There are functions in stb_truetype that can be used to render text in a few different ways. Which ones you use depends on the level of quality, performance and customization you’re interested in. There’s no outdated API afaik. The Truetype demo uses the simple stbtt_BakeFontBitmap/stbtt_GetBakedQuad and the TruetypeOversample demo uses the higher quality stbtt_PackFontRanges/stbtt_GetPackedQuad. Neither demo handles codepoint kerning (not all fonts come with kerning information), but it’s easy to add.

[quote=“zeejfps,post:6,topic:54537”]
The purpose of these demos is to provide sample usage of the stb_truetype API. How to best render the quads is a generic OpenGL question and not specific to font rendering. They’re just simple quads with a position and a texcoord. The answer will depend on the application and how much caching (of character sequences) it is able to do.

[quote=“zeejfps,post:6,topic:54537”]
There’s plenty of javadoc in the STBTruetype class. Also, reading this will be useful.

#8

Thanks for the reply. I realized I am an idiot, my lwjgl wasn’t the latest nightly build so the API differed.

#9

Links are dead! Please update them, thanks :wink:

#10

Thanks, fixed.