Documentation

Import

Use Unity's Package Manager to download and import the asset into your project. Once imported, the asset will be inside Assets/ARB/TextureLoader.

Setup

Setup TextureLoader by opening the Settings Panel from the "Window > TextureLoader" menu and selecting "Settings".

TextureLoader's Settings Panel

Namespace

Import TextureLoader's namespace in all scripts you want to use it:

using ARB.TextureLoader;

Usage

The URL for local textures must start with file://

Always call Dispose() or DisposeAll() methods when textures are no longer needed to avoid memory leaks.

Sample - Basic

using ARB.TextureLoader;
using UnityEngine;

public class Example : MonoBehaviour
{
    private TextureLoader loader;
    
    private readonly string url = "http://example.com/texture.jpg";
    //private readonly string url = "file://" + Path.Combine(Application.streamingAssetsPath, "texture.jpg");
    
    private void Start()
    {
        loader = TextureLoader.Load(url).OnComplete((texture) => Debug.Log("Texture loaded"));
        loader.Start();
    }

    private void OnDestroy()
    {
        loader.Dispose();
    }
}

Sample - Target

Use the Into() method to load the texture into one of the supported targets:

• UnityEngine.Renderer

• UnityEngine.SpriteRenderer

• UnityEngine.UI.Image

• UnityEngine.UI.RawImage

• UnityEngine.UIElements.VisualElement

• UnityEngine.UIElements.Image

Check the Customize section to override or create a new target.

using ARB.TextureLoader;
using UnityEngine;

public class Example : MonoBehaviour
{
    public Renderer Target;

    private TextureLoader loader;
    private readonly string url = "http://example.com/texture.jpg";

    private void Start()
    {
        loader = TextureLoader.Load(url).Into(Target);
        loader.Start();
    }

    private void OnDestroy()
    {
        loader.Dispose();
    }
}

Sample - UIToolkit

using ARB.TextureLoader;
using UnityEngine;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class Example : MonoBehaviour
{
    public VisualTreeAsset ImageTemplate;

    private TextureLoader loader;
    private readonly string url = "http://example.com/texture.jpg";

    private void Start()
    {
        VisualElement root = GetComponent<UIDocument>().rootVisualElement;
        TemplateContainer imageElement = ImageTemplate.CloneTree();
        VisualElement imageContainer = imageElement.Q("container");

        loader = TextureLoader.Load(url).Into(imageContainer);
        root.Add(imageElement);
        loader.Start();
    }

    private void OnDestroy()
    {
        loader.Dispose();
    }
}

Sample - Advanced

using System;
using ARB.TextureLoader;
using UnityEngine;
using UnityEngine.UI;

public class Example : MonoBehaviour
{
    public RawImage Target1;
    public SpriteRenderer Target2;
    
    public Texture2D DefaultPlaceholder;
    public Texture2D LoadingPlaceholder;
    public Texture2D ErrorPlaceholder;

    private TextureLoader loader;
    private readonly string url = "http://example.com/texture.jpg";

    private void Start()
    {
        TextureSettings settings = new()
        {
            MinSize = 0,
            MaxSize = 512,
            MipmapChain = false,
            Readable = false,
            WrapMode = TextureWrapMode.Clamp,
            FilterMode = FilterMode.Bilinear,
            AnisoLevel = 0,
            Compression = TextureCompression.NormalQuality
        };

        loader = TextureLoader.Load(url, settings)
            .Into(Target1, DefaultPlaceholder, LoadingPlaceholder, ErrorPlaceholder, UGUITextureTarget.ScaleMode.ScaleToCover, fadeTime: 0.3f)
            .Into(Target2, DefaultPlaceholder, LoadingPlaceholder, ErrorPlaceholder, fadeTime: 0f)
            .OnStart(() => Debug.Log("Loading started"))
            .OnProgress(progress => Debug.Log($"Loading progress: {progress * 100}%"))
            .OnComplete((texture) => Debug.Log("Loading complete"))
            .OnError(error => Debug.LogError($"Loading error: {error}"))
            .UseCache(true, FileFormat.JPG, quality: 80, duration: TimeSpan.FromDays(7));

        loader.Start(enqueue: true);
    }

    private void OnDestroy()
    {
        loader.Dispose();
    }
}

Sample - No references

using ARB.TextureLoader;
using UnityEngine;

public class Example : MonoBehaviour
{
    private TextureLoader loader;
    private readonly string url1 = "http://example.com/texture1.jpg";
    private readonly string url2 = "file://" + Path.Combine(Application.streamingAssetsPath, "texture.jpg");

    private void OnEnable()
    {
        TextureLoader.OnLoadComplete += OnTextureLoadComplete;
    }

    private void Start()
    {
        TextureLoader.Load(url1);
        TextureLoader.Load(url2);
        TextureLoader.StartAll();
    }

    private void OnDisable()
    {
        TextureLoader.OnLoadComplete -= OnTextureLoadComplete;
    }

    private void OnDestroy()
    {
        TextureLoader.DisposeAll();
    }

    private void OnTextureLoadComplete(TextureLoader loader, Texture2D texture)
    {
        Debug.Log($"Texture loaded: {loader.Url}");
    }
}

Codeless

Don't want or don't need to write code? Use the included components to load textures without writing any code!

Check the Customize section to override or create a new codeless component.

By default textures are loaded on Awake and always disposed on OnDestroy.

Renderer Component

UGUI Image Component

UGUI RawImage Component

SpriteRenderer Component

Customize

TextureLoader allows extending and customizing parts of its main functionality without having to modify the source code.

Targets

Targets are Unity components capable of rendering textures. TextureLoader can apply loaded textures to these targets through the Into(TextureTarget target) method.

Override the included targets or create your own by inheriting from the TextureTarget class or any of its subclasses:

Included targets: ARB/TextureLoader/Scripts/Targets

using ARB.TextureLoader;
using UnityEngine;

public class MyTextureTarget : TextureTarget
{
    // Implement the way to get and set the texture on your target.
    protected override Texture CurrentTexture { get => throw new System.NotImplementedException(); set => throw new System.NotImplementedException(); }

    // Use a constructor to pass the renderer you want to use as a texture target.
    public MyTextureTarget(Renderer target, float fadeTime = 0f)
        : base(fadeTime)
    {
        // Your implementation.
    }

    public override void Dispose()
    {
        // Make sure to destroy any resources that are no longer needed here.
    }

    public override void SetAlpha(float alpha)
    {
        // Implement the way to change the transparency of your renderer (if applicable).
    }

    // Fader:
    // Optional game object placed in front of the target renderer, used to create 
    // a crossfade effect between the current texture and the loaded texture.
    // Temporarily holds the current texture and fades out revealing the new texture behind.

    protected override void SetFaderAlpha(float value)
    {
        // Implement the way to change the transparency of your fader (if applicable).
    }

    protected override void SetFaderTexture(Texture texture)
    {
        // Implement the way to set the texture of the fader (if applicable).
    }
}

Your target is now ready to use:

using ARB.TextureLoader;
using UnityEngine;

public class Example : MonoBehaviour
{
    public MyTextureTarget Target;

    private TextureLoader loader;
    private readonly string url = "http://example.com/texture.jpg";

    private void Start()
    {
        loader = TextureLoader.Load(url).Into(Target);
        loader.Start();
    }

    private void OnDestroy()
    {
        loader.Dispose();
    }
}

Placeholders

Placeholders are game objects that can be optionally displayed during a loading operation when the texture is set to load into a target.

Override the included placeholders or create your own by inheriting from the Placeholder class or any of its subclasses:

Included placeholders: ARB/TextureLoader/Scripts/Targets/Placeholders

using ARB.TextureLoader;
using UnityEngine;

public class MyPlaceholder : Placeholder
{
    // Implement the way to know if your game object is active.
    public override bool IsActive => throw new System.NotImplementedException();

    // Use a constructor to pass the game object you want to use as a placeholder.
    public MyPlaceholder(GameObject go)
    {
        // Your implementation.
    }

    public override void Dispose()
    {
        // Make sure to destroy any resources that are no longer needed here.
    }

    public override void SetActive(bool value)
    {
        // Implement the way to enable/disable your game object here.
    }

    public override void SetAlpha(float value)
    {
        // Implement the way to change the transparency of your game object (if applicable).
    }
}

In order to use your new placeholder either override one of the included texture targets or create a new one. Here's an example overriding an existing texture target:

using ARB.TextureLoader;
using UnityEngine;

public class MyRendererTextureTarget : RendererTextureTarget
{
    public MyRendererTextureTarget(Renderer target, GameObject defaultPlaceholder, GameObject loadingPlaceholder, GameObject errorPlaceholder)
        : base(target, 0f)
    {
        if (defaultPlaceholder != null)
        {
            this.defaultPlaceholder = new MyPlaceholder(defaultPlaceholder);
        }

        if (loadingPlaceholder != null)
        {
            this.loadingPlaceholder = new MyPlaceholder(loadingPlaceholder);
        }

        if (errorPlaceholder != null)
        {
            this.errorPlaceholder = new MyPlaceholder(errorPlaceholder);
        }
    }
}

Optionally implement an extension method:

using ARB.TextureLoader;
using UnityEngine;

public static class TextureLoaderExtensions
{
    public static TextureLoader Into(this TextureLoader loader, Renderer target, GameObject defaultPlaceholder, GameObject loadingPlaceholder, GameObject errorPlaceholder)
    {
        return loader.Into(new MyRendererTextureTarget(target, defaultPlaceholder, loadingPlaceholder, errorPlaceholder));
    }
}

using ARB.TextureLoader;
using UnityEngine;

public class Example : MonoBehaviour
{
    public Renderer Target;
    public GameObject DefaultPlaceholder;
    public GameObject LoadingPlaceholder;
    public GameObject ErrorPlaceholder;

    private TextureLoader loader;
    private readonly string url = "http://example.com/texture.jpg";

    private void Start()
    {
        // With extension method:
        loader = TextureLoader.Load(url).Into(Target, DefaultPlaceholder, LoadingPlaceholder, ErrorPlaceholder);
        
        // Without extension method:
        //loader = TextureLoader.Load(url).Into(new MyRendererTextureTarget(target, defaultPlaceholder, loadingPlaceholder, errorPlaceholder));
        
        loader.Start();
    }

    private void OnDestroy()
    {
        loader.Dispose();
    }
}

Codeless components

Codeless components are those that can be attached to game objects with a texture renderer to load a texture without writing any code.

Override the included loader components or create your own by inheriting from the TargetTextureLoader class or any of its subclasses:

Included components: ARB/TextureLoader/Scripts/Components

using ARB.TextureLoader;
using UnityEngine;

[AddComponentMenu("TextureLoader/My Renderer Texture Loader")]
[RequireComponent(typeof(Renderer))]
public class MyRendererTextureLoader : TargetTextureLoader
{
    private Renderer target;

    protected override TextureTarget Target => new RendererTextureTarget(target, defaultTexture, loadingTexture, errorTexture, fadeTime);

    protected override void OnValidate()
    {
        base.OnValidate();
        if (target == null) target = GetComponent<Renderer>();
    }
}