The Mipmap Streaming system

The Mipmap Streaming system gives you control over how Unity loads mipmaps.

This page contains the following information:

• Overview
• Getting started
  • Enabling Mipmap Streaming
  • Making textures work with the Mipmap Streaming system
  • Making lightmaps work with the Mipmap Streaming system
• Configuring Mipmap Streaming
  • Setting the memory budget
  • Configuring Cameras
  • Configuring Play Mode behavior
• Debugging
• How Unity calculates the required mipmap level
• Limitations

For information about using the API to extend the functionality of this system, see Mipmap Streaming system API.

Overview

This system forces Unity to only load the mipmap levels needed to render the current CameraA component which creates an image of a particular viewpoint in your scene. The output is either drawn to the screen or captured as a texture. More info
See in Glossary position, instead of loading all of them by default. It trades a small amount of CPU resources to save a potentially large amount of GPU memory.

You can set a total memory limit for all textures in an application, and the system automatically reduces mipmap levels to stay within this budget.

In Unity’s Viking Village demo project, the Mipmap Streaming system saves 25–30% of texture memory, depending on Camera location.

Getting started

Enabling Mipmap Streaming

To enable Mipmap Streaming, go to Unity’s Quality Settings (Edit > Project SettingsA broad collection of settings which allow you to configure how Physics, Audio, Networking, Graphics, Input and many other areas of your project behave. More info
See in Glossary > Quality) and enable the Texture Streaming checkbox.

When you enable this setting, the Quality settings window reveals the settings specific to the Mipmap Streaming system. For details on each setting, see documentation on Quality Settings.

By default, this enables Mipmap Streaming for all Cameras in your project.

Making textures work with the Mipmap Streaming system

Now you can set up Mipmap Streaming on individual textures. Select a texture asset, navigate to the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary window and view the Texture Import settings. Open the Advanced settings, and enable the Mip Streaming checkbox.

If you’re developing for Android, you also need to open the Build Settings and set the Compression Method to LZ4 or LZ4HC. Unity requires one of these 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 methods for asynchronous Texture loading, which the Mipmap Streaming system relies upon.

Unity loads mipmap levels at the highest resolution possible while observing the memory budget. You can configure the priority of a texture with the Mip Map Priority setting in the Texture Import Settings.

Unity uses this setting to determine:

• Which textures to prioritize when assigning resources.
• As a mipmap bias value when choosing a mipmap level that fits in the memory budget. For example, with a priority of 2, the mipmap streaming system tries to use a mipmap two levels higher than Textures with a priority of 0.

Positive numbers give higher priority. Valid values range from –128 to 127.

Streaming Lightmaps

You can use the Mipmap Streaming system to stream mipmap levels for lightmapsA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
See in Glossary.

You can edit the Mip Map Streaming settings of the lightmap assets in the same way that you can any other texture, but they reset to their default values when Unity regenerates the lightmaps. To solve this, you can tell Unity to apply these values when it generates the lightmaps. The Player SettingsSettings that let you set various player-specific options for the final game built by Unity. More info
See in Glossary (Edit > Project Settings > Player) provide two controls to set streaming and priority for generated lightmaps: Lightmap Streaming Enabled and Streaming Priority.

Enabling Mip Map Streaming and configuring priority work in the same way for lightmaps as for regular textures.

Configuring Mipmap Streaming

You can configure default settings in the Unity Editor, and then use the Mipmap Streaming API to override these settings if required.

Setting the memory budget

The Memory Budget property determines the maximum amount of memory Unity uses for textures. If your memory budget is too small, Unity lowers the resolution of textures in your 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. This can cause textures to pop or load slowly. However, the memory budget should be as small as possible to allow memory for other resources.

Set the memory budget in the Quality Settings window, with the Texture Streaming > Memory Budget property.

When the memory budget is full, Unity discards mipmaps it’s not using, to make room for those it needs to use. You can control how many unused mipmaps it discards with the Max Level Reduction.

This value is also the mipmap level that the Mipmap Streaming system initially loads at startup. For example, when this is set to 2, Unity skips the two highest mipmaps on first load.

Set this value in the Quality Settings window, with the Texture Streaming > Max Level Reduction property.

Note: Unity prioritises the Max Level Reduction value over the memory budget. It never discards more mipmaps than the Max Level Reduction value, even if this causes the textures memory to exceed the budget.

The memory budget includes textures that do not use Mipmap Streaming. For example, if your budget is 100MB and you have 90MB of textures that don’t use Mipmap Streaming, Unity tries to fit all the streaming mipmaps in the remaining 10MB. If it can’t, it loads them at a lower resolution. Unity always loads textures that don’t use Mipmap Streaming at full resolution, even if that exceeds the budget.

To figure out what your memory budget should be:

1. Look at the Texture.desiredTextureMemory value when your project is running.
2. Set the Memory Budget value slightly higher than the Texture.desiredTextureMemory value.

This makes sure there is enough texture memory available for the most resource-intensive areas of your scene and prevents textures from dropping to a lower resolution. If you have extra memory available, you can set a larger memory budget so that Unity can keep texture data that is not visible in your scene in the streaming cache.

Configuring Cameras

By default, when you enable the Mipmap Streaming system, Unity enables it for all cameras. You can disable this setting if you like.

Control whether Unity enables mipmap Streaming for all Cameras in the Quality Settings window, with the Texture Streaming > Add All Cameras property.

If you want to exclude a specific Camera, add a Streaming Controller component to that Camera and then disable it.

If you disable Add All Cameras, then you must enable mipmap Streaming per-Camera. To do this, add a Streaming Controller component to the same GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary as the Camera component.

This component also allows you to adjust the mipmap bias setting per-Camera.

Configuring Play Mode behavior

Mipmap Streaming is enabled in Play Mode by default.

Control whether Unity enables Mipmap Streaming in Play Mode in the Editor Settings window, with the Streaming Settings > Enable Texture Streaming in Play Mode property.

When Mipmap Streaming is enabled in Play mode, but not enabled in Edit mode (or the other way around), toggling in and out of Play mode takes slightly longer. This prevents Unity from unloading and reloading mipmap data, and should speed up the Play Mode workflow.

Debugging Mipmap Streaming

Unity has a built-in Mipmap Streaming debugging view mode. To access it, click the Scene view control drop-down and select Texture Streaming. This view mode tints GameObjects the following colours, depending on their status in the Mipmap Streaming system:

• Green for Textures that have reduced mipmaps due to the Mipmap Streaming system.
• Red for Textures that have fewer mipmaps because the Mipmap Streaming system does not have enough resources to load them all.
• Blue for Textures that are not set to stream, or if there is no renderer calculating the mipmap levels.

You can also write your own custom debug tools and visualizations using the Debugging API

Important : When the main texture is set using the MainTexture attribute, it is not visible in the game view when you use the texture streaming debugging view mode or a custom debug tool.

How Unity calculates the required mipmap level

For textures that use Mipmap Streaming, Unity calculates the correct mipmap level using one of the following methods:

• If you assign the texture to a material that is used by a Unity Renderer componennt, Unity calculates the mipmap level automatically.
• Otherwise, you must request mipmap levels manually using Texture2D.requestedMipmapLevel.

If you don’t do this, Unity can’t calculate the correct mipmap level, and it loads the texture using low-resolution mipmap levels. These can appear blurry.

Note: The following systems don’t use standard Renderer components. This means you must manually set the requested mipmap levels for these systems:

• Decal projector textures.
• Reflection probeA rendering component that captures a spherical view of its surroundings in all directions, rather like a camera. The captured image is then stored as a Cubemap that can be used by objects with reflective materials. More info
  See in Glossary textures: Lower resolution mipmap levels are a lookup table for roughness. Therefore, if Unity uses a lower mipmap level, it renders materials using the wrong roughness.
• ShadersA program that runs on the GPU. More info
  See in Glossary that use UV texture coordinates in a channel other than Mesh.uv (also called UV0), or change texture coordinates in the shader. The only exceptions are changes to scale and translation (see below).

Limitations

• Unity does not support Mipmap Streaming on 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 textures. This is because Terrain Textures need to be available at full resolution at all times to allow Unity to tile and blend the textures.
• When a Renderer component is active, its mesh requires valid UV distribution metrics to calculate the desired mipmap level. Unity calculates distribution metrics automatically as part of the mesh importing process.
  
  If you create a mesh from code, Unity does not calculate distribution metrics automatically and therefore it loads the wrong mipmap levels. To manually trigger the UV distribution metric calculation use Mesh.RecalculateUVDistributionMetrics.
• When Unity renders a streamed Texture directly with an API (such as Graphics.DrawMeshNow) the system has no renderer bounds or other information to calculate the mipmap level. This means you need to set the Texture mipmap level manually or disable Mipmap Streaming on this Texture. See Texture2D.requestedMipmapLevel for more details on how to manually set which mipmap level Unity loads.
• When Unity calculates the miplevel for a texture it looks for the scale and translation of that texture in a _ST value with the same name as the texture flagged in your shader. For example, if you reference your textures are in the shader using _MainTex, Unity will look for _MainTex_ST.