Outdated Docs > Cocos2D-X Built-in GUI Controls > Text Labels

Text Labels


cocos2d supports both TTF (True Type Fonts) labels, and texture atlas labels.

Pros and Cons of TTF labels: ( CCLabelTTF )

  • All the pros of TTF fonts: any size, kerning support, etc.
  • Easy to use. No need to use an external editor.
  • The creation/update is very slow since a new texture will be created, especially on Android.

Pros and Cons of texture atlas labels: ( CCLabelAtlas, CCLabelBMFont )

  • The creation / update is very fast, since they don’t create a new texture.
  • Fonts can be customized (shadows, gradients, blur, etc)
  • Depends on external editors: AngelCode / Hiero editor, GIMP / Photoshop
  • Text can lose quality if resized

Label objects

Creating labels: Simple way


CCLabelTTF* ttf1 = CCLabelTTF::create("Hello World", "Helvetica", 12, 
                                      CCSizeMake(245, 32), kCCTextAlignmentCenter);

fontName is the TTF font name to be used. You can also use your own custom TTF file. You just need to add the .ttf file to the project.
If it fails to load the font it will use the UIFont class.
Notice: The size of the OpenGL texture will be automatically calculated based on the font size and font name.

Creating labels: Complex way

You can also create textures using this API:

CCLabelTTF* CCLabelTTF::create(const char *string, const char *fontName, float fontSize,
                               const CCSize &dimensions, CCTextAlignment hAlignment, 
                               CCVerticalTextAlignment vAlignment)

Notice: If you use this way, you must pass the dimension of OpenGL texture to be used. If the texture is not big enough, then only some parts of the label will be rendered.


Possible Alignments:
* kCCTextAlignmentLeft (left alignment)
* kCCTextAlignmentCenter (center alignment)
* kCCTextAlignmentRight (right alignment)

If you want to modify the alignment you can use the anchorPoint property. Example:

//left alignment
// right alignment
// center aligment (default)


For any object that implements the CCLabelProtocol protocol, you can update it using the setString method. Example:

label->setString("Hello World 2");

Notice: Every time you call setString a NEW OpenGL texture will be created. This means that setString is as slow as creating a new CCLabel. So, DO NOT use CCLabel objects if you need to update them frequently. Consider using CCLabelAtlas instead.


You can change the color of your fonts by simply calling the color parameter like so:

label.setColor(ccc3(0,0,0)); // or
label.setColor(ccc4(0,0,0,0)); // setOpacity

ccc3 Example Colors:

* white - (255,255,255)
* black - (0,0,0)
* blue - (0,0,255)
* green- (0,255,0)
* red - (255,0,0)
* Grey – (84,84,84)
* Brown – (165,42,42)
* Pink – (255,192,203)
* Purple – (160,32,240)
* Yellow – (255,255,0)
* Gold – (255,215,0)



The CCLabelBMFont is the suggested way to create fast labels since:

  • The bitmap (image) can be customized with the editors
  • You can update/init the label without penalty
  • It is very flexible. Each letter of the label can be treated like an CCSprite
  • It has kerning support

The CCLabelBMFont label parses the Angel Code Font format to create a label. To create these kind of labels, you can use any of these editors:

http://www.n4te.com/hiero/hiero.jnlp (java version)
http://slick.cokeandcode.com/demos/hiero.jnlp (java version)
http://www.angelcode.com/products/bmfont/ (windows only)
http://glyphdesigner.71squared.com/ (Mac only)
http://www.bmglyph.com (Mac only)
http://tinyfont.com (Mac only)

Java editors vs. Windows editor:

The Windows editor is the official Angel Code editor
Java editors: run on Mac
Java editors: have additional features like shadow, gradient, blur

Creating a CCLabelBMFont


CCLabelBMFont *label =CCLabelBMFont::create(LongSentencesExample, "fonts/markerFelt.fnt", size.width/1.5, kCCTextAlignmentCenter);

Since the font is a fixed size you will need to carefully consider which font sizes you will need. Having a separate font for each size may be inefficient due to the amount of texture memory it takes. In this case it might make sense to scale down labels made with a suitable large font to achieve different sizes. Since the label is just a CCNode, you can do this with the scale properly.

Manipulating each character

Since CCLabelBMFont is a subclass of CCSpriteSheet you can manipulate each character as an CCSprite. The 1st character will be added with tag = 0, the 2nd character will be added with tag=1, and so on. Example:

CCLabelBMFont *label =CCLabelBMFont::create("Bitmap Font Atlas" , "bitmapFontTest.fnt");
CCSprite *char_B = label->getChildByTag(0); // character 'B'
CCSprite *char_m = label->getChildByTag(3); // character 'm'



CCLabelAtlas was the 1st fast label added into cocos2d. But it was superseded by CCBitmapFontAtlas. It is being maintained for backwards compatibility, but you should use CCBitmapFontAtlas instead.

Creating a LabelAtlas

CCLabelAtlas* CCLabelAtlas::create(const char *string, const char *charMapFile, unsigned int itemWidth, int unsigned itemHeight, unsigned int startCharMap);


CCLabelAtlas *label1 = CCLabelAtlas::create ("Hello World","tuffy_bold_italic-charmap.png",48,64 ,' ');


charMapFile is an image file that contains all the characters. Each character should be ordered according to its ASCII value and the

  • image can’t contain more than 256 characters.
  • itemWidth is the width of the characters in pixels
  • itemHeight is the height of the characters in pixels
  • startCharMap is the first character of the map.
  • Updating a LabelAtlas / BitmapFontAtlas

CCLabelTTF vs. CCLabelAtlas

The main difference between CCLabelTTF and CCLabelAtlas is that the atlas version (like all the other atlas classes) uses one big texture with all the letters pre-rendered to draw a string. This means that the drawing is much faster, because if you draw 100 labels, the graphics processor doesn’t have to read in 100 textures but just keep one texture in memory. But it also means that all the letters will be of a fixed size. If you want to get around the fixed-size limitation, use CCBitmapFontAtlas.

CCLabelTTF creates one texture for every label, whereas CCLabelAtlas renders the text on the fly, using the provided texture (containing all the characters), so using CCLabelAtlas results in lower memory consumption.


Labels and Fonts

Label_objects.png (65.6 kB) iven, 2013-01-25 08:06

CCLabelBMFont.png (65.2 kB) iven, 2013-01-25 08:06

LabelAtlas.png (60.8 kB) iven, 2013-01-25 08:07

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.