Texture-less Text Rendering

Sometimes, all you want is to quickly print some text into a Renderpass. But traditionally, drawing text requires you first to render all possible glyphs of a font into an atlas, to bind this atlas as a texture, and then to render glyphs one by one by drawing triangles on screen, with every triangle picking the correct glyph from the font atlas texture.

This is how imgui does it, how anyone using stb_truetype does it, and it’s delightfully close to how type setting used to be done ages bygone on physical letterpresses.

In case you wonder – yes

That’s enough (ed).

Quaint, correct, but also quite cumbersome.

What if – for quick and dirty debug messaging – there was a simpler way to do this?

Here, I’ll describe a technique for texture-less rendering of debug text. On top of it all, it draws all the text in a single draw call.

The Font: Pixels Sans Texture 

How can we get rid of the font atlas texture? We’d need to store a font atlas or something similar directly inside the fragment shader. Obviously, we can’t store bitmaps inside our shaders, but we can store integer constants, which, if you squint hard enough, are nothing but maps of bits. Can we pretend that an integer is a bitmap?

We can draw this to the screen using a GLSL fragment shader by mapping a fragment’s xy position to the bit that is covered by it in the “bitmap”. If the bit is set, we draw in the foreground colour. If the bit is not set, we draw in the background colour.

1 2 3 4 5 6 7 8 9

uint bitmap = 0x42; vec4 col_fg = vec4(1,1,1,1); vec4 col_bg = vec4(0,0,0,1); // vec2 uv is the normalized texture coordinate for the fragment // with the origin top-left uint which_bit = 7 - min(7,floor(uv.x * 8)); out_color = mix(col_bg, col_fg, (bitmap >> which_bit) & 1);

glsl

Now, one byte will only draw one line of pixels for us. If we want to draw nicer glyphs, we will need more bytes. If we allowed 16 bytes (that’s 16 lines) per glyph, this would give us an 8×16 pixel canvas to work with. A single uvec4, which is a built-in type in GLSL, covers exactly the correct amount of bytes that we need.

16 bytes per glyph seems small enough; It should allow us to encode the complete ASCII subset of 96 printable glyphs in all of 1536 bytes of shader memory. (We could probably compress this further, but we would lose simplicity and/or readability).

Where do we get the bitmaps from? 

Conveniently, the encoding of a font into bitmaps such as described above is very much the definition of the venerable PSF1 format, give or take a few header bytes. We can therefore harvest the glyph pixels from any PSF1 terminal font by opening it in a hex editor such as ImHex, travelling past the header (4 bytes) and the first section of non-printable glyphs (512 bytes), and then exporting the raw data for the next 96 glyphs (1536 bytes) by using “Copy as → C Array”.

This will give us a nicely formatted array of chars, which we can easily edit into an array of uints, which we then group into uvec4s. We need to remember that just concatenating the raw chars into uints flips the endianness of our uints, but we can always flip this back when we sample the font data…

Once we’re done, this is how our font bitmap data table looks like in the fragment shader:

For the text that we want to print, we have a similarly wasteful situation – the smallest basic vertex attribute data type is usually 32bit wide, and so it makes sense to make best use of this and pack at least 4 characters at a time. If we do this, we must make sure that the message that we want to print has a length divisible by 4. If it was shorter, we need to fill up the difference with zero byte (\0) characters. Conveniently, the zero byte is also used to signal the end of a c-string.

Our per-instance data looks like this:

1
2
3
4

struct word_data {
  float          pos_and_scale[ 3 ]; // xy position + scale 
  uint32_t       word;               // four characters that we want to print
};

It’s the application’s responsibility to split up the message into chunks of 4 characters, to convert these four characters into an unit32_t, and to store it into a word_data struct together with the position offset for where on screen to render these four characters. Once a word_data is filled, we append it into an array where we accumulate all the data for our text draw calls. Once we are ready to draw, we can then bind this array as a per-instance binding to our debug text drawing pipeline, and draw all text with a single instanced draw call, with the number of instances being the number of quads that we want to draw.

More interesting things happen in the vertex and fragment shader of the debug text drawing pipeline.

Vertex Shader 

Our vertex shader produces three outputs.

First, it writes to gl_Position to place the vertices for our triangles on the screen. This operates in NDC = Normalised Device “screen space” Coordinates. We calculate an offset for each vertex using the per-instance pos_and_scale attribute data.

The second output of the vertex shader is the word that we want to render: We just pass though the attribute uint as an output to the fragment shader – but we make sure to use the flat qualifier so that it does not get interpolated.

And then, the vertex shader synthesizes texture coordinates (via gl_VertexIndex). It does so pretty cleverly:

• 12 >> gl_VertexIndex & 1 will give a sequence 0, 0, 1, 1,
• 9 >> gl_VertexIndex & 1 will give a sequence 1, 0, 0, 1,

This creates a sequence of uv coordinates (0,1), (0,0), (1,0), (1,1) in a branchless way.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

#version 450 core #extension GL_ARB_separate_shader_objects : enable #extension GL_ARB_shading_language_420pack : enable // Inputs // Uniforms - Push Constants layout (push_constant) uniform Params { vec2 u_resolution; // screen canvas resolution in physical pixels }; // Input Attributes layout (location = 0) in vec3 pos; // "vanilla" vertex position attribute - given in pixels layout (location = 1) in uint word; // per-instance: four chars layout (location = 2) in vec3 word_pos; // per-instance: where to place the word in screen space layout (location = 3) in vec4 col_fg; // per-instance: foreground colour layout (location = 4) in vec4 col_bg; // per-instance: background colour // Vertex Outputs struct per_word_data { uint msg; vec4 fg_colour; vec4 bg_colour; }; out gl_PerVertex { vec4 gl_Position; }; layout (location = 0) out vec2 outTexCoord; layout (location = 1) flat out per_word_data outMsg; void main() { outMsg.msg = word; outMsg.fg_colour = col_fg; outMsg.bg_colour = col_bg; vec2 scale_factor = vec2(1.,2.)/(u_resolution); outTexCoord = vec2((12 >> gl_VertexIndex) &1, (9 >> gl_VertexIndex ) &1); vec4 position = vec4(0,0,0,1); position.xy = vec2(-1, -1) + (pos.xy * word_pos.z + word_pos.xy) * scale_factor; gl_Position = position; }

glsl

If we at this point visualise just the output of the vertex shader, we will get something like this:

Fragment Shader 

Our fragment shader needs three pieces of information to render text, two of which it receives from the vertex shader stage:

1. The fragment’s interpolated uv coordinate, uv
2. The character that we want to draw, in_word
3. The font data array, font_data

To render a glyph, each fragment must map its uv-coordinate to the correct bit of the glyph bitmap. If the bit at the lookup position is set, then render the fragment in the foreground colour, otherwise render it in background colour.

This mapping works like this:

First, we must map the uv coordinates to word – word not, world! – pixel coordinates. The nice thing about these two coordinate systems is that they both have their origin at the top left, so we only need to bother with scaling, and not origin transformation.

We know that our uv coordinates are normalised floats going from vec2(0.f,0.f) to vec2(1.f,1.f), while our font pixel coordinates are integers, going from uvec2(0,0) to uvec2(7,15).

We also must find out which one of the four characters in the word to draw.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const uint WORD_LEN = 4; // 4 characters in a word

// quantize uv coordinate to discrete steps
uvec2 word_pixel_coord = uvec2(floor(uv.xy * vec2( 8 * WORD_LEN, 16))); 
// limit pixel coord range to uvec2(0..31, 0..15)
word_pixel_coord = min(uvec2( 8 * WORD_LEN -1, 16 -1), word_pixel_coord);
// Find which of the four characters in the word this fragment falls onto
uint printable_character = in_word >> (WORD_LEN - (word_pixel_coord.x / 8));
// Map fragment coordinate to pixel coordinate inside character bitmap
uvec2 glyph_pixel_coord = uvec2(word_pixel_coord.x % 8, word_pixel_coord.y);

Remember, to draw a character, we must look up the character in the font bitmap table, where we must find the correct bit to check based on the uv coordinate of the fragment. You will notice that in the first GLSL example above, we were only worried about the .x coordinate. Now, let’s focus on .y, so that we can draw more lines of pixels by looking up the correct line to sample from.

Let’s do this step by step. First, we fetch the character bitmap from our font_data as an uvec4. Then we use the glyph_pixel_coord.y to pick the correct one of 4 uints that make up the glyph. This will give us four lines of pixels.

1
2
3
4
5
6
7
8

// First, map character ASCII code to an index offset into font_data table. 
// The first character in the font_data table is 0x20, SPACE.
offset = printable_character - 0x20; 
// Then get the bitmap for this glyph
uvec4 character_bitmap = font_data[offset]; 
// Find the uint that contains one of the four lines that 
// are touched by our pixel coordinate
uint four_lines = character_bitmap[glyph_pixel_coord.y / 4];

Once we have the uint covering four lines, we must pick the correct line from it.

Note that lines are stored in reverse order because after we used ImHex to lift the bitmap bytes out of the font file, we just concatenated the chars into uint. This means that our bitmap uints have the wrong endianness; We want to keep it like this though, because it is much less work to just concatenate chars copied form ImHex than to manually convert endianness in a text editor.

1

uint current_line  = (four_lines >> (8*(3-(glyph_pixel_coord.y)%4))) & 0xff;

And, lastly, we must pick the correct bit in the bitmap. Note the 7- – this is because bytes are stored with the most significant bit at the highest index. To map this to a left-to-right coordinate system, we must index backwards, again.

1

uint current_pixel = (current_line >> (7-glyph_pixel_coord.x)) & 0x01;

We now can use the current pixel to shade our fragment, so that if the pixel is set in the bitmap, we shade our fragment in the foreground colour, and if it is not set, shade our fragment in the background colour:

1

vec3 color = mix(background_colour, foreground_colour, current_pixel);

What about the fill chars that get inserted if our printable text is too short to be completely divisible by 4? We detect these in the fragment shader: In case were are about to render such a fill character, we should do absolutely nothing, not even draw the background. We can do this by testing printable_character, and issuing a discard in case the printable character is \0.

A Visual Summary 

Full Implementation & More Source Code 

Using this technique, it is now possible, from nearly anywhere in an Island project, to call:

1
2

char const msg_2[] = { 70, 111, 108, 107, 115, '!', 0 };
le::DebugPrint( "That's all, %s", msg_2 );

And see the following result on screen:

Acknowledgements 

• Diagrams drawn with Excalidraw
• Original source data for the pixel font came from Tamsyn, a free pixel font by Scott Fial

Backlinks 

This article was featured on Graphics Programming Weekly, and discussed on Lobste.rs, and Hacker News.

If you like more of this, subscribe to the rss feed, and if you want the very latest, and hear about occasional sortees into generative art and design, follow me on bluesky or mastodon, or maybe even Instagram. Shameless plug: my services are also available for contract work.

RSS:

Find out first about new posts by subscribing to the RSS Feed