Rendering Text

Creating a text object using the Untold Engine is easy. However, there is a bit of preparation needed. For example, you need to provide the Untold Engine the font type you intend to use. Once this information is available, you provide the text, and the engine will render your text on the desired location.

Preparing the Fonts

Before you can create a Text object, you must provide the desired Font Type to the Untold Engine. There is an excellent app that makes this process very simple. It is called Glyph Designer. The Untold Engine process the output from the Glyph Designer (.xml and .png files) and renders a text using the font type.

I strongly recommend you get a copy of Glyph Designer.

image

Creating the Font Files

Open up Glyph Designer and select your desired font type, color, and size.

image

Once ready, export the files. Make sure the Export Type is .xml(BMFont XML).

Give a name to the file. In this example, the name is “myFont.” Make sure to save the files in the Resources folder of the Untold Engine as shown.

image

Flip the Font Atlas (.png) File

Before we can use the Font Atlas image file (.png), we need to flip the image vertically. You can do so with any image editor. In this instance, I use Gimp to flip the .png file vertically.

image

Copy the files into Xcode

Finally, drag the .xml and .png files from the Resources folder into Xcode project Resources folder as shown below:

image

Step 1. Create a Font Loader Object

A Font Loader Object, U4DEngine::U4DFontLoader, process the .xml and .png files obtained from the Glyph Designer. The U4DFontLoader is in charge of loading font information. Before you can create a Text object, you must create a Font Loader Object.

The snippet below shows how to create a U4DFontLoader object and how to load font information (lines 1 & 2).

//1. Create a Font Loader object
U4DEngine::U4DFontLoader *fontLoader=new U4DEngine::U4DFontLoader();

//2. Load font data into the font loader object. Such as the xml file and image file
fontLoader->loadFontAssetFile("myFont.xml", "myFont.png");

Step 2. Create a Text Object

In the Untold Engine, a Text object is referred as a U4DEngine::U4DText object. Creating a U4DText object requires a pointer to the U4DFontLoader and the space needed between each letter.

The snippet below shows how to create a U4DText object (line 3).

//3. Create a text object. Provide the font loader object and the spacing between letters
U4DEngine::U4DText *myText=new U4DEngine::U4DText(fontLoader, 30);

//4. set the text you want to display
myText->setText("Hola Mundo");

//5. If desire, set the text position. Remember the coordinates for 2D objects, such as text is [-1.0,1.0]
myText->translateTo(0.25, 0.75, 0.0);

//6. Add the text to the scenegraph
addChild(myText,-2);

Once created, you can use the U4DEngine::U4DText::setText() method to assign the text to render (line 4). If desired, you can set the position of the text (line 5). Finally, you must add the text object into the scenegraph, as shown in line 6. Recall that the coordinate system for 2D objects is different than for 3D objects. For 2D objects, the coordinate system ranges between [-1.0,1.0].

Note: Since the demo has a skybox, I’m setting the z-depth in the addChild method to -2. The z-depth provides the rendering order.

Complete Code

The complete code to render a U4DText object, with text “Hello World” should look as shown below:

//1. Create a Font Loader object
U4DEngine::U4DFontLoader *fontLoader=new U4DEngine::U4DFontLoader();

//2. Load font data into the font loader object. Such as the xml file and image file
fontLoader->loadFontAssetFile("myFont.xml", "myFont.png");

//3. Create a text object. Provide the font loader object and the spacing between letters
U4DEngine::U4DText *myText=new U4DEngine::U4DText(fontLoader, 30);

//4. set the text you want to display
myText->setText("Hola Mundo");

//5. If desire, set the text position. Remember the coordinates for 2D objects, such as text is [-1.0,1.0]
myText->translateTo(0.25, 0.75, 0.0);

//6. Add the text to the scenegraph
addChild(myText,-2);

Result

image

Tips

  • To properly render text, the font atlas (.png) image needs to be flipped vertically as shown below. In this instance, I use Gimp to flip the .png file vertically.

image