Filament object creation and destruction lifecycles

Filament object creation and destruction lifecycles

Filament manages its own native allocations. To prevent segmentation faults and memory leaks, follow these rules:

1. ECS Entities & Components

Getting the Entity Manager

• Preferred Method: Retrieve the EntityManager directly from the Engine instance: utils::EntityManager& em = engine->getEntityManager();
• Alternative (Avoid if engine is available): Only use the global singleton if the Engine pointer is inaccessible: utils::EntityManager& em = utils::EntityManager::get();

Entities

• Create: Create Entity IDs using the entity manager: utils::Entity entity = engine->getEntityManager().create();
• Destroy: Free the Entity ID from the entity manager: engine->getEntityManager().destroy(entity);

Components

• Create: Attach components to an existing entity using manager builders:
  • Renderables/Lights: Use RenderableManager::Builder or LightManager::Builder on the entity:

    RenderableManager::Builder(1)
        .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vb, ib)
        .material(0, matInstance)
        .build(*engine, entity);
    

  • Cameras: Attach a Camera component to the entity: Camera* camera = engine->createCamera(entity);
• Destroy (CRITICAL):
  1. To clean up the entire entity: First, destroy all Filament-managed components on the entity: engine->destroy(entity); Second, free the Entity ID: engine->getEntityManager().destroy(entity);

     // Correct Entity Cleanup
     engine->destroy(myEntity);
     engine->getEntityManager().destroy(myEntity);
     

  2. To remove a single component from the entity: