Merge pull request #14 from IvanMurzak/feature/automatic-texture-release

Automatic texture memory release

Author: IvanMurzak

Assets/Samples.meta

@@ -0,0 +1,49 @@
+using Extensions.Unity.ImageLoader;
+using UnityEngine;
+
+static class CacheSample
+{
+    static string url = "";
+    static Sprite sprite;
+
+    static void ChangeDiskCacheFolder()
+    {
+        ImageLoader.settings.diskSaveLocation = Application.persistentDataPath + "/myCustomFolder";
+    }
+    static void OverrideCache()
+    {
+        // Override Memory cache for specific image
+        ImageLoader.SaveToMemoryCache(url, sprite);
+
+        // Take from Memory cache for specific image if exists
+        ImageLoader.LoadFromMemoryCache(url);
+    }
+    static void DoesCacheContainImage()
+    {
+        // Check if any cache contains specific image
+        ImageLoader.CacheContains(url);
+
+        // Check if Memory cache contains specific image
+        ImageLoader.MemoryCacheContains(url);
+
+        // Check if Memory cache contains specific image
+        ImageLoader.DiskCacheContains(url);
+    }
+    static void ClearImage()
+    {
+        // Clear memory Memory and Disk cache
+        ImageLoader.ClearCache();
+
+        // Clear only Memory cache for all images
+        ImageLoader.ClearMemoryCache();
+
+        // Clear only Memory cache for specific image
+        ImageLoader.ClearMemoryCache(url);
+
+        // Clear only Disk cache for all images
+        ImageLoader.ClearDiskCache();
+
+        // Clear only Disk cache for specific image
+        ImageLoader.ClearDiskCache(url);
+    }
+}

Assets/Samples/CacheSample.cs

@@ -0,0 +1,19 @@
+using Extensions.Unity.ImageLoader;
+using Cysharp.Threading.Tasks;
+using UnityEngine;
+using UnityEngine.UI;
+
+public class ImageLoaderSample : MonoBehaviour
+{
+    [SerializeField] string imageURL;
+    [SerializeField] Image image;
+
+    async void Start()
+    {
+        // Loading sprite from web, cached for quick load next time
+        image.sprite = await ImageLoader.LoadSprite(imageURL);
+
+        // Same loading with auto set to image
+        await ImageLoader.SetSprite(imageURL, image);
+    }
+}

Assets/Samples/CacheSample.cs.meta

@@ -0,0 +1,17 @@
+using Extensions.Unity.ImageLoader;
+using Cysharp.Threading.Tasks;
+using UnityEngine;
+using UnityEngine.UI;
+
+public class ImageLoaderSample2 : MonoBehaviour
+{
+    [SerializeField] string imageURL;
+    [SerializeField] Image image1;
+    [SerializeField] Image image2;
+
+    void Start()
+    {
+        // Loading with auto set to image
+        ImageLoader.SetSprite(imageURL, image1, image2).Forget();
+    }
+}

Assets/Samples/ImageLoaderSample.cs

@@ -60,6 +60,18 @@ public class ImageLoaderSample : MonoBehaviour
 }
 ```
 
+# Texture Memory Management
+
+ImageLoader can manager memory usage of loaded textures. To use it need to call `ImageLoader.LoadSpriteRef` instead of `ImageLoader.LoadSprite`. It will return `Reference<Sprite>` object which contains `Sprite` and `Url` objects. When `Reference<Sprite>` object is not needed anymore, call `Dispose` method to release memory, or just don't save the reference on it. It is `IDisposable` and it will clean itself automatically. Each new instance of `Reference<Sprite>` increments reference counter of the texture. When the last reference is disposed, the texture will be unloaded from memory. Also the all related References will be automatically disposed if you call `ImageLoader.ClearMemoryCache` or `ImageLoader.ClearCache`.
+
+``` C#
+// Load sprite image and get reference to it
+await ImageLoader.LoadSpriteRef(imageURL);
+
+// Take from Memory cache reference for specific image if exists
+ImageLoader.LoadFromMemoryCacheRef(url);
+```
+
 # Cache
 
 Cache system based on the two layers. The first layer is **memory cache**, second is **disk cache**. Each layer could be enabled or disabled. Could be used without caching at all. By default both layers are enabled.
@@ -68,7 +80,7 @@ Cache system based on the two layers. The first layer is **memory cache**, secon
 
 - `ImageLoader.settings.useMemoryCache = true;` default value is `true`
 - `ImageLoader.settings.useDiskCache = true;` default value is `true`
-  
+
 Change disk cache folder:
 
 ``` C#

Assets/Samples/ImageLoaderSample.cs.meta

@@ -0,0 +1,129 @@
+using System;
+using UnityEngine;
+using UnityEngine.Networking;
+using Cysharp.Threading.Tasks;
+
+namespace Extensions.Unity.ImageLoader
+{
+    public static partial class ImageLoader
+    {
+        /// <summary>
+        /// Load image from web or local path and return it as Sprite
+        /// </summary>
+        /// <param name="url">URL to the picture, web or local</param>
+        /// <param name="textureFormat">TextureFormat for the Texture2D creation</param>
+        /// <param name="ignoreImageNotFoundError">Ignore error if the image was not found by specified url</param>
+        /// <returns>Returns sprite asynchronously </returns>
+        public static UniTask<Sprite> LoadSprite(string url, TextureFormat textureFormat = TextureFormat.ARGB32, bool ignoreImageNotFoundError = false)
+            => LoadSprite(url, new Vector2(0.5f, 0.5f), textureFormat, ignoreImageNotFoundError);
+
+        /// <summary>
+        /// Load image from web or local path and return it as Sprite
+        /// </summary>
+        /// <param name="url">URL to the picture, web or local</param>
+        /// <param name="pivot">Pivot of created Sprite</param>
+        /// <param name="textureFormat">TextureFormat for the Texture2D creation</param>
+        /// <param name="ignoreImageNotFoundError">Ignore error if the image was not found by specified url</param>
+        /// <returns>Returns sprite asynchronously </returns>
+        public static async UniTask<Sprite> LoadSprite(string url, Vector2 pivot, TextureFormat textureFormat = TextureFormat.ARGB32, bool ignoreImageNotFoundError = false)
+        {
+            if (string.IsNullOrEmpty(url))
+            {
+                if (settings.debugLevel <= DebugLevel.Error)
+                    Debug.LogError($"[ImageLoader] Empty url. Image could not be loaded!");
+                return null;
+            }
+
+            if (MemoryCacheContains(url))
+            {
+                var sprite = LoadFromMemoryCache(url);
+                if (sprite != null)
+                    return sprite;
+            }
+
+            if (IsLoading(url))
+            {
+                if (settings.debugLevel <= DebugLevel.Log)
+                    Debug.Log($"[ImageLoader] Waiting while another task is loading the sprite url={url}");
+                await UniTask.WaitWhile(() => IsLoading(url));
+                return await LoadSprite(url, textureFormat, ignoreImageNotFoundError);
+            }
+
+            AddLoading(url);
+
+            if (settings.debugLevel <= DebugLevel.Log)
+                Debug.Log($"[ImageLoader] Loading new Sprite into memory url={url}");
+            try
+            {
+                var cachedImage = await LoadDiskAsync(url);
+                if (cachedImage != null && cachedImage.Length > 0)
+                {
+                    await UniTask.SwitchToMainThread();
+                    var texture = new Texture2D(2, 2, textureFormat, true);
+                    if (texture.LoadImage(cachedImage))
+                    {
+                        var sprite = ToSprite(texture, pivot);
+                        if (sprite != null)
+                            SaveToMemoryCache(url, sprite, replace: true);
+
+                        RemoveLoading(url);
+                        return sprite;
+                    }
+                }
+            }
+            catch (Exception e)
+            {
+                if (settings.debugLevel <= DebugLevel.Exception)
+                    Debug.LogException(e);
+            }
+
+            UnityWebRequest request = null;
+            var finished = false;
+            UniTask.Post(async () =>
+            {
+                try
+                {
+                    request = UnityWebRequestTexture.GetTexture(url);
+                    await request.SendWebRequest();
+                }
+                catch (Exception e) 
+                {
+                    if (!ignoreImageNotFoundError)
+                        if (settings.debugLevel <= DebugLevel.Exception)
+                            Debug.LogException(e);
+                }
+                finally
+                {
+                    finished = true;
+                }
+            });
+            await UniTask.WaitUntil(() => finished);
+
+            RemoveLoading(url);
+
+#if UNITY_2020_1_OR_NEWER
+            var isError = request.result != UnityWebRequest.Result.Success;
+#else
+            var isError = request.isNetworkError || request.isHttpError;
+#endif
+
+            if (isError)
+            {
+                if (settings.debugLevel <= DebugLevel.Error)
+#if UNITY_2020_1_OR_NEWER
+                    Debug.LogError($"[ImageLoader] {request.result} {request.error}: url={url}");
+#else
+                    Debug.LogError($"[ImageLoader] {request.error}: url={url}");
+#endif
+                return null;
+            }
+            else
+            {
+                await SaveDiskAsync(url, request.downloadHandler.data);
+                var sprite = ToSprite(((DownloadHandlerTexture)request.downloadHandler).texture);
+                SaveToMemoryCache(url, sprite, replace: true);
+                return sprite;
+            }
+        }
+    }
+}