Updated README

IvanMurzak · IvanMurzak · commit e50fab83b94a · 2025-02-20T03:12:46.000-08:00
diff --git a/README.md b/README.md
@@ -7,19 +7,19 @@ Async image loader with two caching layers for Unity. It supports loading images
 
 Wait for image get loaded then set:
 
-``` C#
+```csharp
 image.sprite = await ImageLoader.LoadSprite(imageURL);
 ```
 
 Don't wait, use callback to set loaded image later:
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL).ThenSet(image).Forget();
 ```
 
 Use callback to set image and still wait for the completion:
 
-``` C#
+```csharp
 await ImageLoader.LoadSprite(imageURL).ThenSet(image);
 ```
 
@@ -77,8 +77,15 @@ await ImageLoader.LoadSprite(imageURL).ThenSet(image);
       - [Get references count](#get-references-count)
 - [Other](#other)
   - [Understanding `IFuture<T>`](#understanding-ifuturet)
+    - [Key Properties of `IFuture<T>`](#key-properties-of-ifuturet)
+    - [Key Methods of `IFuture<T>`](#key-methods-of-ifuturet)
+    - [Example Usage of `IFuture<T>`](#example-usage-of-ifuturet)
   - [Understanding `Reference<T>`](#understanding-referencet)
+    - [Key Properties of `Reference<T>`](#key-properties-of-referencet)
+    - [Key Methods of `Reference<T>`](#key-methods-of-referencet)
+    - [Example Usage of `Reference<T>`](#example-usage-of-referencet)
   - [Understanding `Future<Reference<T>>`](#understanding-futurereferencet)
+    - [Why It Is Needed](#why-it-is-needed)
 
 ---
 
@@ -96,7 +103,7 @@ openupm add extensions.unity.imageloader
 
 In the main thread somewhere at the start of the project need to call `ImageLoader.Init();` once to initialize static properties in the right thread. It is required to make in the main thread. Then you can use `ImageLoader` from any thread and at any time.
 
-``` C#
+```csharp
 ImageLoader.Init(); // just once from the main thread
 ```
 
@@ -106,7 +113,7 @@ ImageLoader.Init(); // just once from the main thread
 
 `ImageLoader.LoadSprite` returns `IFuture<Sprite>`. This instance provides all range of callbacks and API to modify it. [Understanding `IFuture<T>`](#understanding-ifuturet).
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL) // loading process started
     // ┌──────────────────────────┬────────────────────────────────────────────────────────────────────────┐
     // │ Loading lifecycle events │                                                                        │
@@ -146,7 +153,7 @@ ImageLoader.LoadSprite(imageURL) // loading process started
 
 > [Full sample source code](https://github.com/IvanMurzak/Unity-ImageLoader/blob/master/Assets/_PackageRoot/Samples/SampleLoadSpriteThenSetImage.cs)
 
-``` C#
+```csharp
 // Load a sprite from the web and cache it for faster loading next time
 image.sprite = await ImageLoader.LoadSprite(imageURL);
 
@@ -158,7 +165,7 @@ await ImageLoader.LoadSprite(imageURL).ThenSet(image);
 
 > [Full sample source code](https://github.com/IvanMurzak/Unity-ImageLoader/blob/master/Assets/_PackageRoot/Samples/SampleLoadTextureThenSetMaterial.cs)
 
-``` C#
+```csharp
 // Load a Texture2D from the web and cache it for faster loading next time
 material.mainTexture = await ImageLoader.LoadTexture(imageURL);
 
@@ -170,15 +177,15 @@ await ImageLoader.LoadTexture(imageURL).ThenSet(material);
 
 > [Full sample source code](https://github.com/IvanMurzak/Unity-ImageLoader/blob/master/Assets/_PackageRoot/Samples/SampleLoadSpriteThenSetIntoMultipleImages.cs)
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL).ThenSet(image1, image2).Forget();
 ```
 
 ## Error handling
 
 > [Full sample source code](https://github.com/IvanMurzak/Unity-ImageLoader/blob/master/Assets/_PackageRoot/Samples/SampleErrorHandle.cs)
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL) // Attempt to load a sprite
     .ThenSet(image) // If successful, set the sprite to the Image component
     .Failed(exception => Debug.LogException(exception)) // If an error occurs, log the exception
@@ -195,7 +202,7 @@ ImageLoader.LoadSprite(imageURL) // Attempt to load a sprite
 
 > [Full sample source code](https://github.com/IvanMurzak/Unity-ImageLoader/blob/master/Assets/_PackageRoot/Samples/SampleAwaitAndForget.cs)
 
-``` C#
+```csharp
 // Load image and wait
 await ImageLoader.LoadSprite(imageURL);
 
@@ -216,7 +223,7 @@ Cancellation is helpful if target image consumer doesn't exist anymore. For exam
 
 ### Cancel by MonoBehaviour events
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL)
     .ThenSet(image)
     .CancelOnEnable(this)   // cancel on OnEnable event of current MonoBehaviour
@@ -226,14 +233,14 @@ ImageLoader.LoadSprite(imageURL)
 
 ### Explicit cancellation
 
-``` C#
+```csharp
 var future = ImageLoader.LoadSprite(imageURL).ThenSet(image);
 future.Cancel();
 ```
 
 ### Cancellation Token
 
-``` C#
+```csharp
 var cancellationTokenSource = new CancellationTokenSource();
 
 // loading with attached cancellation token
@@ -244,7 +251,7 @@ ImageLoader.LoadSprite(imageURL, cancellationToken: cancellationTokenSource.Toke
 cancellationTokenSource.Cancel(); // canceling
 ```
 
-``` C#
+```csharp
 var cancellationTokenSource = new CancellationTokenSource();
 
 ImageLoader.LoadSprite(imageURL)
@@ -257,14 +264,14 @@ cancellationTokenSource.Cancel(); // canceling
 
 ### Cancellation by `using`
 
-``` C#
+```csharp
 using (var future = ImageLoader.LoadSprite(imageURL).ThenSet(image))
 {
     // future would be canceled and disposed outside of the brackets
 }
 ```
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL) // load sprite
     .ThenSet(image) // if success set sprite into image
     .CancelOnDestroy(this) // cancel OnDestroy event of current gameObject
@@ -293,13 +300,13 @@ Timeout triggers `IFuture<T>` cancellation.
 
 Set global timeout in the settings:
 
-``` C#
+```csharp
 ImageLoader.settings.timeout = TimeSpan.FromSeconds(30);
 ```
 
 Set timeout for a specific loading request (`IFuture<T>`):
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(imageURL) // load sprite
     .ThenSet(image) // if success set sprite into image
     .Timeout(TimeSpan.FromSeconds(10)) // set timeout duration 10 seconds
@@ -319,15 +326,15 @@ Cache system based on the two layers. The first layer is **Memory cache**, secon
 
 By default it uses `Application.persistentDataPath + "/ImageLoader"`
 
-``` C#
+```csharp
 ImageLoader.settings.diskSaveLocation = Application.persistentDataPath + "/myCustomFolder";
 ```
 
 #### Override for a specific loading task
 
 It overrides global `ImageLoader.settings`
 
-``` C#
+```csharp
 ImageLoader.LoadSprite(url)
     .SetUseDiskCache(false)
     .SetUseMemoryCache(true);
@@ -337,7 +344,7 @@ ImageLoader.LoadSprite(url)
 
 ### Manually read / write into cache
 
-``` C#
+```csharp
 // Override Memory cache for specific image
 ImageLoader.SaveToMemoryCache(url, sprite);
 
@@ -347,7 +354,7 @@ ImageLoader.LoadSpriteFromMemoryCache(url);
 
 ### Check cache existence
 
-``` C#
+```csharp
 // Check if any cache contains specific image
 ImageLoader.CacheContains(url);
 
@@ -360,7 +367,7 @@ ImageLoader.DiskCacheContains(url);
 
 ### Clear cache
 
-``` C#
+```csharp
 // Clear memory Memory and Disk cache for all images
 ImageLoader.ClearCacheAll();
 
@@ -390,7 +397,7 @@ Texture2D objects consume a lot of memory. Ignoring it may impact performance or
 
 It is simple, just executing this line of code would release memory of a single Texture2D in the case if no other `Reference` pointing on it exists. Before doing that please make sure that no Unity component is using the texture.
 
-``` C#
+```csharp
 ImageLoader.ClearMemoryCache(url);
 ```
 
@@ -402,7 +409,7 @@ Under the hood it calls `UnityEngine.Object.DestroyImmediate(texture)`.
 
 ImageLoader can manager memory releasing of loaded textures. To use it need to call `ImageLoader.LoadSpriteRef` instead of `ImageLoader.LoadSprite`. It returns `Reference<Sprite>` object which contains `Sprite` and `Url`. When `Reference<Sprite>` object is not needed anymore, call `reference.Dispose()` method to release memory, or just don't save the reference on it. It is `IDisposable` and it will be disposed by Garbage Collector. Each new instance of `Reference<Sprite>` increments reference counter of the texture. When the last reference is disposed, the texture memory releases. Also, if any reference is alive, calling `ImageLoader.ClearMemoryCache` or `ImageLoader.ClearCache` would have zero effect for only referenced textures. It prints warning messages about it.
 
-``` C#
+```csharp
 // Load sprite image and get reference to it
 var reference = await ImageLoader.LoadSpriteRef(imageURL);
 
@@ -424,7 +431,7 @@ reference = null;
 
 `Reference<T>.ThenSet` has a unique feature to attach the reference to the target consumer if consumer is `UnityEngine.Component`. The reference would be disposed as only the consumer gets destroyed.
 
-``` C#
+```csharp
 ImageLoader.LoadSpriteRef(imageURL) // load sprite using Reference
     .ThenSet(image) // if success set sprite into image, also creates binding to `image`
     .Forget();
@@ -434,7 +441,7 @@ ImageLoader.LoadSpriteRef(imageURL) // load sprite using Reference
 
 It automatically dispose the reference as only `this.gameObject` gets `OnDestroy` callback.
 
-``` C#
+```csharp
 ImageLoader.LoadSpriteRef(imageURL) // load sprite using Reference
     .Then(reference => reference.DisposeOnDestroy(this))
     .Then(reference =>
@@ -447,14 +454,113 @@ ImageLoader.LoadSpriteRef(imageURL) // load sprite using Reference
 
 #### Get references count
 
-``` C#
+```csharp
 var count = ImageLoader.GetReferenceCount(imageURL); // get count of references
 ```
 
+---
+
 # Other
 
 ## Understanding `IFuture<T>`
 
+The `IFuture<T>` interface represents an asynchronous operation that will eventually produce a result of type `T`. It provides a range of methods and properties to handle the lifecycle of the asynchronous operation, including loading, success, failure, and cancellation events.
+
+### Key Properties of `IFuture<T>`
+
+- **`Id`**: Unique identifier for the future.
+- **`Url`**: URL associated with the future.
+- **`IsCancelled`**: Indicates if the operation has been cancelled.
+- **`IsLoaded`**: Indicates if the operation has successfully loaded the result.
+- **`IsCompleted`**: Indicates if the operation has completed (either successfully or with an error).
+- **`IsInProgress`**: Indicates if the operation is currently in progress.
+- **`Status`**: Current status of the future.
+- **`CancellationToken`**: Token used to cancel the operation.
+- **`Value`**: The result of the operation.
+- **`LogLevel`**: The logging level for the operation.
+
+### Key Methods of `IFuture<T>`
+
+- **``Then(Action<T> onCompleted)``**: Registers a callback to be executed when the operation successfully completes and produces a result.
+- **`Failed(Action<Exception> action)`**: Registers a callback to be executed if the operation fails with an exception.
+- **`Completed(Action<bool> action)`**: Registers a callback to be executed when the operation completes, regardless of success or failure. The boolean parameter indicates whether the operation was successful.
+- **`Canceled(Action action)`**: Registers a callback to be executed if the operation is canceled.
+- **`SetUseDiskCache(bool value = true)`**: Configures whether the operation should use disk caching.
+- **`SetUseMemoryCache(bool value = true)`**: Configures whether the operation should use memory caching.
+- **`SetLogLevel(DebugLevel value)`**: Sets the logging level for the operation.
+- **`Cancel()`**: Cancels the operation if it is still in progress.
+- **`Forget()`**: Ignores the result of the operation, useful for avoiding compilation warnings about unawaited tasks.
+- **`AsUniTask()`**: Converts the `IFuture<T>` instance to a `UniTask<T>`.
+- **`AsTask()`**: Converts the `IFuture<T>` instance to a `Task<T>`.
+- **`AsReference(DebugLevel logLevel = DebugLevel.Trace)`**: Converts the `IFuture<T>` instance to a `Future<Reference<T>>` instance.
+- **`GetAwaiter()`**: Returns an awaiter for the `IFuture<T>` instance, allowing it to be awaited using the `await` keyword.
+- **`PassEvents(IFutureInternal<T> to, bool passCancelled = true)`**: Passes events to another future.
+- **`PassEvents<T2>(IFutureInternal<T2> to, Func<T, T2> convert, bool passCancelled = true)`**: Passes events to another future with conversion.
+- **`Register(CancellationToken cancellationToken)`**: Registers a new cancellation token to cancel the future with it.
+- **`Timeout(TimeSpan duration)`**: Sets a timeout duration for the future. If the duration is reached, it fails the future with a related exception.
+
+### Example Usage of `IFuture<T>`
+
+```csharp
+ImageLoader.LoadSprite(imageURL) // Start loading the sprite
+    .Then(sprite => Debug.Log("Loaded")) // On successful load
+    .Failed(exception => Debug.LogException(exception)) // On failure
+    .Completed(isLoaded => Debug.Log($"Completed, isLoaded={isLoaded}")) // On completion
+    .Canceled(() => Debug.Log("Canceled")) // On cancellation
+    .Forget(); // Avoid compilation warnings
+```
+
 ## Understanding `Reference<T>`
 
+The `Reference<T>` class is used to manage the lifecycle of loaded resources, such as `Texture2D` or `Sprite`, in a memory-efficient manner. It helps to automatically release memory when the resource is no longer needed, preventing memory leaks and optimizing performance.
+
+### Key Properties of `Reference<T>`
+
+- **`Value`**: The actual resource (e.g., `Sprite` or `Texture2D`) that is being referenced.
+- **`Url`**: The URL associated with the resource.
+- **`IsDisposed`**: Indicates whether the reference has been disposed.
+
+### Key Methods of `Reference<T>`
+
+- **`Dispose()`**: Disposes the reference, releasing the associated resource from memory. This should be called when the resource is no longer needed.
+- **`DisposeOnDestroy(Component component)`**: Automatically disposes the reference when the specified `Component` is destroyed. This is useful for ensuring that resources are released when the associated GameObject is destroyed.
+- **`DisposeOnDisable(Component component)`**: Automatically disposes the reference when the specified `Component` is disabled.
+- **`DisposeOnEnable(Component component)`**: Automatically disposes the reference when the specified `Component` is enabled.
+
+### Example Usage of `Reference<T>`
+
+```csharp
+// Load a sprite using Reference
+var reference = await ImageLoader.LoadSpriteRef(imageURL);
+
+// Use the sprite
+var sprite = reference.Value;
+
+// Dispose the reference when the sprite is no longer needed
+reference.Dispose();
+```
+
+```csharp
+// Alternatively, automatically dispose the reference when the GameObject is destroyed
+ImageLoader.LoadSpriteRef(imageURL)
+    .Then(reference => reference.DisposeOnDestroy(this))
+    .Then(reference =>
+    {
+        var sprite = reference.Value;
+        // use sprite
+    })
+    .Forget();
+```
+
 ## Understanding `Future<Reference<T>>`
+
+The `Future<Reference<T>>` class combines the functionality of `IFuture<T>` and `Reference<T>`, providing a powerful tool for managing the lifecycle of asynchronous operations that produce resources such as `Texture2D` or `Sprite`. This combination allows you to handle the loading process and the resource management in a memory-efficient manner.
+
+### Why It Is Needed
+
+The `Future<Reference<T>>` class is needed to ensure that resources are loaded asynchronously and managed efficiently. By using this class, you can:
+
+1. **Load Resources Asynchronously**: Start loading resources such as `Texture2D` or `Sprite` without blocking the main thread.
+2. **Manage Resource Lifecycle**: Automatically release resources when they are no longer needed, preventing memory leaks and optimizing performance.
+3. **Handle Loading Events**: Register callbacks for various events such as success, failure, and cancellation during the loading process.
+4. **Bind Resources to Components**: Automatically dispose of resources when the associated `UnityEngine.Component` is destroyed, ensuring that resources are released when the GameObject is destroyed.
