Platform eXtended Library (PXL)

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Class TBitmapFont

DescriptionHierarchyInternal Classes and RecordsInternal TypesFieldsMethodsProperties

Unit

PXL.Fonts

Declaration

type TBitmapFont = class(TObject)

Description

Bitmap font implementation.

Hierarchy

  • TObject
  • TBitmapFont

Overview

Internal Classes and Records

Public TKernings = class(TObject)
Public TStyleTags = class(TObject)

Internal Types

Published TTextEntryEvent = procedure(const Sender: TObject; const FontImage: TAtlasImage; const SourceRect: TIntRect; const DestRect: TFloatRect; const Color: TColorRect; const UserContext: Pointer);

Fields

Public internal const DefaultBinaryExtension = '.font';
Public internal const DefaultImageExtension = '.png';
Public internal const DefaultXMLExtension = '.xml';
Protected FEntries: array[0..MaxEntriesCount - 1] of TLetterEntry;
Protected FImage: TAtlasImage;
Protected FSize: TPoint2i;

Methods

Public constructor Create(const ADevice: TCustomDevice; const ASubscribedTextures: Boolean = True);
Public function DrawTextCustom(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat; const TextEntryEvent: TTextEntryEvent; const UserContext: Pointer; const RestartStyling: Boolean = True): Boolean;
Public function LoadFromBinaryAsset(const AssetName: StdString; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function LoadFromBinaryFile(const FileName: StdString; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function LoadFromBinaryStream(const Stream: TStream; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function LoadFromXMLAsset(const ImageAssetName: StdString; const XMLAssetName: StdString = ''; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function LoadFromXMLFile(const ImageFileName: StdString; const XMLFileName: StdString = ''; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function LoadFromXMLStream(const ImageExtension: StdString; const ImageStream, XMLStream: TStream; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function LoadSystemFont(const FontImage: TSystemFontImage = TSystemFontImage.Font8x8; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;
Public function TextExtent(const Text: UniString): TPoint2f;
Public function TextExtentInt(const Text: UniString): TPoint2i;
Public function TextHeight(const Text: UniString): VectorFloat;
Public function TextHeightInt(const Text: UniString): VectorInt;
Public function TextWidth(const Text: UniString): VectorFloat;
Public function TextWidthInt(const Text: UniString): VectorInt;
Protected function LoadEntriesFromXMLAsset(const AssetName: StdString): Boolean;
Protected function LoadEntriesFromXMLFile(const FileName: StdString): Boolean;
Protected function LoadEntriesFromXMLStream(const Stream: TStream): Boolean;
Public procedure DrawText(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat = 1);
Public procedure DrawTextAligned(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const HorizAlign, VertAlign: TTextAlignment; const Alpha: VectorFloat = 1; const AlignToPixels: Boolean = True);
Public procedure DrawTextBox(const TopLeft, BoxSize, ParagraphShift: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat = 1);
Public procedure DrawTextCentered(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat = 1; const AlignToPixels: Boolean = True);
Public procedure TextRects(const Text: UniString; const List: TFloatRectList);

Properties

Public property Canvas: TCustomCanvas read FCanvas write FCanvas;
Public property Device: TCustomDevice read FDevice;
Public property Height: VectorInt read FSize.Y;
Public property Image: TAtlasImage read FImage;
Public property Interleave: VectorFloat read FInterleave write FInterleave;
Public property Kernings: TKernings read FKernings;
Public property Name: StdString read FName write FName;
Public property ParagraphSeparators: UniString read FParagraphSeparators write FParagraphSeparators;
Public property Scale: VectorFloat read FScale write FScale;
Public property Size: TPoint2i read FSize;
Public property SpaceWidth: VectorFloat read FSpaceWidth write FSpaceWidth;
Public property StyleTags: TStyleTags read FStyleTags write FStyleTags;
Public property SubscribedTextures: Boolean read FSubscribedTextures;
Public property VerticalSpace: VectorFloat read FVerticalSpace write FVerticalSpace;
Public property Width: VectorInt read FSize.X;
Public property WordSeparators: UniString read FWordSeparators write FWordSeparators;

Description

Internal Types

Published TTextEntryEvent = procedure(const Sender: TObject; const FontImage: TAtlasImage; const SourceRect: TIntRect; const DestRect: TFloatRect; const Color: TColorRect; const UserContext: Pointer);

Event invoked by DrawTextCustom method for custom text rendering, called for each text letter.

Parameters
Sender
Reference to class that invoked this method.
FontImage
Font image that should be used as a source for drawing letter.
SourceRect
Rectangle in font image that contains letter image.
DestRect
Destination rectangle, where font image should be rendered.
Color
Color, which should be used for rendering the letter.
UserContext
User context parameter passed to DrawTextCustom.

Fields

Public internal const DefaultBinaryExtension = '.font';

Default font extension when loading binary fonts.

Public internal const DefaultImageExtension = '.png';

Default image extension when loading fonts provided as pair of XML and image files.

Public internal const DefaultXMLExtension = '.xml';

Default XML extension when loading fonts provided as pair of XML and image files.

Protected FEntries: array[0..MaxEntriesCount - 1] of TLetterEntry;

Information regarding locations, spacing and rendering parameters for each of available letters.

Protected FImage: TAtlasImage;

Current font image that contains pre-rendered letters.

Protected FSize: TPoint2i;

Current font size that defines maximum rectangle that a letter can occupy.

Methods

Public constructor Create(const ADevice: TCustomDevice; const ASubscribedTextures: Boolean = True);

Creates new instance of TBitmapFont class bound to the specified device. ASubscribedTextures indicates whether the textures contained in font image should be subscribed to handle "lost device" events. If this font is part of TBitmapFonts list, which provides its own notification events regarding device status, then ASubscribedTextures should be set to False.

Public function DrawTextCustom(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat; const TextEntryEvent: TTextEntryEvent; const UserContext: Pointer; const RestartStyling: Boolean = True): Boolean;

Draws text by invoking external rendering event for each of the letters.

Parameters
Position
Starting position of text at top/left.
Text
The actual text to be drawn.
Color
Two colors representing vertical gradient to fill the letters with.
Alpha
A separate alpha representing transparency of the font (in addition to alpha provided in Color).
TextEntryEvent
Event to be called for each letter being rendered (this excludes whitespace characters such as space or #0).
UserContext
User context parameter that will be passed to each TextEntryEvent call.
RestartStyling
Whether the initial style of the text should be reset. This is typically needed when rendering multi-line text such as in case of DrawTextBox.
Public function LoadFromBinaryAsset(const AssetName: StdString; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads binary font from file in /assets sub-folder. This includes both letter information and font image. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function LoadFromBinaryFile(const FileName: StdString; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads binary font from external file. This includes both letter information and font image. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function LoadFromBinaryStream(const Stream: TStream; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads binary font from the given stream. This includes both letter information and font image. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function LoadFromXMLAsset(const ImageAssetName: StdString; const XMLAssetName: StdString = ''; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads font letter information and letter image from files in /assets sub-folder. This methods accepts that one of file names is left empty and will be guessed by either changing extension from ".xml" to ".png" or vice-versa. This uses image format manager reference from associated device. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function LoadFromXMLFile(const ImageFileName: StdString; const XMLFileName: StdString = ''; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads font letter information and letter image from external files on disk. This methods accepts that one of file names is left empty and will be guessed by either changing extension from ".xml" to ".png" or vice-versa. This uses image format manager reference from associated device. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function LoadFromXMLStream(const ImageExtension: StdString; const ImageStream, XMLStream: TStream; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads font letter information and letter image from their corresponding streams. This uses image format manager reference from associated device. The image extension indicates what image format for letters image is used. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function LoadSystemFont(const FontImage: TSystemFontImage = TSystemFontImage.Font8x8; const PixelFormat: TPixelFormat = TPixelFormat.Unknown): Boolean;

Loads and initializes one of the predefined system fonts. These are embedded within the final application and can be used at any time. The drawback of this is that these fonts don't look pretty as the pre-rendered ones and typically contain only ASCII characters. The given pixel format, if specified, will be used as a hint for initializing font letters image. Returns True when successful and False otherwise.

Public function TextExtent(const Text: UniString): TPoint2f;

Returns total area size that given text string will occupy when rendered.

Public function TextExtentInt(const Text: UniString): TPoint2i;

Returns total area size (rounded to nearest integer) that given text string will occupy when rendered.

Public function TextHeight(const Text: UniString): VectorFloat;

Returns total area height that given text string will occupy when rendered.

Public function TextHeightInt(const Text: UniString): VectorInt;

Returns total area height (rounded to nearest integer) that given text string will occupy when rendered.

Public function TextWidth(const Text: UniString): VectorFloat;

Returns total area width that given text string will occupy when rendered.

Public function TextWidthInt(const Text: UniString): VectorInt;

Returns total area width (rounded to nearest integer) that given text string will occupy when rendered.

Protected function LoadEntriesFromXMLAsset(const AssetName: StdString): Boolean;

Loads letter information from file within /assets sub-folder. Returns True when succeeded and False otherwise.

Protected function LoadEntriesFromXMLFile(const FileName: StdString): Boolean;

Loads letter information from external XML file. Returns True when succeeded and False otherwise.

Protected function LoadEntriesFromXMLStream(const Stream: TStream): Boolean;

Loads letter information from XML file located in the stream. Returns True when succeeded and False otherwise.

Public procedure DrawText(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat = 1);

Draws text at the given position.

Parameters
Position
Starting position of text at top/left.
Text
The actual text to be drawn.
Color
Two colors representing vertical gradient to fill the letters with.
Alpha
A separate alpha representing transparency of the font (in addition to alpha provided in Color).
Public procedure DrawTextAligned(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const HorizAlign, VertAlign: TTextAlignment; const Alpha: VectorFloat = 1; const AlignToPixels: Boolean = True);

Draws text at the given position with specific alignment.

Parameters
Position
Starting position of text at top/left.
Text
The actual text to be drawn.
Color
Two colors representing vertical gradient to fill the letters with.
HorizAlign
Horizontal text alignment in relation to starting position.
VertAlign
Vertical text alignment in relation to starting position.
Alpha
A separate alpha representing transparency of the font (in addition to alpha provided in Color).
AlignToPixels
Whether to align the resulting text position to start at integer location so that all letters are properly aligned to pixels. This may result in clearer text but can appear choppy during text animations (e.g. zoom in or out).
Public procedure DrawTextBox(const TopLeft, BoxSize, ParagraphShift: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat = 1);

Draws text containing multiple lines onto the designated area.

Parameters
TopLeft
Top/left origin of designated area.
BoxSize
Width and height of the designated area in relation to top/left origin.
ParagraphShift
Offset to apply when new text paragraph begins.
Text
Multi-line text to be drawn.
Color
Two colors representing vertical gradient to fill the letters with.
Alpha
A separate alpha representing transparency of the font (in addition to alpha provided in Color).
Public procedure DrawTextCentered(const Position: TPoint2f; const Text: UniString; const Color: TColorPair; const Alpha: VectorFloat = 1; const AlignToPixels: Boolean = True);

Draws text centered around the specified position.

Parameters
Position
Origin around which the text will be rendered.
Text
The actual text to be drawn.
Color
Two colors representing vertical gradient to fill the letters with.
Alpha
A separate alpha representing transparency of the font (in addition to alpha provided in Color).
AlignToPixels
Whether to align the resulting text position to start at integer location so that all letters are properly aligned to pixels. This may result in clearer text but can appear choppy during text animations (e.g. zoom in or out).
Public procedure TextRects(const Text: UniString; const List: TFloatRectList);

Provides information regarding individual letter position and sizes for the given text string when rendered. This can be useful for components such as text edit box, for highlighting and selecting different letters.

Properties

Public property Canvas: TCustomCanvas read FCanvas write FCanvas;

Destination canvas to which the text should be rendered to. This can be changed between different drawing calls to a different canvas, as long as such canvas is bound to the same device as the font.

Public property Device: TCustomDevice read FDevice;

The device to which this font's image is bound to.

Public property Height: VectorInt read FSize.Y;

Font height that defines maximum height in pixels that a letter can occupy.

Public property Image: TAtlasImage read FImage;

The image containing all available font letters.

Public property Interleave: VectorFloat read FInterleave write FInterleave;

Global spacing that will be added horizontally between text letters. This can be used to expand or shrink the text.

Public property Kernings: TKernings read FKernings;

Individual spacing between each combination of two letters to provide pixel-perfect text rendering.

Public property Name: StdString read FName write FName;

Unique name of the font by which it can be referenced in TBitmapFonts list.

Public property ParagraphSeparators: UniString read FParagraphSeparators write FParagraphSeparators;

Characters that can be used to indicate start of new paragraph in multi-line text drawing with DrawTextBox.

Public property Scale: VectorFloat read FScale write FScale;

Global font scale that is applied to the whole rendered text. Changing this value will likely result in non-pixel-perfect text rendering appearing blurry. However, it can be used for text animations.

Public property Size: TPoint2i read FSize;

Font size that defines maximum rectangle that a letter can occupy.

Public property SpaceWidth: VectorFloat read FSpaceWidth write FSpaceWidth;

The width in pixels corresponding to "space" or other empty characters (that is, characters without an image).

Public property StyleTags: TStyleTags read FStyleTags write FStyleTags;

Style tags that can be used to provide different colors in large texts.

Public property SubscribedTextures: Boolean read FSubscribedTextures;

Indicates whether this font's image has textures subscribed to device events, handling scenarios such as "device lost". If this is set to False, likely the handling is provided by parent list class such as TBitmapFonts by calling the appropriate image functions.

Public property VerticalSpace: VectorFloat read FVerticalSpace write FVerticalSpace;

Global spacing that will be added vertically between text lines when drawing with DrawTextBox.

Public property Width: VectorInt read FSize.X;

Font width that defines maximum width in pixels that a letter can occupy.

Public property WordSeparators: UniString read FWordSeparators write FWordSeparators;

Characters that can be used to separate words in multi-line text drawing with DrawTextBox.

Copyright © 2000 - 2017 Yuriy Kotsarenko. Help files generated by PasDoc.