sheaf committed Jun 26, 2019 1 2 # Examples  o1lo01ol1o committed Dec 27, 2019 3 - [Examples](#examples)  sheaf committed Nov 27, 2020 4  - [Installation instructions](#installation)  o1lo01ol1o committed Dec 27, 2019 5 6  - [Windows](#windows) - [Linux](#linux)  sheaf committed Nov 27, 2020 7 8 9 10  - [MacOS (via MoltenVK and nix)](#darwin) - [Hot reloading](#hotreloading) - [Overview of examples](#overview) - [Kerr space-time](#kerr)  sheaf committed Jan 09, 2021 11  - [Path tracer](#raytracing)  sheaf committed Nov 27, 2020 12 13 14 15 16 17  - [Full graphics pipeline](#fullpipeline) - [FIR logo](#logo) - [Hopf fibration](#hopf) - [Texture sampling](#texture) - [Ising model](#ising) - [Julia set](#julia)  sheaf committed Jun 21, 2021 18  - [Shader toy](#toy)  sheaf committed Nov 27, 2020 19 20  - [Offscreen rendering](#offscreen) - [Bézier curves](#bezier)  sheaf committed Jun 26, 2019 21 22 23 24  ## Installation instructions  sheaf committed Jun 26, 2019 25   sheaf committed Dec 02, 2019 26 Start off by making sure the [library itself installs properly](../getting_started.md#installation).  sheaf committed Jun 26, 2019 27 28  To build the examples, the installation of two external dependencies is necessary: SDL2 (version 2.0.6 or greater), and the Vulkan SDK.  sheaf committed Jul 20, 2019 29 Instructions for building these packages is provided below, for [Windows](#win) and [Linux](#linux).  sheaf committed Jun 26, 2019 30 31  Once these dependencies are installed, you should be able to run:  sheaf committed Jun 26, 2019 32 33 34   > cd fir-examples  sheaf committed Dec 06, 2019 35 > cabal build Example  sheaf committed Jun 26, 2019 36 37 38 39 40 > cabal run Example  where *Example* is any one of the [examples](#overview).  sheaf committed Nov 27, 2020 41   sheaf committed Jun 26, 2019 42 43 44 ### Windows To keep track of external dependencies, we first need to install pkg-config.  sheaf committed Jul 20, 2019 45 If this is not already present on your system, download [pkg-config-lite](https://sourceforge.net/projects/pkgconfiglite/)  sheaf committed Jun 26, 2019 46 47 48 49 50 51 and add the installed location to your PATH, making pkg-config available in the command line. To install SDL2, download the [SDL2 MinGW development library](https://www.libsdl.org/download-2.0.php) (version 2.0.6 or greater). After extracting, we need to: * Add the bin folder to PATH (on 64 bit systems, the folder SDL2-2.x.y\x86_64-w64-mingw32\bin). * Add the lib\pkg-config folder to PKG_CONFIG_PATH to make SDL2 visible to pkg-config.  sheaf committed Jul 20, 2019 52  If PKG_CONFIG_PATH does not exist (echo %PKG_CONFIG_PATH% returns nothing), set it with setx PKG_CONFIG_PATH path\to\sdl2\lib\pkg-config\.  sheaf committed Jun 26, 2019 53 54 You can check that SDL2 is registered with pkg-config using pkg-config --list-all.  sheaf committed Jan 20, 2022 55 The Windows Vulkan SDK installer can be downloaded from the [LunarG website](https://vulkan.lunarg.com/sdk/home). The relevant bin folder (by default VulkanSDK\[vulkan-sdk-version]\Bin) is automatically added to PATH, and the environment variables VULKAN_SDK and VK_SDK_PATH should also have been initialised (pointing to VulkanSDK\[vulkan-sdk-version] by default). You might need to point to the directory in your cabal.project.local file, e.g.  sheaf committed Jun 26, 2019 56   sheaf committed Jan 20, 2022 57 58 59 60 61  package vulkan extra-lib-dirs: C:/VulkanSDK/1.2.198.1/Lib extra-include-dirs: C:/VulkanSDK/1.2.198.1/Include/   sheaf committed Jun 26, 2019 62 63 64 65 66 67 68 69  ### Linux It should be possible to install the SDL2 development kit from your distributions's package repository. * Ubuntu/Debian: sudo apt-get install libsdl2-dev * ArchLinux: pacman -S sdl2  sheaf committed Sep 09, 2019 70 Please ensure that the installed version of SDL2 is at least 2.0.6, as it is this version that adds Vulkan support.  sheaf committed Jun 26, 2019 71 72 73 This might require adding newer package repository lists. For Vulkan, you'll need the Vulkan SDK. What to install will usually depend on your GPU (AMD/NVIDIA/Intel).  sheaf committed Aug 13, 2019 74 The [LunarG website](https://vulkan.lunarg.com/doc/sdk/latest/linux/getting_started.html) provides installation instructions  sheaf committed Jun 26, 2019 75 76 for the Vulkan SDK on Linux.  o1lo01ol1o committed Dec 27, 2019 77 78  ### MacOS (via MoltenVK and nix)  sheaf committed Jan 09, 2021 79 80 81  **TODO:** these instructions are outdated; see issue [#80](https://gitlab.com/sheaf/fir/-/issues/80).  o1lo01ol1o committed Dec 27, 2019 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 default.nix contains overlays for vulkan-api and fir as well as a derivation for fir-examples. Because MoltenVK only supports a subset of the Vulkan spec (and only SPIR-V version 1.0), not all the examples run. JuliaSet, Texture, and Logo run successfuly on MacOS Mojave. Build the project: shell cd fir-examples nix-build  On darwin, nix will prompt you to download the correct LunarG SDK and add it to the store; after which the above will compile the needed dependencies and output fir-examples to result in the fir-examples directory. However, you'll need to be in the correct nix shell for the binaries to have access to the needed paths and frameworks. (Unfortunately due to the project structure this will build fir twice; MRs welcome. ) Enter the shell and run a binary: shell nix-shell -A fir-examples result/bin/JuliaSet   sheaf committed Jun 26, 2019 100   sheaf committed Dec 05, 2019 101 102 103 104 105  ## Hot reloading The examples support shader hot reloading, detecting when any of the used SPIR-V files are modified on disk.  sheaf committed Dec 05, 2019 106 For interactive coding, ghcid can be useful, e.g.:  sheaf committed Dec 05, 2019 107 108 109 110 111 112  ghcid -c "cabal repl ShaderFile" -WT "compileAction" This command watches the Haskell module ShaderFile, reloading it on changes, and runs the action compileAction each time the module successfully loads.  sheaf committed Dec 05, 2019 113 114 To illustrate, consider interactively editing the fragment shader used in the Julia set example, as follows:  sheaf committed Dec 05, 2019 115 116 117 118 119  * Start the executable with cabal run JuliaSet. The executable will watch for shaders changing on disk. Note: you might want to run the executable in the background: - cabal run JuliaSet & on Linux/macOS. - start /b cabal run JuliaSet on Windows.  sheaf committed Dec 05, 2019 120  * Enable live recompilation of the fragment shader:  sheaf committed Dec 05, 2019 121  ghcid -c "cabal repl FIR.Examples.JuliaSet.Shaders" -WT "compileFragmentShader"  sheaf committed Dec 05, 2019 122  This will save changes to the fragment shader to disk.  sheaf committed Dec 05, 2019 123 124 125 126  Remarks: * The -WT flag to ghcid is used to specify an action to run upon loading,  sheaf committed Dec 05, 2019 127  even when warnings were emitted.  sheaf committed Dec 05, 2019 128 129 130 131 132  * The shader files used by the examples are, by default, located in the directory fir/fir-examples/shaders. These are the files that will be watched by the application to check when to reload.  sheaf committed Jun 26, 2019 133 134 135  ## Overview of examples  sheaf committed Dec 05, 2019 136 137 138 139 140 141 142  ### Kerr space-time

 sheaf committed Dec 06, 2019 143 144 145 Render of a rotating black hole with a tilted accretion disk. Consists of a compute shader using a Runge–Kutta numerical integrator to solve the geodesic equations of Kerr space-time backwards in time (relativistic ray-tracing).  sheaf committed Dec 05, 2019 146   sheaf committed Jan 09, 2021 147 148 149 150 151 152 153 154 155 156 157 158 159  ### Path tracer

Spectral path tracer that uses Vulkan ray-tracing shaders. Press L to lock the camera (which lets the renderer converge). Uses uni-directional path tracing with explicit light sampling (weighted with multiple importance sampling). Several scenes are available. Running the example in GHCi, you will be asked to pick a scene. If running the executable directly, the scene name can be passed as a command line argument.  sheaf committed Jun 26, 2019 160 161  ### Full graphics pipeline  sheaf committed Jun 26, 2019 162 
 sheaf committed Sep 18, 2019 163 ![FullPipeline](../img/full_pipeline.png)
 sheaf committed Dec 05, 2019 164 [Application](examples/apps/FIR/Examples/FullPipeline/Application.hs) • [Shaders](examples/shaders/FIR/Examples/FullPipeline/Shaders.hs)  sheaf committed Jun 26, 2019 165 
 sheaf committed Jun 26, 2019 166 167 168  A graphics pipeline containing all shader stages.  sheaf committed Jul 20, 2019 169 170  ### FIR logo  sheaf committed Jun 26, 2019 171 
 sheaf committed Sep 18, 2019 172 ![Logo](../img/logo.png)
 sheaf committed Dec 05, 2019 173 [Application](examples/apps/FIR/Examples/Logo/Application.hs) • [Shaders](examples/shaders/FIR/Examples/Logo/Shaders.hs)  sheaf committed Jun 26, 2019 174 
 sheaf committed Jun 26, 2019 175 176 177  Rendering the FIR logo using simple ray tracing in a compute shader.  sheaf committed Sep 09, 2019 178 179 180  ### Hopf fibration
 sheaf committed Sep 18, 2019 181 ![Hopf](../img/hopf.png)
 sheaf committed Dec 05, 2019 182 [Application](examples/apps/FIR/Examples/Hopf/Application.hs) • [Shaders](examples/shaders/FIR/Examples/Hopf/Shaders.hs)  sheaf committed Sep 09, 2019 183 184 
 sheaf committed Sep 18, 2019 185 186 Illustration of fibers in the Hopf fibration; each circle is thickened out to a torus using a tessellation shader.  sheaf committed Sep 10, 2019 187 Rendered using multisampling with Vulkan resolve attachments.  sheaf committed Sep 18, 2019 188 Also illustrates how to specify location and component layout information in shaders.  sheaf committed Sep 09, 2019 189   sheaf committed Jun 26, 2019 190 191  ### Texture sampling  sheaf committed Jun 26, 2019 192 
 sheaf committed Sep 18, 2019 193 ![Texture](../img/texture.png)
 sheaf committed Dec 05, 2019 194 [Application](examples/apps/FIR/Examples/Texture/Application.hs) • [Shaders](examples/shaders/FIR/Examples/Texture/Shaders.hs)  sheaf committed Jun 26, 2019 195 
 sheaf committed Jun 26, 2019 196 197 198  Demonstrates how to sample a texture.  sheaf committed Nov 27, 2020 199 200 201 202 203 204 205 206 207 208 209  ### Ising model
![Ising](../img/ising.png)
Simulation of a ferromagnetic Ising model. Mouse x-coordinate affects temperature, y-coordinate an externally applied magnetic field. Demonstrates usage of shared local memory in a compute shader, synchronised using a control barrier.  sheaf committed Jun 26, 2019 210 211 212  ### Julia set
 sheaf committed Sep 18, 2019 213 ![JuliaSet](../img/julia.png)
 sheaf committed Dec 05, 2019 214 [Application](examples/apps/FIR/Examples/JuliaSet/Application.hs) • [Shaders](examples/shaders/FIR/Examples/JuliaSet/Shaders.hs)  sheaf committed Jun 26, 2019 215 216 217 218 
Interactive Julia set rendering, computed within a fragment shader.  sheaf committed Jun 21, 2021 219 220 221 222 223 224  ### Shader toy
 Tristan de Cacqueray committed Jul 10, 2021 225 Shader toy like example using Dear ImGui to provide interactive sliders whose values are passed on to the shader.  sheaf committed Jun 21, 2021 226   Tristan de Cacqueray committed Jul 10, 2021 227 228 Use the mouse wheel and left button to adjust the position. In the map mode, use the right button to adjust the seed (represented by a pink square).  sheaf committed Jun 21, 2021 229   sheaf committed Jun 26, 2019 230 231  ### Offscreen rendering  sheaf committed Jun 26, 2019 232 
 sheaf committed Sep 18, 2019 233 ![Offscreen](../img/offscreen.png)
 sheaf committed Dec 05, 2019 234 [Application](examples/apps/FIR/Examples/Offscreen/Application.hs) • [Shaders](examples/shaders/FIR/Examples/Offscreen/Shaders.hs)  sheaf committed Jun 26, 2019 235 
 sheaf committed Jun 26, 2019 236 237 238 239 240  Offscreen rendering of a single frame. ### Bézier curves  sheaf committed Jun 26, 2019 241 
 sheaf committed Sep 18, 2019 242 ![Bezier](../img/bezier.png)
 sheaf committed Dec 05, 2019 243 [Application](examples/apps/FIR/Examples/Bezier/Application.hs) • [Shaders](examples/shaders/FIR/Examples/Bezier/Shaders.hs)  sheaf committed Jun 26, 2019 244 
 sheaf committed Jun 26, 2019 245 246 247  Work in progress: rendering Bézier curves using tessellation and geometry shaders. Currently computes signed distance to the outline. Still requires a second pass in a compute shader to fill in the outline.