Scene
A Scene is a flat container of Renderable and Light instances.
Overview
A Scene manages the list of entities to render. It is not a scene graph or hierarchy—entities are stored in a flat list.
A Renderable must be added to a Scene to be rendered, and the Scene must be provided to a View.
Creation and destruction
Create using Engine::createScene() and destroy using Engine::destroy():
#include <filament/Scene.h>
#include <filament/Engine.h>
using namespace filament;
Engine* engine = Engine::create();
Scene* scene = engine->createScene();
// ... use scene ...
engine->destroy(scene);
Adding entities
Add single entity
The entity to add (ignored if it lacks Renderable or Light component)
utils::Entity entity = utils::EntityManager::get().create();
// Add renderable component
RenderableManager::Builder(1)
.boundingBox({{-1, -1, -1}, {1, 1, 1}})
.material(0, materialInstance)
.geometry(0, RenderableManager::PrimitiveType::TRIANGLES,
vertexBuffer, indexBuffer, 0, 6)
.build(*engine, entity);
// Add to scene
scene->addEntity(entity);
An entity can only be added once to a Scene. Adding it again has no effect.
Add multiple entities
Number of entities in the array
utils::Entity entities[100];
// ... create and configure entities ...
scene->addEntities(entities, 100);
Removing entities
Remove single entity
Remove multiple entities
utils::Entity entities[10];
// ... entities to remove ...
scene->removeEntities(entities, 10);
Remove all entities
scene->removeAllEntities();
Removing an entity from the Scene does not destroy it. Use EntityManager::destroy() or Engine::destroy() on components to fully clean up.
Skybox
Set a skybox to fill untouched pixels:
Skybox* skybox = Skybox::Builder()
.environment(envTexture)
.build(*engine);
scene->setSkybox(skybox);
// Get skybox
Skybox* currentSkybox = scene->getSkybox();
// Remove skybox
scene->setSkybox(nullptr);
Indirect light (IBL)
Set image-based lighting:
IndirectLight* ibl = IndirectLight::Builder()
.reflections(reflectionsTexture)
.irradiance(3, irradianceSH)
.intensity(30000.0f)
.build(*engine);
scene->setIndirectLight(ibl);
// Get IBL
IndirectLight* currentIbl = scene->getIndirectLight();
// Remove IBL
scene->setIndirectLight(nullptr);
Querying entities
Check if entity exists
if (scene->hasEntity(entity)) {
// Entity is in the scene
}
Get entity counts
// Total entities (alive or not)
size_t totalCount = scene->getEntityCount();
// Active renderable count
size_t renderableCount = scene->getRenderableCount();
// Active light count
size_t lightCount = scene->getLightCount();
Iterate entities
Function called for each entity in the scene
scene->forEach([](utils::Entity entity) {
// Process entity
std::cout << "Entity: " << entity.getId() << std::endl;
});
Do not add or remove entities from the Scene within the forEach functor.
Complete example
using namespace filament;
using namespace utils;
Engine* engine = Engine::create();
Scene* scene = engine->createScene();
// Create skybox
Texture* envTexture = loadEnvironmentMap(engine);
Skybox* skybox = Skybox::Builder()
.environment(envTexture)
.build(*engine);
scene->setSkybox(skybox);
// Create IBL
IndirectLight* ibl = IndirectLight::Builder()
.reflections(envTexture)
.intensity(30000.0f)
.build(*engine);
scene->setIndirectLight(ibl);
// Add renderables
for (int i = 0; i < 10; i++) {
Entity entity = EntityManager::get().create();
RenderableManager::Builder(1)
.boundingBox({{-1, -1, -1}, {1, 1, 1}})
.material(0, materialInstance)
.geometry(0, RenderableManager::PrimitiveType::TRIANGLES,
vertexBuffer, indexBuffer)
.build(*engine, entity);
scene->addEntity(entity);
}
// Add lights
Entity sunEntity = EntityManager::get().create();
LightManager::Builder(LightManager::Type::SUN)
.color({1.0f, 1.0f, 1.0f})
.intensity(100000.0f)
.direction({0, -1, 0})
.castShadows(true)
.build(*engine, sunEntity);
scene->addEntity(sunEntity);
std::cout << "Renderables: " << scene->getRenderableCount() << std::endl;
std::cout << "Lights: " << scene->getLightCount() << std::endl;
// Cleanup
scene->removeAllEntities();
engine->destroy(skybox);
engine->destroy(ibl);
engine->destroy(scene);
View
Rendering configuration
RenderableManager
Create renderables
LightManager
Create lights
Entities and components
Learn about ECS