Using the TextBlockRenderer

The TextBlockRenderer is another tier above the SpriteRenderer. It is specialized for rendering arbitrary 2D text in form of blocks and aligning those in a rectangle.

You have to create a TextBlockRenderer for each font that you want to use, because the renderer will prerender a sprite sheet for its font. More information about that are given in the next section.

The actual rendering of the text will be delegated to a SpriteRenderer. Therefore, an instance of this class has to be passed to the TextBlockRenderer’s constructor. Furthermore, the font’s specifications must be provided:

var myTextBlockRenderer = new SpriteTextRenderer.SlimDX.TextBlockRenderer(Sprite, "Arial", FontWeight.Bold, FontStyle.Normal, FontStretch.Normal, 12);

What happens on initialization of a TextBlockRenderer

The TextBlockRenderer uses DirectWrite and Direct2D to prerender a sprite sheet of chars. Therefore, a DirectX10 device, a DirectWriteFactory and a Direct2DFactory is created on instantiation of the first renderer. These are shared across instances and will be destroyed, when the last instance of TextBlockRenderer is disposed of.

Every critical code section (i.e. sections, where the Direct3D 11 device of the SpriteRenderer is used) is locked by the System.Threading.Monitor on the device. If you need the device in another thread (e.g. for drawing a loading screen), you should lock the critical sections in the same way.

After initialization, the first sprite sheet is created. Every sprite sheet contains 256 chars. The sprite sheet number for a char is the first (most significant) byte of the char. The first sheet that is created is sheet number 0. On this sheet are all chars from Unicode 0x00 to 0xff. This also includes the full ASCII range which is sufficient for most cases. For performance reasons, each sprite sheet is extended to a power of two size. Here is an example sheet. The black background is added for readability:

If the renderer encounters a char that is not on a sprite sheet yet, the new sheet is created automatically.

Drawing strings

Drawing strings is very simple. Just choose an appropriate overload of the DrawString method and call it. The following call will draw the text “Example Text” in the top left corner in a white color:

myTextBlockRenderer.DrawString("Example Text", Vector2.Zero, Color.White);

There are overloads that can align the text in a rectangle at the usual positions (top, vertical center, bottom; left, horizontal center, right). These overloads are pretty intuitive. If you need assistance with any of the overloads, have a look in the class documentation.

Don’t forget to call (Flush) on the underlying SpriteRenderer at the end of a frame.

Strings can contain line breaks. However, only complete line breaks are valid as defined by Environment.NewLine. This is a combination of “carriage return” (\r) and “line feed” (\n). \r and \n can occur independently of each other in texts that are aligned top left or that are not aligned at all. Then, they will do what they are made for: \r returns the cursor to the beginning of the line; \n moves the cursor to the next line preserving the horizontal position.

Measuring strings

Text can be measured with the Measure() method. Additionally, every Draw() call returns a StringMetrics object with the metrics of the rendered string. The exact explanation of StringMetrics can be found in the class documentation. Here is the according overview figure:

Last edited May 4, 2014 at 9:58 AM by Nico201, version 3