Merge pull request #258 from libktx/feature/assets-async

Asynchronous coroutines-based asset manager: AssetLoader #182

.github/CONTRIBUTORS.md

@@ -10,7 +10,7 @@ Project contributors listed chronologically.
   * Contributed LibGDX [collections](../collections) utilities.
 * [@sreich](https://github.com/sreich)
   * Contributed various utilities from the [Ore Infinium](https://github.com/sreich/ore-infinium) project.
-* [@raincole](https://github.com/raincole)
+* [@yhlai-code](https://github.com/yhlai-code) (_raincole_)
   * Contributed LibGDX [collections](../collections) utilities.
   * Provided insightful review of the [`Async`](../async) module.
 * [@Jkly](https://github.com/Jkly)
@@ -46,6 +46,7 @@ Project contributors listed chronologically.
   * Contributed [actors](../actors) utilities.
   * Wrote a complete [KTX tutorial](https://github.com/Quillraven/SimpleKtxGame/wiki) based on the original LibGDX introduction.
   * Author of the [preferences](../preferences) module.
+  * Tested and reviewed the [assets async](../assets-async) module.
 * [@FocusPo1nt](https://github.com/FocusPo1nt)
   * Added utilities to [style module](../style).
 * [@maltaisn](https://github.com/maltaisn)

CHANGELOG.md

@@ -9,7 +9,35 @@
     - `PerformanceCounter.prettyPrint` allows to print basic performance data after profiling.
 - **[CHANGE]** (`ktx-app`) `LetterboxingViewport` moved from `ktx-app` to `ktx-graphics`.
 - **[FEATURE]** (`ktx-ashley`) Added `Entity.contains` (`in` operator) that checks if an `Entity` has a `Component`.
+- **[FEATURE]** (`ktx-assets-async`) Added a new KTX module: coroutines-based asset loading.
+    - `AssetStorage` is a non-blocking coroutines-based alternative to LibGDX `AssetManager`.
+         - `get` operator obtains an asset from the storage or throws a `MissingAssetException`.
+         - `getOrNull` obtains an asset from the storage or return `null` if the asset is unavailable.
+         - `getAsync` obtains a reference to the asset from the storage as `Deferred`.
+         - `load` suspends a coroutine until an asset is loaded and returns its instance.
+         - `loadAsync` schedules asynchronous loading of an asset.
+         - `loadSync` blocks the thread until selected asset is loaded.
+         - `unload` schedules asynchronous unloading of an asset.
+         - `add` allows to manually add a loaded asset to `AssetManager`.
+         - `dispose` unloads all assets from the storage.
+         - `getLoader` and `setLoader` manage `AssetLoader` instances used to load assets.
+         - `isLoaded` checks if loading of an asset was finished.
+         - `contains` operator checks if the asset was scheduled for loading or added to the storage.
+         - `progress` allows to check asset loading progress.
+         - `getReferenceCount` returns how many times the asset was loaded or referenced by other assets as a dependency.
+         - `getDependencies` returns a list of dependencies of the selected asset.
+         - `getAssetDescriptor` creates an `AssetDescriptor` with loading data for the selected asset.
+         - `getIdentifier` creates an `Identifier` uniquely pointing to an asset of selected type and file path.
+    - `Identifier` data class added as an utility to uniquely identify assets by their type and path.
+         - `Identifier.toAssetDescriptor` allows to convert an `Identifier` to an `AssetDescriptor`. 
+    - `AssetDescriptor.toIdentifier` allows to convert an `AssetDescriptor` to `Identifier` used to uniquely identify `AssetStorage` assets.
+    - `LoadingProgress` is an internal class used by the `AssetStorage` to track loading progress.
 - **[FEATURE]** (`ktx-async`) Added `RenderingScope` factory function for custom scopes using rendering thread dispatcher.
+- **[FEATURE]** (`ktx-async`) `newAsyncContext` and `newSingleThreadAsyncContext` now support `threadName` parameter
+that allows to set thread name pattern of `AsyncExecutor` threads.
+- **[FIX]** (`ktx-async`) `isOnRenderingThread` now behaves consistently regardless of launching coroutine context.
+- **[FEATURE]** (`ktx-freetype-async`) This KTX module is now restored and updated to the new `AssetStorage` API.
+There are no public API changes since the last released version.
 - **[FEATURE]** (`ktx-graphics`) Added `LetterboxingViewport` from `ktx-app`.
 - **[FEATURE]** (`ktx-graphics`) Added `takeScreenshot` utility function that allows to save a screenshot of the application.
 - **[FEATURE]** (`ktx-graphics`) Added `BitmapFont.center` extension method that allows to center text on an object.

README.md

@@ -19,9 +19,9 @@ Examples of Kotlin language features used to improve usability, performance and
 * *Extension methods* with sensible *default parameters*.
 * *Inline methods* with reduced runtime overhead for various listeners, builders and loggers.
 * *Nullable types* which improve typing information of selected interfaces and functions.
-* *Default interface methods* simplifying the implementation.
+* *Default interface methods* for common interfaces, simplifying their implementations.
 * *Type-safe builders* for GUI, styling and physics engine.
-* *Coroutines context* providing concurrency utilities.
+* *Coroutines context* providing concurrency utilities and non-blocking asset loading.
 * *Reified types* that simplify usage of methods normally consuming `Class` parameters.
 
 See the [_Choosing KTX_](https://github.com/libktx/ktx/wiki/Choosing-KTX) article for pros and cons of this framework.
@@ -33,26 +33,28 @@ You can include selected **KTX** modules based on the needs of your application.
 
 Module | Dependency name | Description
 :---: | :--- | ---
-[actors](actors) | `ktx-actors` | General [`Scene2D`](https://github.com/libgdx/libgdx/wiki/Scene2d) GUI utilities for stages, actors, actions and event listeners.
-[app](app) | `ktx-app` | `ApplicationListener` implementations and other general application utilities.
+[actors](actors) | `ktx-actors` | [`Scene2D`](https://github.com/libgdx/libgdx/wiki/Scene2d) GUI extensions for stages, actors, actions and event listeners.
+[app](app) | `ktx-app` | `ApplicationListener` implementations and general application utilities.
 [ashley](ashley) | `ktx-ashley` | [`Ashley`](https://github.com/libgdx/ashley) entity-component-system utilities.
 [assets](assets) | `ktx-assets` | Resources management utilities.
+[assets-async](assets-async) | `ktx-assets-async` | Non-blocking asset loading using coroutines.
 [async](async) | `ktx-async` | [Coroutines](https://kotlinlang.org/docs/reference/coroutines.html) context based on LibGDX threading model.
 [box2d](box2d) | `ktx-box2d` | [`Box2D`](https://github.com/libgdx/libgdx/wiki/Box2d) physics engine utilities.
 [collections](collections) | `ktx-collections` | Extensions for LibGDX custom collections.
-[freetype](freetype) | `ktx-freetype` | `FreeType` font loading utilities.
+[freetype](freetype) | `ktx-freetype` | `FreeType` fonts loading utilities.
+[freetype-async](freetype-async) | `ktx-freetype-async` | Non-blocking `FreeType` fonts loading using coroutines.
 [graphics](graphics) | `ktx-graphics` | Utilities related to rendering tools and graphics.
 [i18n](i18n) | `ktx-i18n` | Internationalization API utilities.
-[inject](inject) | `ktx-inject` | A simple dependency injection system with low overhead and no reflection usage.
+[inject](inject) | `ktx-inject` | A dependency injection system with low overhead and no reflection usage.
 [json](json) | `ktx-json` | Utilities for LibGDX [JSON](https://github.com/libgdx/libgdx/wiki/Reading-and-writing-JSON) serialization API.
 [log](log) | `ktx-log` | Minimal runtime overhead cross-platform logging using inlined functions.
 [math](math) | `ktx-math` | Operator functions for LibGDX math API and general math utilities.
 [preferences](preferences) | `ktx-preferences` | Improved API for accessing and saving [preferences](https://github.com/libgdx/libgdx/wiki/Preferences).
 [scene2d](scene2d) | `ktx-scene2d` | Type-safe Kotlin builders for [`Scene2D`](https://github.com/libgdx/libgdx/wiki/Scene2d) GUI.
 [style](style) | `ktx-style` | Type-safe Kotlin builders for `Scene2D` widget styles extending `Skin` API.
 [tiled](tiled) | `ktx-tiled` | Utilities for [Tiled](https://www.mapeditor.org/) maps.
-[vis](vis) | `ktx-vis` | Type-safe Kotlin builders for [`VisUI`](https://github.com/kotcrab/vis-ui/). An _alternative_ to the [scene2d](scene2d) module.
-[vis-style](vis-style) | `ktx-vis-style` | Type-safe Kotlin builders for `VisUI` widget styles. An _extension_ of [style](style) module.
+[vis](vis) | `ktx-vis` | Type-safe Kotlin builders for [`VisUI`](https://github.com/kotcrab/vis-ui/). An _alternative_ to [scene2d](scene2d).
+[vis-style](vis-style) | `ktx-vis-style` | Type-safe Kotlin builders for `VisUI` widget styles.
 
 ### Installation