BitmapTextCreator Class


BitmapTextCreator Class

BitmapTextCreator class can be used to generate SceneNodes that show text by using bitmap fonts. Bitmap font is defined by one or more textures with rendered characters and font data that define where on the texture the character is. The binary font data can be created by a third party "Bitmap Font Generator" (for example from https://www.angelcode.com/products/bmfont/). To use the build-in default font call the GetDefaultBitmapTextCreator(Scene) method. See remarks for more information on how to generate bitmap font files.

Inheritance Hierarchy

SystemObject
Ab4d.SharpEngine.UtilitiesBitmapTextCreator

Namespace: Ab4d.SharpEngine.Utilities
Assembly: Ab4d.SharpEngine (in Ab4d.SharpEngine.dll) Version: 1.0.8740+deb2991acfe86a95cca780cd4f82bcae2805c1a5

Syntax

Copy

public class BitmapTextCreator : IDisposable

The BitmapTextCreator type exposes the following members.

Constructors

	Name	Description
	BitmapTextCreator(Scene, BitmapFont, IBitmapIO)	BitmapTextCreator constructor with custom BitmapFont. To use the default bitmap font, use GetDefaultBitmapTextCreator(Scene) static method.
	BitmapTextCreator(Scene, BitmapFont, FuncString, RawImageData)	BitmapTextCreator constructor with custom BitmapFont. To use the default bitmap font, use GetDefaultBitmapTextCreator(Scene) static method.

Top

Properties

	Name	Description
	AdditionalCharacterSpace	Gets or sets additional space after each character.
	AdditionalLineSpace	Gets or sets additional space after each line.
	AlphaClipThreshold	Gets or sets a float that specifies at which alpha value the pixel will be skipped in the fragment shader. Default value is 0.1.
	BitmapFont	BitmapFont used by this BitmapTextCreator
	CacheFontGpuImages	When true (by default) than loaded font GpuImages are cached on the Scene's cache.
	CustomMaterialProvider	When CustomMaterialProvider is set, it is used to create the material for the specified font page index. If CustomMaterialProvider is null or if it returns null, then the material is created by the BitmapTextCreator.
	CustomMipMapBitmapProvider	When CustomMipMapBitmapProvider is set, then the Func is called to get the custom mip-map bitmaps. The first parameter is texture file name for the current page, the second parameter is page index and the third parameter is mip level (0 for original bitmap). If this Func is not set, then mip-maps are generated by Vulkan.
	IsKerningUsed	Gets or sets a Boolean that specifies if font kerning is used (different distance between characters may be used based on the two characters).
	IsTwoSided	Gets or sets a Boolean that specifies if the same font material is also set to the BackMaterial property of the MeshModelNode.
	UnknownChar	Gets or sets a character that is displayed in case the character in the specified text is not defined in the bitmap font. By default the UnknownChar is set to space. When UnknownChar is set to null char ('\0') that means that the unknown character is skipped (current position is not changed).

Top

Methods

	Name	Description
	CreateTextNode	CreateTextNode creates a SceneNode (MeshModelNode or GroupNode) with the specified text and at the specified position, direction and size.
	Dispose
	GetDefaultBitmapTextCreator	Returns the BitmapTextCreator with the default bitmap font that is build into the Ab4d.SharpEngine. The bitmap font is created from Roboto font (Google's Open Font) with size of character set to 64 pixels.
	GetTextSize	Returns the size of the specified text.

Top

Remarks

To create a SceneNode with text, call the CreateTextNode(String, Vector3, PositionTypes, Vector3, Vector3, Single, Color4, Boolean, Single, Single, String) method. To only measure the size of the rendered text, call the GetTextSize(String, Single, Single, Single) method.

To use the build-in default font call the GetDefaultBitmapTextCreator(Scene) method. This will use the Robot font with size of character set to 64 pixels.

The samples project also comes with some already prepared fonts: Arial, ArialBlack, ArialBlack with outline, Roboto, RobotoBlack, RobotoBlack with outline. See the Ab4d.SharpEngine.Samples.Common/Resources/BitmapFonts folder.

To use other font, you will need to create the font data file (.fnt file) and rendered texture (in png file format). This can be created by a third party "Bitmap Font Generator" (for example from https://www.angelcode.com/products/bmfont/). The following are tips for using the Bitmap Font Generator:
- In "Export options" use "White text with alpha" preset and use 32 bit depth
- For better quality when scaling it is very good that the font texture has mip-maps (see internet for more into about mip-maps). Because mip-maps are scaled down versions of the original image, the font must be rendered with padding to prevent that pixels from sibling characters would affect the scaled down mip-maps. It is not needed to provide all mip-map levels (to 1x1 bitmap). But it is recommended to provide mip-maps until the mip-map where each character is 8x8 pixels big. Each mip-map requires to double the padding, for example:
- for texture with character size 64 pixels: if we provide 8px padding, we can use 3 mip-maps: 32x32, 16x16, 8x8
- for texture with character size 128 pixels: if we provide 16px padding, we can use 4 mip-maps: 64x64, 32x32, 16x16, 8x8
BitmapTextCreator will read the padding and create the mip maps based on the padding value.
- Note that when creating 8 bit png bitmap with "Bitmap font generator" does not correctly create a alpha-transparent bitmap. Therefore it is better to store into 32 bit bitmap and then use some third-party imaging tool to convert to 8-bit png with proper transparency.

Reference

Ab4d.SharpEngine.Utilities Namespace