Filament
This package contains several executables and libraries you can use to build applications using
Filament. Latest versions are available on the project page.
Binaries
cmgen
, Image-based lighting asset generatorfilamesh
, Mesh converterglslminifier
, Tool to minify GLSL shadersgltf_viewer
, glTF 2.0 viewer that lets you explore many features of Filamentmatc
, Material compilermaterial_sandbox
, simple mesh viewer that lets you explore material and lighting featuresmatinfo
, Displays information about materials compiled with matc
mipgen
, Generates a series of miplevels from a source image.normal-blending
, Tool to blend normal mapsresgen
, Tool to convert files into binary resources to be embedded at compie timeroughness-prefilter
, Pre-filters a roughness map from a normal map to reduce aliasingspecular-color
, Computes the specular color of conductors based on spectral data
You can refer to the individual documentation files in docs/
for more information.
Libraries
Filament is distributed as a set of static libraries you must link against:
backend
, Required, implements all backendsbluegl
, Required to render with OpenGL or OpenGL ESbluevk
, Required to render with Vulkanfilabridge
, Support library for Filamentfilaflat
, Support library for Filamentfilament
, Main Filament librarybackend
, Filament render backend libraryibl
, Image-based lighting support libraryutils
, Support library for Filamentgeometry
, Geometry helper library for Filamentsmol-v
, SPIR-V compression library, used only with Vulkan support
To use Filament from Java you must use the following two libraries instead:
filament-java.jar
, Contains Filament's Java classesfilament-jni
, Filament's JNI bindings
To link against debug builds of Filament, you must also link against:
matdbg
, Support library that adds an interactive web-based debugger to Filament
To use the Vulkan backend on macOS you must install the LunarG SDK, enable "System Global
Components", and reboot your machine.
The easiest way to install those files is to use the macOS
LunarG Vulkan SDK installer.
Linking against Filament
This walkthrough will get you successfully compiling and linking native code
against Filament with minimum dependencies.
To start, download Filament's latest binary release
and extract into a directory of your choosing. Binary releases are suffixed
with the platform name, for example, filament-20181009-linux.tgz
.
Create a file, main.cpp
, in the same directory with the following contents:
#include <filament/FilamentAPI.h>
#include <filament/Engine.h>
using namespace filament;
int main(int argc, char** argv)
{
Engine *engine = Engine::create();
engine->destroy(&engine);
return 0;
}
The directory should look like:
|-- README.md
|-- bin
|-- docs
|-- include
|-- lib
|-- main.cpp
We'll use a platform-specific Makefile to compile and link main.cpp
with Filament's libraries.
Copy your platform's Makefile below into a Makefile
inside the same directory.
Linux
FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -lvkshaders -libl
CC=clang++
main: main.o
$(CC) -Llib/x86_64/ main.o $(FILAMENT_LIBS) -lpthread -lc++ -ldl -o main
main.o: main.cpp
$(CC) -Iinclude/ -std=c++17 -pthread -c main.cpp
clean:
rm -f main main.o
.PHONY: clean
macOS
FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -lvkshaders -libl
FRAMEWORKS=-framework Cocoa -framework Metal -framework CoreVideo
CC=clang++
main: main.o
$(CC) -Llib/x86_64/ main.o $(FILAMENT_LIBS) $(FRAMEWORKS) -o main
main.o: main.cpp
$(CC) -Iinclude/ -std=c++17 -c main.cpp
clean:
rm -f main main.o
.PHONY: clean
Windows
Note that the static libraries distributed for Windows include several
variants: mt, md, mtd, mdd. These correspond to the run-time library
flags
/MT
, /MD
, /MTd
, and /MDd
, respectively. Here we use the mt variant. For the debug variants,
be sure to also include matdbg.lib
in FILAMENT_LIBS
.
When building Filament from source, the USE_STATIC_CRT
CMake option can be
used to change the run-time library version.
FILAMENT_LIBS=filament.lib backend.lib bluegl.lib bluevk.lib filabridge.lib filaflat.lib \
utils.lib geometry.lib smol-v.lib ibl.lib vkshaders.lib
CC=cl.exe
main.exe: main.obj
$(CC) main.obj /link /libpath:"lib\\x86_64\\mt\\" $(FILAMENT_LIBS) \
gdi32.lib user32.lib opengl32.lib
main.obj: main.cpp
$(CC) /MT /Iinclude\\ /std:c++17 /c main.cpp
clean:
del main.exe main.obj
.PHONY: clean
Compiling
You should be able to invoke make
and run the executable successfully:
$ make
$ ./main
FEngine (64 bits) created at 0x106471000 (threading is enabled)
On Windows, you'll need to open up a Visual Studio Native Tools Command Prompt
and invoke nmake
instead of make
.
Generating C++ documentation
To generate the documentation you must first install doxygen
and graphviz
, then run the
following commands:
cd filament/filament
doxygen docs/doxygen/filament.doxygen
Finally simply open docs/html/index.html
in your web browser.