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.
This commit is contained in:
Philip Rideout
2022-03-10 11:36:46 -08:00
parent 5c4f12fa00
commit dc60f57a9a
14 changed files with 41 additions and 55 deletions
@@ -60,7 +60,6 @@ import java.nio.Buffer;
* }
* resourceLoader.loadResources(filamentAsset)
* resourceLoader.destroy()
* animator = asset.getAnimator()
* filamentAsset.releaseSourceData();
*
* scene.addEntities(filamentAsset.entities)
@@ -198,11 +198,11 @@ public class FilamentAsset {
}
/**
* Creates or retrieves the <code>Animator</code> interface for this asset.
* Retrieves the <code>Animator</code> interface for this asset.
*
* <p>When calling this for the first time, this must be called after
* {@link ResourceLoader#loadResources}. When the asset is destroyed, its
* animator becomes invalid.</p>
* {@link ResourceLoader#loadResources} or {@link ResourceLoader#asyncBeginLoad}. When the asset
* is destroyed, its animator becomes invalid.</p>
*/
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);
@@ -74,10 +74,7 @@ public class FilamentInstance {
}
/**
* Creates or retrieves the <code>Animator</code> for this instance.
*
* <p>When calling this for the first time, this must be called after
* {@link ResourceLoader#loadResources}.</p>
* Retrieves the <code>Animator</code> for this instance.
*/
public @NonNull Animator getAnimator() {
if (mAnimator != null) {
+5
View File
@@ -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;
};
+2 -5
View File
@@ -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();
+3 -4
View File
@@ -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;
@@ -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;
};
+3 -1
View File
@@ -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;
+2 -1
View File
@@ -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)
+6 -13
View File
@@ -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();
}
+7 -12
View File
@@ -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;
}
+3
View File
@@ -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;
}
+2 -3
View File
@@ -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();
}
-3
View File
@@ -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();