Project 5: Zhihao Ruan

.gitignore

@@ -0,0 +1,130 @@
+
+# Created by https://www.toptal.com/developers/gitignore/api/windows,linux,macos,c++,cmake
+# Edit at https://www.toptal.com/developers/gitignore?templates=windows,linux,macos,c++,cmake
+
+### C++ ###
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+### CMake ###
+CMakeLists.txt.user
+CMakeCache.txt
+CMakeFiles
+CMakeScripts
+Testing
+Makefile
+cmake_install.cmake
+install_manifest.txt
+compile_commands.json
+CTestTestfile.cmake
+_deps
+
+### CMake Patch ###
+# External projects
+*-prefix/
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/windows,linux,macos,c++,cmake
+
+.vscode
+bin
+build

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 2.8.12)
+cmake_minimum_required(VERSION 3.15)
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake")
 
 project(cis565_project4_vulkan_grass_rendering)
@@ -8,15 +8,16 @@ OPTION(USE_D2D_WSI "Build the project using Direct to Display swapchain" OFF)
 find_package(Vulkan REQUIRED)
 
 IF(WIN32)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DVK_USE_PLATFORM_WIN32_KHR")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DVK_USE_PLATFORM_WIN32_KHR")
 ELSE(WIN32)
-    find_package(Threads REQUIRED)
+  find_package(Threads REQUIRED)
 IF(USE_D2D_WSI)
-    MESSAGE("Using direct to display extension...")
-    add_definitions(-D_DIRECT2DISPLAY)
+  MESSAGE(STATUS "Vulkan: Using direct to display extension -D_DIRECT2DISPLAY...")
+  add_definitions(-D_DIRECT2DISPLAY)
 ELSE(USE_D2D_WSI)
-    find_package(XCB REQUIRED)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DVK_USE_PLATFORM_XCB_KHR")
+  message(STATUS "Vulkan: Using default WSI -DVK_USE_PLATFORM_XCB_KHR...")
+  find_package(XCB REQUIRED)
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DVK_USE_PLATFORM_XCB_KHR")
 ENDIF(USE_D2D_WSI)
     # Todo : android?
 ENDIF(WIN32)
@@ -49,18 +50,18 @@ function(InternalTarget folder target)
   endif()
 endfunction(InternalTarget)
 
-# Compiler specific stuff
-IF(MSVC)
-    SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /EHsc")
-ENDIF(MSVC)
-
 IF(WIN32)
   # Nothing here (yet)
 ELSE(WIN32)
     link_libraries(${XCB_LIBRARIES} ${VULKAN_LIB})
 ENDIF(WIN32)
 
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/bin/")
+if(WIN32)
+  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/bin)
+else(WIN32)
+  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+endif(WIN32)
+
 
 add_subdirectory(external)
 add_subdirectory(src)

README.md

@@ -3,10 +3,59 @@ Vulkan Grass Rendering
 
 **University of Pennsylvania, CIS 565: GPU Programming and Architecture, Project 5**
 
-* (TODO) YOUR NAME HERE
-* Tested on: (TODO) Windows 22, i7-2222 @ 2.22GHz 22GB, GTX 222 222MB (Moore 2222 Lab)
+* Zhihao Ruan
+* Tested on: Windows 10 Home 21H1 Build 19043.1288, Ryzen 7 3700X @ 3.59GHz 48GB, RTX 2060 Super 8GB
 
-### (TODO: Your README)
+![](img/overall.gif)
 
-*DO NOT* leave the README to the last minute! It is a crucial part of the
-project, and we will not be able to grade you without a good README.
+## Highlights
+This project implements physically-based grass rendering & culling with Vulkan compute shaders:
+- Physically-based real-time rendering of grass blades;
+- 3 different culling tests: orientation culling, view-frustum culling, distance culling;
+- Tessellating Bezier curves into grass blades with GLSL tessellation shader
+
+A detailed instruction of this project can be found [here](INSTRUCTION.md).
+
+## Vulkan
+[Vulkan](https://vulkan-tutorial.com/) is considered as the next-generation graphics API developed by [Khronos group](https://www.khronos.org/), in replacement for the old OpenGL. It is fast, high-performance, and cross-platform. However, the downside of this API is that it exposes all details of GPU hardware to users for possible customization, so that it generally takes a significantly large amount of code for users to set up the rendering pipeline than OpenGL.
+
+This project sets up a standard Vulkan graphics pipeline with compute shaders & tessellation shaders. The goal of this project is to implement the paper [Responsive Real-Time Grass Rendering for General 3D Scenes](https://www.cg.tuwien.ac.at/research/publications/2017/JAHRMANN-2017-RRTG/JAHRMANN-2017-RRTG-draft.pdf) for effective grass simulation in 3D rendering. 
+
+## [Responsive Real-Time Grass Rendering for General 3D Scenes](https://www.cg.tuwien.ac.at/research/publications/2017/JAHRMANN-2017-RRTG/JAHRMANN-2017-RRTG-draft.pdf)
+Grass is a critical component in 3D graphics. Almost every modern video games have some scenes that involve the rendering of grass. It is also a typical example of massive parallelization, as with the power of GPU one can easily think of ways to render every grass blade with a single GPU thread for photorealistic effects. However, approximations are still needed, and the paper chooses Bezier curves. Bezier curves are a special family of curve that produces smooth splines geometry in 3D space. The generation of Bezier curve requires pre-defining multiple control points, and the curve would then be generated following a fixed function that interpolates between adjacent control points (for more details, see [Wikipedia](https://en.wikipedia.org/wiki/B%C3%A9zier_curve)).
+
+![](img/blade_model.jpg)
+
+### Basic Geometry
+From the paper, a single grass blade can be defined as a Bezier curve with 3 control points: `v0`, `v1`, `v2`. `v0` is the base point specifying the 3D position of the base of the grass blade, `v1` is the guide for the curve that is always "above" `v0` and defines the blade's up direction, and `v2` is the control points where we execute all kinds of simulation forces. The paper provides a very detailed usage for tweaking basic 3D geometry shapes for rendering with Bezier curves (see Section 6.3 of paper). 
+
+### Physics Simulation
+As for physical simulation, we define the following basic forces:
+- **Gravity force** that pulls `v2` to the ground, creating bends on the blade;
+- **Recovery force** that tends to recover the up-straight pose of the blade;
+- **Wind force** that produces random displacement on the tip of the blade (specifically, on `v2`).
+
+### Blade Culling
+Blade culling is an optimization technique that the paper mentions to improve FPS in real-time rendering. By culling we do not wish to render the grass blades that:
+- are too far away;
+- are outside the camera's view frustum;
+- are not facing towards the camera.
+
+Culling tests are conducted in the compute shader so that the number of grass blades that need rendering varies with the position and orientation of the camera.
+
+## Visual Effects
+The following images demonstrates effects due to different culling operations:
+|       Orientation Culling        |       View-Frustum Culling        |       Distance Culling        |
+| :------------------------------: | :-------------------------------: | :---------------------------: |
+| ![](img/orientation_culling.gif) | ![](img/view_frustum_culling.gif) | ![](img/distance_culling.gif) |
+
+The following image demonstrates the up-straight pose of the blade (no physics forces, no culling):
+
+![](img/blade_upstraight.png)
+
+## Performance Analysis 
+The following FPS tests on different culling options is conducted with `NUM_BLADES = 1 << 18`:
+
+![](img/performance_analysis.png)
+
+We can see that orientation culling improves the rendering FPS the most, while all the others also have some improvements on the FPS.

cmake/FindXCB.cmake

@@ -35,15 +35,15 @@ foreach(comp ${XCB_FIND_COMPONENTS})
         ${PC_${comp}_LIBRARY_DIRS}
         )
 
-    find_package_handle_standard_args(${comp}
-        FOUND_VAR ${comp}_FOUND
+    find_package_handle_standard_args(${compname}
+        FOUND_VAR ${compname}_FOUND
         REQUIRED_VARS ${compname}_INCLUDE_DIR ${compname}_LIBRARY)
     mark_as_advanced(${compname}_INCLUDE_DIR ${compname}_LIBRARY)
 
     list(APPEND XCB_INCLUDE_DIRS ${${compname}_INCLUDE_DIR})
     list(APPEND XCB_LIBRARIES ${${compname}_LIBRARY})
 
-    if(NOT ${comp}_FOUND)
+    if(NOT ${compname}_FOUND)
         set(XCB_FOUND false)
     endif()
 endforeach()

external/CMakeLists.txt

@@ -3,7 +3,8 @@ set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "Build the GLFW example programs")
 set(GLFW_BUILD_TESTS OFF CACHE BOOL "Build the GLFW test programs")
 set(GLFW_BUILD_DOCS OFF CACHE BOOL "Build the GLFW documentation")
 set(GLFW_INSTALL OFF CACHE BOOL "Generate installation target")
-add_subdirectory(GLFW)
+add_subdirectory(glfw-3.3.4)
+add_subdirectory(spdlog-1.9.2)
 
-set(GLM_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/glm PARENT_SCOPE)
+set(GLM_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/glm-0.9.9.8 PARENT_SCOPE)
 set(STB_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/stb PARENT_SCOPE)