From dc60f57a9a02d04173ff32afdc7aa5fa02888ae1 Mon Sep 17 00:00:00 2001 From: Philip Rideout Date: Wed, 9 Mar 2022 14:01:04 -0800 Subject: [PATCH] gltfio: simplify API, make animator always available. In the past there was an API gotcha because users had to "get" the animator before releasing the glTF source data. This could have been surprising because it was a getter method, not a factory method. This was due to overeager optimization on my part, I wanted to avoid animator overhead for non-animated models, when in fact it has very little overhead. Moreover, the animator is conceivably useful even when there are no pre-supplied animations (e.g. for applying skins), so let's just create it unconditionally. Motivated by #5299. --- .../android/filament/gltfio/AssetLoader.java | 1 - .../filament/gltfio/FilamentAsset.java | 12 ++++++------ .../filament/gltfio/FilamentInstance.java | 5 +---- libs/gltfio/include/gltfio/Animator.h | 5 +++++ libs/gltfio/include/gltfio/AssetLoader.h | 7 ++----- libs/gltfio/include/gltfio/FilamentAsset.h | 7 +++---- libs/gltfio/include/gltfio/FilamentInstance.h | 3 +-- libs/gltfio/src/FFilamentAsset.h | 4 +++- libs/gltfio/src/FFilamentInstance.h | 3 ++- libs/gltfio/src/FilamentAsset.cpp | 19 ++++++------------- libs/gltfio/src/FilamentInstance.cpp | 19 +++++++------------ libs/gltfio/src/ResourceLoader.cpp | 3 +++ libs/viewer/src/SimpleViewer.cpp | 5 ++--- samples/gltf_viewer.cpp | 3 --- 14 files changed, 41 insertions(+), 55 deletions(-) diff --git a/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java b/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java index 1b586e7b31..9cb8d9e68c 100644 --- a/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java +++ b/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java @@ -60,7 +60,6 @@ import java.nio.Buffer; * } * resourceLoader.loadResources(filamentAsset) * resourceLoader.destroy() - * animator = asset.getAnimator() * filamentAsset.releaseSourceData(); * * scene.addEntities(filamentAsset.entities) diff --git a/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java b/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java index db7895395a..dada72845b 100644 --- a/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java +++ b/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java @@ -198,11 +198,11 @@ public class FilamentAsset { } /** - * Creates or retrieves the Animator interface for this asset. + * Retrieves the Animator interface for this asset. * *

When calling this for the first time, this must be called after - * {@link ResourceLoader#loadResources}. When the asset is destroyed, its - * animator becomes invalid.

+ * {@link ResourceLoader#loadResources} or {@link ResourceLoader#asyncBeginLoad}. When the asset + * is destroyed, its animator becomes invalid.

*/ public @NonNull Animator getAnimator() { if (mAnimator != null) { @@ -235,9 +235,9 @@ public class FilamentAsset { /** * Reclaims CPU-side memory for URI strings, binding lists, and raw animation data. * - * This should only be called after ResourceLoader#loadResources(). - * If using Animator, this should be called after getAnimator(). - * If this is an instanced asset, this prevents creation of new instances. + * This should only be called after ResourceLoader#loadResources() or + * ResourceLoader#asyncBeginLoad(). If this is an instanced asset, this prevents creation of new + * instances. */ public void releaseSourceData() { nReleaseSourceData(mNativeObject); diff --git a/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java b/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java index ccf4ac9bb5..accc49790d 100644 --- a/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java +++ b/android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java @@ -74,10 +74,7 @@ public class FilamentInstance { } /** - * Creates or retrieves the Animator for this instance. - * - *

When calling this for the first time, this must be called after - * {@link ResourceLoader#loadResources}.

+ * Retrieves the Animator for this instance. */ public @NonNull Animator getAnimator() { if (mAnimator != null) { diff --git a/libs/gltfio/include/gltfio/Animator.h b/libs/gltfio/include/gltfio/Animator.h index 53695d5cde..ab47f57241 100644 --- a/libs/gltfio/include/gltfio/Animator.h +++ b/libs/gltfio/include/gltfio/Animator.h @@ -80,6 +80,11 @@ private: Animator(FFilamentAsset* asset, FFilamentInstance* instance); ~Animator(); + + Animator(const Animator& animator) = delete; + Animator(Animator&& animator) = delete; + Animator& operator=(const Animator&) = delete; + AnimatorImpl* mImpl; }; diff --git a/libs/gltfio/include/gltfio/AssetLoader.h b/libs/gltfio/include/gltfio/AssetLoader.h index 4fede91f30..81feaeb23d 100644 --- a/libs/gltfio/include/gltfio/AssetLoader.h +++ b/libs/gltfio/include/gltfio/AssetLoader.h @@ -94,9 +94,6 @@ struct AssetConfiguration { * // Load buffers and textures from disk. * ResourceLoader({engine, ".", true}).loadResources(asset); * - * // Obtain the simple animation interface. - * Animator* animator = asset->getAnimator(); - * * // Free the glTF hierarchy as it is no longer needed. * asset->releaseSourceData(); * @@ -105,8 +102,8 @@ struct AssetConfiguration { * * // Execute the render loop and play the first animation. * do { - * animator->applyAnimation(0, time); - * animator->updateBoneMatrices(); + * asset->getAnimator()->applyAnimation(0, time); + * asset->getAnimator()->updateBoneMatrices(); * if (renderer->beginFrame(swapChain)) { * renderer->render(view); * renderer->endFrame(); diff --git a/libs/gltfio/include/gltfio/FilamentAsset.h b/libs/gltfio/include/gltfio/FilamentAsset.h index bdbcf7e8dd..bc413af113 100644 --- a/libs/gltfio/include/gltfio/FilamentAsset.h +++ b/libs/gltfio/include/gltfio/FilamentAsset.h @@ -194,14 +194,14 @@ public: const char* getExtras(utils::Entity entity = {}) const noexcept; /** - * Lazily creates the animation engine or returns it from the cache. + * Returns the animation engine. * * The animator is owned by the asset and should not be manually deleted. - * The first time this is called, it must be called before FilamentAsset::releaseSourceData(). + * Must be called after loadResources or asyncBeginLoad, otherwise returns null. * If the asset is instanced, this returns a "primary" animator that controls all instances. * To animate each instance individually, use \see FilamentInstance. */ - Animator* getAnimator() noexcept; + Animator* getAnimator() const noexcept; /** * Get the target name at target index in the given entity. @@ -223,7 +223,6 @@ public: * Reclaims CPU-side memory for URI strings, binding lists, and raw animation data. * * This should only be called after ResourceLoader::loadResources(). - * If using Animator, this should be called after getAnimator(). * If this is an instanced asset, this prevents creation of new instances. */ void releaseSourceData() noexcept; diff --git a/libs/gltfio/include/gltfio/FilamentInstance.h b/libs/gltfio/include/gltfio/FilamentInstance.h index 007116a776..8d462eab56 100644 --- a/libs/gltfio/include/gltfio/FilamentInstance.h +++ b/libs/gltfio/include/gltfio/FilamentInstance.h @@ -57,7 +57,7 @@ public: utils::Entity getRoot() const noexcept; /** - * Lazily creates the animation engine for the instance, or returns it from the cache. + * Returns the animation engine for the instance. * * Note that an animator can be obtained either from an individual instance, or from the * originating FilamentAsset. In the latter case, the animation frame is shared amongst all @@ -65,7 +65,6 @@ public: * individual instances. * * The animator is owned by the asset and should not be manually deleted. - * The first time this is called, it must be called before FilamentAsset::releaseSourceData(). */ Animator* getAnimator() noexcept; }; diff --git a/libs/gltfio/src/FFilamentAsset.h b/libs/gltfio/src/FFilamentAsset.h index 7d4d998c13..92804e0f67 100644 --- a/libs/gltfio/src/FFilamentAsset.h +++ b/libs/gltfio/src/FFilamentAsset.h @@ -191,7 +191,7 @@ struct FFilamentAsset : public FilamentAsset { size_t getEntitiesByPrefix(const char* prefix, utils::Entity* entities, size_t maxCount) const noexcept; - Animator* getAnimator() noexcept; + Animator* getAnimator() const noexcept { return mAnimator; } const char* getMorphTargetNameAt(utils::Entity entity, size_t targetIndex) const noexcept; @@ -228,6 +228,8 @@ struct FFilamentAsset : public FilamentAsset { return mInstances.size() > 0; } + void createAnimators(); + filament::Engine* mEngine; utils::NameComponentManager* mNameManager; utils::EntityManager* mEntityManager; diff --git a/libs/gltfio/src/FFilamentInstance.h b/libs/gltfio/src/FFilamentInstance.h index 6487f6d1d9..d740ac8154 100644 --- a/libs/gltfio/src/FFilamentInstance.h +++ b/libs/gltfio/src/FFilamentInstance.h @@ -54,7 +54,8 @@ struct FFilamentInstance : public FilamentInstance { FFilamentAsset* owner; SkinVector skins; NodeMap nodeMap; - Animator* getAnimator() noexcept; + void createAnimator(); + Animator* getAnimator() const noexcept; }; FILAMENT_UPCAST(FilamentInstance) diff --git a/libs/gltfio/src/FilamentAsset.cpp b/libs/gltfio/src/FilamentAsset.cpp index 96f6905932..5b8e543847 100644 --- a/libs/gltfio/src/FilamentAsset.cpp +++ b/libs/gltfio/src/FilamentAsset.cpp @@ -83,19 +83,12 @@ const char* FFilamentAsset::getExtras(utils::Entity entity) const noexcept { return iter == mNodeExtras.cend() ? nullptr : iter->second.c_str(); } -Animator* FFilamentAsset::getAnimator() noexcept { - if (!mAnimator) { - if (!mResourcesLoaded) { - slog.e << "Cannot create animator before resource loading." << io::endl; - return nullptr; - } - if (!mSourceAsset) { - slog.e << "Cannot create animator from frozen asset." << io::endl; - return nullptr; - } - mAnimator = new Animator(this, nullptr); +void FFilamentAsset::createAnimators() { + assert_invariant(mAnimator == nullptr); + mAnimator = new Animator(this, nullptr); + for (FFilamentInstance* instance : mInstances) { + instance->createAnimator(); } - return mAnimator; } const char* FFilamentAsset::getMorphTargetNameAt(utils::Entity entity, @@ -292,7 +285,7 @@ const char* FilamentAsset::getExtras(Entity entity) const noexcept { return upcast(this)->getExtras(entity); } -Animator* FilamentAsset::getAnimator() noexcept { +Animator* FilamentAsset::getAnimator() const noexcept { return upcast(this)->getAnimator(); } diff --git a/libs/gltfio/src/FilamentInstance.cpp b/libs/gltfio/src/FilamentInstance.cpp index cd142ff74e..b84a5b6d87 100644 --- a/libs/gltfio/src/FilamentInstance.cpp +++ b/libs/gltfio/src/FilamentInstance.cpp @@ -26,21 +26,16 @@ using namespace utils; namespace gltfio { -Animator* FFilamentInstance::getAnimator() noexcept { - if (!animator) { - if (!owner->mResourcesLoaded) { - slog.e << "Cannot create animator before resource loading." << io::endl; - return nullptr; - } - if (!owner->mSourceAsset) { - slog.e << "Cannot create animator from frozen asset." << io::endl; - return nullptr; - } - animator = new Animator(owner, this); - } +Animator* FFilamentInstance::getAnimator() const noexcept { + assert_invariant(animator); return animator; } +void FFilamentInstance::createAnimator() { + assert_invariant(animator == nullptr); + animator = new Animator(owner, this); +} + FilamentAsset* FilamentInstance::getAsset() const noexcept { return upcast(this)->owner; } diff --git a/libs/gltfio/src/ResourceLoader.cpp b/libs/gltfio/src/ResourceLoader.cpp index efc09bdba9..80a8535237 100644 --- a/libs/gltfio/src/ResourceLoader.cpp +++ b/libs/gltfio/src/ResourceLoader.cpp @@ -539,6 +539,9 @@ bool ResourceLoader::loadResources(FFilamentAsset* asset, bool async) { // Finally, create Filament Textures and begin loading image files. asset->mResourcesLoaded = pImpl->createTextures(async); + + asset->createAnimators(); + return asset->mResourcesLoaded; } diff --git a/libs/viewer/src/SimpleViewer.cpp b/libs/viewer/src/SimpleViewer.cpp index 9e10ac2d68..bf61911372 100644 --- a/libs/viewer/src/SimpleViewer.cpp +++ b/libs/viewer/src/SimpleViewer.cpp @@ -972,8 +972,7 @@ void SimpleViewer::updateUserInterface() { // We do not yet support animation selection in the remote UI. To support this feature, we // would need to send a message from DebugServer to the WebSockets client. - if (mAnimator && mAnimator->getAnimationCount() > 0 && - ImGui::CollapsingHeader("Animation")) { + if (mAnimator->getAnimationCount() > 0 && ImGui::CollapsingHeader("Animation")) { ImGui::Indent(); int selectedAnimation = mCurrentAnimation; ImGui::RadioButton("Disable", &selectedAnimation, 0); @@ -992,7 +991,7 @@ void SimpleViewer::updateUserInterface() { } if (mCurrentMorphingEntity && ImGui::CollapsingHeader("Morphing")) { - const bool isAnimating = mCurrentAnimation > 0 && mAnimator && mAnimator->getAnimationCount() > 0; + const bool isAnimating = mCurrentAnimation > 0 && mAnimator->getAnimationCount() > 0; if (isAnimating) { ImGui::BeginDisabled(); } diff --git a/samples/gltf_viewer.cpp b/samples/gltf_viewer.cpp index 140271ec56..5b2f33add2 100644 --- a/samples/gltf_viewer.cpp +++ b/samples/gltf_viewer.cpp @@ -425,9 +425,6 @@ int main(int argc, char** argv) { app.resourceLoader = new gltfio::ResourceLoader(configuration); } app.resourceLoader->asyncBeginLoad(app.asset); - - // Load animation data then free the source hierarchy. - app.asset->getAnimator(); app.asset->releaseSourceData(); auto ibl = FilamentApp::get().getIBL();