Text Shaders

The Text Box product includes a collection of shaders suitable for rendering text. Except for the alpha blending shader, they all use a distance map instead of a regular font atlas. You can use the free Distance Map Generator product to transform font atlases into good distance maps.

All shaders are relatively straightforward and serve as examples in case you want to create your own custom shader or want to combine the effects of multiple shaders.

As text is virtually always viewed from the front, all shaders are invisible if viewed from behind, but this is easily changed by uncommenting a line in the shader code.

All shader properties are either textures, colors, or floats. Every shader has a main texture parameter named Distance Map (Alpha), except for Text, Alpha Blend for which it is named Font Atlas (Alpha).

You typically only use the alpha channel and don't want to compress distance maps, so Alpha 8 is most likely the best texture format to use. The shaders assume you only use the alpha channel and ignore the RGB channels of the distance map. However, each shader contains alternative code you can uncomment in case you do want to use the color channels.

All shaders can be found under Text Box in the material's shader selection field.

Hardware Support

The Alpha Blend and Alpha Test shaders support fixed function pipelines and basically run on all hardware. The other shaders require at least Shader Model 2.0 and fall back to either alpha blending or alpha testing.

Shader Model 2.0 is supported by all iOS devices except the most ancient (iPhone, iPhone3G, 1st and 2nd generation iPod Touch).

Alpha Blend

Alpha Blend is a very simple shader that alpha blends based on the alpha channel of the vertices and the font atlas. It is not intended to be used with a distance map. This shader is suited for fixed-size pixel-perfect text without any effects or with effects baked into the font atlas.
alpha blending

Alpha Test

Alpha Test is a very simple shader that alpha tests based on the alpha channel of the vertices and the font atlas. It can be used either with or without a distance map. Using a distance map, you're able to grow and shrink the text by varying AlphaBoundary. It produces aliased edges but does write to the depth buffer, unlike all other text shaders.
font atlas distance map
alpha testing, atlas vs distance map

Parameters

Alpha Boundary
_AlphaBoundary

Pixels are discarded if their alpha is below this value.

boundary 0.25
boundary 0.50
boundary 0.75
alpha boundaries of 0.25, 0.50, and 0.75

Smooth

Smooth uses alpha blending to look like an anti-aliased version of Alpha Test. It does this by defining a distance range within which it smoothly transitions from fully transparent to fully opaque.
smooth edges

Parameters

Edge Minimum (Outside)
_EdgeMin

Beyond this distance pixels are fully transparent.

Edge Maximum (Inside)
_EdgeMax

Up to this distance pixels are fully colored.

If Edge Minimum is larger than Edge Maximum then the inside and outside will be swapped, resulting in an inverted image.
15 to 55 45 to 55 45 to 85 15 to 85 55 to 45
various edge minima and maxima

Smooth Bold

Smooth Bold is a variant of Smooth that allows you to bold portions of the text. It does this by defining two sets or edge minima and maxima and interpolating between them based on the alpha channel of the vertex colors. An alpha of 1 corresponds to fully bold while an alpha of 0 corresponds to fully normal.

Note that because this shader uses the alpha channel of the vertices for a specialized purpose, it is not factored into the final opacity of the character pixels.

alternating between fully bold and fully normal words

Parameters

Edge Minimum (Outside)
_EdgeMin

Beyond this distance normal character pixels are fully transparent.

Edge Maximum (Inside)
_EdgeMax

Up to this distance normal character pixels are fully colored.

Bold Minimum (Outside)
_BoldMin

Beyond this distance bold character pixels are fully transparent.

Bold Maximum (Inside)
_BoldMax

Up to this distance bold character pixels are fully colored.

You could use the CCTextMarkedColorer or CCTextRangeColorer to control which characters are bolded by adjusting their alpha value.

Smooth Fade

Smooth Fade is a variant of Smooth that fades the text based on view distance. It does this by gradually increasing Edge Maximum to 1. This results in text that becomes vague at a distance while still remaining visible.
without fading with fading
smooth text without and with fading

Parameters

Edge Minimum (Outside)
_EdgeMin

Beyond this distance pixels are fully transparent.

Edge Maximum (Inside)
_EdgeMax

Up to this distance pixels are fully colored.

Fade Distance (Begin)
_FadeDistance

View distance in world units beyond which _EdgeMax will increase.

Fade Strength (Increase per Unit)
_FadeStrength

How much _EdgeMax is increased per unit distance, up to 1.

If viewed head-on, you can get a focus effect by viewing the text at Fade Distance and using a high Fade Strength.
focusing on the center of the text
Because this shader computes the view distance for each vertex, it is more expensive than the other text shaders. Only use it if you really need the fade effect.

Smooth Outline

Smooth Outline is a variant of Smooth that adds an outline effect to the text.

Effectively, there are two separate transitions, one for color and one for the fade to transparency. Edge Minimum and Edge Maximum define the transition range from the text's color to the outline color, while Outline Minimum and Outline Maximum define the outer edge of the outline.

smooth outline

Parameters

Edge Minimum (Outside)
_EdgeMin

Beyond this distance pixels are fully colored by the outline color.

Edge Maximum (Inside)
_EdgeMax

Up to this distance pixels are fully colored by the text color.

Outline Color
_OutlineColor

Color of the outline.

Outline Minimum (Outside)
_OutlineMin

Beyond this distance pixels are fully transparent.

Outline Maximum (Inside)
_OutlineMax

Up to this distance pixels are fully colored by the outline color.

Setting Outline Maximum greater than Edge Minimum results in the text beginning to fade before the outline color starts.
25 to 35 25 to 55 25 to 75
various outline minima and maxima

Smooth Shadow

Smooth Shadow is a variant of Smooth that adds a shadow effect to the text.

Effectively, this shader draws the text twice with two different transitions. By offsetting the texture coordinates of the bottom text you can create the illusion of a shadow.

Be sure to make enough room in your bitmap font to fit the offset shadow in the sprites. Also keep in mind that successive character sprites are rendered on top of each other, which might cause shadows to cover preceding characters.

While it is possible to achieve the same effects as Smooth, Outline with this shader, it is more expensive because it samples the distance map twice. So only use this shader when taking advantage of the offset.

smooth shadow

Parameters

Edge Minimum (Outside)
_EdgeMin

Beyond this distance pixels are fully transparent or shadow.

Edge Maximum (Inside)
_EdgeMax

Up to this distance pixels are fully colored by the text color.

Shadow Color
_ShadowColor

Color of the shadow.

Shadow Minimum (Outside)
_ShadowMin

Beyond this distance pixels are fully transparent or covered by text.

Shadow Maximum (Inside)
_ShadowMax

Up to this distance pixels are fully colored by the shadow color or covered by text.

Shadow Offset U
_ShadowOffsetU

Horizontal offset of the shadow, in texture space.

Shadow Offset V
_ShadowOffsetV

Vertical offset of the shadow, in texture space.

Because the shadow offset is in texture space (0–1 for the entire texture width or height), it is always a very small amount. Also, if you want the texture to appear to the right, you have to offset to the left, as if you were moving the imaginary light source. Likewise for offsetting vertically.
default leftwards hard small upwards
various shadow minima, maxima, and offsets

Gradient

Gradient uses the distance map to index a gradient map. It can be used to create more complex color transitions than the Smooth, Outline shader can handle. Depending on how you configure the textures, it can also produce a smoother result that degrades more gracefully the smaller the text gets.
text colored with a gradient

Parameters

Gradient Map (RGBA)
_Gradient

Gradient map used to color the pixels.

You can use CCGradient to create gradient maps in Unity.
fuzzy red floating outline black with double outline inner and outer glow
various gradients