README.md 3.83 KB
Newer Older
Dajo Frey's avatar
Dajo Frey committed
1
# ProtoRender
Dajo Frey's avatar
...  
Dajo Frey committed
2

Dajo Frey's avatar
Dajo Frey committed
3
### Raytracing based Renderer for [Sphere-Packings]
Dajo Frey's avatar
...  
Dajo Frey committed
4

Dajo Frey's avatar
Dajo Frey committed
5
<div align="center">
Dajo Frey's avatar
Dajo Frey committed
6 7
<img src="data/images/screenshot1.png" width="752" height="475.5"/>
</div>
r1c3w1nd's avatar
...  
r1c3w1nd committed
8

Dajo Frey's avatar
Dajo Frey committed
9 10 11
- [x] Written in C
- [x] Uses Vulkan API
- [x] Features Raytracing/Pathtracing Shaders
Dajo Frey's avatar
Dajo Frey committed
12 13
- [x] Grid/BVH Acceleration Structures
- [x] Tiled Rendering  
Dajo Frey's avatar
Dajo Frey committed
14
- [x] Cross-Platform (Microsoft Windows, Linux)
Dajo Frey's avatar
Dajo Frey committed
15

Dajo Frey's avatar
Dajo Frey committed
16 17
[Gitlab Repository]

Dajo Frey's avatar
...  
Dajo Frey committed
18
## General Dependencies
Dajo Frey's avatar
Dajo Frey committed
19
* [Git] (to download submodules)
20
* [CMake], version minimum: 3.7.1
Dajo Frey's avatar
...  
Dajo Frey committed
21
* [Vulkan] Driver (will build without, but needed at runtime)
Dajo Frey's avatar
Dajo Frey committed
22
* Optional: [doxygen] (to generate documentation)
Dajo Frey's avatar
...  
Dajo Frey committed
23 24 25

## Build

Dajo Frey's avatar
Dajo Frey committed
26
Generally, it is required to run ```git submodule update --init --recursive deps``` 
Dajo Frey's avatar
Dajo Frey committed
27 28 29
atleast once to download all submodules. The platform-specific build-scripts will do this for you,
so I recommend using them.

Dajo Frey's avatar
...  
Dajo Frey committed
30
### Linux:
Dajo Frey's avatar
Dajo Frey committed
31

Dajo Frey's avatar
Dajo Frey committed
32
**Recommended Build Process:** Run build/build.bash
Dajo Frey's avatar
Dajo Frey committed
33

Dajo Frey's avatar
Dajo Frey committed
34 35 36
Additional Dependencies:
* [Make]
* [X11] environment (Wayland is not supported)
Dajo Frey's avatar
...  
Dajo Frey committed
37

Dajo Frey's avatar
Dajo Frey committed
38 39
Additional Info:
* compilation tested with GCC
Dajo Frey's avatar
Dajo Frey committed
40
* if you are using Arch Linux (or any other Linux distribution), I advise you to use the [vulkan-amdgpu-pro] driver
Dajo Frey's avatar
Dajo Frey committed
41

Dajo Frey's avatar
...  
Dajo Frey committed
42 43
### Windows:

Dajo Frey's avatar
Dajo Frey committed
44
**Recommended Build Process:** Run build/build.bat
Dajo Frey's avatar
...  
Dajo Frey committed
45

Dajo Frey's avatar
Dajo Frey committed
46 47 48
Additional Dependencies:
* [msbuild] (included in Visual Studio)

Dajo Frey's avatar
...  
Dajo Frey committed
49
Additional Info:
Dajo Frey's avatar
Dajo Frey committed
50
* compilation tested with MSVC
Dajo Frey's avatar
Dajo Frey committed
51
* make sure the binary path to [msbuild] is set in the Path environment variable, Reference:  
Dajo Frey's avatar
...  
Dajo Frey committed
52
https://stackoverflow.com/questions/6319274/how-do-i-run-msbuild-from-the-command-line-using-windows-sdk-7-1
53 54
* [msbuild] can be separately downloaded from https://visualstudio.microsoft.com/downloads/ under the 'Build Tools for Visual Studio' entry.
This avoids needing to install Visual Studio.
Dajo Frey's avatar
Dajo Frey committed
55
* generally when using Visual Studio, **at least** Visual Studio 15 2017 is required, because it utilizes the required build tools 
56 57
(v141).

58
##### Building using Visual Studio (tested on Visual Studio 15 2017):
59 60 61
CMake can generate Visual Studio project files. To build the project, first configure and generate the dependencies using
```deps/build/CMakeLists.txt```. Next, click on the generated ALL_BUILD file and compile the project using VS. Repeat the same 
procedure for ```build/CMakeLists.txt```. Make sure that the active configuration is set to release. Please note that it's still 
Dajo Frey's avatar
Dajo Frey committed
62
necessary to run ```git submodule update --init --recursive deps``` at least once, otherwise there will be missing submodules.
Dajo Frey's avatar
...  
Dajo Frey committed
63

64
## Input
Dajo Frey's avatar
Dajo Frey committed
65 66 67 68
* The program only works with sphere packings  

Sphere packings have a ```.spheres``` file extension and use the following format: x y z radius

69
* You can load a sphere packing via command line (Linux only)
70 71 72

Example: ```./ProtoRender -f /home/username/cube.spheres```

Dajo Frey's avatar
Dajo Frey committed
73 74 75
## Development

### Build shaders
Dajo Frey's avatar
Dajo Frey committed
76
* You can automatically (re)build shaders when you add them to build/CMakeLists.txt (shaders are at the bottom)  
Dajo Frey's avatar
Dajo Frey committed
77

Dajo Frey's avatar
Dajo Frey committed
78
In order to do that, you need to change 2 lines in build/build.bash or build/build.bat:    
Dajo Frey's avatar
Dajo Frey committed
79 80
change ```cmake -B../deps/build -H../deps/build``` to ```cmake -DBUILD_GLSL=ON -B../deps/build -H../deps/build```  
change ```cmake .``` to ```cmake -DBUILD_SHADERS=ON .```  
Dajo Frey's avatar
Dajo Frey committed
81 82

### Generate Documentation
Dajo Frey's avatar
Dajo Frey committed
83 84
* You can generate html documentation with doxygen, which may be easier to read   

Dajo Frey's avatar
Dajo Frey committed
85 86
Go to data/doxygen/ and run ```doxygen Doxyfile```  
The output will be in doc/. To view, load doc/index.html with a browser.
Dajo Frey's avatar
...  
Dajo Frey committed
87 88 89 90 91

[CMake]: https://cmake.org/
[Make]: https://www.gnu.org/software/make/
[Vulkan]: https://www.khronos.org/vulkan/
[various_utils]: https://github.com/ojadyref-forks/various_utils
Dajo Frey's avatar
Dajo Frey committed
92
[X11]: https://en.wikipedia.org/wiki/X_Window_System
Dajo Frey's avatar
Dajo Frey committed
93
[msbuild]: https://visualstudio.microsoft.com/de/downloads/ 
Dajo Frey's avatar
Dajo Frey committed
94
[doxygen]: http://www.doxygen.nl/
r1c3w1nd's avatar
...  
r1c3w1nd committed
95
[Git]: https://git-scm.com/
Dajo Frey's avatar
Dajo Frey committed
96
[vulkan-amdgpu-pro]: http://aur.archlinux.org/packages/vulkan-amdgpu-pro/
97
[Sphere-Packings]: https://en.wikipedia.org/wiki/Sphere_packing
Dajo Frey's avatar
Dajo Frey committed
98
[Gitlab Repository]: https://gitlab.informatik.uni-bremen.de/s_2otc2b/ProtoRender