Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

FontFile

Eredita: Font < Resource < RefCounted < Object

Contiene i dati sorgente del font e la cache dei glifi prerenderizzati, importati da un font dinamico o bitmap.

Descrizione

FontFile contiene un insieme di glifi per rappresentare i caratteri Unicode importati da un file di font, oltre che una cache di glifi rasterizzati e un insieme di Font di riserva da usare.

Utilizza FontVariation per accedere a una specifica variazione OpenType del font, creare una versione simulata in grassetto/inclinata e disegnare righe di testo.

Per un'elaborazione più complessa di testo, utilizza FontVariation insieme a TextLine o TextParagraph.

Formati di font supportati:

  • Importatore di font dinamico: TrueType (.ttf), collezione TrueType (.ttc), OpenType (.otf), collezione OpenType (.otc), WOFF (.woff), WOFF2 (.woff2), Type 1 (.pfb, .pfm).

  • Importatore di font bitmap: AngelCode BMFont (.fnt, .font), varianti di formato testo e binario (versione 3).

  • Importatore di font immagine a spaziatura fissa: tutti i formati immagine supportati.

Nota: Un carattere è un simbolo che rappresenta un elemento (lettera, cifra, ecc.) in modo astratto.

Nota: Un glifo è una bitmap o una forma utilizzata per disegnare uno o più caratteri in modo dipendente dal contesto. Gli indici dei glifi sono associati alla specifica sorgente dati del font.

Nota: Se nessuna delle sorgenti dati del font contiene glifi per un carattere usato in una stringa, il carattere in questione sarà sostituito con una casella che visualizza il suo codice esadecimale.

var f = load("res://BarlowCondensed-Bold.ttf")
$Label.add_theme_font_override("font", f)
$Label.add_theme_font_size_override("font_size", 64)

Tutorial

Proprietà

bool

allow_system_fallback

true

FontAntialiasing

antialiasing

1

PackedByteArray

data

PackedByteArray()

bool

disable_embedded_bitmaps

true

int

fixed_size

0

FixedSizeScaleMode

fixed_size_scale_mode

0

String

font_name

""

int

font_stretch

100

BitField[FontStyle]

font_style

0

int

font_weight

400

bool

force_autohinter

false

bool

generate_mipmaps

false

Hinting

hinting

1

bool

keep_rounding_remainders

true

bool

modulate_color_glyphs

false

int

msdf_pixel_range

16

int

msdf_size

48

bool

multichannel_signed_distance_field

false

Dictionary

opentype_feature_overrides

{}

float

oversampling

0.0

String

style_name

""

SubpixelPositioning

subpixel_positioning

1

Metodi

void

clear_cache()

void

clear_glyphs(cache_index: int, size: Vector2i)

void

clear_kerning_map(cache_index: int, size: int)

void

clear_size_cache(cache_index: int)

void

clear_textures(cache_index: int, size: Vector2i)

float

get_cache_ascent(cache_index: int, size: int) const

int

get_cache_count() const

float

get_cache_descent(cache_index: int, size: int) const

float

get_cache_scale(cache_index: int, size: int) const

float

get_cache_underline_position(cache_index: int, size: int) const

float

get_cache_underline_thickness(cache_index: int, size: int) const

int

get_char_from_glyph_index(size: int, glyph_index: int) const

float

get_embolden(cache_index: int) const

float

get_extra_baseline_offset(cache_index: int) const

int

get_extra_spacing(cache_index: int, spacing: SpacingType) const

int

get_face_index(cache_index: int) const

Vector2

get_glyph_advance(cache_index: int, size: int, glyph: int) const

int

get_glyph_index(size: int, char: int, variation_selector: int) const

PackedInt32Array

get_glyph_list(cache_index: int, size: Vector2i) const

Vector2

get_glyph_offset(cache_index: int, size: Vector2i, glyph: int) const

Vector2

get_glyph_size(cache_index: int, size: Vector2i, glyph: int) const

int

get_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int) const

Rect2

get_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int) const

Vector2

get_kerning(cache_index: int, size: int, glyph_pair: Vector2i) const

Array[Vector2i]

get_kerning_list(cache_index: int, size: int) const

bool

get_language_support_override(language: String) const

PackedStringArray

get_language_support_overrides() const

bool

get_script_support_override(script: String) const

PackedStringArray

get_script_support_overrides() const

Array[Vector2i]

get_size_cache_list(cache_index: int) const

int

get_texture_count(cache_index: int, size: Vector2i) const

Image

get_texture_image(cache_index: int, size: Vector2i, texture_index: int) const

PackedInt32Array

get_texture_offsets(cache_index: int, size: Vector2i, texture_index: int) const

Transform2D

get_transform(cache_index: int) const

Dictionary

get_variation_coordinates(cache_index: int) const

Error

load_bitmap_font(path: String)

Error

load_dynamic_font(path: String)

void

remove_cache(cache_index: int)

void

remove_glyph(cache_index: int, size: Vector2i, glyph: int)

void

remove_kerning(cache_index: int, size: int, glyph_pair: Vector2i)

void

remove_language_support_override(language: String)

void

remove_script_support_override(script: String)

void

remove_size_cache(cache_index: int, size: Vector2i)

void

remove_texture(cache_index: int, size: Vector2i, texture_index: int)

void

render_glyph(cache_index: int, size: Vector2i, index: int)

void

render_range(cache_index: int, size: Vector2i, start: int, end: int)

void

set_cache_ascent(cache_index: int, size: int, ascent: float)

void

set_cache_descent(cache_index: int, size: int, descent: float)

void

set_cache_scale(cache_index: int, size: int, scale: float)

void

set_cache_underline_position(cache_index: int, size: int, underline_position: float)

void

set_cache_underline_thickness(cache_index: int, size: int, underline_thickness: float)

void

set_embolden(cache_index: int, strength: float)

void

set_extra_baseline_offset(cache_index: int, baseline_offset: float)

void

set_extra_spacing(cache_index: int, spacing: SpacingType, value: int)

void

set_face_index(cache_index: int, face_index: int)

void

set_glyph_advance(cache_index: int, size: int, glyph: int, advance: Vector2)

void

set_glyph_offset(cache_index: int, size: Vector2i, glyph: int, offset: Vector2)

void

set_glyph_size(cache_index: int, size: Vector2i, glyph: int, gl_size: Vector2)

void

set_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int, texture_idx: int)

void

set_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int, uv_rect: Rect2)

void

set_kerning(cache_index: int, size: int, glyph_pair: Vector2i, kerning: Vector2)

void

set_language_support_override(language: String, supported: bool)

void

set_script_support_override(script: String, supported: bool)

void

set_texture_image(cache_index: int, size: Vector2i, texture_index: int, image: Image)

void

set_texture_offsets(cache_index: int, size: Vector2i, texture_index: int, offset: PackedInt32Array)

void

set_transform(cache_index: int, transform: Transform2D)

void

set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary)


Descrizioni delle proprietà

bool allow_system_fallback = true 🔗

  • void set_allow_system_fallback(value: bool)

  • bool is_allow_system_fallback()

Se impostato su true, i font del sistema possono essere utilizzati automaticamente come alternative di riserva.


FontAntialiasing antialiasing = 1 🔗

Modalità anti-aliasing del font.


PackedByteArray data = PackedByteArray() 🔗

Contenuto del file sorgente del font dinamico.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.


bool disable_embedded_bitmaps = true 🔗

  • void set_disable_embedded_bitmaps(value: bool)

  • bool get_disable_embedded_bitmaps()

Se impostato su true, il caricamento delle bitmap dei font incorporati è disabilitato (i font solo con bitmap e i font colorati ignorano questa proprietà).


int fixed_size = 0 🔗

  • void set_fixed_size(value: int)

  • int get_fixed_size()

Dimensione del font, utilizzata solo per i font bitmap.


FixedSizeScaleMode fixed_size_scale_mode = 0 🔗

Modalità di ridimensionamento, utilizzata solo per i font bitmap con fixed_size maggiore di zero.


String font_name = "" 🔗

Nome della famiglia del font.


int font_stretch = 100 🔗

  • void set_font_stretch(value: int)

  • int get_font_stretch()

Quantità di allungamento del font, rispetto a una larghezza normale. Un valore percentuale compreso tra 50% e 200%.


BitField[FontStyle] font_style = 0 🔗

Flag di stile del font.


int font_weight = 400 🔗

  • void set_font_weight(value: int)

  • int get_font_weight()

Peso (grassetto) del font. Un valore nell'intervallo 100...999, il peso normale di un font è 400, il peso di un font in grassetto è 700.


bool force_autohinter = false 🔗

  • void set_force_autohinter(value: bool)

  • bool is_force_autohinter()

Se impostato su true, l'hinting automatico è supportato e preferito rispetto all'hinting integrato nel font. Utilizzato solo dai font dinamici (i font MSDF non supportano l'hinting).


bool generate_mipmaps = false 🔗

  • void set_generate_mipmaps(value: bool)

  • bool get_generate_mipmaps()

Se impostato su true, genera mipmap per le texture del font.


Hinting hinting = 1 🔗

Modalità di hinting del font. Utilizzata solo dai font dinamici.


bool keep_rounding_remainders = true 🔗

  • void set_keep_rounding_remainders(value: bool)

  • bool get_keep_rounding_remainders()

Se impostato su true, quando si allineano i glifi ai confini dei pixel, il resto dopo l'arrotondamento viene accumulato per garantire una distribuzione più uniforme dei glifi. Questa impostazione non ha effetto se è abilitato il posizionamento subpixel.


bool modulate_color_glyphs = false 🔗

  • void set_modulate_color_glyphs(value: bool)

  • bool is_modulate_color_glyphs()

Se impostato su true, la modulazione del colore è applicata quando si disegnano glifi colorati, altrimenti è applicata solo ai glifi monocromatici.


int msdf_pixel_range = 16 🔗

  • void set_msdf_pixel_range(value: int)

  • int get_msdf_pixel_range()

The width of the range around the shape between the minimum and maximum representable signed distance. If using font outlines, msdf_pixel_range must be set to at least twice the size of the largest font outline. The default msdf_pixel_range value of 16 allows outline sizes up to 8 to look correct.


int msdf_size = 48 🔗

  • void set_msdf_size(value: int)

  • int get_msdf_size()

Dimensione del font sorgente utilizzata per generare le texture MSDF. Valori più alti consentono una maggiore precisione, ma sono più lenti da renderizzare e richiedono più memoria. Aumenta questo valore solo se noti una notevole mancanza di precisione nel rendering dei glifi.


bool multichannel_signed_distance_field = false 🔗

  • void set_multichannel_signed_distance_field(value: bool)

  • bool is_multichannel_signed_distance_field()

Se impostato su true, i glifi di tutte le dimensioni sono renderizzati attraverso un singolo multichannel signed distance field (MSDF) generato dai dati dinamici del vettore del font. Poiché questo approccio non si basa sulla rasterizzazione del font ogni volta che ne cambia la dimensione, ciò consente di ridimensionare il font in tempo reale senza alcuna penalità sulle prestazioni. Il testo non apparirà granuloso per i Control ridimensionati (o per i Label3D visti da molto lontano). Come svantaggio, l'hinting del font non è disponibile con MSDF. Senza hinting i font potrebbero essere meno nitidi e meno leggibili a piccole dimensioni.

Nota: Se si utilizzano contorni del font, msdf_pixel_range deve essere impostato almeno su il doppio della dimensione del contorno del font più grande.

Nota: Il rendering dei font MSDF non renderizza correttamente i glifi con forme sovrapposte. Le forme sovrapposte non sono valide secondo lo standard OpenType, ma sono comunque presenti in molti file di font, in particolare quelli convertiti da Google Fonts. Per evitare problemi con i glifi sovrapposti, si consiglia di scaricare il file dei font direttamente dalla type foundry invece di affidarti a Google Fonts.


Dictionary opentype_feature_overrides = {} 🔗

  • void set_opentype_feature_overrides(value: Dictionary)

  • Dictionary get_opentype_feature_overrides()

Sostituzione dell'insieme di funzionalità OpenType dei font.


float oversampling = 0.0 🔗

  • void set_oversampling(value: float)

  • float get_oversampling()

Se impostato su un valore positivo, sostituisce il fattore di sovracampionamento della viewport in cui è utilizzato questo font. Vedi Viewport.oversampling. Questo valore non sostituisce il parametro oversampling dei metodi draw_*.


String style_name = "" 🔗

  • void set_font_style_name(value: String)

  • String get_font_style_name()

Nome dello stile del font.


SubpixelPositioning subpixel_positioning = 1 🔗

Modalità di posizionamento subpixel del glifo del font. Il posizionamento subpixel fornisce testo più definito e migliore crenatura per le dimensioni di font più piccole, a costo di un maggiore utilizzo di memoria e di una minore velocità di rasterizzazione del font. Utilizza TextServer.SUBPIXEL_POSITIONING_AUTO per abilitarlo automaticamente in base alle dimensioni del font.


Descrizioni dei metodi

void clear_cache() 🔗

Rimuove tutte le voci nella cache del font.


void clear_glyphs(cache_index: int, size: Vector2i) 🔗

Rimuove tutte le informazioni sui glifi renderizzati dalla voce nella cache.

Nota: Questa funzione non rimuoverà le texture associate ai glifi, usa remove_texture() per rimuoverle manualmente.


void clear_kerning_map(cache_index: int, size: int) 🔗

Rimuove tutte le sostituzioni di crenatura.


void clear_size_cache(cache_index: int) 🔗

Rimuove tutte le dimensioni del font dalla voce nella cache.


void clear_textures(cache_index: int, size: Vector2i) 🔗

Rimuove tutte le texture dalla voce nella cache del font.

Nota: Questa funzione non rimuoverà i glifi associati alla texture, usa remove_glyph() per rimuoverli manualmente.


float get_cache_ascent(cache_index: int, size: int) const 🔗

Restituisce l'ascesa del font (numero di pixel sopra la linea di base).


int get_cache_count() const 🔗

Restituisce il numero delle voci nella cache del font.


float get_cache_descent(cache_index: int, size: int) const 🔗

Restituisce la discesa del font (numero di pixel sotto la linea di base).


float get_cache_scale(cache_index: int, size: int) const 🔗

Restituisce il fattore di scala del font bitmap a colori.


float get_cache_underline_position(cache_index: int, size: int) const 🔗

Restituisce l'offset in pixel della sottolineatura sotto la linea di base.


float get_cache_underline_thickness(cache_index: int, size: int) const 🔗

Restituisce lo spessore della sottolineatura in pixel.


int get_char_from_glyph_index(size: int, glyph_index: int) const 🔗

Restituisce il codice carattere associato all'indice glyph_index, oppure 0 se glyph_index non è valido. Vedi get_glyph_index().


float get_embolden(cache_index: int) const 🔗

Restituisce l'intensità del grassetto, se non è uguale a zero, applica il grassetto ai contorni del font. I valori negativi riducono lo spessore del contorno.


float get_extra_baseline_offset(cache_index: int) const 🔗

Restituisce lo scostamento aggiuntivo dalla linea di base (come frazione dell'altezza del font).


int get_extra_spacing(cache_index: int, spacing: SpacingType) const 🔗

Restituisce la spaziatura per spacing in pixel (non relativa alle dimensioni del font).


int get_face_index(cache_index: int) const 🔗

Restituisce un indice di faccia attivo nella collezione TrueType / OpenType.


Vector2 get_glyph_advance(cache_index: int, size: int, glyph: int) const 🔗

Restituisce l'avanzamento di un glifo (scostamento del glifo successivo).

Nota: L'avanzamento per i contorni dei glifi è lo stesso di quello di base e non viene salvato.


int get_glyph_index(size: int, char: int, variation_selector: int) const 🔗

Restituisce l'indice del glifo del carattere char, facoltativamente modificato dal selettore di variazione variation_selector.


PackedInt32Array get_glyph_list(cache_index: int, size: Vector2i) const 🔗

Restituisce la lista dei glifi renderizzati nella voce nella cache.


Vector2 get_glyph_offset(cache_index: int, size: Vector2i, glyph: int) const 🔗

Restituisce l'offset del glifo dalla linea di base.


Vector2 get_glyph_size(cache_index: int, size: Vector2i, glyph: int) const 🔗

Restituisce le dimensioni del glifo.


int get_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int) const 🔗

Restituisce l'indice della texture nella cache contenente il glifo.


Rect2 get_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int) const 🔗

Restituisce il rettangolo nella texture nella cache contenente il glifo.


Vector2 get_kerning(cache_index: int, size: int, glyph_pair: Vector2i) const 🔗

Restituisce la crenatura per la coppia di glifi.


Array[Vector2i] get_kerning_list(cache_index: int, size: int) const 🔗

Restituisce la lista delle sostituzioni di crenatura.


bool get_language_support_override(language: String) const 🔗

Restituisce true se la sostituzione di supporto è abilitata per la lingua language.


PackedStringArray get_language_support_overrides() const 🔗

Restituisce la lista di sostituzioni di supporto di lingua.


bool get_script_support_override(script: String) const 🔗

Restituisce true se la sostituzione di supporto è abilitata per l'alfabeto script.


PackedStringArray get_script_support_overrides() const 🔗

Restituisce la lista delle sostituzioni di supporto d'alfabeto.


Array[Vector2i] get_size_cache_list(cache_index: int) const 🔗

Restituisce la lista delle dimensioni del font nella cache. Ogni dimensione è un Vector2i con dimensioni del font e dimensioni del contorno.


int get_texture_count(cache_index: int, size: Vector2i) const 🔗

Restituisce il numero di texture utilizzate dalla voce nella cache del font.


Image get_texture_image(cache_index: int, size: Vector2i, texture_index: int) const 🔗

Restituisce una copia dell'immagine della texture nella cache del font.


PackedInt32Array get_texture_offsets(cache_index: int, size: Vector2i, texture_index: int) const 🔗

Restituisce una copia dell'array contenente i dati di impacchettamento dei glifi.


Transform2D get_transform(cache_index: int) const 🔗

Restituisce una trasformazione 2D, applicata ai contorni del font, che può essere utilizzata per inclinare, capovolgere e ruotare i glifi.


Dictionary get_variation_coordinates(cache_index: int) const 🔗

Restituisce le coordinate di variazione per la voce specificata nella cache del font. Vedi Font.get_supported_variation_list() per maggiori informazioni.


Error load_bitmap_font(path: String) 🔗

Carica un font bitmap AngelCode BMFont (.fnt, .font) dal file al percorso path.

Attenzione: Questo metodo dovrebbe essere utilizzato solo nell'editor o nei casi in cui è necessario caricare font esterni in fase di esecuzione, come i font che si trovano nella cartella user://.


Error load_dynamic_font(path: String) 🔗

Carica un font dinamico TrueType (.ttf), OpenType (.otf), WOFF (.woff), WOFF2 (.woff2) o Type 1 (.pfb, .pfm) dal file al percorso path.

Attenzione: Questo metodo dovrebbe essere utilizzato solo nell'editor o nei casi in cui è necessario caricare font esterni in fase di esecuzione, come i font che si trovano nella cartella user://.


void remove_cache(cache_index: int) 🔗

Rimuove la voce specificata nella cache del font.


void remove_glyph(cache_index: int, size: Vector2i, glyph: int) 🔗

Rimuove le informazioni specificate sui glifi renderizzati dalla voce nella cache.

Nota: Questa funzione non rimuoverà le texture associate ai glifi, usa remove_texture() per rimuoverle manualmente.


void remove_kerning(cache_index: int, size: int, glyph_pair: Vector2i) 🔗

Rimuove la sostituzione della crenatura per la coppia di glifi.


void remove_language_support_override(language: String) 🔗

Rimuove la sostituzione di supporto di lingua.


void remove_script_support_override(script: String) 🔗

Rimuove la sostituzione di supporto d'alfabeto.


void remove_size_cache(cache_index: int, size: Vector2i) 🔗

Rimuove la dimensione specificata del font dalla voce nella cache.


void remove_texture(cache_index: int, size: Vector2i, texture_index: int) 🔗

Rimuove la texture specificata dalla voce nella cache.

Nota: Questa funzione non rimuoverà i glifi associati alla texture. Rimuovili manualmente usando remove_glyph().


void render_glyph(cache_index: int, size: Vector2i, index: int) 🔗

Renderizza il glifo specificato nella texture nella cache del font.


void render_range(cache_index: int, size: Vector2i, start: int, end: int) 🔗

Renderizza l'intervallo di caratteri nella texture nella cache del font.


void set_cache_ascent(cache_index: int, size: int, ascent: float) 🔗

Imposta l'ascesa del font (numero di pixel sopra la linea di base).


void set_cache_descent(cache_index: int, size: int, descent: float) 🔗

Imposta la discesa del font (numero di pixel sotto la linea di base).


void set_cache_scale(cache_index: int, size: int, scale: float) 🔗

Imposta il fattore di scala del font bitmap a colori.


void set_cache_underline_position(cache_index: int, size: int, underline_position: float) 🔗

Imposta l'offset in pixel della sottolineatura sotto la linea di base.


void set_cache_underline_thickness(cache_index: int, size: int, underline_thickness: float) 🔗

Imposta lo spessore della sottolineatura in pixel.


void set_embolden(cache_index: int, strength: float) 🔗

Imposta l'intensità del grassetto, se non è uguale a zero, applica il grassetto ai contorni del font. I valori negativi riducono lo spessore del contorno.


void set_extra_baseline_offset(cache_index: int, baseline_offset: float) 🔗

Imposta lo scostamento aggiuntivo dalla linea di base (come frazione dell'altezza del font).


void set_extra_spacing(cache_index: int, spacing: SpacingType, value: int) 🔗

Imposta la spaziatura per spacing su value in pixel (non relativa alla dimensione del font).


void set_face_index(cache_index: int, face_index: int) 🔗

Imposta un indice di faccia attivo nella collezione TrueType/OpenType.


void set_glyph_advance(cache_index: int, size: int, glyph: int, advance: Vector2) 🔗

Imposta l'avanzamento del glifo (offset del glifo successivo).

Nota: L'avanzamento per i contorni dei glifi è lo stesso dell'avanzamento del glifo di base e non viene salvato.


void set_glyph_offset(cache_index: int, size: Vector2i, glyph: int, offset: Vector2) 🔗

Imposta l'offset del glifo dalla linea di base.


void set_glyph_size(cache_index: int, size: Vector2i, glyph: int, gl_size: Vector2) 🔗

Imposta le dimensioni del glifo.


void set_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int, texture_idx: int) 🔗

Imposta l'indice della texture nella cache contenente il glifo.


void set_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int, uv_rect: Rect2) 🔗

Imposta il rettangolo nella texture nella cache contenente il glifo.


void set_kerning(cache_index: int, size: int, glyph_pair: Vector2i, kerning: Vector2) 🔗

Imposta la crenatura per la coppia di glifi.


void set_language_support_override(language: String, supported: bool) 🔗

Aggiunge una sostituzione per Font.is_language_supported().


void set_script_support_override(script: String, supported: bool) 🔗

Aggiunge una sostituzione per Font.is_script_supported().


void set_texture_image(cache_index: int, size: Vector2i, texture_index: int, image: Image) 🔗

Imposta l'immagine della texture nella cache del font.


void set_texture_offsets(cache_index: int, size: Vector2i, texture_index: int, offset: PackedInt32Array) 🔗

Imposta l'array contenente i dati di impacchettamento dei glifi.


void set_transform(cache_index: int, transform: Transform2D) 🔗

Imposta la trasformazione 2D, applicata ai contorni del font, che può essere utilizzata per inclinare, capovolgere e ruotare i glifi.


void set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary) 🔗

Imposta le coordinate di variazione per la voce specificata nella cache del font. Vedi Font.get_supported_variation_list() per maggiori informazioni.