Falcor 4.2 (#253)

Author: kyaoNV

.gitignore

@@ -12,6 +12,7 @@ Bin/*
 *.pyc
 *.o
 *slang-dump-*
+*.mp4
 Source/Externals/.packman/*
 Media
 Tools/.packman

Build/deploycommon.bat

@@ -18,14 +18,12 @@ IF not exist %OutDir%\Data\ mkdir %OutDir%\Data >nul
 call %~dp0\deployproject.bat %FalcorDir% %OutDir%
 
 rem Copy externals
-robocopy %ExtDir%\Python\ %OutDir% Python37*.dll /r:0 >nul
+robocopy %ExtDir%\Python\ %OutDir% Python36*.dll /r:0 >nul
 robocopy %ExtDir%\Python %OutDir%\Python /E /r:0 >nul
 robocopy %ExtDir%\AntTweakBar\lib %OutDir% AntTweakBar64.dll /r:0 >nul
 robocopy %ExtDir%\FreeImage %OutDir%  freeimage.dll /r:0 >nul
 robocopy %ExtDir%\assimp\bin\%2 %OutDir%  *.dll /r:0 >nul
 robocopy %ExtDir%\FFMpeg\bin\%2 %OutDir%  *.dll /r:0 >nul
-rem robocopy %ExtDir%\dxcompiler\%2 %OutDir%  dxcompiler.dll /r:0 >nul
-robocopy %ExtDir%\openvr\bin\win64 %OutDir%  openvr_api.dll /r:0 >nul
 robocopy %ExtDir%\Slang\bin\windows-x64\release %OutDir%  *.dll /r:0 >nul
 robocopy %ExtDir%\GLFW\lib %OutDir%  *.dll /r:0 >nul
 robocopy %ExtDir%\WinPixEventRuntime\bin\x64 %OutDir% WinPixEventRuntime.dll /r:0 >nul

Docs/Getting-Started.md

@@ -24,7 +24,7 @@ The `RenderPasses` folder contains a number of components ("Render Passes") that
 There are two main workflows when using Falcor:
 
 ### Render Graphs
-The recommended workflow when prototyping or implementing rendering techniques is to create render passes, render graphs, then render them with Mogwai. The [tutorials](../Tutorials/index.md) focus on this workflow.
+The recommended workflow when prototyping or implementing rendering techniques is to create render passes, render graphs, then render them with Mogwai. The [tutorials](./Tutorials/index.md) focus on this workflow.
 
 #### To run a sample Render Graph:
 1. Build the Falcor Solution
@@ -65,9 +65,9 @@ When running from Visual Studio:
     - Any directory that was added to the data directories list by calling `addDataDirectory()`.
 - Falcor looks for Shader files relative to your project folder.
 
-Upon building, a project's `Data` folders and shader files will be automatically deployed to the `Data` and `Shader` folders in the executable directory while preserving folder hierarchy. When running an application from its executable, Falcor will search in these folders instead. This allows the build output folder to be self-contained for easy sharing.
+Upon building, a project's `Data` folder and shader files will be automatically deployed to the `Data` and `Shaders` folders in the executable directory while preserving folder hierarchy. When running an application from its executable, Falcor will search in these folders instead. This allows the build output folder to be self-contained for easy sharing.
 
-The best practice is to create a directory called `Data/` next to your **project** file and place all your data files there. Your shader files should also have a `.slang`, `.slangh`, `.hlsl`, or `.hlsli` extension. Files with these extensions will be marked with the `Shader Source` item type in Visual Studio, and only these files will be deployed. Headers with a `.h` should be used for host-only files. Headers that will be shared between host and shader files should use the `.slangh` extension.
+The best practice is to create a directory called `Data` next to your **project** file and place all your data files there. Your shader files should also have a `.slang`, `.slangh`, `.hlsl`, or `.hlsli` extension. Files with these extensions will be marked with the `Shader Source` item type in Visual Studio, and only these files will be deployed. Headers with a `.h` should be used for host-only files. Headers that will be shared between host and shader files should use the `.slang` or `.slangh` extension.
 
 To search for a data or shader file, call `findFileInDataDirectories()` or `findFileInShaderDirectories()` respectively.
 

Docs/Tutorials/01-Mogwai-Usage.md

@@ -2,6 +2,8 @@
 
 --------
 
+# Mogwai Usage
+
 ## Building Mogwai
 
 In Visual Studio:
@@ -13,16 +15,26 @@ In Visual Studio:
 ## Running Mogwai
 
 Run Mogwai from within Visual Studio (by pressing Ctrl+F5), or from the command prompt using:
+
 ```
-Mogwai .exe [options]
+  Mogwai {OPTIONS}
+
+    Mogwai render application.
 
-Options:
-    -script <file>      Load this script at startup (`.py` files)
-    -silent             Launch Mogwai minimized with input and message boxes disabled.
-                        Use with -script to run a renderer in the background.
-    -logfile <path>     Specify where to save the log file. By default, this is next to the executable.
+  OPTIONS:
+
+      -h, --help                        Display this help menu.
+      -s[path], --script=[path]         Python script file to run.
+      -l[path], --logfile=[path]        File to write log into.
+      --silent                          Starts Mogwai with a minimized window
+                                        and disables mouse/keyboard input as
+                                        well as error message dialogs.
+      --width=[pixels]                  Initial window width.
+      --height=[pixels]                 Initial window height.
 ```
 
+Using `--silent` together with `--script` allows to run Mogwai for rendering in the background.
+
 If you start it without specifying any options, Mogwai starts with a blank screen.
 
 ## Loading Scripts and Assets
@@ -40,7 +52,7 @@ Mogwai loads the scene specified by the script, if any. If the script did not lo
 A sample Arcade scene is included, which can be found at `Media/Arcade/Arcade.fscene`.
 
 ## Mogwai UI
-Once you have a script (and optionally, a scene) loaded, you should see something similar to 
+Once you have a script (and optionally, a scene) loaded, you should see something similar to
 
 ![MogwaiUI](./images/MogwaiUI.png)
 
@@ -79,4 +91,4 @@ The following is a list of available controls:
 `Shift` - Speeds up camera movement when held down\
 `Ctrl` - Slows down camera movement when held down\
 `Z` - Magnify the currently hovered area\
-`Mouse Wheel` - Change zoom level when magnifying a pixel
+`Mouse Wheel` - Change zoom level when magnifying a pixel

Docs/Tutorials/02-Implementing-a-Render-Pass.md

@@ -2,6 +2,8 @@
 
 --------
 
+# Implementing a Render Pass
+
 Now that you've successfully loaded a render graph into Mogwai through a script, let's create one. A render graph is formed from a number of component render passes. This tutorial will focus on creating render passes through an example pass that blits a source texture into a destination texture; graph creation and editing will be the subject of the next.
 
 ## Creating a Render Pass Project
@@ -89,4 +91,4 @@ extern "C" __declspec(dllexport) void getPasses(Falcor::RenderPassLibrary& lib)
 }
 ```
 
-We will ignore further details regarding render passes and their implementation for the purposes of this tutorial. Additional information can be found [here](../Usage/Render-Passes.md).
+We will ignore further details regarding render passes and their implementation for the purposes of this tutorial. Additional information can be found [here](../Usage/Render-Passes.md).

Docs/Tutorials/03-Creating-and-Editing-Render-Graphs.md

@@ -2,6 +2,8 @@
 
 --------
 
+# Creating and Editing Render Graphs
+
 Now that we've written a simple render pass, we turn our attention to creating and editing render graphs. There are two methods of doing this: using the Render Graph Editor and using Python scripting. We will cover both in this tutorial though using the editor is recommended.
 
 ## Render Graph Editor
@@ -71,9 +73,9 @@ The graph containing `ExampleBlitPass` we created using the editor above would l
 ```python
 def render_graph_ExampleBlitPass():
     g = RenderGraph("ExampleBlitPass Example")
-    ExampleBlitPass = RenderPass("ExampleBlitPass")
+    ExampleBlitPass = createPass("ExampleBlitPass")
     g.addPass(ExampleBlitPass, "MyBlitPass")
-    ImageLoader = RenderPass("ImageLoader", {'filename': 'Cubemaps\\Sorsele3\\posz.jpg',
+    ImageLoader = createPass("ImageLoader", {'filename': 'Cubemaps\\Sorsele3\\posz.jpg',
                              'mips': False, 'srgb': True, 'arrayIndex': 0, 'mipLevel': 0})
     g.addPass(ImageLoader, "ImageLoader")
     g.addEdge("ImageLoader.dst", "MyBlitPass.input")

Docs/Tutorials/04-Writing-Shaders.md

@@ -2,6 +2,8 @@
 
 --------
 
+# Writing Shaders
+
 Now that we've written a basic render pass and render graph, let's look at writing more complex passes that use shaders. Falcor uses the Slang shading language and compiler, and files should use one of the following extensions: `.slang`, `.slangh`, `.hlsl`, `.hlsli`. For more information on best practices for working with shaders in Falcor, please refer to the *Using Shaders and Data Files* section of the [Getting Started](../Getting-Started.md) page.
 
 For this tutorial, we'll create a pass that renders a scene as a wireframe of a particular color.
@@ -60,15 +62,17 @@ WireframePass::WireframePass()
 ```
 
 ### `setScene()`
-Our first render pass had no need for a `Scene` object; however, this pass does and will need this function to set `mpScene`. We will also need to add all scene macro definitions to `mpProgram` and create our `GraphicsVars` so that we can bind shader values later in `execute()`. These are done like so:
+Our first render pass had no need for a `Scene` object; however, this pass does and will need this function to set `mpScene`. We first need to set `mpScene` to the scene that's passed in then add all scene defines to `mpProgram`. We then create our `GraphicsVars` so that we can bind shader variables later in `execute()`. These are done like so:
 ```c++
 void WireframePass::setScene(RenderContext* pRenderContext, const Scene::SharedPtr& pScene)
 {
     mpScene = pScene;
-    mpProgram->addDefines(mpScene->getSceneDefines());
+    if (mpScene) mpProgram->addDefines(mpScene->getSceneDefines());
     mpVars = GraphicsVars::create(mpProgram->getReflector());
 }
 ```
+#### Why scene defines?
+We need some way to tell Slang/HLSL exactly how many resources the scene needs to bind and need to ensure that this scene data is portable between shaders. However, there's currently no way to do this automatically, so we use scene defines to communicate this information.
 
 ### `execute()`
 This function will need to perform several operations: create and bind an FBO for our output to the `GraphicsState`, set the render state, and render our scene by calling `Scene::render()`.
@@ -94,7 +98,7 @@ With our scene, shader, and both the `GraphicsState` and `RasterizerState` set u
 ```c++
 mpScene->render(pRenderContext, mpGraphicsState.get(), mpGraphicsVars.get(), renderFlags);
 ```
-Your `execute()` function should now look like this:
+Your `execute()` function should now look like this, with a check for `mpScene` so we avoid accessing the scene when it isn't set:
 ```c++
 void WireframePass::execute(RenderContext* pRenderContext, const RenderData& renderData)
 {
@@ -103,14 +107,17 @@ void WireframePass::execute(RenderContext* pRenderContext, const RenderData& ren
     pRenderContext->clearFbo(pTargetFbo.get(), clearColor, 1.0f, 0, FboAttachmentType::All);
     mpGraphicsState->setFbo(pTargetFbo);
 
-    // Set render state
-    Scene::RenderFlags renderFlags = Scene::RenderFlags::UserRasterizerState;
-    mpVars["PerFrameCB"]["gColor"] = float4(0, 1, 0, 1);
+    if (mpScene)
+    {
+        // Set render state
+        Scene::RenderFlags renderFlags = Scene::RenderFlags::UserRasterizerState;
+        mpVars["PerFrameCB"]["gColor"] = float4(0, 1, 0, 1);
 
-    mpScene->render(pRenderContext, mpGraphicsState.get(), mpVars.get(), renderFlags);
+        mpScene->render(pRenderContext, mpGraphicsState.get(), mpVars.get(), renderFlags);
+    }
 }
 ```
 
-Using the Render Graph Editor, create a graph solely containing this pass then launch it in Mogwai. Don't worry about needing to load a scene; Mogwai will load the Arcade scene by default. You should see something similar to this:
+Using the Render Graph Editor, create a graph solely containing this pass then launch it in Mogwai. You should see a black screen as there is no scene currently loaded. Load a scene by going to `File -> Load Scene`, and you should now see the wireframe for the scene you selected. We used Arcade.fscene (located in the `Media` folder), which looks like this:
 
 ![WireframePass](./images/WireframePass.png)

Docs/Tutorials/images/RenderGraphEditor.png

@@ -10,5 +10,5 @@ The following environment variables are used in Falcor:
 |-----|-----|
 | `FALCOR_DEVMODE` | Set to `1` to enable development mode. In development mode, shader and data files are picked up from the `Source` folder instead of the binary output directory allowing for shader hot reloading (`F5`). Note that this environment variable is set by default when launching any of the Falcor projects from Visual Studio. |
 | `FALCOR_MEDIA_FOLDERS` | Specifies a semi-colon (`;`) separated list of absolute path names containing Falcor scenes. Falcor will search in these paths when loading a scene from a relative path name. |
-| `FALCOR_GPU_VENDOR_ID` | Specify which GPU vendor to use for rendering. This is useful when having multiple GPUs in a system (e.g. laptop with both integrated and discrete GPUs). Use `0x10DE` to select the NVIDIA GPU. |
-| `FALCOR_GPU_DEVICE_ID` | Specify which GPU to use for rendering. This is useful when having multiple GPUs that can be used in parallel by multiple Falcor instances. |
+| `FALCOR_GPU_VENDOR_ID` | Specify which GPU vendor to use for rendering. This is useful when having multiple GPUs in a system (e.g. laptop with both integrated and discrete GPUs). Falcor tries to select an NVIDIA GPU by default. |
+| `FALCOR_GPU_DEVICE_ID` | Of the GPUs matching the vendor ID specified by `FALCOR_GPU_VENDOR_ID` (or NVIDIA GPUs if unspecified), selects which GPU index to choose. This is useful when having multiple GPUs that can be used in parallel by multiple Falcor instances. By default, the first GPU (ID 0) is used. |

Docs/Usage/Environment-Variables.md

@@ -13,6 +13,7 @@
     - From the top menu bar, click `Load Script`, then navigate to `PathTracer.py`.
     - Press `Ctrl + O`, then navigate to `PathTracer.py`.
     - Drag and drop  `PathTracer.py` into the application window.
+    - Load at startup using the Mogwai `--script` command line option.
 5. Load a model or scene using one of the following methods. A sample scene is included, located at `Media/Arcade/Arcade.fscene`. Falcor can also load any format supported by Assimp.
     - From the top menu bar, click `Load Scene`, then select a file.
     - Press `Ctrl + Shift + O` then select a file.
@@ -22,7 +23,7 @@
 
 ![PathTracer-overview](./images/PathTracer-Overview.png)
 
-The `MegakernelPathTracer` render pass implements an unbiased path tracer in DXR. Paths are created in a raygen shader and hit/miss points are reported back from the respective shader stages. The raygen shader loops over path segments up to the maximum configured path length.
+The `MegakernelPathTracer` render pass implements an unbiased path tracer in DXR 1.0. Paths are created in a raygen shader and hit/miss points are reported back from the respective shader stages. The raygen shader loops over path segments up to the maximum configured path length.
 
 For each pixel on screen, `samplesPerPixel` paths are traced.
 At each path vertex (black dots), a configurable number `lightSamplesPerVertex` of shadow rays (dashed lines) is traced to sampled light sources. 
@@ -43,7 +44,7 @@ The V-buffer input is the default. It is configured using a parameter `useVBuffe
 
 When configured to use G-buffer input:
 
-- `bitangentW` is optional and only really needed for anisotropic materials (not supported yet) or if consistent tangent frames are needed. If not connected, a tangent frame is created based on the normal.
+- `tangentW` is optional and only really needed for anisotropic materials (not supported yet) or if consistent tangent frames are needed. If not connected, a tangent frame is created based on the normal.
 - `viewW` is optional but needed for correct shading with depth-of-field (otherwise the view direction points towards the camera origin, instead of the actual lens sample position).
 - `vbuffer` is optional but needed for correct shading with dielectrics (glass), as the renderer fetches the material ID from this input.
 - All other inputs are required.
@@ -52,7 +53,9 @@ When configured to use G-buffer input:
 
 - All outputs are optional.
 - Only outputs that are connected are computed.
-- The `rayCount` is a fullscreen 32-bit integer buffer storing number of rays traced per pixel (for debugging/visualization purposes).
+- The `rayCount` is a fullscreen 32-bit uint buffer storing number of rays traced per pixel for debugging/visualization purposes.
+- The `pathLength` is a fullscreen 32-bit uint buffer storing the path length per pixel for debugging/visualization purposes.
+- The `time` output is a fullscreen 32-bit uint buffer with GPU execution time per pixel (requires NVAPI).
 
 
 ### Example: Progressive path tracer in the render graph editor
@@ -70,48 +73,48 @@ Note: Multiple importance sampling is applied to the strategies marked MIS.
 
 ### BSDF sampling (MIS)
 
-- Disney isotropic diffuse
-- Trowbridge-Reitz GGX specular reflection/transmission
-- Diffuse/specular reflection or transmission is chosen stochastically
+- Disney isotropic diffuse.
+- Trowbridge-Reitz GGX specular reflection/transmission with VNDF sampling.
+- Diffuse/specular reflection or transmission is chosen stochastically.
 
 ### Environment map sampling (MIS)
 
-- A hierarchical importance map (mipmap) is computed at startup
-- Importance sampling by hierarchical warping of 2D uniform number
-- The PDF is proportional to incoming radiance, ignoring cosine term and visiblity
+- A hierarchical importance map (mipmap) is computed at startup.
+- Importance sampling by hierarchical warping of 2D uniform number.
+- The PDF is proportional to incoming radiance, ignoring cosine term and visiblity.
 
 ### Emissive meshes light sampling (MIS)
 
-- A light BVH is built over all emissive triangles
-- The per-triangle flux is pre-integrated and zero emissive triangles culled
-- Hierarchical importance sampling (see the book "Ray Tracing Gems", chapter 18)
-- There is an optional uniform light sampling mode
+- A light BVH is built over all emissive triangles.
+- The per-triangle flux is pre-integrated and zero emissive triangles culled.
+- Hierarchical importance sampling (see the book "Ray Tracing Gems", chapter 18).
+- There is an optional uniform light sampling mode.
 
 ### Analytic light sampling
 
-- Used for point, directional, and quad/disc/sphere area lights
-- Lights are specified in the FBX file (point, directional) or scene file (.fscene)
-- Each light source is selected with equal probability
+- Used for point, directional, distant, and quad/disc/sphere area lights.
+- Lights are specified in the FBX file (point, directional) or Python scene file (.pyscene).
+- Each light source is selected with equal probability.
 
 
 ## Validation/debugging tools
 
 ### MinimalPathTracer
 
-- Separate `MinimalPathTracer` pass
+- Separate `MinimalPathTracer` pass.
 - Naive/simple to be easy to verify, no importance sampling or MIS etc.
-- Produces ground truth images (but converges slowly)
-- Does not support dielectric materials (transmission)
+- Produces ground truth images (but converges slowly).
+- Does not support transmission or nested dielectric materials yet.
 
 ### ErrorMeasurePass
 
-- Takes a source image and a reference image
-- The reference can either be loaded from disk, or taken from a pass input
-- Makes it possible to run two separate configs in parallel, compare their output
+- Takes a source image and a reference image.
+- The reference can either be loaded from disk, or taken from a pass input.
+- Makes it possible to run two separate configs in parallel, compare their output.
 
 ### Shader print/assert
 
-- The `MegakernelPathTracer` pass supports debugging with `print()` in the shader
-- Click *Pixel Debug* in the UI to enable, click on a pixel to show it's output
-- It's useful to freeze the random seed (UI option) to avoid flickering values
-- There is also an `assert()` call that prints the coordinates of triggered asserts in the UI
+- The `MegakernelPathTracer` pass supports debugging with `print()` in the shader.
+- Click *Pixel Debug* in the UI to enable, click on a pixel to show it's output.
+- It's useful to freeze the random seed (UI option) to avoid flickering values.
+- There is also an `assert()` call that prints the coordinates of triggered asserts in the UI.