API Reference

Class TCastleFont

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleFonts

Declaration

type TCastleFont = class(TCastleAbstractFont)

Description

Font loaded from a font file, like ttf or otf. This class is typically used for outline (scalable, vector) fonts in ttf or otf formats. But it can really deal with any font supported by the FreeType library, even bitmap fonts, see the summary of font formats supported by FreeType.

This can load a font file, or it can use ready data in TTextureFontData. The latter allows to use this for fonts embedded in a Pascal source code, since our texture-font-to-pascal can convert a font file to a unit that defines ready TTextureFontData instance.

Hierarchy

Overview

Fields

Public nested const DefaultOptimalSize = 20;

Methods

Public constructor Create(AOwner: TComponent); overload; override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public function FontLoaded: Boolean; overload; override;
Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharList = nil); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';
Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TSetOfChars); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';
Public procedure Load(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharList = nil; const AdjustProperties: Boolean = true); overload; deprecated 'assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';
Public procedure Load(const Data: TTextureFontData; const OwnsData: Boolean = false; const AdjustProperties: Boolean = true); overload;
Public procedure PrepareResources; override;
Public procedure Print(const X, Y: Single; const Color: TCastleColor; const S: String); override;
Public function TextWidth(const S: String): Single; override;
Public function TextHeight(const S: String): Single; override;
Public function TextHeightBase(const S: String): Single; override;
Public function TextMove(const S: String): TVector2; override;

Properties

Public property FontData: TTextureFontData read FFont; deprecated 'you should not need to use this directly';
Public property Scale: Single read GetScale write SetScale;
Published property Url: String read FUrl write SetUrl;
Published property DistanceField: Boolean read FDistanceField write SetDistanceField default false;
Published property OptimalSize: Cardinal read FOptimalSize write SetOptimalSize default DefaultOptimalSize;
Published property AntiAliased: Boolean read FAntiAliased write SetAntiAliased default true;
Published property LoadBasicCharacters: Boolean read FLoadBasicCharacters write SetLoadBasicCharacters default true;
Published property LoadCharacters: String read FLoadCharacters write SetLoadCharacters;

Description

Fields

Public nested const DefaultOptimalSize = 20;

This item has no description.

Methods

Public constructor Create(AOwner: TComponent); overload; override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Public function FontLoaded: Boolean; overload; override;

This item has no description. Showing description inherited from TCastleAbstractFont.FontLoaded.

If the font is loaded, it can actually display and measure some characters.

Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharList = nil); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';

Warning: this symbol is deprecated: use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url

This item has no description.

Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TSetOfChars); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';

Warning: this symbol is deprecated: use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url

This item has no description.

Public procedure Load(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharList = nil; const AdjustProperties: Boolean = true); overload; deprecated 'assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';

Warning: this symbol is deprecated: assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url

Load by reading a FreeType font file, like ttf.

Providing charaters list as Nil means that we only create glyphs for SimpleAsciiCharacters, which includes only the basic ASCII characters. The ACharacters instance does not become owned by this object, so remember to free it after calling this constructor.

Loading a font data also changes Size to the underlying (optimal to render) font data size.

Public procedure Load(const Data: TTextureFontData; const OwnsData: Boolean = false; const AdjustProperties: Boolean = true); overload;

Load from a ready TTextureFontData instance.

Parameters
Data
TTextureFontData instance containing loaded image and glyphs parameters.
OwnsData
If True, the Data instance becomes owned by this class (will be freed in our constructor). Usually you do not want this, since usually you pass Data from a unit generated by texture-font-to-pascal. In this case, the finalization of CastleTextureFont_Xxx unit will already free the TTextureFontData instance.
AdjustProperties
Adjust Url, OptimalSize, Size, AntiAliased to reflect loaded Data. Or reset them to reflect empty Url (and the rest at defaults) when Data = nil.
Public procedure PrepareResources; override;

This item has no description. Showing description inherited from TCastleAbstractFont.PrepareResources.

The font may require some OpenGL resources for drawing. You can explicitly create them using PrepareResources (although it is never needed, resources will be automatically created if needed). There's no public method to explicitly destroy them, they are always destroyed automatically.

Public procedure Print(const X, Y: Single; const Color: TCastleColor; const S: String); override;

This item has no description. Showing description inherited from TCastleAbstractFont.Print.

Draw text at the given position with given color. If the last Color component is not 1, the text is rendered with blending.

Overloaded version without X, Y uses WindowPos (but doesn't modify it, in contrast to PrintAndMove). Overloaded version without Color uses CurrentColor, last color set by glColorv. It is not adviced to use overloaded versions without X, Y or Color — using global state leads to messy code. You should upgrade your code to use the version that gets X,Y,Color explicitly.

Public function TextWidth(const S: String): Single; override;

This item has no description.

Public function TextHeight(const S: String): Single; override;

This item has no description.

Public function TextHeightBase(const S: String): Single; override;

This item has no description. Showing description inherited from TCastleAbstractFont.TextHeightBase.

The height (above the baseline) of the text. This doesn't take into account height of the text below the baseline (for example letter "y" has the tail below the baseline in most fonts).

Public function TextMove(const S: String): TVector2; override;

This item has no description.

Properties

Public property FontData: TTextureFontData read FFont; deprecated 'you should not need to use this directly';

Warning: this symbol is deprecated: you should not need to use this directly

Underlying font data.

Public property Scale: Single read GetScale write SetScale;

Scale applied to the rendered font, compared to FontData.Size. Changing this is equivalent to changing the Size property.

Published property Url: String read FUrl write SetUrl;

Loaded font file. Typically this is used for outline (scalable, vector) fonts in ttf or otf formats. But it can really deal with any font format supported by the FreeType library, even bitmap fonts, see the summary of font formats supported by FreeType.

Published property DistanceField: Boolean read FDistanceField write SetDistanceField default false;

Use "distance field" font rendering. This is a font rendering technique that may result in a better quality when the text is large.

Underneath, the font is processed to a different texture than usual (that expresses distances to glyphs) and rendered usign a special shader.

The positive outcome is that the font looks better (not blurred) even when scaled up. "Scaling up" occurs when the actual font size (derived from TCastleUserInterfaceFont.FontSize and UI scaling) is significantly larger than the optimal size for which the font image was prepared (OptimalSize). In this case, rendering without distance field (when this is False, by default) results in blurred font look. When this is True, the look remains "crisp".

Disadvantages:

One, preparing a distance field font texture is more time-consuming. So loading time may be slightly larger. This increased loading time is generally negligible if you just have a few fonts. But be sure to profile your loading time (see https://castle-engine.io/manual_optimization.php ) if you use a lot of fonts with DistanceField = True.

A more serious disadvantage is that the result is not always a better quality: At really large sizes, the artifacts of distance field rendering may be visible – the letters are "crisp" but their shape may be slightly distorted. If you don't mind extra memory usage, you can likely get better quality by just loading a larger font texture (with larger OptimalSize) and leaving this property at False.

Morover, when the final font size is *smaller* than the size for which the font was prepared, it will definitely look worse.

TODO: We could defeat some of the issues mentioned above. You're welcome to ping us ( https://castle-engine.io/talk.php ) and support ( https://www.patreon.com/castleengine ) to make it happen.

  • The loading time of fonts (with and without distance fields) could be improved by generating the necessary texture at preprocessing, introducing "castle-engine auto-generate" command that would generalize current "castle-engine auto-generate-textures".

  • TCastleText (text in a viewport) cannot handle fonts with DistanceField yet. Result would not be sensible. For now, TCastleText.FontStyleFontChanged warns about it and forces DistanceField to False.

  • It is possible that the quality could be improved:

    Implement normalization. Can this make downscaling better? Does this make upscaling better? See https://libgdx.com/wiki/graphics/2d/fonts/distance-field-fonts what it means.

  • Introduce a fallback on non-distance-field texture, used when downscaling happens?

    This means larger memory usage, and potential jump in look if someone animates FontSize.

Published property OptimalSize: Cardinal read FOptimalSize write SetOptimalSize default DefaultOptimalSize;

Optimal font size (in real device pixels), the font will be scaled when other size is actually needed. This also sets default Size used for rendering this font.

Published property AntiAliased: Boolean read FAntiAliased write SetAntiAliased default true;

Anti-aliased font has smooth edges and is rendered using blending. Usually this is much better for quality. Non-anti-aliased means that font uses simple yes/no transparency and is rendered using alpha testing.

Published property LoadBasicCharacters: Boolean read FLoadBasicCharacters write SetLoadBasicCharacters default true;

Load from font all "basic" characters, which include digits, English letters and standard ASCII symbols. See SimpleAsciiCharacters for exact definition. These are loaded in addition to characters listed on LoadCharacters.

Published property LoadCharacters: String read FLoadCharacters write SetLoadCharacters;

Load from font all characters listed here. As everywhere in CGE (same as in Lazarus LCL), this is an String composed from UTF-8 characters.

Generated by PasDoc 0.16.0-snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.