Instance Methods | List of all members
CC3MeshNode(BitmapLabel) Category Reference

#import <CC3BitmapLabelNode.h>

Instance Methods

(void) - populateAsBitmapFontLabelFromString:fromFontFile:andLineHeight:andTextAlignment:andRelativeOrigin:andTessellation:

Detailed Description

CC3MeshNode extension to support bitmapped labels.

Method Documentation

- (void) populateAsBitmapFontLabelFromString: (NSString *)  lblString
fromFontFile: (NSString *)  fontFileName
andLineHeight: (GLfloat)  lineHeight
andTextAlignment: (NSTextAlignment)  textAlignment
andRelativeOrigin: (CGPoint)  origin
andTessellation: (CC3Tessellation divsPerChar 

Populates this instance as a rectangular mesh displaying the text of the specified string, built from bitmap character images taken from a texture atlas as defined by the bitmpped font configuration loaded from the specified font configuration file.

A compatible bitmap font configuration file, and associated texture, can be created using any of these editors: http://glyphdesigner.71squared.com/ (Commercial, Mac OS X) http://www.bmglyph.com/ (Commercial, Mac OS X - also available through AppStore) http://www.n4te.com/hiero/hiero.jnlp (Free, Java) http://slick.cokeandcode.com/demos/hiero.jnlp (Free, Java) http://www.angelcode.com/products/bmfont/ (Free, Windows only)

The texture that matches the specified font configuration (and identified in the font configuration), is automatically loaded and assigned to the texture property of this mesh node.

The text may be multi-line, and can be left-, center- or right-aligned, as specified.

The specified lineHeight define the height of a line of text in the coordinate system of this mesh node. This parameter can be set to zero to use the natural line height of the font.

For example, a font with font size of 16 might have a natural line height of 19. Setting the lineHeight parameter to zero would result in a mesh where a line of text would be 19 units high. On the other hand, setting this property to 0.2 will result in a mesh where the same line of text has a height of 0.2 units. Depending on the size of other models in your scene, you may want to set this lineHeight to something compatible. In addition, the visual size of the text will also be affected by the value of the scale or uniformScale properties of this node. Both the lineHeight and scale properties work to establish the visual size of the label text.

For a more granular mesh, each character rectangle can be divided into many smaller divisions. Building a rectanglular surface from more than one division can dramatically improve realism when the surface is illuminated with specular lighting or a tightly focused spotlight, or if the mesh is to be deformed in some way by a later process (such as wrapping the text texture around some other shape).

The divsPerChar argument indicates how to break each character rectangle into multiple faces. The X & Y elements of the divsPerChar argument indicate how each axis if the rectangle for each character should be divided into faces. The number of faces in the rectangle for each character will therefore be the multiplicative product of the X & Y elements of the divsPerChar argument.

For example, a value of {3,2} for the divsPerChar argument will result in each character being divided into 6 smaller rectangular faces, arranged into a 3x2 grid.

The relative origin defines the location of the origin for texture alignment, and is specified as a fraction of the size of the overall label layout, starting from the bottom-left corner.

For example, origin values of (0, 0), (0.5, 0.5), and (1, 1) indicate that the label mesh should be aligned so that the bottom-left corner, center, or top-right corner, respectively, should be located at the local origin of the corresponding mesh.

The vertexContentType property of this mesh may be set prior to invoking this method, to define the content type for each vertex. Content types kCC3VertexContentLocation, kCC3VertexContentNormal, and kCC3VertexContentTextureCoordinate are populated by this method.

If the vertexContentType property has not already been set, that property is set to a value of (kCC3VertexContentLocation | kCC3VertexContentNormal | kCC3VertexContentTextureCoordinate), and the mesh will be populated with location, normal and texture coordinates for each vertex.

This method may be invoked repeatedly to change the label string. The mesh will automomatically be rebuilt to the correct number of vertices required to display the currently specified string.

Extends class CC3MeshNode.

The documentation for this category was generated from the following file: