From d1c0f8887ed5b576008f1beeed3668d09f2a3949 Mon Sep 17 00:00:00 2001 From: Iceflower Date: Sun, 19 Apr 2020 13:51:26 +0200 Subject: [PATCH 1/2] [doc] Readthedocs support --- .readthedocs.yml | 9 +++++++++ documentation/requirements.txt | 4 ++++ 2 files changed, 13 insertions(+) create mode 100644 .readthedocs.yml create mode 100644 documentation/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..25ef06eae --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,9 @@ +version: 2 + +sphinx: + configuration: documentation/source/conf.py +formats: all +python: + version: 3.8 + install: + - requirements: documentation/requirements.txt diff --git a/documentation/requirements.txt b/documentation/requirements.txt new file mode 100644 index 000000000..54a5379ac --- /dev/null +++ b/documentation/requirements.txt @@ -0,0 +1,4 @@ +sphinx>=3.0.1 +sphinx_rtd_theme>=0.4.3 +exhale>=0.2.3 +sphinxcontrib-mermaid>=0.4.0 From a58634bb26e071c45071c04d5e4f922db9405258 Mon Sep 17 00:00:00 2001 From: Iceflower Date: Sun, 19 Apr 2020 15:24:19 +0200 Subject: [PATCH 2/2] [doc] Convert md to rst and update documentation --- BUILDING.md | 70 ----- CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.rst | 47 ++-- CONTRIBUTING.md | 29 --- CONTRIBUTING.rst | 29 +++ README.md | 210 --------------- README.rst | 240 ++++++++++++++++++ documentation/source/content.rst.inc | 4 +- .../source/contributing/code_of_conduct.rst | 3 + .../source/contributing/contributors.rst | 4 + documentation/source/contributing/main.rst | 9 + documentation/source/development/building.rst | 94 +++++++ .../source/development/preparation.rst | 3 + documentation/source/license/main.rst | 6 + 13 files changed, 417 insertions(+), 331 deletions(-) delete mode 100644 BUILDING.md rename CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.rst (72%) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst delete mode 100644 README.md create mode 100644 README.rst create mode 100644 documentation/source/contributing/code_of_conduct.rst create mode 100644 documentation/source/contributing/contributors.rst create mode 100644 documentation/source/contributing/main.rst create mode 100644 documentation/source/license/main.rst diff --git a/BUILDING.md b/BUILDING.md deleted file mode 100644 index f3c7ee7f1..000000000 --- a/BUILDING.md +++ /dev/null @@ -1,70 +0,0 @@ -# Building vulkan-renderer - -## Windows -* It is recommended to use [Visual Studio 2019](https://visualstudio.microsoft.com/). You can use any IDE that CMake can generate a project map for. -* Download the latest [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/). It is updated frequently! -* Download [CMake](https://cmake.org/). -* Download [Python](https://www.python.org/). -* Install [Conan package manager](https://conan.io/) using `pip install conan`. You can also use the Windows installer. -* Clone the source code. We recommend [GitHub Desktop](https://desktop.github.com/). -* Open CMake and select the root folder which contains `CMakeLists.txt` (not just `src` folder!). -* You can choose any location for the `build` folder. -* Click "Configure" and select `Visual Studio 16 2019`. Click "Finish". -* CMake will now set up dependencies automatically for you. This might take a while. If this fails, you really should open a ticket! -* Click "Generate". You can now open the Visual Studio project file in your `build` folder. -* You must compile all `.glsl` shaders in the `shaders` folder to the [SPIR-V](https://en.wikipedia.org/wiki/Standard_Portable_Intermediate_Representation) format. Therefore, you need to execute `compile_shaders.bat`. Make sure you have found `glslangValidator.exe` in the Vulkan SDK's bin folder and add it to your path variable. -* Please check that the root directory of the repository is set as working directory for debugging. Usually, CMake should take care of this already. -* You are now ready to start debugging! We want master branch to stay stable at all time. - -## Linux - -### Gentoo -* Install dependencies and tools: -```bash -emerge \ - dev-util/cmake \ - dev-util/conan \ - dev-util/vulkan-headers \ - dev-util/vulkan-tools \ - dev-vcs/git \ - media-libs/vulkan-layers \ - media-libs/vulkan-loader -``` -* Install ninja build tool (optional): -```bash -emerge dev-util/ninja -``` -* Clone the repository: -```bash -git clone https://github.com/inexorgame/vulkan-renderer -cd vulkan-renderer -``` -* Create build directory: -```bash -mkdir build -cd $_ -``` -* Configure cmake: - * `INEXOR_USE_VMA_RECORDING` is required to be `OFF` in linux builds. - * Only pass `-GNinja` if the ninja build tool is installed. -```bash -cmake .. \ - -DCMAKE_BUILD_TYPE=Debug \ - -DINEXOR_USE_VMA_RECORDING=OFF \ - -GNinja -``` -* Build and run: -```bash -cd .. -cmake --build build --target inexor-vulkan-renderer-example -./build/bin/inexor-vulkan-renderer-example -``` - -### Other distributions -* [We are working on it](https://github.com/inexorgame/vulkan-renderer/issues/19). - -## Mac -Currently, we do not support Mac because it would require us to use [MoltenVK](https://github.com/KhronosGroup/MoltenVK) to get Vulkan running on Mac OS. - -## Android -We might support Android in the future. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.rst similarity index 72% rename from CODE_OF_CONDUCT.md rename to CODE_OF_CONDUCT.rst index 217b42b98..82c8b22c5 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.rst @@ -1,6 +1,8 @@ -# Contributor Covenant Code of Conduct +Contributor Covenant Code of Conduct +==================================== -## Our Pledge +Our Pledge +---------- In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and @@ -9,29 +11,31 @@ size, disability, ethnicity, sex characteristics, gender identity and expression level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. -## Our Standards +Our Standards +-------------- Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or +- The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting -## Our Responsibilities +Our Responsibilities +-------------------- Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in @@ -43,7 +47,8 @@ that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. -## Scope +Scope +----- This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of @@ -52,10 +57,11 @@ address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. -## Enforcement +Enforcement +----------- Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at info@inexor.org. All +reported by contacting the project team at ``info@inexor.org``. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. @@ -65,12 +71,11 @@ Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. -## Attribution +Attribution +----------- -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +This Code of Conduct is adapted from the `Contributor Covenant `__, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html -[homepage]: https://www.contributor-covenant.org - For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 6a97246ba..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,29 +0,0 @@ -We are always open for suggestios or pull requests. - -Join our discord server: https://discord.gg/acUW8k7. - -[Iceflower](https://github.com/IceflowRE) -* Threadpool improvements. -* Advice on thread safety and code design. -* CMake improvements and feedback. -* Feedback on Travis CI and Github actions. -* Support for [Exhale](https://exhale.readthedocs.io/en/latest/). - -[Shikijo](https://github.com/Shikijo) -* Pointed out broken glsl compiler batch script on Windows. - -[Croydon](https://github.com/Croydon) -* Advice on [conan package manager](https://conan.io/). - -[uilianries](https://github.com/uilianries) -* [Travis CI setup](https://stackoverflow.com/questions/61209668/travis-ci-reports-linker-errors-for-gcc-7-for-a-vulkan-project) - -[yeetari](https://github.com/yeetari) -* Building and testing vulkan-renderer on Linux. -* Added USE_VMA_RECORDING CMake option so vulkan-renderer can be build on Linux until VMA recording has been ported. -* Feedback on Travis CI and Github actions. -* Add build instructions for gentoo. -* Replace `_DEBUG` with NDEBUG. - -[joetoth](https://github.com/joetoth) -* Help with Discord server. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..79eb4df3e --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,29 @@ +We are always open for suggestions or pull requests. + +Join our discord server: https://discord.gg/acUW8k7. + +`Iceflower `__ + - Threadpool improvements. + - Advice on thread safety and code design. + - CMake improvements and feedback. + - Feedback on Travis CI and Github actions. + - Support for `Exhale `__. + +`Shikijo `__ + - Pointed out broken glsl compiler batch script on Windows. + +`Croydon `__ + - Advice on `conan package manager `__. + +`uilianries `__ + - `Travis CI setup `__ + +`yeetari `__ + - Building and testing vulkan-renderer on Linux. + - Added USE_VMA_RECORDING CMake option so vulkan-renderer can be build on Linux until VMA recording has been ported. + - Feedback on Travis CI and Github actions. + - Add build instructions for gentoo. + - Replace ``_DEBUG`` with NDEBUG. + +`joetoth `__ + - Help with Discord server. diff --git a/README.md b/README.md deleted file mode 100644 index a8d9ba19e..000000000 --- a/README.md +++ /dev/null @@ -1,210 +0,0 @@ -# vulkan-renderer -[![Build Status](https://travis-ci.org/inexorgame/vulkan-renderer.svg?branch=master)](https://travis-ci.org/inexorgame/vulkan-renderer) -![Discord](https://img.shields.io/discord/698219248954376256) -[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT) -![Issues](https://img.shields.io/github/issues/inexorgame/vulkan-renderer) -![Contributors](https://img.shields.io/github/contributors/inexorgame/vulkan-renderer) -![Downloads](https://img.shields.io/github/downloads/inexorgame/vulkan-renderer/total) -[![Documentation](https://img.shields.io/badge/docs-doxygen-blue.svg)](https://github.com/inexorgame/vulkan-renderer) -![Last Commit](https://img.shields.io/github/last-commit/inexorgame/vulkan-renderer) -![Code Size](https://img.shields.io/github/languages/code-size/inexorgame/vulkan-renderer) - -A new octree-based game+engine using [Vulkan API](https://www.khronos.org/vulkan/) and [C++17](https://stackoverflow.com/questions/38060436/what-are-the-new-features-in-c17). - -Our very first tech demo `v0.1-alpha.1` can be downloaded [here](https://github.com/inexorgame/vulkan-renderer/releases). Please send your logfiles to info@inexor.org. - -Please visit [inexor.org](https://inexor.org) and join our [discord](https://discord.gg/acUW8k7). - -![Add frontbanner here](https://raw.githubusercontent.com/inexorgame/artwork/179e891a10f8ee1cd4c0f777aff40485f0212c76/vulkan/readme/front_banner_1.jpg) - -## What is Vulkan? -![Vulkan API logo here..](https://upload.wikimedia.org/wikipedia/commons/thumb/3/30/Vulkan.svg/300px-Vulkan.svg.png) - -Vulkan is a new, low level API ([application programming interface](https://en.wikipedia.org/wiki/Application_programming_interface)) for high-performance graphics programming and computing. It is seen by some as the successor to OpenGL, although it is important to state that is is very different from it. Vulkan is not just a new version of OpenGL or an extension of it. Both Vulkan and OpenGL are being developed by the [Khronos Group](https://www.khronos.org/). Like DirectX 12 or Apple's Metal, Vulkan is a low level API which allows for much deeper control over the graphics card and the driver. This offers better performance (higher FPS) due to reduction of overhead and driver guesswork during runtime. In general, Vulkan does a lot of work during the initialisation of the application but therefore reduces work during rendering. Since Vulkan is much more explicit in terms of code, it foces you to think about the structure and architecture of your code. - -## Getting into Vulkan -You really should watch these expert talks on YouTube: - -* [GDC 2018 - Getting explicit: How Hard is Vulkan really?](https://www.youtube.com/watch?v=0R23npUCCnw) -Dustin Land, Software engineer, id-Software. - -* [DevU 2017: Getting Started with Vulkan](https://www.youtube.com/watch?v=yHZ3-AMJA6Y) -Developers from Imagination, Google and LunarG. - -* [Porting your engine to Vulkan or DX12](https://www.youtube.com/watch?v=6NWfznwFnMs) -Adam Sawicki, Developer Software Engineer, AMD. - -* [Vulkan Best Practices Roundtable discussion](https://www.youtube.com/watch?v=owuJRPKIUAg) -NVidia, Imagination, Qualcomm, id-Software, EPIC-games and Google. - -* [Vulkan Memory Management](https://www.youtube.com/watch?v=rXSdDE7NWmA) -Jordan Logan, Developer technology engineer, AMD. - -* [Vulkan Memory Managenent](https://www.youtube.com/watch?v=zSG6dPq57P8) -Steven Tovey, Developer technology engineer, AMD. - -* [Vulkan: State of the Union 2019](https://www.youtube.com/watch?v=KLZsAJQBR5o) -Developers from ARM, LunarG, NVidia. - - -## Why use Vulkan? -* Unlike OpenGL, Vulkan fits the design of modern GPUs as it is not just one single [state machine](https://stackoverflow.com/questions/31282678/what-is-the-opengl-state-machine). -* Vulkan is a low-level API which gives much more control over GPU behaviour. This reduces driver guesswork und avoids undefined behaviour of graphics drivers. -* The API is asynchronous and encourages multithreaded rendering. This is a major advantage over OpenGL! Vulkan also wants you to use the GPU asynchronously. -* Lower and more predictable CPU load which results in [better performance](https://stackoverflow.com/questions/56766983/what-can-vulkan-do-specifically-that-opengl-4-6-cannot) and a reduction of driver guesswork. -* The reduction of CPU workload and it's improved predictability can enforce the GPU to be the limiting factor (as it should be), instead of the CPU. -* Vulkan implies memory-management to be done by the application (by you) rather than the driver. -* Vulkan is a fresh start, whereas OpenGL contains a myriad of hacks to support very rare use cases. -* Available on a variety of platforms: Windows, Linux, mobile devices and much more! -* [Validation layers](https://github.com/KhronosGroup/Vulkan-ValidationLayers) and diagnostics can be independently activated during development, allowing better error handling and debugging compared with OpenGL or DirectX. Upon release builds, the validation layers can be deactivated easily. -* Vulkan pre-compiles shaders to a [standardised bytecode format](https://en.wikipedia.org/wiki/Standard_Portable_Intermediate_Representation). This again reduces driver guesswork during runtime. -* Vulkan API and most of the drivers are [open source](https://en.wikipedia.org/wiki/Open_source)! (unlike DirectX 12 for example) -* Vulkan has layers and extensions as part of its design. For example it's easy to put steam overlay into a game simply by enabling Valve's steam overlay layer. -* Vulkan is being developed through an [unprecedented collaboration](https://www.khronos.org/members/list) of major industry-leading companies. It is not being developed by one company only (like DirectX by Microsoft). As Vulkan's motto states, it really is `industry-forged`. -* The [ending of the OpenGL era](https://www.reddit.com/r/opengl/comments/b44tyu/apple_is_deprecating_opengl/) has begun. - -## Roadmap - -[Initialisation and glTF2 demo (0.1 alpha), April 12th, 2020](https://github.com/inexorgame/vulkan-renderer/releases/tag/v0.1-alpha.1) - -Next planned releases: - -### [Threadpool](https://en.wikipedia.org/wiki/Thread_pool) demo (0.2 alpha) (est. April 26th, 2020) -* [ ] Implement `-threads ` command line argument. -* [ ] Refactor `render_frame` method: Account for N buffering (prefer triple buffering). -* [X] Create a threadpool using C++17. -* [ ] Refactor the engine so it loads resources with worker threads. Use C++17 synchronisation techniques. -* [ ] Abstract command buffer recording into manager classes. -* [ ] Abstract pipeline creation into manager classes. -* [ ] Record command buffers on demand using separate thread. -* [ ] Update uniform buffers in separate thread. -* [ ] Poll window events in separate thread. -* [ ] Implement Vulkan pipeline statistics. -* [ ] Create new threads on demand. -* [ ] Give threadpool tasks a name. -* [ ] Use `std::chrono` to measure how long a task took to finish. - -### [imgui](https://github.com/ocornut/imgui) demo (0.3 alpha) (date not set) -* [ ] Add [imgui](https://github.com/ocornut/imgui) support. - -### Octree demo (0.4 alpha) (date not set) -* [ ] Suggest implementation for inexor octree file format. -* [ ] Load octree data from a file. -* [ ] Render some world geometry which was generated from octree data. - - -## How to build -Feel free to open a ticket if you have problems generating project map files or building code. - -[How to build vulkan-renderer](BUILDING.md) - -## Who develops Vulkan? -The [Khronos Group](https://www.khronos.org/), which also made [OpenGL](https://www.opengl.org/). - -## Who supports Vulkan ? -Just to give a selection of supporters: -* Google -* Intel -* Apple -* AMD -* NVidia -* Sony -* Samsung -* Huawei -* Qualcomm -* Valve Software - -For a full list of contributors, see [this link](https://www.khronos.org/members/list). - -## Which engines support Vulkan already? -* Unity engine -* Unreal engine (EPIC games) -* CryEngine (Crytek) -* id-Tech 7 (id-Software) -* Source engine (Valve) -* AnvilNext (Ubisoft) -* Godot 4 -and many more.. - -## Links -### Vulkan API -https://www.khronos.org/vulkan/ -https://vulkan-tutorial.com/ - -### Vulkan Examples -Sascha Willems' Vulkan examples: - -https://github.com/SaschaWillems/Vulkan - -Khronos Vulkan samples: - -https://github.com/KhronosGroup/Vulkan-Samples - -LunarG Vulkan samples: - -https://github.com/LunarG/VulkanSamples - -Intel Vulkan introduction: - -https://github.com/GameTechDev/IntroductionToVulkan - -Minimal Vulkan compute shader: - -https://github.com/Erkaman/vulkan_minimal_compute - -Vulkan Tutorial Github page: - -https://github.com/Overv/VulkanTutorial - -Niko Kauppi's Github page: - -https://github.com/Niko40/Vulkan-API-Tutorials - -Shabi's Vulkan Tutorials: - -https://github.com/ShabbyX/vktut - -### Vulkan Debuggers -https://renderdoc.org/ - -### Advantages of Vulkan -https://stackoverflow.com/questions/56766983/what-can-vulkan-do-specifically-that-opengl-4-6-cannot - -https://gamedev.stackexchange.com/questions/96014/what-is-vulkan-and-how-does-it-differ-from-opengl - -https://www.imgtec.com/blog/stuck-on-opengl-es-time-to-move-on-why-vulkan-is-the-future-of-graphics/ - -https://www.toptal.com/api-developers/a-brief-overview-of-vulkan-api - -https://developer.nvidia.com/Vulkan - -https://www.quora.com/What-advantages-does-Vulkan-have-over-already-established-graphics-APIs - -### Vulkan Tutorials -https://devblogs.nvidia.com/vulkan-dos-donts/ - -https://vulkan.lunarg.com/doc/sdk/1.0.26.0/linux/tutorial.html - -https://www.toptal.com/api-developers/a-brief-overview-of-vulkan-api - -https://vulkan-tutorial.com/ - -http://ogldev.atspace.co.uk/www/tutorial50/tutorial50.html - -http://jhenriques.net/development.html - -http://www.duskborn.com/posts/a-simple-vulkan-compute-example/ - - -https://www.fasterthan.life/blog/2017/7/11/i-am-graphics-and-so-can-you-part-1 - -https://software.intel.com/en-us/articles/api-without-secrets-introduction-to-vulkan-part-1 - -### Multithreading in Vulkan -https://www.reddit.com/r/vulkan/comments/52aodq/multithreading_in_vulkan_where_should_i_start/ - -### OpenGL -https://www.opengl.org/ - -### MoltenVK -https://moltengl.com/moltenvk/ diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..74850b204 --- /dev/null +++ b/README.rst @@ -0,0 +1,240 @@ +*************** +vulkan-renderer +*************** + +|programming language| |license| + +|travis ci| |readthedocs| + +|issues| |last commit| |code size| |contributors| |downloads| + +---- + +A new octree-based game+engine using `Vulkan API `__ and `C++17 `__. + +Our very first tech demo ``v0.1-alpha.1`` can be downloaded `here `__. Please send your logfiles to info@inexor.org. + +Please visit `inexor.org `__ and join our `discord `__. + +---- + +.. image:: https://raw.githubusercontent.com/inexorgame/artwork/179e891a10f8ee1cd4c0f777aff40485f0212c76/vulkan/readme/front_banner_1.jpg + +What is Vulkan? +############### + +.. image:: https://upload.wikimedia.org/wikipedia/commons/thumb/3/30/Vulkan.svg/300px-Vulkan.svg.png + +Vulkan is a new, low level API (`application programming interface `__) for high-performance graphics programming and computing. It is seen by some as the successor to OpenGL, although it is important to state that is is very different from it. Vulkan is not just a new version of OpenGL or an extension of it. Both Vulkan and OpenGL are being developed by the `Khronos Group `__. Like DirectX 12 or Apple's Metal, Vulkan is a low level API which allows for much deeper control over the graphics card and the driver. This offers better performance (higher FPS) due to reduction of overhead and driver guesswork during runtime. In general, Vulkan does a lot of work during the initialisation of the application but therefore reduces work during rendering. Since Vulkan is much more explicit in terms of code, it foces you to think about the structure and architecture of your code. + +Getting into Vulkan +################### + +You really should watch these expert talks on YouTube: + +`GDC 2018 - Getting explicit: How Hard is Vulkan really? `__ + Dustin Land, Software engineer, id-Software. +`DevU 2017: Getting Started with Vulkan `__ + Developers from Imagination, Google and LunarG. +`Porting your engine to Vulkan or DX12 `__ + Adam Sawicki, Developer Software Engineer, AMD. +`Vulkan Best Practices Roundtable discussion `__ + NVidia, Imagination, Qualcomm, id-Software, EPIC-games and Google. +`Vulkan Memory Management `__ + Jordan Logan, Developer technology engineer, AMD. +`Vulkan Memory Managenent `__ + Steven Tovey, Developer technology engineer, AMD. +`Vulkan: State of the Union 2019 `__ + Developers from ARM, LunarG, NVidia. + + +Why use Vulkan? +############### + +- Unlike OpenGL, Vulkan fits the design of modern GPUs as it is not just one single `state machine `__. +- Vulkan is a low-level API which gives much more control over GPU behaviour. This reduces driver guesswork und avoids undefined behaviour of graphics drivers. +- The API is asynchronous and encourages multithreaded rendering. This is a major advantage over OpenGL! Vulkan also wants you to use the GPU asynchronously. +- Lower and more predictable CPU load which results in `better performance `__ and a reduction of driver guesswork. +- The reduction of CPU workload and it's improved predictability can enforce the GPU to be the limiting factor (as it should be), instead of the CPU. +- Vulkan implies memory-management to be done by the application (by you) rather than the driver. +- Vulkan is a fresh start, whereas OpenGL contains a myriad of hacks to support very rare use cases. +- Available on a variety of platforms: Windows, Linux, mobile devices and much more! +- `Validation layers `__ and diagnostics can be independently activated during development, allowing better error handling and debugging compared with OpenGL or DirectX. Upon release builds, the validation layers can be deactivated easily. +- Vulkan pre-compiles shaders to a `standardised bytecode format `__. This again reduces driver guesswork during runtime. +- Vulkan API and most of the drivers are `open source `__! (unlike DirectX 12 for example) +- Vulkan has layers and extensions as part of its design. For example it's easy to put steam overlay into a game simply by enabling Valve's steam overlay layer. +- Vulkan is being developed through an `unprecedented collaboration `__ of major industry-leading companies. It is not being developed by one company only (like DirectX by Microsoft). As Vulkan's motto states, it really is `industry-forged`. +- The `ending of the OpenGL era `__ has begun. + +Roadmap +####### + +`Initialisation and glTF2 demo (0.1 alpha), April 12th, 2020 `__ + +Next planned releases: + +`Threadpool `__ demo (0.2 alpha) (est. April 26th, 2020) +--------------------------------------------------------------------------------------------------- + +- [ ] Implement `-threads ` command line argument. +- [ ] Refactor `render_frame` method: Account for N buffering (prefer triple buffering). +- [X] Create a threadpool using C++17. +- [ ] Refactor the engine so it loads resources with worker threads. Use C++17 synchronisation techniques. +- [ ] Abstract command buffer recording into manager classes. +- [ ] Abstract pipeline creation into manager classes. +- [ ] Record command buffers on demand using separate thread. +- [ ] Update uniform buffers in separate thread. +- [ ] Poll window events in separate thread. +- [ ] Implement Vulkan pipeline statistics. +- [ ] Create new threads on demand. +- [ ] Give threadpool tasks a name. +- [ ] Use `std::chrono` to measure how long a task took to finish. + +`imgui `__ demo (0.3 alpha) (date not set) +---------------------------------------------------------------------------- + +- [ ] Add `imgui `__ support. + +Octree demo (0.4 alpha) (date not set) +--------------------------------------- + +- [ ] Suggest implementation for inexor octree file format. +- [ ] Load octree data from a file. +- [ ] Render some world geometry which was generated from octree data. + + +How to build +############ + +Feel free to open a ticket if you have problems generating project map files or building code. + +`How to build vulkan-renderer `__ + +Who develops Vulkan? +#################### + +The `Khronos Group `__, which also made `OpenGL `__. + +## Who supports Vulkan ? +Just to give a selection of supporters: +- Google +- Intel +- Apple +- AMD +- NVidia +- Sony +- Samsung +- Huawei +- Qualcomm +- Valve Software + +For a full list of contributors, see `this link `__. + +Which engines support Vulkan already? +##################################### + +- Unity engine +- Unreal engine (EPIC games) +- CryEngine (Crytek) +- id-Tech 7 (id-Software) +- Source engine (Valve) +- AnvilNext (Ubisoft) +- Godot 4 +and many more.. + +Links +##### + +Vulkan API +---------- + +- https://www.khronos.org/vulkan/ +- https://vulkan-tutorial.com/ + +Vulkan Examples +--------------- + +- https://github.com/SaschaWillems/Vulkan + Sascha Willems' Vulkan examples +- https://github.com/KhronosGroup/Vulkan-Samples + Khronos Vulkan samples +- https://github.com/LunarG/VulkanSamples + LunarG Vulkan samples +- https://github.com/GameTechDev/IntroductionToVulkan + Intel Vulkan introduction +- https://github.com/Erkaman/vulkan_minimal_compute + Minimal Vulkan compute shader +- https://github.com/Overv/VulkanTutorial + Vulkan Tutorial Github page +- https://github.com/Niko40/Vulkan-API-Tutorials + Niko Kauppi's Github page +- https://github.com/ShabbyX/vktut + Shabi's Vulkan Tutorials + +Vulkan Debuggers +---------------- + +- https://renderdoc.org/ + +Advantages of Vulkan +-------------------- + +- https://stackoverflow.com/questions/56766983/what-can-vulkan-do-specifically-that-opengl-4-6-cannot +- https://gamedev.stackexchange.com/questions/96014/what-is-vulkan-and-how-does-it-differ-from-opengl +- https://www.imgtec.com/blog/stuck-on-opengl-es-time-to-move-on-why-vulkan-is-the-future-of-graphics/ +- https://www.toptal.com/api-developers/a-brief-overview-of-vulkan-api +- https://developer.nvidia.com/Vulkan +- https://www.quora.com/What-advantages-does-Vulkan-have-over-already-established-graphics-APIs + +Vulkan Tutorials +---------------- + +- https://devblogs.nvidia.com/vulkan-dos-donts/ +- https://vulkan.lunarg.com/doc/sdk/1.0.26.0/linux/tutorial.html +- https://www.toptal.com/api-developers/a-brief-overview-of-vulkan-api +- https://vulkan-tutorial.com/ +- http://ogldev.atspace.co.uk/www/tutorial50/tutorial50.html +- http://jhenriques.net/development.html +- http://www.duskborn.com/posts/a-simple-vulkan-compute-example/ +- https://www.fasterthan.life/blog/2017/7/11/i-am-graphics-and-so-can-you-part-1 +- https://software.intel.com/en-us/articles/api-without-secrets-introduction-to-vulkan-part-1 + +Multithreading in Vulkan +------------------------ + +- https://www.reddit.com/r/vulkan/comments/52aodq/multithreading_in_vulkan_where_should_i_start/ + +OpenGL +------ + +- https://www.opengl.org/ + +MoltenVK +-------- +- https://moltengl.com/moltenvk/ + +.. Badges. + +.. |license| image:: https://img.shields.io/badge/License-MIT-brightgreen.svg + :target: https://github.com/inexorgame/vulkan-renderer/blob/master/LICENSE.rst + +.. |programming language| image:: https://img.shields.io/badge/Language-C++17-orange.svg + :target: https://inexor-vulkan-renderer.readthedocs.io/en/latest/development/design/coding-style.html + +.. |travis ci| image:: https://img.shields.io/travis/inexorgame/vulkan-renderer/master.svg?label=Travis%20CI + :target: https://travis-ci.org/inexorgame/vulkan-renderer + +.. |contributors| image:: https://img.shields.io/github/contributors/inexorgame/vulkan-renderer + :target: https://inexor-vulkan-renderer.readthedocs.io/en/latest/contributors/main.html + +.. |downloads| image:: https://img.shields.io/github/downloads/inexorgame/vulkan-renderer/total + +.. |readthedocs| image:: https://readthedocs.org/projects/inexor-vulkan-renderer/badge/?version=latest + :target: https://inexor-vulkan-renderer.readthedocs.io + +.. |last commit| image:: https://img.shields.io/github/last-commit/inexorgame/vulkan-renderer + +.. |issues| image:: https://img.shields.io/github/issues/inexorgame/vulkan-renderer + :target: https://github.com/inexorgame/vulkan-renderer/issues + +.. |code size| image:: https://img.shields.io/github/languages/code-size/inexorgame/vulkan-renderer diff --git a/documentation/source/content.rst.inc b/documentation/source/content.rst.inc index 74e68c427..02d16adeb 100644 --- a/documentation/source/content.rst.inc +++ b/documentation/source/content.rst.inc @@ -2,12 +2,14 @@ Documentation ============= -.. include:: ../../README.md +.. include:: ../../README.rst .. toctree:: :maxdepth: 2 :hidden: changelog/main + contributing/main development/main code/main + license/main diff --git a/documentation/source/contributing/code_of_conduct.rst b/documentation/source/contributing/code_of_conduct.rst new file mode 100644 index 000000000..ac5b0d70b --- /dev/null +++ b/documentation/source/contributing/code_of_conduct.rst @@ -0,0 +1,3 @@ +:orphan: + +.. include:: ../../../CODE_OF_CONDUCT.rst diff --git a/documentation/source/contributing/contributors.rst b/documentation/source/contributing/contributors.rst new file mode 100644 index 000000000..10bda95e3 --- /dev/null +++ b/documentation/source/contributing/contributors.rst @@ -0,0 +1,4 @@ +Contributors +============ + +.. include:: ../../../CONTRIBUTING.rst diff --git a/documentation/source/contributing/main.rst b/documentation/source/contributing/main.rst new file mode 100644 index 000000000..d35b888f3 --- /dev/null +++ b/documentation/source/contributing/main.rst @@ -0,0 +1,9 @@ +************ +Contributing +************ + +.. toctree:: + :maxdepth: 2 + + code_of_conduct + contributors diff --git a/documentation/source/development/building.rst b/documentation/source/development/building.rst index 795e95c71..90b548b47 100644 --- a/documentation/source/development/building.rst +++ b/documentation/source/development/building.rst @@ -51,3 +51,97 @@ Available CMake options cmake -G "Visual Studio 16 2019" -A x64 -B./cmake-build-debug-vs/ -DCMAKE_BUILD_TYPE=Debug ./ # Build all targets cmake --build ./cmake-build-debug/ + +Building vulkan-renderer +------------------------ + +Windows +^^^^^^^ + +- It is recommended to use `Visual Studio 2019 `__. You can use any IDE that CMake can generate a project map for. +- Clone the source code. We recommend `GitHub Desktop `__. +- Open CMake and select the root folder which contains ``CMakeLists.txt`` (not just ``src`` folder!). +- You can choose any location for the ``build`` folder. +- Click "Configure" and select ``Visual Studio 16 2019``. Click "Finish". +- CMake will now set up dependencies automatically for you. This might take a while. If this fails, you really should open a ticket! +- Click "Generate". You can now open the Visual Studio project file in your ``build`` folder. +- You must compile all ``.glsl`` shaders in the ``shaders`` folder to the `SPIR-V `__ format. Therefore, you need to execute ``compile_shaders.bat``. Make sure you have found ``glslangValidator.exe`` in the Vulkan SDK's bin folder and add it to your path variable. +- Please check that the root directory of the repository is set as working directory for debugging. Usually, CMake should take care of this already. +- You are now ready to start debugging! We want master branch to stay stable at all time. + +Linux +^^^^^ + +Gentoo +"""""" + +Install dependencies and tools: + +.. code-block:: bash + + emerge \ + dev-util/cmake \ + dev-util/conan \ + dev-util/vulkan-headers \ + dev-util/vulkan-tools \ + dev-vcs/git \ + media-libs/vulkan-layers \ + media-libs/vulkan-loader + +Install ninja build tool (optional): + +.. code-block:: bash + + emerge dev-util/ninja + +Clone the repository: + +.. code-block:: bash + + git clone https://github.com/inexorgame/vulkan-renderer + cd vulkan-renderer + +Create build directory: + +.. code-block:: bash + + mkdir build + cd $_ + +Configure cmake: + +.. note:: + + - ``INEXOR_USE_VMA_RECORDING`` is required to be ``OFF`` in linux builds. + - Only pass ``-GNinja`` if the ninja build tool is installed. + +.. code-block:: bash + + cmake .. \ + -DCMAKE_BUILD_TYPE=Debug \ + -DINEXOR_USE_VMA_RECORDING=OFF \ + -GNinja + +Build and run: + +.. code-block:: bash + + cd .. + cmake --build build --target inexor-vulkan-renderer-example + ./build/bin/inexor-vulkan-renderer-example + + +Other distributions +""""""""""""""""""" + +`We are working on it `__ + +Mac +^^^ + +Currently, we do not support Mac because it would require us to use `MoltenVK `__ to get Vulkan running on Mac OS. + +Android +^^^^^^^ + +We might support Android in the future. diff --git a/documentation/source/development/preparation.rst b/documentation/source/development/preparation.rst index d7b1b8068..a119eeb04 100644 --- a/documentation/source/development/preparation.rst +++ b/documentation/source/development/preparation.rst @@ -19,6 +19,9 @@ Required Software Optional Software ----------------- +`Ninja Build System `__ + Improve your build times with ninja. + `Doxygen `__ Required by the documentation. Must be available from command line. diff --git a/documentation/source/license/main.rst b/documentation/source/license/main.rst new file mode 100644 index 000000000..77e547211 --- /dev/null +++ b/documentation/source/license/main.rst @@ -0,0 +1,6 @@ +******* +License +******* + + +.. include:: ../../../LICENSE.md