gltfio: Introduce AssetLoader API for instancing.

Issue #1513

libs/gltfio/include/gltfio/AssetLoader.h

@@ -85,7 +85,8 @@ struct AssetConfiguration {
  *
  * // Parse the glTF content and create Filament entities.
  * std::vector<uint8_t> content(...);
- * FilamentAsset* asset = loader->createAssetFromJson(content.data(), content.size());
+ * FilamentAsset* asset;
+ * loader->createAssets(content.data(), content.size(), &asset, 1);
  * content.clear();
  *
  * // Load buffers and textures from disk.
@@ -138,6 +139,26 @@ class AssetLoader {
      */
     static void destroy(AssetLoader** loader);
 
+    /**
+     * Consumes the contents of a glTF 2.0 file and produces one or more instanced assets.
+     *
+     * The returned assets share all their textures, material instances, and vertex buffers. However
+     * each asset has its own unique set of entities and components.
+     *
+     * Clients must use ResourceLoader to load resources on one of the instances. This needs to
+     * occur only once, not repeated for each instance.
+     *
+     * @param bytes the contents of a glTF 2.0 file (JSON or GLB)
+     * @param numBytes the number of bytes in "bytes"
+     * @param assets destination pointer, to be populated by the requested number of assets
+     * @param numAssets requested number of assets
+     * @return true if successful, false otherwise.
+     *
+     * \see destroyAssets()
+     */
+    bool createAssets(const uint8_t* bytes, uint32_t numBytes, FilamentAsset** assets,
+            size_t numAssets);
+
     /**
      * Takes a pointer to the contents of a JSON-based glTF 2.0 file and returns a bundle
      * of Filament objects. Returns null on failure.
@@ -166,6 +187,9 @@ class AssetLoader {
     /** Destroys the given asset and all of its associated Filament objects. */
     void destroyAsset(const FilamentAsset* asset);
 
+    /** Destroys a list of assets and all associated Filament objects. */
+    void destroyAssets(const FilamentAsset** assets, size_t numAssets);
+
     /**
      * Gets a weak reference to an array of cached materials, used internally to create material
      * instances for assets.