Engine
Engine is Filament's main entry-point.
An Engine instance keeps track of all resources created by the user and manages the rendering thread as well as the hardware renderer.
To use Filament, an Engine instance must be created first using Engine.create(). Engine essentially represents (or is associated with) a hardware context (e.g., an OpenGL ES context or a Vulkan device).
Rendering typically happens in an operating system's window (which can be fullscreen), which is managed by a Renderer.
A typical Filament render loop looks like this:
val engine = Engine.create()!!
val swapChain = engine.createSwapChain(nativeWindow)
val renderer = engine.createRenderer()
val scene = engine.createScene()
val view = engine.createView()
view.setScene(scene)
while (!quit) {
// Wait for VSYNC and user input events
if (renderer.beginFrame(swapChain)) {
renderer.render(view)
renderer.endFrame()
}
}
engine.destroy(view)
engine.destroy(scene)
engine.destroy(renderer)
engine.destroy(swapChain)
Engine.destroy(engine)Types
How the engine handles asynchronous operations.
Rendering backend selection.
A feature flag: a last-resort switch for a faulty feature, set when the Engine is built and, unless constant, at any time with setFeatureFlag.
Backend feature levels control available rendering capabilities and performance characteristics.
A tri-state for compile's shadow-receiver and skinning variants.
GPU context priority, a hint to the driver for work scheduling and preemption.
Stereoscopic rendering technique for VR and 3D displays.
The opaque token Builder.build's callback gets, for getEngine.
Properties
The currently active feature level.
The rendering backend being used by this Engine.
The canvas this engine renders into.
The configuration this Engine was built with.
The default Material: 80% white, lit. Owned by the Engine.
The EntityManager for creating and managing entities.
Whether the Engine is in an unrecoverable failure state (e.g. the GPU device was lost). Once true, the Engine must be destroyed and recreated.
Whether asynchronous operations can be used (see Config.asynchronousMode).
Whether the engine batches identical renderables into instanced draw calls.
Whether the render thread is paused. Set to pause or resume it.
The LightManager for managing light components.
The maximum number of instances automatic instancing batches together.
The native object, for interop with code calling the Fila* C API directly. Read-only: this wrapper owns it.
The RenderableManager for managing renderable components.
The highest feature level supported by this backend.
The TransformManager for managing entity transforms.
Functions
Cancels the async call id (runCommandAsync, setBufferAsync, setBufferAtAsync, setImageAsync…). Its completion callback still runs, with AsyncCallStatus.CANCELED. False if it's running, done or already canceled.
Asynchronously compiles the variants of material needed to render it in view, taking into account the view's features (lighting, fog, stereo, shadowing) and shadowReceiver and skinning.
Creates a Camera component on entity.
Creates a Fence.
Creates a Renderer.
Creates a Scene.
Creates a SwapChain rendering into a native display surface.
Creates an offscreen SwapChain of the given size.
Creates a View.
Destroys a BufferObject.
Destroys a ColorGrading.
Destroys a Fence.
Destroys a FramePacer.
Destroys an IndexBuffer.
Destroys an IndirectLight.
Destroys an InstanceBuffer.
Destroys a Material; its instances must be destroyed first.
Destroys a MaterialInstance.
Destroys a MorphTargetBuffer.
Destroys a RenderTarget.
Destroys a Renderer.
Destroys a Scene.
Destroys a SkinningBuffer.
Destroys a Skybox.
Destroys a Stream.
Destroys a SwapChain, and releases the native window it rendered into.
Destroys a Texture.
Destroys a VertexBuffer.
Destroys a View.
Destroys every Filament component of entity; the entity itself is the EntityManager's.
Destroys the Camera component of entity.
Enables high-precision world-space translations, for better numerical stability with large translations.
Blocks until all pending commands have been executed by the GPU.
Blocks until all pending commands have been executed by the GPU, or timeout nanoseconds pass.
The Camera component of entity, or null if it has none.
A feature flag's value, or null if it doesn't exist.
The feature flags this Engine knows.
Whether a feature flag named name exists.
Whether this Engine supports stereoscopicType rendering.
Whether bufferObject is a live object of this Engine.
Whether colorGrading is a live object of this Engine.
Whether fence is a live object of this Engine.
Whether indexBuffer is a live object of this Engine.
Whether indirectLight is a live object of this Engine.
Whether instanceBuffer is a live object of this Engine.
Whether material is a live object of this Engine.
Whether morphTargetBuffer is a live object of this Engine.
Whether renderTarget is a live object of this Engine.
Whether renderer is a live object of this Engine.
Whether scene is a live object of this Engine.
Whether skinningBuffer is a live object of this Engine.
Whether skybox is a live object of this Engine.
Whether stream is a live object of this Engine.
Whether swapChain is a live object of this Engine.
Whether texture is a live object of this Engine.
Whether vertexBuffer is a live object of this Engine.
Whether view is a live object of this Engine.
Whether materialInstance is a live instance of material.
Whether materialInstance is a live instance of any of this Engine's materials; slower than isValid.
Runs the pending user callbacks now instead of later, e.g. once per frame after the vsync tick.
Queues command to run asynchronously, in order with the other async calls (texture and buffer uploads), and returns an ID for cancelAsyncCall. Meant for resource preparation such as asset loading; flooding it delays those uploads. onComplete runs once on the main thread (see pumpMessageQueues): AsyncCallStatus.COMPLETED if command ran, AsyncCallStatus.CANCELED if it never did. Needs isAsynchronousModeEnabled.
Activates featureLevel, at most supportedFeatureLevel; a level can't be lowered once activated.
Sets a feature flag; constant flags can only be set on the Builder. @return false if it doesn't exist or is constant.
Switches the command queue to unprotected mode, after a frame on a protected SwapChain.