readme.md 10.2 KB
Newer Older
1
2
# Examples

3
- [Examples](#examples)
sheaf's avatar
sheaf committed
4
  - [Installation instructions](#installation)
5
6
    - [Windows](#windows)
    - [Linux](#linux)
sheaf's avatar
sheaf committed
7
8
9
10
    - [MacOS (via MoltenVK and nix)](#darwin)
  - [Hot reloading](#hotreloading)
  - [Overview of examples](#overview)
    - [Kerr space-time](#kerr)
sheaf's avatar
sheaf committed
11
    - [Path tracer](#raytracing)
sheaf's avatar
sheaf committed
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's avatar
sheaf committed
18
    - [Shader toy](#toy)
sheaf's avatar
sheaf committed
19
20
    - [Offscreen rendering](#offscreen)
    - [Bézier curves](#bezier)
21
22
23
24


<a name="installation"></a>
## Installation instructions
25

26
Start off by making sure the [library itself installs properly](../getting_started.md#installation).
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.
29
Instructions for building these packages is provided below, for [Windows](#win) and [Linux](#linux).
30
31

Once these dependencies are installed, you should be able to run:
32
33
34

```
> cd fir-examples
sheaf's avatar
sheaf committed
35
> cabal build Example
36
37
38
39
40
> cabal run Example
```

where *Example* is any one of the [examples](#overview).

sheaf's avatar
sheaf committed
41
<a name="windows"></a>
42
43
44
### Windows

To keep track of external dependencies, we first need to install `pkg-config`.
45
If this is not already present on your system, download [pkg-config-lite](https://sourceforge.net/projects/pkgconfiglite/)
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.
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\`.
53
54
You can check that SDL2 is registered with pkg-config using `pkg-config --list-all`.

sheaf's avatar
sheaf committed
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.
56

sheaf's avatar
sheaf committed
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/
```
62
63
64
65
66
67
68
69

<a name="linux"></a>
### 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`

70
Please ensure that the installed version of SDL2 is at least 2.0.6, as it is this version that adds Vulkan support.
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's avatar
sheaf committed
74
The [LunarG website](https://vulkan.lunarg.com/doc/sdk/latest/linux/getting_started.html) provides installation instructions
75
76
for the Vulkan SDK on Linux.

77
78
<a name="darwin"></a>
### MacOS (via MoltenVK and nix)
sheaf's avatar
sheaf committed
79
80
81

**TODO:** these instructions are outdated; see issue [#80](https://gitlab.com/sheaf/fir/-/issues/80).    

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
```

100

101
102
103
104
105
<a name="hotreloading"></a>
## Hot reloading

The examples support shader hot reloading, detecting when any of the used SPIR-V files are modified on disk.    

sheaf's avatar
sheaf committed
106
For interactive coding, `ghcid` can be useful, e.g.:
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's avatar
sheaf committed
113
114
To illustrate, consider interactively editing the fragment shader used in the Julia set example, as follows:   

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's avatar
sheaf committed
120
  * Enable live recompilation of the fragment shader:    
121
    `ghcid -c "cabal repl FIR.Examples.JuliaSet.Shaders" -WT "compileFragmentShader"`    
sheaf's avatar
sheaf committed
122
    This will save changes to the fragment shader to disk.   
123
124
125
126

Remarks:

  * The `-WT` flag to `ghcid` is used to specify an action to run upon loading,
sheaf's avatar
sheaf committed
127
    even when warnings were emitted.
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.


133
134
135
<a name="overview"></a>
## Overview of examples

sheaf's avatar
sheaf committed
136
137
138
139
140
141
142
<a name="kerr"></a>
### Kerr space-time
<div align="center">
<a href="../img/kerr_large.png"><img src="../img/kerr_small.png" alt="Kerr"></a> <br>
[Application](examples/apps/FIR/Examples/Kerr/Application.hs)   •   [Shaders](examples/shaders/FIR/Examples/Kerr/Shaders.hs)
</div>

sheaf's avatar
sheaf committed
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's avatar
sheaf committed
146

sheaf's avatar
sheaf committed
147
148
149
150
151
152
153
154
155
156
157
158
159
<a name="raytracing"></a>
### Path tracer
<div align="center">
<a href="../img/raytracing_large.png"><img src="../img/raytracing_small.png" alt="RayTracing"></a> <br>
[Application](examples/apps/FIR/Examples/RayTracing/Application.hs)   •   [Shaders](examples/shaders/FIR/Examples/RayTracing/Shaders.hs)
</div>

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.

160
161
<a name="fullpipeline"></a>
### Full graphics pipeline
sheaf's avatar
sheaf committed
162
<div align="center">
163
![FullPipeline](../img/full_pipeline.png) <br>
sheaf's avatar
sheaf committed
164
[Application](examples/apps/FIR/Examples/FullPipeline/Application.hs)[Shaders](examples/shaders/FIR/Examples/FullPipeline/Shaders.hs)
sheaf's avatar
sheaf committed
165
</div>
166
167
168

A graphics pipeline containing all shader stages.

169
170
<a name="logo"></a>
### FIR logo
sheaf's avatar
sheaf committed
171
<div align="center">
172
![Logo](../img/logo.png) <br>
sheaf's avatar
sheaf committed
173
[Application](examples/apps/FIR/Examples/Logo/Application.hs)[Shaders](examples/shaders/FIR/Examples/Logo/Shaders.hs)
sheaf's avatar
sheaf committed
174
</div>
175
176
177

Rendering the FIR logo using simple ray tracing in a compute shader.

178
179
180
<a name="hopf"></a>
### Hopf fibration
<div align="center">
181
![Hopf](../img/hopf.png) <br>
sheaf's avatar
sheaf committed
182
[Application](examples/apps/FIR/Examples/Hopf/Application.hs)[Shaders](examples/shaders/FIR/Examples/Hopf/Shaders.hs)
183
184
</div>

185
186
Illustration of fibers in the Hopf fibration; each circle is thickened out to a torus using a tessellation shader.

187
Rendered using multisampling with Vulkan resolve attachments.
188
Also illustrates how to specify location and component layout information in shaders.
189

190
191
<a name="texture"></a>
### Texture sampling
sheaf's avatar
sheaf committed
192
<div align="center">
193
![Texture](../img/texture.png) <br>
sheaf's avatar
sheaf committed
194
[Application](examples/apps/FIR/Examples/Texture/Application.hs)[Shaders](examples/shaders/FIR/Examples/Texture/Shaders.hs)
sheaf's avatar
sheaf committed
195
</div>
196
197
198

Demonstrates how to sample a texture.

sheaf's avatar
sheaf committed
199
200
201
202
203
204
205
206
207
208
209
<a name="ising"></a>
### Ising model
<div align="center">
![Ising](../img/ising.png) <br>
[Application](examples/apps/FIR/Examples/Ising/Application.hs)[Shaders](examples/shaders/FIR/Examples/Ising/Shaders.hs)
</div>

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's avatar
sheaf committed
210
211
212
<a name="julia"></a>
### Julia set
<div align="center">
213
![JuliaSet](../img/julia.png) <br>
sheaf's avatar
sheaf committed
214
[Application](examples/apps/FIR/Examples/JuliaSet/Application.hs)[Shaders](examples/shaders/FIR/Examples/JuliaSet/Shaders.hs)
sheaf's avatar
sheaf committed
215
216
217
218
</div>

Interactive Julia set rendering, computed within a fragment shader.

sheaf's avatar
sheaf committed
219
220
221
222
223
224
<a name="toy"></a>
### Shader toy
<div align="center">
[Application](examples/apps/FIR/Examples/Toy/Application.hs)[Shaders](examples/shaders/FIR/Examples/Toy/Shaders.hs)
</div>

225
Shader toy like example using Dear ImGui to provide interactive sliders whose values are passed on to the shader.
sheaf's avatar
sheaf committed
226

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's avatar
sheaf committed
229

230
231
<a name="offscreen"></a>
### Offscreen rendering
sheaf's avatar
sheaf committed
232
<div align="center">
233
![Offscreen](../img/offscreen.png) <br>
sheaf's avatar
sheaf committed
234
[Application](examples/apps/FIR/Examples/Offscreen/Application.hs)[Shaders](examples/shaders/FIR/Examples/Offscreen/Shaders.hs)
sheaf's avatar
sheaf committed
235
</div>
236
237
238
239
240

Offscreen rendering of a single frame.

<a name="bezier"></a>
### Bézier curves
sheaf's avatar
sheaf committed
241
<div align="center">
242
![Bezier](../img/bezier.png) <br>
sheaf's avatar
sheaf committed
243
[Application](examples/apps/FIR/Examples/Bezier/Application.hs)[Shaders](examples/shaders/FIR/Examples/Bezier/Shaders.hs)
sheaf's avatar
sheaf committed
244
</div>
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.