Tutorial 8: Text
In this tutorial you will learn how to create text.
Before starting this tutorial be sure to setup an empty project with the Setup Tutorial.
Ness::String
Ness::String is the type of string used throughout ness-engine. you should use it as well. current implementation is just an alias for std::string.
to convert numbers to string either use ness_to_string() or ness_int_to_string()
Creating a text entity
Text entity behaves just like a sprite: you provide it with text to display and a font file, and it will render the given text on the screen. you can then manipulate it with all available transformations (scale, color, rotate, etc..). to create a basic text entity, simply copy this code:
That's it. :)
Now that you know about text entities, time to learn about z-ordering!
continue to next tutorial -->
Ness::TextPtr text = scene->create_text("ness-engine/resources/fonts/courier.ttf", "text to show!", 24);
Ness::MultiTextPtr text2 = scene->create_multitext("ness-engine/resources/fonts/courier.ttf",
"first line \n second line", 24);
class ShadowText : public Ness::Text
{
public:
ShadowText(Ness::Renderer* renderer, const Ness::String& FontFile, const Ness::String& text, int fontSize = 12) :
Ness::Text(renderer, FontFile, text, fontSize)
{ }
virtual void do_render(const Ness::Rectangle& target, const Ness::SRenderTransformations& transformations)
{
// set target rect for shadow
Ness::Rectangle shadowTarget = target;
shadowTarget.y += 5;
shadowTarget.x -= 2;
// render shadow
m_renderer->blit(m_texture, nullptr, shadowTarget, Ness::BLEND_MODE_BLEND,
Ness::Color::GREY, transformations.rotation, m_anchor);
// now render the original text
Ness::Text::do_render(target, transformations);
}
};
SharedPtr<ShadowText> shadowText = ness_make_ptr<ShadowText>(&renderer, "ness-engine/resources/fonts/courier.ttf",
"Text with shadow!!!", 24);
scene->add(shadowText);
let's go over the params:
first param is the font file to use. fonts are handled like textures, meaning they will be loaded into memory once used and unloaded once no longer referenced. any ttf file will work with the text entity.
second param is the text to display. you can change it later with change_text().
last param is font size. remember you can scale the text entity, but scaling text with originally small font willjust end up blurry.
alignment
alignment in text basically effects the anchor point of the text. you can change alignment by calling set_alignment().
color
by default all text entities are white. the idea is that you use the color transformation to change the text color.
Creating a multi-line text entity
The basic text entity does not support multi lines. if you want a multi-line text you need to create the MultiText entity:
as you can see the character '\n' is used as the line-breaker. you don't need to add '\r'.
line width
multi-line text has an important property a regular text does not have: line width. you can set maximum line width by calling set_line_width(), which will do word wrap on the text.
Text efficiency
The text entity in ness-engine is based on SDL_ttf, which as you may or may not know, is known to be not very fast. to overcome the efficiency issue what ness-engine does is to render the text only once, on an empty texture, and then render that texture as if it was a regular sprite.
so rendering a text entity or a multi-text entity is as-efficient as rendering sprites. you will suffer the overhead only when changing the text.
Text with shadow
Just for fun, let's create our own customized text entity - with shadow:
not too hard right? creating customized entities should be an easy task with ness-engine. in this case all we did was overriding the rendering function and adding the rendering of the shadow before the rendering of the text itself. now let's create an instance of it:
and the result should look like this:
Never be afraid to create your own entities with ness-engine! it sould be easy and work smoothly.
Help ness-engine grow!