filament README

The project's README from github.com/google/filament. As one markdown file: README.md.

Filament

Android Build Status iOS Build Status Linux Build Status macOS Build Status Windows Build Status Web Build Status

Filament is a real-time physically based rendering engine for Android, iOS, Linux, macOS, Windows, and WASM. It is designed to be as small as possible and as efficient as possible on Android.

Download

Download Filament releases to access stable builds. Filament release archives contains host-side tools that are required to generate assets.

Make sure you always use tools from the same release as the runtime library. This is particularly important for matc (material compiler).

If you'd rather build Filament yourself, please refer to our build manual.

Android

Android projects can simply declare Filament libraries as Maven dependencies:

repositories {
    // ...
    mavenCentral()
}

dependencies {
    implementation 'com.google.android.filament:filament-android:1.76.1'
}

Here are all the libraries available in the group com.google.android.filament:

Artifact Description
filament-android The Filament rendering engine itself.
filament-android-debug Debug version of filament-android.
gltfio-android A glTF 2.0 loader for Filament, depends on filament-android.
filament-utils-android KTX loading, Kotlin math, and camera utilities, depends on gltfio-android.
filamat-android A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.

iOS

iOS projects can use CocoaPods to install the latest release:

pod 'Filament', '~> 1.76.1'

Documentation

Examples

Night scene Night scene Materials Materials Helmet Screen-space refraction

Features

APIs

Backends

Rendering

Post processing

glTF 2.0

Rendering with Filament

Native Linux, macOS and Windows

You must create an Engine, a Renderer and a SwapChain. The SwapChain is created from a native window pointer (an NSView on macOS or a HWND on Windows for instance):

Engine* engine = Engine::create();
SwapChain* swapChain = engine->createSwapChain(nativeWindow);
Renderer* renderer = engine->createRenderer();

To render a frame you must then create a View, a Scene and a Camera:

Camera* camera = engine->createCamera(EntityManager::get().create());
View* view = engine->createView();
Scene* scene = engine->createScene();

view->setCamera(camera);
view->setScene(scene);

Renderables are added to the scene:

Entity renderable = EntityManager::get().create();
// build a quad
RenderableManager::Builder(1)
        .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
        .material(0, materialInstance)
        .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vertexBuffer, indexBuffer, 0, 6)
        .culling(false)
        .build(*engine, renderable);
scene->addEntity(renderable);

The material instance is obtained from a material, itself loaded from a binary blob generated by matc:

Material* material = Material::Builder()
        .package((void*) BAKED_MATERIAL_PACKAGE, sizeof(BAKED_MATERIAL_PACKAGE))
        .build(*engine);
MaterialInstance* materialInstance = material->createInstance();

To learn more about materials and matc, please refer to the materials documentation.

To render, simply pass the View to the Renderer:

// beginFrame() returns false if we need to skip a frame
if (renderer->beginFrame(swapChain)) {
    // for each View
    renderer->render(view);
    renderer->endFrame();
}

For complete examples of Linux, macOS and Windows Filament applications, look at the source files in the samples/ directory. These samples are all based on libs/filamentapp/ which contains the code that creates a native window with SDL2 and initializes the Filament engine, renderer and views.

For more information on how to prepare environment maps for image-based lighting please refer to BUILDING.md.

Android

See android/samples for examples of how to use Filament on Android.

You must always first initialize Filament by calling Filament.init().

Rendering with Filament on Android is similar to rendering from native code (the APIs are largely the same across languages). You can render into a Surface by passing a Surface to the createSwapChain method. This allows you to render to a SurfaceTexture, a TextureView or a SurfaceView. To make things easier we provide an Android specific API called UiHelper in the package com.google.android.filament.android. All you need to do is set a render callback on the helper and attach your SurfaceView or TextureView to it. You are still responsible for creating the swap chain in the onNativeWindowChanged() callback.

iOS

Filament is supported on iOS 11.0 and above. See ios/samples for examples of using Filament on iOS.

Filament on iOS is largely the same as native rendering with C++. A CAEAGLLayer or CAMetalLayer is passed to the createSwapChain method. Filament for iOS supports both Metal (preferred) and OpenGL ES.

Assets

To get started you can use the textures and environment maps found respectively in third_party/textures and third_party/environments. These assets are under CC0 license. Please refer to their respective URL.txt files to know more about the original authors.

Environments must be pre-processed using cmgen or using the libiblprefilter library.

How to make contributions

Please read and follow the steps in CONTRIBUTING.md. Make sure you are familiar with the code style.

Directory structure

This repository not only contains the core Filament engine, but also its supporting libraries and tools.

License

Please see LICENSE.

Disclaimer

This is not an officially supported Google product.

filament (google/filament)

graphics-programming
Searching Database…

20.6K ·GitHub
Filament
What is this?Filament is Google's open-source, real-time physically based rendering engine (PBR) for Android, iOS, Linux, macOS, Windows and WASM/WebGL2, designed to be as small and efficient as possible — especially on Android.
Is it a library I code against, or a ready-made app?It is a C++ rendering library you link into your own app, not a ready-made program — with a Java/JNI API on Android and a JavaScript API for web builds.
How do I add it to my project?Android: declare the com.google.android.filament Maven artifacts (filament-android, gltfio-android for glTF, filament-utils-android for KTX and math helpers). iOS: install via CocoaPods. Desktop: build from source and start from the SDL2-based samples in samples/.
Which graphics APIs does it use under the hood — do I need Vulkan?It renders through OpenGL 4.1+, OpenGL ES 3.0+, Metal, Vulkan 1.0, WebGPU or WebGL 2.0 depending on platform — Metal is preferred on iOS, and the WebGL 2.0 backend runs in any supporting browser.
What's the catch with materials?Materials are authored ahead of time and compiled offline with the matc tool into binary blobs the engine loads at runtime — and host tools must come from the same release as the runtime library or assets can break.
Does it work on iOS, and which versions?iOS 11.0 and above is supported. Metal is the preferred backend there with OpenGL ES also available, and rendering on iOS works much like the native C++ path on desktop.
What rendering features does it ship with out of the box?A clustered forward renderer with Cook-Torrance BRDF, image-based lighting, a physically-based camera and physical light units, cascaded and contact shadows, SSAO, screen-space reflections, fog, depth-of-field bokeh, HDR bloom, several tone mappers, color grading, and TAA/FXAA/MSAA anti-aliasing.
Which host tools come with the repo?matc (material compiler), cmgen (image-based lighting asset generator), mipgen (miplevel generator), filamesh (mesh converter), matinfo, matedit and glslminifier. Environment maps must be pre-processed with cmgen or libiblprefilter before use.
Are there sample assets I can experiment with?Yes — the repo ships CC0 textures and environment maps under thirdparty/textures and thirdparty/environments, plus 3D models under permissive licenses, and desktop sample apps built on SDL2 in samples/.
Is Filament an officially supported Google product?It is developed by Google, but the README carries the disclaimer: 'This is not an officially supported Google product.' Treat it as open source without a support guarantee.
What are similar projects?bgfx, wgpu, 3d-game-shaders-for-beginners, Vulkan, assimp, renderdoc, crosstl, tinyrenderer
Which topics is it in?gltf, graphics-programming, 3d-graphics, webgpu, shaders, opengl, computer-graphics, metal, vulkan, webgl, rendering, compiler
Creator
google
Size
1.1 GB
Stars
20.6K
Updated
CommitOct 17Releasev1.78.0Oct 13
Age
8y
Commits · 90 Days