 | |
Bitmap | |
Inheritance HierarchyNamespace: Ab4d.SharpEngine.Utilities
Assembly: Ab4d.SharpEngine (in Ab4d.SharpEngine.dll) Version: 2.0.8956+4c7684e186ca1be74e7a284fbe739d9a1b843d3c
Syntaxpublic 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. |
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). |
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. |
RemarksBitmapTextCreator 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.
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.
See Also