TextServer¶
Inherits: RefCounted < Object
Inherited By: TextServerAdvanced, TextServerExtension, TextServerFallback
Interface for the fonts and complex text layouts.
Description¶
TextServer
is the API backend for managing fonts, and rendering complex text.
Methods¶
Enumerations¶
enum Direction:
DIRECTION_AUTO = 0 --- Text direction is determined based on contents and current locale.
DIRECTION_LTR = 1 --- Text is written from left to right.
DIRECTION_RTL = 2 --- Text is written from right to left.
enum Orientation:
ORIENTATION_HORIZONTAL = 0 --- Text is written horizontally.
ORIENTATION_VERTICAL = 1 --- Left to right text is written vertically from top to bottom.
Right to left text is written vertically from bottom to top.
enum JustificationFlag:
JUSTIFICATION_NONE = 0 --- Do not justify text.
JUSTIFICATION_KASHIDA = 1 --- Justify text by adding and removing kashidas.
JUSTIFICATION_WORD_BOUND = 2 --- Justify text by changing width of the spaces between the words.
JUSTIFICATION_TRIM_EDGE_SPACES = 4 --- Remove trailing and leading spaces from the justified text.
JUSTIFICATION_AFTER_LAST_TAB = 8 --- Only apply justification to the part of the text after the last tab.
JUSTIFICATION_CONSTRAIN_ELLIPSIS = 16 --- Apply justification to the trimmed line with ellipsis.
enum LineBreakFlag:
BREAK_NONE = 0 --- Do not break the line.
BREAK_MANDATORY = 32 --- Break the line at the line mandatory break characters (e.g.
"\n"
).BREAK_WORD_BOUND = 64 --- Break the line between the words.
BREAK_GRAPHEME_BOUND = 128 --- Break the line between any unconnected graphemes.
BREAK_WORD_BOUND_ADAPTIVE = 320 --- Break the line between the words, or any unconnected graphemes if line is too short to fit the whole word.
enum TextOverrunFlag:
OVERRUN_NO_TRIMMING = 0 --- No trimming is performed.
OVERRUN_TRIM = 1 --- Trims the text when it exceeds the given width.
OVERRUN_TRIM_WORD_ONLY = 2 --- Trims the text per word instead of per grapheme.
OVERRUN_ADD_ELLIPSIS = 4 --- Determines whether an ellipsis should be added at the end of the text.
OVERRUN_ENFORCE_ELLIPSIS = 8 --- Determines whether the ellipsis at the end of the text is enforced and may not be hidden.
OVERRUN_JUSTIFICATION_AWARE = 16
enum GraphemeFlag:
GRAPHEME_IS_VALID = 1 --- Grapheme is supported by the font, and can be drawn.
GRAPHEME_IS_RTL = 2 --- Grapheme is part of right-to-left or bottom-to-top run.
GRAPHEME_IS_VIRTUAL = 4 --- Grapheme is not part of source text, it was added by justification process.
GRAPHEME_IS_SPACE = 8 --- Grapheme is whitespace.
GRAPHEME_IS_BREAK_HARD = 16 --- Grapheme is mandatory break point (e.g.
"\n"
).GRAPHEME_IS_BREAK_SOFT = 32 --- Grapheme is optional break point (e.g. space).
GRAPHEME_IS_TAB = 64 --- Grapheme is the tabulation character.
GRAPHEME_IS_ELONGATION = 128 --- Grapheme is kashida.
GRAPHEME_IS_PUNCTUATION = 256 --- Grapheme is punctuation character.
GRAPHEME_IS_UNDERSCORE = 512 --- Grapheme is underscore character.
GRAPHEME_IS_CONNECTED = 1024 --- Grapheme is connected to the previous grapheme. Breaking line before this grapheme is not safe.
enum Hinting:
HINTING_NONE = 0 --- Disables font hinting (smoother but less crisp).
HINTING_LIGHT = 1 --- Use the light font hinting mode.
HINTING_NORMAL = 2 --- Use the default font hinting mode (crisper but less smooth).
enum SubpixelPositioning:
SUBPIXEL_POSITIONING_DISABLED = 0 --- Glyph horizontal position is rounded to the whole pixel size, each glyph is rasterized once.
SUBPIXEL_POSITIONING_AUTO = 1 --- Glyph horizontal position is rounded based on font size.
To one quarter of the pixel size if font size is smaller or equal to
16
.To one half of the pixel size if font size is smaller or equal to
20
.To the whole pixel size for larger fonts.
SUBPIXEL_POSITIONING_ONE_HALF = 2 --- Glyph horizontal position is rounded to one half of the pixel size, each glyph is rasterized up to two times.
SUBPIXEL_POSITIONING_ONE_QUARTER = 3 --- Glyph horizontal position is rounded to one quarter of the pixel size, each glyph is rasterized up to four times.
enum Feature:
FEATURE_BIDI_LAYOUT = 1 --- TextServer supports bidirectional layouts.
FEATURE_VERTICAL_LAYOUT = 2 --- TextServer supports vertical layouts.
FEATURE_SHAPING = 4 --- TextServer supports complex text shaping.
FEATURE_KASHIDA_JUSTIFICATION = 8 --- TextServer supports justification using kashidas.
FEATURE_BREAK_ITERATORS = 16 --- TextServer supports complex line/word breaking rules (e.g. dictionary based).
FEATURE_FONT_SYSTEM = 32 --- TextServer supports loading system fonts.
FEATURE_FONT_VARIABLE = 64 --- TextServer supports variable fonts.
FEATURE_CONTEXT_SENSITIVE_CASE_CONVERSION = 128 --- TextServer supports locale dependent and context sensitive case conversion.
FEATURE_USE_SUPPORT_DATA = 256 --- TextServer require external data file for some features.
enum ContourPointTag:
CONTOUR_CURVE_TAG_ON = 1 --- Contour point is on the curve.
CONTOUR_CURVE_TAG_OFF_CONIC = 0 --- Contour point isn't on the curve, but serves as a control point for a conic (quadratic) Bézier arc.
CONTOUR_CURVE_TAG_OFF_CUBIC = 2 --- Contour point isn't on the curve, but serves as a control point for a cubic Bézier arc.
enum SpacingType:
SPACING_GLYPH = 0 --- Spacing for each glyph.
SPACING_SPACE = 1 --- Spacing for the space character.
SPACING_TOP = 2 --- Spacing at the top of the line.
SPACING_BOTTOM = 3 --- Spacing at the bottom of the line.
enum FontStyle:
FONT_BOLD = 1 --- Font is bold.
FONT_ITALIC = 2 --- Font is italic or oblique.
FONT_FIXED_WIDTH = 4 --- Font have fixed-width characters.
Method Descriptions¶
RID create_font ( )
Creates new, empty font cache entry resource. To free the resulting resourec, use free_rid method.
RID create_shaped_text ( Direction direction=0, Orientation orientation=0 )
Creates new buffer for complex text layout, with the given direction
and orientation
. To free the resulting buffer, use free_rid method.
Note: Direction is ignored if server does not support FEATURE_BIDI_LAYOUT feature (supported by TextServerAdvanced).
Note: Orientation is ignored if server does not support FEATURE_VERTICAL_LAYOUT feature (supported by TextServerAdvanced).
Draws box displaying character hexadecimal code. Used for replacing missing characters.
Removes all rendered glyphs information from the cache entry.
Note: This function will not remove textures associated with the glyphs, use font_remove_texture to remove them manually.
Removes all kerning overrides.
void font_clear_size_cache ( RID font_rid )
Removes all font sizes from the cache entry
Removes all textures from font cache entry.
Note: This function will not remove glyphs associated with the texture, use font_remove_glyph to remove them manually.
void font_draw_glyph ( RID font_rid, RID canvas, int size, Vector2 pos, int index, Color color=Color(1, 1, 1, 1) ) const
Draws single glyph into a canvas item at the position, using font_rid
at the size size
.
Note: Glyph index is specific to the font, use glyphs indices returned by shaped_text_get_glyphs or font_get_glyph_index.
void font_draw_glyph_outline ( RID font_rid, RID canvas, int size, int outline_size, Vector2 pos, int index, Color color=Color(1, 1, 1, 1) ) const
Draws single glyph outline of size outline_size
into a canvas item at the position, using font_rid
at the size size
.
Note: Glyph index is specific to the font, use glyphs indices returned by shaped_text_get_glyphs or font_get_glyph_index.
Returns the font ascent (number of pixels above the baseline).
Returns the font descent (number of pixels below the baseline).
Returns font embolden strength.
Returns bitmap font fixed size.
float font_get_global_oversampling ( ) const
Returns the font oversampling factor, shared by all fonts in the TextServer.
Returns glyph advance (offset of the next glyph).
Note: Advance for glyphs outlines is the same as the base glyph advance and is not saved.
Dictionary font_get_glyph_contours ( RID font, int size, int index ) const
Returns outline contours of the glyph as a Dictionary
with the following contents:
points
- PackedVector3Array, containing outline points. x
and y
are point coordinates. z
is the type of the point, using the ContourPointTag values.
contours
- PackedInt32Array, containing indices the end points of each contour.
orientation
- bool, contour orientation. If true
, clockwise contours must be filled.
Returns the glyph index of a char
, optionally modified by the variation_selector
.
Returns list of rendered glyphs in the cache entry.
Returns glyph offset from the baseline.
Returns size of the glyph.
Returns index of the cache texture containing the glyph.
Returns rectangle in the cache texture containing the glyph.
Returns the font hinting mode. Used by dynamic fonts only.
Returns kerning for the pair of glyphs.
Returns list of the kerning overrides.
Returns true
if support override is enabled for the language
.
PackedStringArray font_get_language_support_overrides ( RID font_rid )
Returns list of language support overrides.
Returns the width of the range around the shape between the minimum and maximum representable signed distance.
Returns source font size used to generate MSDF textures.
Returns font family name.
Dictionary font_get_opentype_feature_overrides ( RID font_rid ) const
Returns font OpenType feature set override.
Returns font oversampling factor, if set to 0.0
global oversampling factor is used instead. Used by dynamic fonts only.
Returns scaling factor of the color bitmap font.
Returns true
if support override is enabled for the script
.
PackedStringArray font_get_script_support_overrides ( RID font_rid )
Returns list of script support overrides.
Returns list of the font sizes in the cache. Each size is Vector2i
with font size and outline size.
int font_get_spacing ( RID font_rid, int size, SpacingType spacing ) const
Returns extra spacing added between glyphs in pixels.
Returns font style flags, see FontStyle.
Returns font style name.
SubpixelPositioning font_get_subpixel_positioning ( RID font_rid ) const
Returns font sub-pixel glyph positioning mode.
Returns a string containing all the characters available in the font.
Returns number of textures used by font cache entry.
Returns font cache texture image data.
PackedInt32Array font_get_texture_offsets ( RID font_rid, Vector2i size, int texture_index ) const
Returns array containing the first free pixel in the each column of texture. Should be the same size as texture width or empty.
Transform2D font_get_transform ( RID font_rid ) const
Returns 2D transform applied to the font outlines.
Returns pixel offset of the underline below the baseline.
Returns thickness of the underline in pixels.
Dictionary font_get_variation_coordinates ( RID font_rid ) const
Returns variation coordinates for the specified font cache entry. See font_supported_variation_list for more info.
Returns true
if a Unicode char
is available in the font.
Returns true
if font 8-bit anitialiased glyph rendering is supported and enabled.
Returns true
if auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only.
Returns true
, if font supports given language (ISO 639 code).
Returns true
if glyphs of all sizes are rendered using single multichannel signed distance field generated from the dynamic font vector data.
Returns true
, if font supports given script (ISO 15924 code).
Removes specified rendered glyph information from the cache entry.
Note: This function will not remove textures associated with the glyphs, use font_remove_texture to remove them manually.
Removes kerning override for the pair of glyphs.
Remove language support override.
Removes script support override.
Removes specified font size from the cache entry.
Removes specified texture from font cache entry.
Note: This function will not remove glyphs associated with the texture, remove them manually, using font_remove_glyph.
Renders specified glyph the the font cache texture.
Renders the range of characters to the font cache texture.
If set to true
, 8-bit antialiased glyph rendering is used, otherwise 1-bit rendering is used. Used by dynamic fonts only.
Sets the font ascent (number of pixels above the baseline).
void font_set_data ( RID font_rid, PackedByteArray data )
Sets font source data, e.g contents of the dynamic font source file.
Sets the font descent (number of pixels below the baseline).
Sets font embolden strength. If strength
is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness.
Sets bitmap font fixed size. If set to value greater than zero, same cache entry will be used for all font sizes.