Falcor 3.0
Falcor is a real-time rendering framework supporting DirectX 12 and Vulkan. It aims to improve productivity of research and prototype projects. Its features include:
- Abstracting many common graphics operations, such as shader compilation, model loading and scene rendering
- VR support using OpenVR
- Common rendering effects such as shadows and post-processing effects
- DirectX Raytracing abstraction
Prerequisites
- GPU that supports DirectX 12 or Vulkan
- Windows 10 RS2 (version 1703) or newer, or Ubuntu 17.10
On Windows:
- Visual Studio 2017
- Microsoft Windows SDK ver 10.0.15063.468
- To run DirectX 12 applications with the debug layer enabled, you need to install the Graphics Tools optional feature. The tools version must match the OS version you are using (not to be confused with the SDK version used for building Falcor). There are 2 ways to install it:
- Click the Windows button and type
Optional Features
, in the window that opens clickAdd a feature
and selectGraphics Tools
. - Download an offline pacakge from here. Choose a ZIP file that matches the OS version you are using. The ZIP includes a document which explains how to install the graphics tools.
- Click the Windows button and type
DirectX Raytracing
Falcor 3.0 adds support for DirectX Raytracing. It adds 2 new build configurations - ReleaseDXR
and DebugDXR
. These are the only configurations which will build the DXR abstraction layer.
The HelloDXR sample demonstrates how to use Falcor’s DXR abstraction layer.
- Requirements:
- Windows 10 RS4 (version 1803)
- Windows 10 Developer Mode enabled (Windows Settings -> Update & Security -> For developers -> Developer mode)
- You do not need to download the DXR SDK yourself, it is packaged with Falcor.
- A GPU which supports DirectX Raytracing, such as the NVIDIA Titan V or GeForce RTX (make sure you have the latest driver).
Currently, Falcor doesn’t support the DXR fallback layer. We will add support for it in the near future.
Please note that the DXR abstraction layer is considererd an experimental feature, just like DXR itself. The interfaces and features might change in future releases.
TensorFlow Support
Refer to the README located in the Samples\Core\LearningWithEmbeddedPython
for instructions on how to set up your environment to use TensorFlow and Python with Falcor.
Linux
Falcor is tested on Ubuntu 17.10, but may also work with other versions and distributions.
To build and run Falcor on Linux:
- Install the Vulkan SDK following the instructions HERE
- Install additional dependencies:
sudo apt-get install python libassimp-dev libglfw3-dev libgtk-3-dev libfreeimage-dev libavcodec-dev libavdevice-dev libavformat-dev libswscale-dev libavutil-dev
- Run the
Makefile
- To only build the library, run
make Debug
ormake Release
depending on the desired configuration - To build samples, run
make
using the target for the sample(s) you want to build. Config can be changed by settingSAMPLE_CONFIG
toDebug
orRelease
- To only build the library, run
Building Falcor
Open Falcor.sln
and it should build successfully in Visual Studio out of the box. If you wish to skip this step and add Falcor to your own Visual Studio solution directly,
follow the instructions below.
Creating a New Project
- If you haven't done so already, create a Visual Studio solution and project for your code. Falcor only supports 64-bit builds, so make sure you have a 64-bit build configuration
- Add Falcor.props to your project (Property Manager -> Right click your project -> Add existing property sheet)
- Add Falcor.vcxproj to your solution
- Add a reference to Falcor in your project (Solution Explorer -> Your Project -> Right Click
References
-> ClickAdd Reference...
-> Choose Falcor)
Sample Class
This is the bootstrapper class of the application. Your class should inherit from it and override its protected methods which serve as the callback functions. A good place to start looking for examples would be the ModelViewer sample.
Build Configurations
Falcor has the following build configurations for DirectX 12, Vulkan and DXR, respectively:
DebugD3D12
ReleaseD3D12
DebugVK
ReleaseVK
DebugDXR
ReleaseDXR
Debug builds enable file logging and message boxes by default, and there is a lot of runtime error checking. If debug layers for the selected API are installed, they will be loaded as well.
Release builds disable logging and most runtime error checks. Use this configuration to measure performance.
Setting Up Debug Layers
To use the DirectX 12 debug layer:
- Open the Start menu
- Type "Manage optional features" and press Enter
- Click "Add a feature"
- Install "Graphics Tools"
To use Vulkan debug layers:
- Install the Vulkan SDK
Falcor Configuration
FalcorConfig.h
contains some flags which control Falcor's behavior.
_LOG_ENABLED
- Enable/disable log messages. By default, it is set tofalse
for release build andtrue
for debug builds_PROFILING_ENABLED
- Enable/Disable the internal CPU/GPU profiler. By default, it is set totrue
Data Files
Data files include shader files, textures, and models. By default, Falcor looks for data files in the following locations:
- The working directory. In some cases this is not the same as the executable directory. For example, if you launch the application from Visual Studio, by default the working directory is the directory containing the project file
- The executable directory
- An optional environment variable named
FALCOR_MEDIA_FOLDERS
. It is a semicolon-separated list of folders - Any directory that was added to the data directories list by calling
addDataDirectory()
- A directory called "Data/" under any of the above directories
To search for a data file, call findFileInDataDirectories()
.
Shaders
Falcor uses the Slang shading language and compiler.
Users can write HLSL/Slang shader code in .hlsl
or .slang
files.
The framework handles cross-compilation to SPIR-V for you when targetting Vulkan; GLSL shaders are not supported.
Deployment
The best practice is to create a directory called "Data/" next to your project file and place all your data files there (shaders/models). If that directory exists, Falcor will copy it to the output directory, making the output directory self-contained (you can zip only the output directory and it should work). If not, you will have to copy the data files yourself.
Citation
If you use Falcor in a research project leading to a publication, please cite the project. The BibTex entry is
@Misc{Benty17,
author = {Nir Benty and Kai-Hwa Yao and Tim Foley and Conor Lavelle and Chris Wyman},
title = {The {Falcor} Rendering Framework},
year = {2017},
month = {07},
url = {https://github.com/NVIDIAGameWorks/Falcor},
note= {\url{https://github.com/NVIDIAGameWorks/Falcor}}
}