Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
Plugins		Plugins
Runtime		Runtime
Tests		Tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CHANGELOG.md.meta		CHANGELOG.md.meta
LICENSE		LICENSE
LICENSE.meta		LICENSE.meta
Plugins.meta		Plugins.meta
README.md		README.md
README.md.meta		README.md.meta
Runtime.meta		Runtime.meta
Tests.meta		Tests.meta
package.json		package.json
package.json.meta		package.json.meta

Repository files navigation

Unity Asynchronous Image Loader

ImageConversion.LoadImage andTexture2D.LoadImage are slow when loading large images (greater than 2K) at runtime. They blocks the Unity main thread when loading the image for a duration between a hundred milliseconds and even a few seconds. This is a dealbreaker for those games and applications that want to load those images programmatically at runtime.

This package aims to offload image loading, image decoding and mipmap generation to other threads. It creates smoother gameplay and reduces lag spike on the Unity main thread when loading large images.

This package usesFreeImage. which is the same library used by Unity to process image data.

Unity Version

This package is developed in Unity 2019.1. It may work on Unity 2020 and Unity 2021.

Installation

The package can be installed using the Git URLhttps://github.com/Looooong/UnityAsyncImageLoader.git by followingInstalling from a Git URL instructions.

Dependencies

Unity Burst
Unity Mathematics

Usage

Loader Settings

/// <summary>Settings used by the image loader.</summary>publicstructLoaderSettings{/// <summary>Create linear texture. Only applicable to methods that create new <c>Texture2D</c>. Defaults to false.</summary>publicboollinear;/// <summary>Texture data won't be readable on the CPU after loading. Defaults to false.</summary>publicboolmarkNonReadable;/// <summary>Whether or not to generate mipmaps. Defaults to true.</summary>publicboolgenerateMipmap;/// <summary>Automatically calculate the number of mipmap levels. Defaults to true. Only applicable to methods that create new <c>Texture2D</c>.</summary>publicboolautoMipmapCount;/// <summary>Mipmap count, including the base level. Must be greater than 1. Only applicable to methods that create new <c>Texture2D</c>.</summary>publicintmipmapCount;/// <summary>Used to explicitly specify the image format. Defaults to FIF_UNKNOWN, which the image format will be automatically determined.</summary>publicFreeImage.Formatformat;/// <summary>Whether or not to log exception caught by this method. Defaults to true.</summary>publicboollogException;publicstaticLoaderSettingsDefault=>newLoaderSettings{linear=false,markNonReadable=false,generateMipmap=true,autoMipmapCount=true,format=FreeImage.Format.FIF_UNKNOWN,logException=true,};}

Load Image Asynchronously

varimageData=File.ReadAllBytes();vartexture=newTexture2D(1,1);varloaderSettings=AsyncImageLoader.LoaderSettings.Default;varsuccess=false;// =====================================// Load image data into existing texture// =====================================// Use the default LoaderSettingssuccess=awaitAsyncImageLoader.LoadImageAsync(texture,imageData);// Similar to ImageConversion.LoadImage// Mark texture as unreadable after reading.success=awaitAsyncImageLoader.LoadImageAsync(texture,imageData,true);// Use a custom LoaderSettingssuccess=awaitAsyncImageLoader.LoadImageAsync(texture,imageData,loaderSettings);// ==================================// Create new texture from image data// ==================================// Use the default LoaderSettingstexture=awaitAsyncImageLoader.CreateFromImageAsync(imageData);// Use a custom LoaderSettingstexture=awaitAsyncImageLoader.CreateFromImageAsync(imageData,loaderSettings);

Load Image Synchronously

The synchronous variants are the same as the asynchronous counterparts but withoutAsync suffix in theirs name. They are useful for debugging and profiling within a frame.

varimageData=File.ReadAllBytes();vartexture=newTexture2D(1,1);varloaderSettings=AsyncImageLoader.LoaderSettings.Default;varsuccess=false;// =====================================// Load image data into existing texture// =====================================// Use the default LoaderSettingssuccess=AsyncImageLoader.LoadImage(texture,imageData);// Similar to ImageConversion.LoadImage// Mark texture as unreadable after reading.success=AsyncImageLoader.LoadImage(texture,imageData,true);// Use a custom LoaderSettingssuccess=AsyncImageLoader.LoadImage(texture,imageData,loaderSettings);// ==================================// Create new texture from image data// ==================================// Use the default LoaderSettingstexture=AsyncImageLoader.CreateFromImage(imageData);// Use a custom LoaderSettingstexture=AsyncImageLoader.CreateFromImage(imageData,loaderSettings);

After Loading

Texture Format

If the image has alpha channel, the format will beRGBA32, otherwise, it will beRGB24.

Mipmap Count

If theLoadImage andLoadImageAsync variants are used withgenerateMipmap set totrue, the mipmap count is set to the maximum possible number for a particular texture. If you want to control the number of mipmap, you can use theCreateFromImage andCreateFromImageAsync instead.

Mipmap Data

The mipmaps are generated using box filtering with 2x2 kernel. The final result won't be the same as Unity's counterpart when using texture import in the editor.

Troubleshooting

There is still lag spike when loading large images

AfterAsyncImageLoader method finishes executing, the image data are still transfering to the GPU. Therefore, any object, like material or UI, that wants to use the texture afterward will have to wait for the texture to finish uploading and thus block the Unity main thread.

There is no easy way to detect if the texture has finished uploading its data. The workarounds are:

Wait for a second or more before using the texture.
(Not tested) UseAsyncGPUReadback to request a single pixel from the texture. It will wait for the texture to finish uploading before downloading that single pixel. Then the request callback can be used to notify the Unity main thread about the texture upload completion.