improvements to EntityManagers and Filament APIs (#7302)

* prevent public classes from being created on the stack

- we used to to this by deleting operator delete, but this prevented
  the internal "F" classes from being virtual; which can be useful
  when using EntityManger::Listener.
  now we just make the destructor protected in each class.

- EntityManger::Listener now has a virtual destructor so that
  objects could be correctly destroyed from Listener*

* improve EntityManger and Component managers

- all component managers now have the same "base" API
    - getComponentCount()
	- empty()
    - getEntity()
    - getEntities()

- Scene now has getEntityCount()

- EntityManager now has getEntityCount()

- all component manager implement gc() the same way, by calling destroy()

- SingleInstanceComponentManager::gc() that calls removeComponent() has
  been removed because it's dangerous. removeComponent() is often
  not enough, some additional cleanup might be needed.

android/filament-android/src/main/cpp/Scene.cpp

@@ -71,6 +71,13 @@ Java_com_google_android_filament_Scene_nRemoveEntities(JNIEnv *env, jclass type,
     env->ReleaseIntArrayElements(entities, (jint*) nativeEntities, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Scene_nGetEntityCount(JNIEnv *env, jclass type,
+        jlong nativeScene) {
+    Scene* scene = (Scene*) nativeScene;
+    return (jint) scene->getEntityCount();
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Scene_nGetRenderableCount(JNIEnv *env, jclass type,
         jlong nativeScene) {

android/filament-android/src/main/java/com/google/android/filament/Scene.java

@@ -146,18 +146,29 @@ public void removeEntities(@Entity int[] entities) {
     }
 
     /**
-     * Returns the number of {@link RenderableManager} components in the <code>Scene</code>.
+     * Returns the total number of Entities in the <code>Scene</code>, whether alive or not.
      *
-     * @return number of {@link RenderableManager} components in the <code>Scene</code>..
+     * @return the total number of Entities in the <code>Scene</code>.
+     */
+    public int getEntityCount() {
+        return nGetEntityCount(getNativeObject());
+    }
+
+    /**
+     * Returns the number of active (alive) {@link RenderableManager} components in the
+     * <code>Scene</code>.
+     *
+     * @return number of {@link RenderableManager} components in the <code>Scene</code>.
      */
     public int getRenderableCount() {
         return nGetRenderableCount(getNativeObject());
     }
 
     /**
-     * Returns the number of {@link LightManager} components in the <code>Scene</code>.
+     * Returns the number of active (alive) {@link LightManager} components in the
+     * <code>Scene</code>.
      *
-     * @return number of {@link LightManager} components in the <code>Scene</code>..
+     * @return number of {@link LightManager} components in the <code>Scene</code>.
      */
     public int getLightCount() {
         return nGetLightCount(getNativeObject());
@@ -189,6 +200,7 @@ void clearNativeObject() {
     private static native void nAddEntities(long nativeScene, int[] entities);
     private static native void nRemove(long nativeScene, int entity);
     private static native void nRemoveEntities(long nativeScene, int[] entities);
+    private static native int nGetEntityCount(long nativeScene);
     private static native int nGetRenderableCount(long nativeScene);
     private static native int nGetLightCount(long nativeScene);
     private static native boolean nHasEntity(long nativeScene, int entity);

filament/include/filament/BufferObject.h

@@ -110,6 +110,10 @@ class UTILS_PUBLIC BufferObject : public FilamentAPI {
      * @return The maximum capacity of the BufferObject.
      */
     size_t getByteCount() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~BufferObject() = default;
 };
 
 } // namespace filament

filament/include/filament/Camera.h

@@ -565,6 +565,10 @@ class UTILS_PUBLIC Camera : public FilamentAPI {
      * @return                  effective full field of view in degrees
      */
     static double computeEffectiveFov(double fovInDegrees, double focusDistance) noexcept;
+
+protected:
+    // prevent heap allocation
+    ~Camera() = default;
 };
 
 } // namespace filament

filament/include/filament/ColorGrading.h

@@ -478,6 +478,10 @@ class UTILS_PUBLIC ColorGrading : public FilamentAPI {
     private:
         friend class FColorGrading;
     };
+
+protected:
+    // prevent heap allocation
+    ~ColorGrading() = default;
 };
 
 } // namespace filament

filament/include/filament/DebugRegistry.h

@@ -142,6 +142,10 @@ class UTILS_PUBLIC DebugRegistry : public FilamentAPI {
         float pid_i = 0.0f;
         float pid_d = 0.0f;
     };
+
+protected:
+    // prevent heap allocation
+    ~DebugRegistry() = default;
 };
 
 

filament/include/filament/Fence.h

@@ -75,6 +75,10 @@ class UTILS_PUBLIC Fence : public FilamentAPI {
      *          FenceStatus::ERROR otherwise.
      */
     static FenceStatus waitAndDestroy(Fence* fence, Mode mode = Mode::FLUSH);
+
+protected:
+    // prevent heap allocation
+    ~Fence() = default;
 };
 
 } // namespace filament

filament/include/filament/FilamentAPI.h

@@ -49,8 +49,6 @@ class UTILS_PUBLIC FilamentAPI {
     // prevent heap allocation
     static void *operator new     (size_t) = delete;
     static void *operator new[]   (size_t) = delete;
-    static void  operator delete  (void*)  = delete;
-    static void  operator delete[](void*)  = delete;
 };
 
 template<typename T>

filament/include/filament/IndexBuffer.h

@@ -118,6 +118,10 @@ class UTILS_PUBLIC IndexBuffer : public FilamentAPI {
      * @return The number of indices the IndexBuffer holds.
      */
     size_t getIndexCount() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~IndexBuffer() = default;
 };
 
 } // namespace filament

filament/include/filament/IndirectLight.h

@@ -342,6 +342,10 @@ class UTILS_PUBLIC IndirectLight : public FilamentAPI {
     /** @deprecated use static versions instead */
     UTILS_DEPRECATED
     math::float4 getColorEstimate(math::float3 direction) const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~IndirectLight() = default;
 };
 
 } // namespace filament

filament/include/filament/InstanceBuffer.h

@@ -91,6 +91,10 @@ class UTILS_PUBLIC InstanceBuffer : public FilamentAPI {
      * @param offset index of the first instance to set local transforms
      */
     void setLocalTransforms(math::mat4f const* localTransforms, size_t count, size_t offset = 0);
+
+protected:
+    // prevent heap allocation
+    ~InstanceBuffer() = default;
 };
 
 } // namespace filament

filament/include/filament/LightManager.h

@@ -143,27 +143,38 @@ class UTILS_PUBLIC LightManager : public FilamentAPI {
     using Instance = utils::EntityInstance<LightManager>;
 
     /**
-     * Returns the number of component in the LightManager, not that component are not
+     * Returns the number of component in the LightManager, note that component are not
      * guaranteed to be active. Use the EntityManager::isAlive() before use if needed.
      *
      * @return number of component in the LightManager
      */
     size_t getComponentCount() const noexcept;
 
-    /**
-     * Returns the list of Entity for all components. Use getComponentCount() to know the size
-     * of the list.
-     * @return a pointer to Entity
-     */
-    utils::Entity const* getEntities() const noexcept;
-
     /**
      * Returns whether a particular Entity is associated with a component of this LightManager
      * @param e An Entity.
      * @return true if this Entity has a component associated with this manager.
      */
     bool hasComponent(utils::Entity e) const noexcept;
 
+    /**
+     * @return true if the this manager has no components
+     */
+    bool empty() const noexcept;
+
+    /**
+     * Retrieve the `Entity` of the component from its `Instance`.
+     * @param i Instance of the component obtained from getInstance()
+     * @return
+     */
+    utils::Entity getEntity(Instance i) const noexcept;
+
+    /**
+     * Retrieve the Entities of all the components of this manager.
+     * @return A list, in no particular order, of all the entities managed by this manager.
+     */
+    utils::Entity const* getEntities() const noexcept;
+
     /**
      * Gets an Instance representing the Light component associated with the given Entity.
      * @param e An Entity.
@@ -953,19 +964,9 @@ class UTILS_PUBLIC LightManager : public FilamentAPI {
      */
     bool isShadowCaster(Instance i) const noexcept;
 
-    /**
-     * Helper to process all components with a given function
-     * @tparam F    a void(Entity entity, Instance instance)
-     * @param func  a function of type F
-     */
-    template<typename F>
-    void forEachComponent(F func) noexcept {
-        utils::Entity const* const pEntity = getEntities();
-        for (size_t i = 0, c = getComponentCount(); i < c; i++) {
-            // Instance 0 is the invalid instance
-            func(pEntity[i], Instance(i + 1));
-        }
-    }
+protected:
+    // prevent heap allocation
+    ~LightManager() = default;
 };
 
 } // namespace filament

filament/include/filament/Material.h

@@ -375,6 +375,10 @@ class UTILS_PUBLIC Material : public FilamentAPI {
 
     //! Returns this material's default instance.
     MaterialInstance const* getDefaultInstance() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~Material() = default;
 };
 
 } // namespace filament

filament/include/filament/MaterialInstance.h

@@ -479,6 +479,10 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
      */
     void setStencilWriteMask(uint8_t writeMask,
             StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
+
+protected:
+    // prevent heap allocation
+    ~MaterialInstance() = default;
 };
 
 } // namespace filament

filament/include/filament/MorphTargetBuffer.h

@@ -136,6 +136,10 @@ class UTILS_PUBLIC MorphTargetBuffer : public FilamentAPI {
      * @return The number of targets the MorphTargetBuffer holds.
      */
     size_t getCount() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~MorphTargetBuffer() = default;
 };
 
 } // namespace filament

filament/include/filament/RenderTarget.h

@@ -180,6 +180,10 @@ class UTILS_PUBLIC RenderTarget : public FilamentAPI {
      * @return Number of color attachments usable in a render target.
      */
     uint8_t getSupportedColorAttachmentsCount() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~RenderTarget() = default;
 };
 
 } // namespace filament

filament/include/filament/RenderableManager.h

@@ -102,6 +102,29 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI {
      */
     Instance getInstance(utils::Entity e) const noexcept;
 
+    /**
+     * @return the number of Components
+     */
+    size_t getComponentCount() const noexcept;
+
+    /**
+     * @return true if the this manager has no components
+     */
+    bool empty() const noexcept;
+
+    /**
+     * Retrieve the `Entity` of the component from its `Instance`.
+     * @param i Instance of the component obtained from getInstance()
+     * @return
+     */
+    utils::Entity getEntity(Instance i) const noexcept;
+
+    /**
+     * Retrieve the Entities of all the components of this manager.
+     * @return A list, in no particular order, of all the entities managed by this manager.
+     */
+    utils::Entity const* getEntities() const noexcept;
+
     /**
      * The transformation associated with a skinning joint.
      *
@@ -829,6 +852,10 @@ class UTILS_PUBLIC RenderableManager : public FilamentAPI {
             typename = typename is_supported_index_type<INDEX>::type>
     static Box computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count,
             size_t stride = sizeof(VECTOR)) noexcept;
+
+protected:
+    // prevent heap allocation
+    ~RenderableManager() = default;
 };
 
 RenderableManager::Builder& RenderableManager::Builder::morphing(uint8_t level, size_t primitiveIndex,

filament/include/filament/Renderer.h

@@ -579,6 +579,10 @@ class UTILS_PUBLIC Renderer : public FilamentAPI {
      * getUserTime()
      */
     void resetUserTime();
+
+protected:
+    // prevent heap allocation
+    ~Renderer() = default;
 };
 
 } // namespace filament

filament/include/filament/Scene.h

@@ -140,16 +140,22 @@ class UTILS_PUBLIC Scene : public FilamentAPI {
     void removeEntities(const utils::Entity* entities, size_t count);
 
     /**
-     * Returns the number of Renderable objects in the Scene.
+     * Returns the total number of Entities in the Scene, whether alive or not.
+     * @return Total number of Entities in the Scene.
+     */
+    size_t getEntityCount() const noexcept;
+
+    /**
+     * Returns the number of active (alive) Renderable objects in the Scene.
      *
-     * @return number of Renderable objects in the Scene.
+     * @return The number of active (alive) Renderable objects in the Scene.
      */
     size_t getRenderableCount() const noexcept;
 
     /**
-     * Returns the total number of Light objects in the Scene.
+     * Returns the number of active (alive) Light objects in the Scene.
      *
-     * @return The total number of Light objects in the Scene.
+     * @return The number of active (alive) Light objects in the Scene.
      */
     size_t getLightCount() const noexcept;
 
@@ -168,6 +174,10 @@ class UTILS_PUBLIC Scene : public FilamentAPI {
      * @param functor User provided functor called for each entity in the scene
      */
     void forEach(utils::Invocable<void(utils::Entity entity)>&& functor) const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~Scene() = default;
 };
 
 } // namespace filament

filament/include/filament/SkinningBuffer.h

@@ -115,6 +115,10 @@ class UTILS_PUBLIC SkinningBuffer : public FilamentAPI {
      * @return The number of bones the SkinningBuffer holds.
      */
     size_t getBoneCount() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~SkinningBuffer() = default;
 };
 
 } // namespace filament

filament/include/filament/Skybox.h

@@ -174,6 +174,10 @@ class UTILS_PUBLIC Skybox : public FilamentAPI {
      * @return the associated texture, or null if it does not exist
      */
     Texture const* getTexture() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~Skybox() = default;
 };
 
 } // namespace filament

filament/include/filament/Stream.h

@@ -207,6 +207,10 @@ class UTILS_PUBLIC Stream : public FilamentAPI {
      * @return timestamp in nanosecond.
      */
     int64_t getTimestamp() const noexcept;
+
+protected:
+    // prevent heap allocation
+    ~Stream() = default;
 };
 
 } // namespace filament