Using KSPTextureLoader to Load Textures

This page shows you how to use KSPTextureLoader to load textures. If you're just looking to author textures that KSPTextureLoader can pick up then you can ignore this page.

Examples

Load a single Texture2D asynchronously over multiple frames

TextureHandle<Texture2D> handle = TextureLoader.LoadTexture<Texture2D>("path/to/texture.dds");

// Wait for the texture to be ready
yield return handle;

Texture2D texture;
try
{
   texture = handle.GetTexture();
}
catch (Exception e)
{
   Debug.LogError($"Failed to load texture");
   Debug.LogException(e);
   texture = null;
}

// do things with texture
// make sure to hold on to the texture handle until you don't need the texture anymore

Loading a bunch of textures all at once

var handles = new List<TextureHandle<Texture2D>>();

// Start loading all the textures
foreach (var path in myTexturePaths)
    handles.Add(TextureLoader.LoadTexture<Texture2D>(path));

// Generally, textures will load in the order that they were requested
foreach (var handle in handles)
{
   yield return handle;

   Texture2D texture;
   try
   {
       texture = handle.GetTexture();
   }
   catch (Exception e)
   {
       Debug.LogError($"Failed to load texture");
       Debug.LogException(e);
       texture = null;
   }

   // do things with the texture. e.g.
   material.SetTexture("_MyTex", texture);
}

// Hold onto the handles until you don't need the texture anymore.
// Dispose of them once you no longer need the texture.

API Documentation

class TextureLoader

This is the main entry point to this library. Pretty much all the APIs you will use will start here.

• static TextureHandle<T> LoadTexture<T>(string path, TextureLoadOptions options)

  Load a texture from disk or an asset bundle.

  The texture will be loaded asynchronously in the background (as much as possible, given unity's limitations) and the handle will be shared between all the callers who have loaded the same texture path.

  You can set T to a specific texture type if you know what texture type you want (e.g. Texture2D, or Cubemap). TextureLoader will implicitly convert a texture to the desired type in some cases (Texture2D can be converted to Cubemap). You can disable these implicit conversions by setting AllowImplicitConversions to false in the options.

  Supported texture types are

  • Texture
  • Texture2D
  • Texture2DArray
  • Texture3D
  • Cubemap
  • CubemapArray

  Any other type will result in an exception being thrown.

• static bool TextureExists(string path, TextureLoadOptions options)

  Check whether a texture exists on disk or in an asset bundle.

  This method can be somewhat slow as it needs to load all the asset bundles that could contain the texture. It also only checks that the texture exists, not that it can be loaded without errors or that it is of the expected type.

• static AssetBundleHandle LoadAssetBundle(string path, bool sync = true)

  Load an asset bundle from the shared cache. You can only have one copy of any given asset bundle loaded at a time, so if you want to load assets from an asset bundle that might be used by the texture loader then you should use this method.

  Make sure to dispose of the AssetBundleHandle when you are done with it.

class TextureHandle

This is a reference counted handle to a shared texture. Make sure to call Dispose once you are done with or else the texture will leak. TextureLoader.LoadTexture returns a typed version of this class (TextureHandle<T>) which inherits from this one.

This class inherits from CustomYieldInstruction so you can yield it in a coroutine to wait until the texture is loaded.

• Texture GetTexture()

  Get the texture for this texture handle. This will block if the texture has not fully loaded yet and will throw an exception if the texture failed to load.

• Texture TakeTexture()

  Take ownership of the texture from the handle. If this is the only reference to the texture then it will be removed from the pool and passed. If not, it will be cloned and the clone will be returned.

  In either case this will dispose of the TextureHandle, so take care not to dispose of it again afterwards.

• void WaitUntilComplete()

  Block until the texture is fully loaded. However, this version does not throw an exception if the texture failed to load.

• TextureHandle Acquire()

  Get a copy of this texture handle that refers to the same texture. This increases the reference count and should be used if passing a handle to another location that will also be responsible for disposing of the texture.

• void Dispose()

  Decrement the reference count of this texture handle. If the reference count hits zero then the texture will be destroyed.

struct TextureLoadOptions

Options configuring the loaded texture as well as how it should be loaded.

• TextureLoadHint Hint

  A hint to the texture loader informing it of how soon you intend to call GetTexture. This can make quite a bit of difference in how much overhead texture loading has on the main thread.

  Available hints are:

  • Synchronous - You intend to block on GetTexture immediately. This will result in several expensive operations being done on the main thread while the disk read is happening.
  • BatchSynchronous - You intend to start loading multiple textures and after that immediately block on GetTexture for each of them.
  • BatchAsynchronous - You intend to start loading multiple textures and will then wait on them asynchronously. This is the default. The main difference between this and Asynchronous is that it will load asset bundles synchronously so that all the asset bundle reads can be queued up immediately.
  • Asynchronous - You want minimal overhead on the main thread and are OK with that taking extra frames to achieve.

• string[] AssetBundles

  A list of asset bundles to consider when loading this texture, in addition to any registered implicit asset bundles. Any nulls in this list will be automatically ignored.

• bool Unreadable

  Controls whether the resulting texture should be readable or not. This option only applies when loading from texture files. Textures loaded from asset bundles have their isReadable property controlled by the import settings in the editor.

  This defaults to true.

• bool? Linear

  Override automatic detection for whether a texture is sRGB. This option only applies when loading from texture files. Textures loaded from asset bundles have this set on their import settings in the editor. Also note that unity ignores this option for compressed texture formats, and will create the textures as UNorm textures regardless.

• bool AllowImplicitConversions

  Whether implicit texture conversions (e.g. Texture2D to Cubemap or creating texture arrays out of a single layer) are performed. If false then an error will be thrown instead of converting the texture.

  This defaults to true.