Skip to main content

​
Engine

The Engine class is Filament’s main entry point and central manager for all rendering resources.

​
Overview

An Engine instance keeps track of all resources created by the user (vertex buffers, materials, textures, etc.) and manages the rendering thread and hardware renderer. Each Engine represents a graphics hardware context (e.g., an OpenGL ES context).
An Engine instance is not thread-safe. If multi-threading is needed, synchronization must be external.

​
Creation and destruction

Create an engine using the static create() method and destroy it with the static destroy() method: 
#include <filament/Engine.h>
using namespace filament;

// Create engine
Engine* engine = Engine::create();

// ... use engine ...

// Destroy engine (also clears the pointer)
Engine::destroy(&engine);

​
Basic usage

A typical render loop: 
#include <filament/Engine.h>
#include <filament/Renderer.h>
#include <filament/Scene.h>
#include <filament/View.h>
using namespace filament;

Engine* engine       = Engine::create();
SwapChain* swapChain = engine->createSwapChain(nativeWindow);
Renderer* renderer   = engine->createRenderer();
Scene* scene         = engine->createScene();
View* view           = engine->createView();

view->setScene(scene);

do {
    // Wait for VSYNC and user input events
    if (renderer->beginFrame(swapChain)) {
        renderer->render(view);
        renderer->endFrame();
    }
} while (!quit);

// Cleanup
engine->destroy(view);
engine->destroy(scene);
engine->destroy(renderer);
engine->destroy(swapChain);
Engine::destroy(&engine);

​
Builder

Use Engine::Builder to configure engine creation:

​
Backend selection

​
backend
Backend
Select the graphics backend (OPENGL, VULKAN, METAL, etc.)
Engine* engine = Engine::Builder()
    .backend(Engine::Backend::VULKAN)
    .build();

​
Configuration

​
config
Config
Configure memory footprint and threading
Engine::Config config;
config.commandBufferSizeMB = 6;        // 6 MiB for command buffer
config.perRenderPassArenaSizeMB = 4;   // 4 MiB per-frame arena
config.jobSystemThreadCount = 4;        // 4 worker threads

Engine* engine = Engine::Builder()
    .config(&config)
    .build();

​
Feature level

​
featureLevel
FeatureLevel
Set minimum feature level (FEATURE_LEVEL_0, FEATURE_LEVEL_1, etc.)
Engine* engine = Engine::Builder()
    .featureLevel(Engine::FeatureLevel::FEATURE_LEVEL_2)
    .build();

​
Resource creation

​
Create scene objects

Scene* scene = engine->createScene();
View* view = engine->createView();
Renderer* renderer = engine->createRenderer();
Camera* camera = engine->createCamera(entity);

​
Create swap chain

​
nativeWindow
void*
Platform-specific native window handle
// Platform-specific native window
SwapChain* swapChain = engine->createSwapChain(nativeWindow);

// Headless swap chain (no window)
SwapChain* offscreen = engine->createSwapChain(1920, 1080);

​
Create geometry

VertexBuffer* vb = VertexBuffer::Builder()
    .vertexCount(3)
    .bufferCount(1)
    .attribute(VertexAttribute::POSITION, 0, 
               VertexBuffer::AttributeType::FLOAT3)
    .build(*engine);

IndexBuffer* ib = IndexBuffer::Builder()
    .indexCount(3)
    .bufferType(IndexBuffer::IndexType::USHORT)
    .build(*engine);

​
Create materials and textures

// Material from compiled package
Material* material = Material::Builder()
    .package(BAKED_MATERIAL_PACKAGE, sizeof(BAKED_MATERIAL_PACKAGE))
    .build(*engine);

MaterialInstance* mi = material->createInstance();

// Texture
Texture* texture = Texture::Builder()
    .width(512)
    .height(512)
    .levels(1)
    .format(Texture::InternalFormat::RGBA8)
    .build(*engine);

​
Resource management

​
Destroy resources

All resources must be destroyed to avoid leaks: 
engine->destroy(vertexBuffer);
engine->destroy(indexBuffer);
engine->destroy(material);
engine->destroy(materialInstance);
engine->destroy(texture);
Resources are automatically freed when the engine is destroyed, but a warning is emitted for leaked resources. Always explicitly destroy resources.

​
Flush commands

​
flushAndWait
void
Block until all pending commands are executed
// Wait for GPU to finish all work
engine->flushAndWait();

​
Multi-threading

When created, the Engine starts:
  • A render thread with elevated priority
  • Multiple worker threads (count based on platform)
On platforms with asymmetric cores (ARM Big.Little), Filament automatically assigns threads to appropriate cores.

​
Job system

Access the engine’s job system: 
utils::JobSystem& js = engine->getJobSystem();

​
Component managers

Access ECS component managers: 
// Get managers
RenderableManager& rm = engine->getRenderableManager();
LightManager& lm = engine->getLightManager();
TransformManager& tm = engine->getTransformManager();

// Use managers
rm.destroy(entity);

​
Active backend

Query the active graphics backend: 
Engine::Backend backend = engine->getBackend();
if (backend == Engine::Backend::VULKAN) {
    // Vulkan-specific code
}

​
Supported backends

BackendPlatforms
OPENGLLinux, macOS, Windows
GLES3Android, iOS
VULKANAndroid, Linux, macOS, Windows
METALmacOS, iOS
WEBGPUAndroid, Linux, macOS, Windows
WEBGL2Web browsers

Renderer

Frame rendering and swap chains

Scene

Entity container

View

Camera and scene association

Rendering loop

Learn about the render loop

Build docs developers (and LLMs) love

Get started for freeTalk to us