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...
TextureStreaming
Experimental: This class may be changed or removed in future versions.
Inherits: Object
Manages dynamic texture mipmap streaming to optimize VRAM usage.
Description
The TextureStreaming singleton manages dynamic loading and unloading of texture mipmap levels based on what is visible in the current frame. This allows projects with many large textures to significantly reduce VRAM usage while maintaining visual quality for visible textures.
Texture streaming works by analyzing shader feedback to determine which textures are actively being used and at what resolution they're being displayed. Textures that are far from the camera or not currently visible have their higher-resolution mipmap levels unloaded, while textures being displayed up close are loaded at higher resolutions.
The system includes a memory budget feature that automatically manages texture resolutions to stay within a specified VRAM limit. When the budget is exceeded, the system prioritizes textures based on how recently they were used and how much screen space they occupy.
Note: Texture streaming must be enabled in the Project Settings (ProjectSettings.rendering/textures/streaming/enabled) and textures must be imported with streaming support to use this feature.
Properties
|
||
|
||
|
Methods
void |
|
Signals
flush_completed() 🔗
Emitted when a texture streaming flush operation finishes, after flush_texture_streaming() has been called and all managed textures have reached their target resolutions.
Property Descriptions
Overrides the maximum LOD (mipmap level) that can be loaded for streamed textures at runtime. Lower values allow higher resolution textures. Valid values are 0 (full resolution) to 13 (lowest resolution). Values outside that range clear the override and use the default from ProjectSettings.rendering/textures/streaming/max_lod; when no override is active this property returns -1.
int memory_budget_mb_override = 4294967295 🔗
Overrides the memory budget for streamed textures at runtime (in megabytes). When the budget is exceeded, the system reduces texture resolution to stay within the limit. A value of UINT32_MAX (4294967295, the maximum unsigned 32-bit integer) disables the override and uses the default from ProjectSettings.rendering/textures/streaming/memory_budget_mb.
Overrides the minimum LOD (mipmap level) that textures start at when loaded. Higher values result in lower initial resolution. Valid values are 0 (full resolution) to 13 (lowest resolution). Values outside that range clear the override and use the default from ProjectSettings.rendering/textures/streaming/min_lod; when no override is active this property returns -1.
Method Descriptions
void flush_texture_streaming() 🔗
Forces all currently queued texture streaming operations to complete immediately, bypassing the normal gradual transition and I/O throttling. This immediately loads or unloads mipmap levels to reach the target resolution for all managed textures, then emits the flush_completed signal. Useful during loading screens or when teleporting the player to ensure all textures are at their optimal resolution without a visible transition.
int get_memory_budget_bytes_used() 🔗
Returns the current VRAM usage of streamed textures in bytes. This represents the total memory consumed by all streamed textures at their currently loaded mipmap levels.