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.

Checking the stable version of the documentation...

Importazione di immagini

Formati di immagine supportati

Godot può importare i seguenti formati di immagine:

• BMP (.bmp) - No support for 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported.

• DirectDraw Surface (.dds) - If mipmaps are present in the texture, they will be loaded directly. This can be used to achieve effects using custom mipmaps.

• Khronos Texture (.ktx) - Decoding is done using libktx. Only supports 2D images. Cubemaps, texture arrays and de-padding are not supported.

• OpenEXR (.exr) - Supporta HDR (altamente consigliato per i cieli panoramici).

• Radiance HDR (.hdr) - Supporta HDR (altamente consigliato per cieli panoramici).

• JPEG (.jpg, .jpeg) - Non supporta la trasparenza a causa delle limitazioni del formato.

• PNG (.png) - La precisione è limitata a 8 bit per canale all'importazione (niente immagini HDR).

• Truevision Targa (.tga)

• SVG (.svg) - SVGs are rasterized using ThorVG when importing them. Support is limited; complex vectors may not render correctly. Text must be converted to paths; otherwise, it won't appear in the rasterized image. You can check whether ThorVG can render a certain vector correctly using its web-based viewer. For complex vectors, rendering them to PNGs using Inkscape is often a better solution. This can be automated thanks to its command-line interface.

• WebP (.webp) - I file WebP supportano la trasparenza e possono essere compressi con o senza perdita di dati. La precisione è limitata a 8 bit per canale.

Nota

If you've compiled the Godot editor from source with specific modules disabled, some formats may not be available.

Importazione di texture

The default action in Godot is to import images as textures. Textures are stored in video memory. Their pixel data can't be accessed directly from the CPU without converting them back to an Image in a script. This is what makes drawing them efficient.

There are over a dozen import options that can be adjusted after selecting an image in the FileSystem dock:

Opzioni di importazione nel pannello Importazione dopo aver selezionato un'immagine nel pannello FileSystem Alcune di queste opzioni sono visibili solo con determinate modalità di compressione.

Cambiare il tipo da importare

È possibile scegliere altri tipi di risorse importate nel pannello Importazione:

• BitMap: Texture monocromatica a 1 bit (pensata all'uso come maschera di clic in TextureButton e TouchScreenButton). Questo tipo di risorsa non si può visualizzare direttamente su nodi 2D o 3D, ma è possibile richiedere i valori dei pixel da uno script tramite get_bit.

• Cubemap: Importa la texture come cubemap a 6 lati, con interpolazione tra i lati della cubemap (continua senza bordi netti), che può essere campionata in shader personalizzati.

• CubemapArray: Import the texture as a collection of 6-sided cubemaps, which can be sampled in custom shaders. This resource type can only be displayed when using the Forward+ or Mobile renderers, not the Compatibility renderer.

• Font Data (Monospace Image Font): Import the image as a bitmap font where all characters have the same width. See Utilizzare i font.

• Immagine: Importa l'immagine così com'è. Questo tipo di risorsa non può essere visualizzato direttamente su nodi 2D o 3D, ma è possibile richiedere i valori dei pixel da uno script tramite get_pixel.

• Texture2D: importa l'immagine come texture bidimensionale, adatta alla visualizzazione su superfici 2D e 3D. Questa è la modalità di importazione predefinita.

• Texture2DArray: Importa l'immagine come una raccolta di texture bidimensionali. Texture2DArray è simile a una texture tridimensionale, ma senza interpolazione tra i livelli. Gli shader 2D e 3D integrati non possono visualizzare array di texture, quindi è necessario creare uno shader personalizzato in 2D o 3D per visualizzare una texture da un array di texture.

• Texture3D: importa l'immagine come texture tridimensionale. Questa non è una texture 2D applicata su una superficie 3D. Texture3D è simile a un array di texture, ma con interpolazione tra i livelli. Texture3D è in genere utilizzata per le mappe di densità di un FogMaterial nella nebbia volumetrica, per i campi vettoriali degli attrattori di particelle, per la correzione del colore LUT 3D Environment e per shader personalizzati.

• TextureAtlas: importa l'immagine come un atlante di diverse texture. Si può usare per ridurre l'uso di memoria per gli sprite 2D animati. Supportato solo in 2D a causa del supporto mancante negli shader 3D integrati.

Per Cubemap, l'ordine previsto delle immagini è X+, X-, Y+, Y-, Z+, Z- (nel sistema di coordinate di Godot, quindi Y+ è "su" e Z- è "avanti"). Ecco alcuni modelli che si possono utilizzare per le immagini cubemap (clic destro > Salva collegamento con nome…):

• modello di cubemap 2×3 (opzione di layout predefinta)

• modello di cubemap 3×2

• modello di cubemap 1×6

• modello di cubemap 6×1

Rileva 3D

The default import options (no mipmaps and Lossless compression) are suited for 2D, but are not ideal for most 3D projects. Detect 3D makes Godot aware of when a texture is used in a 3D scene (such as a texture in a BaseMaterial3D). If this happens, several import options are changed so the texture flags are friendlier to 3D. Mipmaps are enabled and the compression mode is changed to VRAM Compressed unless Detect 3D > Compress To is changed. The texture is also reimported automatically.

Quando viene rilevata una texture utilizzata in 3D, viene visualizzato un messaggio nel pannello Output.

If you run into quality issues when a texture is detected to be used in 3D (e.g. for pixel art textures), change the Detect 3D > Compress To option before using the texture in 3D, or change Compress > Mode to Lossless after using the texture in 3D. This is preferable to disabling Detect 3D, as mipmap generation remains enabled to prevent textures from looking grainy at a distance.

Opzioni di importazione

Vedi anche

Since Godot 4.0, texture filter and repeat modes are set in the CanvasItem properties in 2D (with a project setting acting as a default), and in a per-material configuration in 3D. In custom shaders, filter and repeat mode is changed on the sampler2D uniform using hints described in the Linguaggio di shading documentation.

Compress > Mode

Le immagini sono una delle risorse più importanti di un gioco. Per gestirle in modo efficiente, devono essere compresse. Godot offre diversi metodi di compressione, a seconda del caso d'uso.

• Lossless: This is the default and most common compression mode for 2D assets. It shows assets without any kind of artifacting, and disk compression is decent. It will use considerably more amount of video memory than VRAM Compression, though. This is also the recommended setting for pixel art.

• Lossy: This is a good choice for large 2D assets. It has some artifacts, but less than VRAM compression and the file size is several times lower compared to Lossless or VRAM Uncompressed. Video memory usage isn't decreased by this mode; it's the same as with Lossless or VRAM Uncompressed.

• VRAM Compressed: This is the default and most common compression mode for 3D assets. Size on disk is reduced and video memory usage is also decreased considerably (usually by a factor between 4 and 6). This mode should be avoided for 2D as it exhibits noticeable artifacts, especially for lower-resolution textures.

• VRAM Uncompressed: Only useful for formats that can't be compressed, such as raw floating-point images.

• Basis Universal: This alternative VRAM compression mode encodes the texture to a format that can be transcoded to most GPU-compressed formats at load-time. This provides very small files that make use of VRAM compression, at the cost of lower quality compared to VRAM Compressed and slow compression times. VRAM usage is usually the same as VRAM Compressed. Basis Universal does not support floating-point image formats (the engine will internally fall back to VRAM Compressed instead).

Nota

Even in 3D, "pixel art" textures should have VRAM compression disabled as it will negatively affect their appearance, without improving performance significantly due to their low resolution.

In questa tabella, ciascuna delle 5 opzioni è descritta insieme ai relativi vantaggi e svantaggi ( = la migliore, = la peggiore):

Modalità di compressione	Senza perdita	Con perdita	Compresso per VRAM	Non compresso per VRAM	Basis Universal
Descrizione	Memorizzato come WebP/PNG senza perdita (lossless)	Memorizzato come WebP con perdita (Lossy)	Memorizzato come S3TC, BPTC o ETC2 a seconda della piattaforma	Memorizzati come pixel grezzi	Transcodificato in formato compresso per VRAM
Dimensione sul disco	Piccolo	Molto piccolo	Piccolo	Largo	Molto piccolo
Utilizzo di memoria	Largo	Largo	Piccolo	Largo	Piccolo
Prestazioni	Normale	Normale	Veloce	Normale	Veloce
Perdita di qualità	Nessuna	Leggera	Moderata	Nessuna	Moderata
Tempo di caricamento	Lento	Lento	Veloce	Normale	Normale

Utilizzo stimato della memoria per una singola texture RGBA8 con mipmap abilitate:

Dimensioni della texture	Senza perdita	Con perdita	Compresso per VRAM	Non compresso per VRAM	Basis Universal
128×128	85 KiB	85 KiB	21 KiB	85 KiB	21 KiB
256×256	341 KiB	341 KiB	85 KiB	341 KiB	85 KiB
512×512	1.33 MiB	1.33 MiB	341 KiB	1.33 MiB	341 KiB
1024×1024	5.33 MiB	5.33 MiB	1.33 MiB	5.33 MiB	1.33 MiB
2048×2048	21.33 MiB	21.33 MiB	5.33 MiB	21.33 MiB	5.33 MiB
4096×4096	85.33 MiB	85.33 MiB	21.33 MiB	85.33 MiB	21.33 MiB

Nota

Nella tabella sopra, l'utilizzo della memoria sarà ridotto del 25% per le immagini che non hanno un canale alfa (RGB8). L'utilizzo della memoria sarà ulteriormente ridotto del 25% per le immagini con mipmap disabilitate.

Si noti come, a risoluzioni più elevate, l'impatto della compressione VRAM sia molto maggiore. Con un rapporto di compressione di 4:1 (6:1 per texture opache con S3TC), la compressione VRAM consente effettivamente di raddoppiare le dimensioni di una texture su ciascun asse, utilizzando la stessa quantità di memoria sulla GPU.

La compressione VRAM riduce anche la larghezza di banda di memoria necessaria per campionare la texture, il che può accelerare il rendering in scenari limitati dalla larghezza di banda (frequenti su schede grafiche integrate e dispositivi mobili). Questi fattori combinati rendono la compressione VRAM un must per i giochi 3D con texture ad alta risoluzione.

È possibile vedere in anteprima la quantità di memoria occupata da una texture facendo doppio clic su di essa nel pannello FileSystem, quindi osservando l'Ispettore:

Anteprima di una texture nell'Ispettore. Crediti: Red Brick 03 - Poly Haven

Compress > High Quality

Nota

La compressione delle texture in VRAM di alta qualità è supportata solo nei renderer Forward+ e Mobile.

Quando si utilizza il renderer Compatibilità, questa opzione è sempre considerata disabilitata.

Se abilitato, utilizza la compressione BPTC sulle piattaforme desktop e la compressione ASTC sulle piattaforme mobili. Quando si utilizza BPTC, BC7 è utilizzato per le texture SDR e BC6H per le texture HDR.

Se disabilitato (predefinito), utilizza la compressione S3TC, più veloce ma di qualità inferiore, sulle piattaforme desktop e ETC2 sulle piattaforme mobile/web. Quando si utilizza S3TC, DXT1 (BC1) è utilizzato per le texture opache e DXT5 (BC3) per le texture trasparenti o a mappa di normali (RGTC).

BPTC e ASTC supportano la compressione VRAM per le texture HDR, ma S3TC ed ETC2 no (vedere Compressione HDR di seguito).

Comprimi > Compressione HDR

Nota

Questa opzione ha effetto solo sulle texture importate in formati HDR in Godot (file .hdr e .exr).

If set to Disabled, never uses VRAM compression for HDR textures, regardless of whether they're opaque or transparent. Instead, the texture is converted to RGBE9995 (9-bits per channel + 5-bit exponent = 32 bits per pixel) to reduce memory usage compared to a half-float or single-precision float image format.

If set to Opaque Only (default), only uses VRAM compression for opaque HDR textures. This is due to a limitation of HDR formats, as there is no VRAM-compressed HDR format that supports transparency at the same time.

If set to Always, will force VRAM compression even for HDR textures with an alpha channel. To perform this, the alpha channel is discarded on import.

Comprimi > Mappa di normali

When using a texture as normal map, only the red and green channels are required. Given regular texture compression algorithms produce artifacts that don't look that nice in normal maps, the RGTC compression format is the best fit for this data. Forcing this option to Enable will make Godot import the image as RGTC compressed. By default, it's set to Detect. This means that if the texture is ever detected to be used as a normal map, it will be changed to Enable and reimported automatically.

Note that RGTC compression affects the resulting normal map image. You will have to adjust custom shaders that use the normal map's blue channel to take this into account. Built-in material shaders already ignore the blue channel in a normal map (regardless of the actual normal map's contents).

In the example below, the normal map with RGTC compression is able to preserve its detail much better, while using the same amount of memory as a standard RGBA VRAM-compressed texture:

Normal map with standard VRAM compression (left) and with RGTC VRAM compression (right)

Nota

Godot requires the normal map to use the X+, Y+ and Z+ coordinates, which is known as an OpenGL-style normal map. If you've imported a material made to be used with another engine, it may be DirectX-style. In this case, the normal map needs to be converted by enabling the Normal Map Invert Y import option.

Ulteriori informazioni sulle mappe di normali (inclusa una tabella di ordine delle coordinate per i motori più diffusi) sono disponibili qui.

Compress > Channel Pack

If set to sRGB Friendly (default), prevents the RG color format from being used as it does not support sRGB color.

If set to Optimized, allows the RG color format to be used if the texture does not use the blue channel.

A third option Normal Map (RG Channels) is only available in layered textures (Cubemap, CubemapArray, Texture2DArray and Texture3D). This forces all layers from the texture to be imported with the RG color format, with only the red and green channels preserved. RGTC compression is able to preserve its detail much better, while using the same amount of memory as a standard RGBA VRAM-compressed texture. This only has an effect on textures with the VRAM Compressed or Basis Universal compression modes.

Mipmap > Genera

If enabled, smaller versions of the texture are generated on import. For example, a 64×64 texture will generate 6 mipmaps (32×32, 16×16, 8×8, 4×4, 2×2, 1×1). This has several benefits:

• Textures will not become grainy in the distance (in 3D), or if scaled down due to camera zoom or CanvasItem scale (in 2D).

• Performance will improve if the texture is displayed in the distance, since sampling smaller versions of the original texture is faster and requires less memory bandwidth.

The downside of mipmaps is that they increase memory usage by roughly 33%.

It's recommended to enable mipmaps in 3D. However, in 2D, this should only be enabled if your project visibly benefits from having mipmaps enabled. If the camera never zooms out significantly, there won't be a benefit to enabling mipmaps but memory usage will increase.

Mipmap > Limite

Avvertimento

Mipmaps > Limit is currently not implemented and has no effect when changed.

If set to a value greater than -1, limits the maximum number of mipmaps that can be generated. This can be decreased if you don't want textures to become too low-resolution at extreme distances, at the cost of some graininess.

Rugosità > Modalità

The color channel to consider as a roughness map in this texture. Only effective if Roughness > Src Normal is not empty.

Roughness > Src Normal

The path to the texture to consider as a normal map for roughness filtering on import. Specifying this can help decrease specular aliasing slightly in 3D.

Roughness filtering on import is only used in 3D rendering, not 2D.

Process > Fix Alpha Border

This puts pixels of the same surrounding color in transition from transparent to opaque areas. For textures displayed with bilinear filtering, this helps mitigate the outline effect when exporting images from an image editor.

It's recommended to leave this enabled (as it is by default), unless this causes issues for a particular image.

Process > Premult Alpha

An alternative to fixing darkened borders with Fix Alpha Border is to use premultiplied alpha. By enabling this option, the texture will be converted to this format. A premultiplied alpha texture requires specific materials to be displayed correctly:

• In 2D, a CanvasItemMaterial will need to be created and configured to use the Premul Alpha blend mode on CanvasItems that use this texture. In custom canvas item shaders, render_mode blend_premul_alpha; should be used.

• In 3D, a BaseMaterial3D will need to be created and configured to use the Premul Alpha blend mode on materials that use this texture. In custom spatial shaders, render_mode blend_premul_alpha; should be used.

Process > Normal Map Invert Y

Godot requires the normal map to use the X+, Y+ and Z+ coordinates, which is known as an OpenGL-style normal map. If you've imported a material made to be used with another engine, it may be DirectX-style. In this case, the normal map needs to be converted by enabling the Normal Map Invert Y import option.

Ulteriori informazioni sulle mappe di normali (inclusa una tabella di ordine delle coordinate per i motori più diffusi) sono disponibili qui.

Process > HDR as sRGB

Some HDR images you can find online may be broken and contain sRGB color data (instead of linear color data). It is advised not to use those files. If you absolutely have to, enabling this option on will make them look correct.

Avvertimento

Enabling HDR as sRGB on well-formatted HDR images will cause the resulting image to look too dark, so leave this disabled if unsure.

Process > HDR Clamp Exposure

Some HDR panorama images you can find online may contain extremely bright pixels, due to being taken from real life sources without any clipping.

While these HDR panorama images are accurate to real life, this can cause the radiance map generated by Godot to contain sparkles when used as a background sky. This can be seen in material reflections (even on rough materials in extreme cases). Enabling HDR Clamp Exposure can resolve this using a smart clamping formula that does not introduce visible clipping – glow will keep working when looking at the background sky.

Process > Size Limit

If set to a value greater than 0, the size of the texture is limited on import to a value smaller than or equal to the value specified here. For non-square textures, the size limit affects the longer dimension, with the shorter dimension scaled to preserve aspect ratio. Resizing is performed using cubic interpolation.

This can be used to reduce memory usage without affecting the source images, or avoid issues with textures not displaying on mobile/web platforms (as these usually can't display textures larger than 4096×4096).

Detect 3D > Compress To

This changes the Compress > Mode option that is used when a texture is detected as being used in 3D.

Changing this import option only has an effect if a texture is detected as being used in 3D. Changing this to Disabled then reimporting will not change the existing compress mode on a texture (if it's detected to be used in 3D), but choosing VRAM Compressed or Basis Universal will.

SVG > Scala

This is only available for SVG images.

The scale the SVG should be rendered at, with 1.0 being the original design size. Higher values result in a larger image. Note that unlike font oversampling, this affects the physical size the SVG is rendered at in 2D. See also Editor > Scale With Editor Scale below.

Editor > Scale With Editor Scale

This is only available for SVG images.

If true, scales the imported image to match the editor's display scale factor. This should be enabled for editor plugin icons and custom class icons, but should be left disabled otherwise.

Editor > Converti i colori con il tema dell'editor

This is only available for SVG images.

If checked, converts the imported image's colors to match the editor's icon and font color palette. This assumes the image uses the exact same colors as Godot's own color palette for editor icons, with the source file designed for a dark editor theme. This should be enabled for editor plugin icons and custom class icons, but should be left disabled otherwise.

Importare immagini SVG con testo

As the SVG library used in Godot doesn't support rasterizing text found in SVG images, text must be converted to a path first. Otherwise, text won't appear in the rasterized image.

There are two ways to achieve this in a non-destructive manner, so you can keep editing the original text afterwards:

• Select your text object in Inkscape, then duplicate it in place by pressing Ctrl + D and use Path > Object to Path. Hide the original text object afterwards using the Layers and Objects dock.

• Use the Inkscape command line to export an SVG from another SVG file with text converted to paths:

inkscape --export-text-to-path --export-filename svg_with_text_converted_to_path.svg svg_with_text.svg

Le migliori pratiche

Supportare dimensioni di texture ad alta risoluzione in 2D senza artefatti

Per supportare più risoluzioni con immagini nitide ad alta risoluzione, sarà necessario utilizzare immagini sorgente ad alta risoluzione (adatte alla risoluzione più alta che serve supportare senza sfocature, che in genere è 4K nei moderni giochi per desktop).

Ci sono due modi per procedere:

• Utilizza una risoluzione base elevata nelle impostazioni del progetto (ad esempio 4K), quindi utilizza le texture nella scala originale. Questo è un approccio più semplice.

• Utilizza una risoluzione base bassa nelle impostazioni del progetto (ad esempio 1080p), poi riduci la risoluzione delle texture quando le usi. Questo è spesso più difficile e può rendere noiosi vari calcoli nello script, quindi si consiglia l'approccio descritto in precedenza.

Dopo averlo fatto, potresti notare che le texture diventano granulose a risoluzioni più basse. Per risolvere questo problema, abilita Mipmap sulle texture utilizzate in 2D nel pannello Importazione. Questo aumenterà l'utilizzo di memoria.

Enabling mipmaps can also make textures appear blurrier, but you can choose to make textures sharper (at the cost of some graininess) by setting Rendering > Textures > Default Filters > Texture Mipmap Bias to a negative value.

Usa dimensioni di texture appropriate in 3D

Sebbene non ci sia una raccomandazione valida per tutto, ecco alcuni consigli generali per scegliere le dimensioni delle texture in 3D:

• Le dimensioni di una texture si dovrebbero regolare in modo da avere una densità di texel uniforme rispetto agli oggetti circostanti. Sebbene ciò non si possa garantire perfettamente mantenendo le dimensioni pari a potenze di due, di solito è possibile mantenere un dettaglio della texture abbastanza uniforme in tutta una scena 3D.

• Più piccolo appare l'oggetto sullo schermo, più piccola dovrebbe essere la sua texture. Ad esempio, un albero che appare solo sullo sfondo non ha bisogno di una risoluzione di texture elevata quanto quella di altri oggetti vicino ai quali il giocatore potrebbe camminare.

• Si consiglia di utilizzare dimensioni di texture pari a potenze di due, ma non è obbligatorio. Le texture non devono essere quadrate: dimensioni come 1024×512 sono accettabili.

• There are diminishing returns to using large texture sizes, despite the increased memory usage and loading times. Most modern 3D games not using a pixel art style stick to 2048×2048 textures on average, with 1024×1024 and 512×512 for textures spanning smaller surfaces.

• Quando si lavora con materiali basati sulla fisica in 3D, è possibile ridurre l'utilizzo di memoria e le dimensioni dei file senza compromettere eccessivamente la qualità, utilizzando una risoluzione più bassa per alcune mappe di texture. Questo funziona particolarmente bene per le texture che presentano solo dettagli a bassa frequenza (come una mappa di normali per una texture di neve).

Se hai il controllo sul modo in cui sono creati i modelli 3D, vale la pena di approfondire anche questi suggerimenti:

• Quando si lavora con modelli 3D prevalentemente simmetrici, si potrebbero utilizzare UV speculari per raddoppiare la densità effettiva dei texel. Tuttavia, ciò potrebbe apparire innaturale se applicato ai volti umani.

• Quando si lavora con modelli 3D aventi uno stile low-poly e colori semplici, è possibile affidarsi ai colori dei vertici anziché alle texture per rappresentare i colori sulle superfici del modello.

Vedi anche

Le immagini si possono caricare e salvare in fase di esecuzione utilizzando caricamento e salvataggio di file in fase di esecuzione, anche da un progetto esportato.