Skip to main content
Version: Next (dev)

Memory Budgets

The engine keeps resource loading and streaming inside four memory domains: CPU resource storage, GPU (device) memory, temporary upload storage, and ray tracing acceleration structures (BLAS). Before optional work starts, such as a streamed mip, a mesh detail level or a volume frame, it reserves the memory it will need. If a domain is full, the work waits instead of pushing the device over its limit.

The GPU budget comes from the device. DX12 uses the DXGI report. Vulkan uses VK_EXT_memory_budget when the driver supports it, and estimates otherwise. The policy is active in Shipping builds too.

How the GPU budget is split​

The application GPU budget is the device's budget minus Memory.GPUHeadroomPercent (10%), which stays free for driver allocations and budget changes. Memory.GPUAppBudgetMB can lower it further, for example to test a smaller card.

The three streaming pools take shares of that budget:

PoolShareUpper bound
Texture mips45% (Rendering.Textures.Streaming.BudgetPercent)Rendering.Textures.Streaming.BudgetMB (0 = no extra cap)
Mesh detail (streamed full meshes)35%Rendering.Meshes.Streaming.BudgetMB (2048)
BLAS (ray tracing)20%, shared by static and dynamic BLASRendering.RT.Scene.StaticBLASBudgetMB (2048, 0 = no extra cap)

Each pool also never takes more than the headroom that other allocations leave free. Render targets, shadow maps, GI buffers and other non-streamed allocations are not part of the pools, but they count towards the device total.

Pressure and priorities​

Each domain has a pressure state: Normal, Elevated from 85% use, and Critical from 95%. It returns to Normal below 80%, and to Elevated below 90%.

How much of a budget a load may use depends on its resource priority:

PriorityMay fill the budget up to
Critical100%
High, Very High95%
Medium90%
Low, Very Low80%

Under pressure:

  • Textures outside the main and editor views drop mips (see pressure bias).
  • Mesh detail can be evicted, and the static BLAS cache releases unused entries sooner.
  • World streaming stops speculative preloads, and idle level content is released at once instead of after Streaming.ResourceKeepAliveSeconds.
  • Staging pools stop growing and release empty pools.

Loads that something is blocked on are always admitted, even over budget, so that one resource waiting for another cannot deadlock. Speculative preloads never use that path.

note

The budgets are an admission policy based on estimates, not a hard process-wide memory cap. Required loads, very large single uploads, render targets and non-resource allocations can exceed them.

Configuration​

These CVars are saved, so a project can override them in its configuration.

CVarDefaultDescription
Memory.CPUResourceBudgetMB4096CPU resource data, pending loads and staging pools together. 0 = unlimited.
Memory.GPUAppBudgetMB0Optional smaller GPU application limit. 0 = use the device budget.
Memory.GPUHeadroomPercent10Share of the device budget kept free for the driver and budget changes.
Memory.UploadBudgetMB256Temporary resource reads, geometry and volume fetches, and staging pools together. Also counts against the CPU budget. 0 = unlimited.
Memory.UploadPerFrameMB64Upload allowance per frame shared by optional mesh-detail requests and volume frames.
Resource.MaxConcurrentLoads4Resource files read at the same time, 1–64.
Resource.MaxPendingLoads16Resource reads and content updates in flight together, 1–256.
Resource.LoadReservationMB16Storage reserved for a load before its real size is known.
Streaming.ResourceKeepAliveSeconds30How long idle level prefab and collection content stays loaded. Pressure removes the delay.

Monitor the budgets​

  • Memory HUD. Rendering.Memory.Hud shows the GPU total against the budget, each streaming pool against its own budget, and GPU memory by owner. See Texture Streaming.
  • Status bar. In the editor, the GPU readout in the status bar shows the engine process's GPU use against its budget.
  • Stats. Memory/CPU/, Memory/GPU/, Memory/Upload/ and Memory/BLAS/ each publish LimitMB, UsedMB, ReservedMB, PeakMB, Pressure (0 = Normal, 1 = Elevated, 2 = Critical), Deferred and RequiredAdmissions. Memory/CancelledLoads, Memory/Upload/FramePeakMB and Memory/Upload/FrameDeferred explain cancelled loads and upload pacing. See Stats.
  • Streaming ledger. Streaming.DumpLedger writes per-frame memory domain values next to the read, content update, upload, BLAS and release stages, so you can correlate memory with loading work.

Troubleshooting​

SymptomCause and fix
Loading falls behind the camera, Deferred keeps growingA domain is full. Check which domain's Pressure is 2. Raise its budget, or lower texture or mesh quality.
Large one-off spikes in uploadAn indivisible resource larger than Memory.UploadPerFrameMB progresses alone. Split the content into smaller pieces if the spike matters.
Memory never comes down after leaving an areaContent is shared with another level, or a load is still running. Idle content is released after Streaming.ResourceKeepAliveSeconds.

See Also​