Page thumbnail

Beware of 'Padding' in TextMeshPro

TextMeshPro renders text wrong?

When you want to display text in Unity (starting circa version 2021,) the text components default to TextMeshPro (TMP). TextMeshPro makes you create an asset called “Font Asset” before you can display anything. It contains a Font Atlas, which is a collection of pre-rendered letters packed into a single image, whose mapping TMP keeps track of to display the text afterwards.
When making the atlas, you can set the sampling point size (SPS), which is the font size used to pre-render the letters. This also translates to the biggest font size at which TMP can safely display the letters (for the most part). For example, smaller SPS sometimes characters to be positioned incorrectly. Bigger SPS requires larger atlas size, but it helps you avoid weird issues… or does it?

Let’s try an excessive case: we crank up the atlas size to maximum (8192 x 8192) and create the font atlas. With the auto sizing option for SPS, we should get a nicest result, right?

An English sentence displayed using an excessively large Font Atlas via TextMeshPro. The letters appear to be contained in semitransparent boxes.

… !?

Of course, I did not add any font-related effects or shader effects or something related to that. This is a TMP text displayed with the default setting with the Font Asset we just created.

Environment

  • Unity 2021.3.6f1
  • TextMeshPro 3.0.6

Let’s see what happened

For this experiment, we use M+ Font (2p) which can be retrieved from Google Fonts (or directly from M+ Font distribution site)

We just created a Font Asset with the maximum possible atlas size. TMP’s Font Asset Creator reports the atlas information, so let’s take a look:

Log for big font atlas

“Point Size” is the SPS that TMP has chosen for this atlas generation. It reports it’s 1394. Quite excessive, but let’s move on for now.

For comparison, let’s also create a Font Asset with a sensibly-sized atlas:

Log for small font atlas

The SPS this time is just 23.

Now what happens if we display text using those fonts?

In this image, we compare 2 Text Mesh Pro labels displaying some texts. One label uses the font asset with an excessively large atlas while other uses the asset with a sensibly-sized atlas. To our surprise, the label using the excessively large font asset is rendering the text wrong; each letter is surrounded by a transparent box.

The label using the big font asset has catastrophically failed to render the text correctly!

Why?

This issue has been raised in Unity Forum; the SPS becomes larger as the atlas size gets bigger… and it becomes too big for the character to be way too tightly packed! Each character needs to be spaced out for TMP to work correctly. To space them out, you need to use, you guessed it, the Spacing property.

https://forum.unity.com/threads/text-mesh-pro-box-around-text-unwanted-effect-bug.665647/

TextMesh Pro - Text Mesh Pro - "box" around text unwanted effect / bug

I've got text in my scene and it seems to keep creating boxes around the text, like so:[ATTACH] Im using Unity version 2019.1, and the newest text...

In the thread, the Sampling Point Size and Padding should satisfy the next formula:

SPS / Padding = 10

If you look at the log closely, this ratio is reported SP/PD Ratio. The value here should say 10% or somewhere around that value.

SPS defaults to Auto Sizing when you first introduce TMP to your project. This means that TMP will adjust the SPS according to the Font Atlas size. However, there is no way (and no apparent instructions) to set the Padding automatically (it defaults to 5 and can be as big as 64), so it may fly under your radar.

If you only need ASCII, the size of 512x512 ~ 1024x1024 should do. If you choose to set your SPS yourself, you can control it further and you don’t even need to force the atlas to be a square. Just make sure that SPS/PD ratio is 10%, and find the atlas size that can pack the letters as tightly as possible.

Setting SPS yourself. Notice that SPS/PD ratio is 10%. (Setting SPS yourself. Notice that SPS/PD ratio is 10%.)