Loading texture and mesh data

Unity can load texture and meshThe main graphics primitive of Unity. Meshes make up a large part of your 3D worlds. Unity supports triangulated or Quadrangulated polygon meshes. Nurbs, Nurms, Subdiv surfaces must be converted to polygons. More info
See in Glossary data from disk and upload it to the GPU in two different ways: synchronously or asynchronously. These two processes are called the synchronous upload pipeline and the asynchronous upload pipeline.

When Unity uses the synchronous upload pipeline, it cannot perform other tasks while it loads and uploads the data. This can cause visible pauses in your application. When Unity uses the asynchronous upload pipeline, it can perform other tasks while it loads and uploads the data in the background.

If a texture or mesh is eligible for the asynchronous upload pipeline, Unity uses the asynchronous upload pipeline automatically. If a texture or mesh is ineligible for the asynchronous upload pipeline, Unity uses the synchronous upload pipeline automatically.

How it works

The main difference between the synchronous and asynchronous upload pipelines is where Unity saves the data at build time, which affects how Unity loads it at runtime.

In the synchronous upload pipeline, Unity must load both the metadata (header data) and the texel or vertex data (binary data) for the texture or mesh in a single frame. In the asynchronous upload pipeline, Unity must load only the header data in a single frame, and it can stream the binary data to the GPU over subsequent frames.

In the synchronous upload pipeline:

• At build time, Unity writes both the header and the binary data for the mesh or texture to the same .res file.
• At runtime, when the application needs the texture or mesh, Unity loads both the header data and binary data for that texture or mesh from the .res file into memory. When all of the data is in memory, Unity then uploads the binary data from memory to the GPU. The loading and uploading operations occur mainly on the main thread, in a single frame.

In the asynchronous upload pipeline:

• At build time, Unity writes the header data to a .res file and the binary data to a separate .resS file.
• At runtime, when the application needs the texture or mesh, Unity loads the header from the .res file into memory. When the header is in memory, Unity then streams the binary data from the .resS file to the GPU using a fixed-sized ring buffer. Unity streams the binary data using multiple threads, over the course of several frames. Note that on some console platforms where Unity already knows the GPU hardware, Unity skips the ring buffer and loads straight into the GPU memory.

Texture and mesh data eligibility

A texture is eligible for the asynchronous upload pipeline if the following conditions are met:

• The texture is not read/write enabled.
• The texture is not in the Resources folder.
• If the build target is Android, LZ4 compressionA method of storing data that reduces the amount of storage space it requires. See Texture Compression, Animation Compression, Audio Compression, Build Compression.
  See in Glossary is enabled in the Project’s Build Settings.

Note that if you load a texture using LoadImage(byte[] data), this forces Unity to use the synchronous upload pipeline, even if the above conditions are met.

A mesh is eligible for the asynchronous upload pipeline if the following conditions are met:

• The mesh is not read/write enabled.
• The mesh is not in the Resources folder.
• The mesh has no BlendShapes.
• Unity has not applied Dynamic BatchingAn automatic Unity process which attempts to render multiple meshes as if they were a single mesh for optimized graphics performance. The technique transforms all of the GameObject vertices on the CPU and groups many similar vertices together. More info
  See in Glossary to the mesh, either because the mesh is ineligible for Dynamic Batching or because Dynamic Batching is disabled. For more information on Dynamic Batching, see Draw call batching.
• The mesh vertex/index data is not needed by a Particle SystemA component that simulates fluid entities such as liquids, clouds and flames by generating and animating large numbers of small 2D images in the scene. More info
  See in Glossary, a TerrainThe landscape in your scene. A Terrain GameObject adds a large flat plane to your scene and you can use the Terrain’s Inspector window to create a detailed landscape. More info
  See in Glossary, or a Mesh ColliderA free-form collider component which accepts a mesh reference to define its collision surface shape. More info
  See in Glossary.
• The mesh has no bone weights.
• The mesh topology is not quadsA primitive object that resembles a plane but its edges are only one unit long, it uses only 4 vertices, and the surface is oriented in the XY plane of the local coordinate space. More info
  See in Glossary.
• The meshCompression for the mesh assetAny media or data that can be used in your game or Project. An asset may come from a file created outside of Unity, such as a 3D model, an audio file or an image. You can also create some asset types in Unity, such as an Animator Controller, an Audio Mixer or a Render Texture. More info
  See in Glossary is set to Off. If the build target is Android, LZ4 compression is enabled in the Project’s Build Settings.

In all other circumstances, Unity loads textures and meshes synchronously.

How to identify which upload pipeline Unity is using

You can use the ProfilerA window that helps you to optimize your game. It shows how much time is spent in the various areas of your game. For example, it can report the percentage of time spent rendering, animating or in your game logic. More info
See in Glossary or another profiling tool to identify when Unity is using the asynchronous upload pipeline, by observing thread activity and profiler markers.

The following indicate that Unity is using the asynchronous upload pipeline to upload textures or meshes:

• The AsyncUploadManager.ScheduleAsyncRead, AsyncReadManager.ReadFile, and Async.DirectTextureLoadBegin profiler markers.
• Activity on the AsyncRead thread.

If you do not see this activity, then Unity is not using the asynchronous upload pipeline.

Note that the following profiler markers do not indicate that Unity is using the asynchronous upload pipeline; Unity calls them to check whether any asynchronous upload work needs to occur:

• Initialization.AsyncUploadTimeSlicedUpdate
• AsyncUploadManager.AsyncResourceUpload
• AsyncUploadManager.ScheduleAsyncCommands

Configuring the asynchronous upload pipeline

You can configure these settings for the asynchronous upload pipeline. Note that you cannot configure settings for the synchronous upload pipeline.

Async Upload Buffer

Unity re-uses a single ring buffer to stream texture and mesh data to the GPU. This reduces the number of memory allocations required.

The Async Upload Buffer determines the size of this ring buffer in megabytes. It has a minimum size of 2, and a maximum size of 512.

Unity automatically resizes the buffer to fit the largest texture or mesh that is currently loading. This can be a slow operation, especially if Unity has to perform it more than once; for example, if you are loading many textures that are larger than the default buffer size. To reduce the number of times that Unity must resize the buffer, set this value to fit the largest value that you expect to load. This is usually the largest texture in the SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary.

You can configure this value in the Quality settings window, or using the QualitySettings.asyncUploadBufferSize API.

Async Upload Time Slice

Async Upload Time Slice is the amount of time the CPU spends uploading texture or mesh data to the GPU, in milliseconds per frame.

A larger value means the data will be ready on the GPU sooner, but the CPU will spend more time on upload operations during those frames. Note that Unity only uses this time for uploading if there is data waiting in the buffer to be uploaded to the GPU; if there is no data waiting, Unity can use this time for other operations.

You can configure this value in the Quality settings window, or using the QualitySettings.asyncUploadTimeSlice API.

Further information

For more information on uploading texture and mesh data asynchronously, see the Unity blog post Optimizing loading performance: Understanding the Async Upload Pipeline.