Version: 2023.2
Language : English
The Mipmap Streaming system
Streaming Controller component

The Mipmap Streaming system API

Use this API to override the default settings in the Mipmap Streaming system, or get more fine-grained control.

This page contains the following information:

For general information about this system, see Mipmap Streaming system.

Overview

You can use the API to override behavior for specific situations, while the Mipmap Streaming system automatically manages the default settings.

This is useful if you know that Unity needs to fully load certain textures; for example, if they relate to GameObjectsThe 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
that move large distances quickly, or if you use instantaneous 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
cuts.

Controlling the Mipmap Streaming system

To enable and control Mipmap Streaming on a texture, use the following properties:

Mipmap Streaming automatically reduces the mipmap level of textures until they fit into the Mipmap Streaming Memory Budget. The Texture’s Mip Map Priority number is roughly a mipmap offset for the Memory Budget. For example, with a priority of 2, the Mipmap Streaming system tries to use a mipmap level that is two levels higher than other textures with a priority of 0. Negative values are also valid. If it can’t do this, it uses a lower mipmap level to fit the Memory Budget.

These properties are read-only at runtime:

To control what happens at runtime, use the following static properties:

Controlling Cameras

When cutting from one location to another, the Mipmap Streaming system needs time to stream the required Textures into Unity. To trigger preloading at a disabled target Camera location, call StreamingController.SetPreloading on the target Camera’s Streaming Controller component. You can specify a time-out to end the preloading phase. To automatically enable the Camera at the end of the preloading phase, set the activateCameraOnTimeout flag to true in script. To disable a Camera after you cut from it to the new one, pass that Camera as the disableCameraCuttingFrom parameter.

void StreamingController.SetPreloading(float timeoutSeconds=0.0f, bool activateCameraOnTimeout=false, Camera disableCameraCuttingFrom=null)

To cancel or query the preloading state, use the following methods:

To determine whether the Mipmap Streaming system is still loading Textures, you can query the following properties:

Note that there is delay between when you enable a Camera and when these properties become a value other than zero. This delay is because the Mipmap Streaming system calculates the required mipmaps using time-sliced processing. For this reason, during a Camera cut you should wait a minimum length of time before the cut. Texture budget and 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
movement can cause continuous Mipmap Streaming, so you also need to set a maximum length of time before the cut.

Loading a specific mipmap level

To override the mipmap level calculation for a specific Texture, use Texture2D.requestedMipmapLevel. This is an exact mipmap level ranging from 0 to the maximum mipmap level of the specific Texture, or the Max Level Reduction value if that is lower. 0 is the highest resolution mipmap.

To check if your requested mipmap level has loaded, use Texture2D.IsRequestedMipmapLevelLoaded.

If you no longer want to override the mipmap level you requested and instead want the system to continue to calculate mipmap levels, use Texture2D.ClearRequestedMipmapLevel to reset the value.

To get an estimate of the UV density on a 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
, use the following:

float Mesh.GetUVDistributionMetric(int uvSetIndex)

You can use the UV distribution metric to calculate the mipmap level you need, based on the position of the Camera. See Mesh.GetUVDistributionMetric for example code.

To override the system and force all mipmap levels to load, use Texture.streamingTextureForceLoadAll.

Debugging and profiling

To get per-texture streaming info in material properties that can be used for creating debug visualisations use Texture.SetStreamingTextureMaterialDebugProperties.

You can use Texture.SetStreamingTextureMaterialDebugProperties to assign streaming status information for each texture to material properties. You can then use these properties in the shaderA program that runs on the GPU. More info
See in Glossary
to create debug visualizations.

You can also use these properties to create Mipmap Streaming profiling and debugging tools for your project.

To get information about the number of Textures or renderers the Mipmap Streaming system is interacting with, use the following properties:

To get information about mipmap levels for a texture, use the following properties:

Related Unity API methods

To get and set a Texture assigned to a Material, use:

To get all Texture properties on a Material, use:

The Mipmap Streaming system
Streaming Controller component