diff --git a/DOCS.md b/DOCS.md index 9dc7960207a5860063ef4ff3e60fd2c79bde0422..4f90461a99c0560a0fc082435f0e6c7bed6dfc38 100644 --- a/DOCS.md +++ b/DOCS.md @@ -1,34 +1,49 @@ -<a href="https://lava-block.com"><img align="left" src="https://github.com/liblava.png" width="100"></a> +<a href="https://lava-block.com"><img align="left" src="https://github.com/liblava.png" width="100" style="margin:0px 20px 0px 0px"></a> -# liblava docs [](https://git.io/liblava) +# liblava docs [](https://git.io/liblava) -[Features](#features) • **[Tutorial](#tutorial)** • [Modules](#modules) • **[Guide](#guide)** • [Tests](#tests) • **[Build](#build)** • [Install](#install) +[Features](#features) **[Tutorial](#tutorial)** [Modules](#modules) **[Guide](#guide)** [Tests](#tests) **[Build](#build)** [Install](#install) + +<br /> ## Features *WIP* +<br /> + ## Tutorial -<a href="https://www.khronos.org/vulkan/" target="_blank"><img align="right" hspace="20" src="res/Vulkan_170px_Dec16.png" width="400"></a> +<a href="https://www.khronos.org/vulkan/" target="_blank"><img align="right" hspace="20" src="res/Vulkan_170px_Dec16.png" width="300"></a> Let's write **Hello World** in Vulkan... +<br /> + **"a simple app that renders a colored window"** -All we need is a `window`, `device` and `renderer`. +⇒ All we need is a `window`, `device` and `renderer` + +<br /> + +**Vulkan** is a low-level, verbose graphics API and such a program can take several hundred lines of code -**Vulkan** is a low-level, verbose graphics API and such a program can take several hundred lines of code. +<br /> -The good news is that **liblava** will help you... +The good news is that **liblava** will help you! + +<br /> ```c++ #include <liblava/lava.hpp> using namespace lava; ``` +<br /> + +⇓ Here are a few examples to get to know `lava` -Here are a few examples to get to know `lava` +<br /> #### 1. frame init @@ -41,7 +56,9 @@ int main(int argc, char* argv[]) { } ``` -This is how to initialize `lava frame` with command line arguments. +This is how to initialize `lava frame` with command line arguments + +<br /> #### 2. run loop @@ -67,7 +84,9 @@ frame.add_run([&]() { return frame.run(); ``` -The last line performs a loop with the **run** we added before. If *count* reaches 3 that **loop** will exit. +The last line performs a loop with the **run** we added before - If *count* reaches 3 that **loop** will exit + +<br /> #### 3. window input @@ -104,7 +123,11 @@ frame.add_run([&]() { return frame.run(); ``` -Straightforward - with this knowledge in hand let's write **Hello World** now... +<br /> + +Straightforward ⇒ With this knowledge in hand let's write our **Hello World** now... + +<br /> #### 4. clear color @@ -230,21 +253,33 @@ frame.add_run_end([&]() { return frame.run(); ``` -##### Welcome on **Planet Vulkan**. That's a lot to display a colored window. +<br /> + +##### Welcome on **Planet Vulkan** - That's a lot to display a colored window! + +<br /> Phew! Take a closer look at the `build_cmd_bufs` function: * We create a **command pool** and **command buffers** for each frame of the render target * And set each command buffer to clear the frame image with some random color -The *VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT* flag specifies the reusage of command buffers. +<br /> + +The *VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT* flag specifies the reusage of command buffers + +`clean_cmd_bufs` frees all buffers and destroys the command pool - In case of swap chain restoration we simply recreate command buffers with a new random color - This happens for example on window resize -`clean_cmd_bufs` frees all buffers and destroys the command pool. In case of swap chain restoration we simply recreate command buffers with a new random color. This happens for example on window resize. +<br /> -After all, this is a very static example. Vulkan supports a more *dynamic* and common usage by resetting a command pool before recording new commands. +After all, this is a very static example ⇒ Vulkan supports a more *dynamic* and common usage by resetting a command pool before recording new commands + +<br /> Ok, it's time for... `lava block` +<br /> + #### 5. color block ```c++ @@ -281,11 +316,17 @@ block.add_command([&](VkCommandBuffer cmd_buf) { }); ``` -##### Nice, this is much more simpler than before. +<br /> + +##### Nice, this is much more simpler than before! + +<br /> + +We create a `lava block` and add just one **command** that clears the current frame image -We create a `lava block` and add one **command** that clears the current frame image. +<br /> -All we need to do is to process the block in the run loop... +All we need to do now is to process the block in the run loop... ```c++ if (!block.process(*frame_index)) @@ -294,7 +335,9 @@ if (!block.process(*frame_index)) return plotter.end_frame(block.get_buffers()); ``` -... and call the renderer with our recorded command buffers. +... and call the renderer with our recorded command buffers + +<br /> Don't forget to clean it up: @@ -302,13 +345,17 @@ Don't forget to clean it up: block.destroy(); ``` +<br /> + ##### New to Vulkan? Take a look at this [Vulkan Guide](https://github.com/KhronosGroup/Vulkan-Guide) -Check [Awesome Vulkan ecosystem](http://www.vinjn.com/awesome-vulkan/) for tutorials, samples and books. +Check [Awesome Vulkan ecosystem](http://www.vinjn.com/awesome-vulkan/) for tutorials, samples and books + +<br /> #### 8. imgui demo -Out of blocks, `lava app` supports the awesome [Dear ImGui](https://github.com/ocornut/imgui) for **tooling** and **easy prototyping**. +Out of blocks `lava app` supports the awesome [Dear ImGui](https://github.com/ocornut/imgui) for **tooling** and **easy prototyping**: ```c++ int main(int argc, char* argv[]) { @@ -325,16 +372,22 @@ int main(int argc, char* argv[]) { } ``` -##### What's next? - Check <a href="https://git.io/liblava-demo">demonstration projects</a> and clone <a href="https://git.io/liblava-template">starter template</a> +<br /> + +##### What's next? ⇒ Check some <a href="https://git.io/liblava-demo">demos</a> and clone a <a href="https://git.io/liblava-template">starter template</a> to try it out! <a href="https://github.com/liblava/liblava-demo/#readme"><img src="res/demo.png"></a> +<br /> + ## Modules #### lava [app](https://github.com/liblava/liblava/tree/master/liblava/app) [](https://github.com/liblava/liblava/tree/master/liblava/app/app.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/app/camera.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/app/forward_shading.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/app/gui.hpp) +<br /> + #### lava [block](https://github.com/liblava/liblava/tree/master/liblava/block) [](https://github.com/liblava/liblava/tree/master/liblava/block/attachment.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/block/block.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/block/descriptor.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/block/pipeline.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/block/render_pass.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/block/subpass.hpp) @@ -343,17 +396,21 @@ int main(int argc, char* argv[]) { [](https://github.com/liblava/liblava/tree/master/liblava/frame/frame.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/frame/input.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/frame/render_target.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/frame/renderer.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/frame/swapchain.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/frame/window.hpp) +<br /> + #### lava [asset](https://github.com/liblava/liblava/tree/master/liblava/asset) -[](https://github.com/liblava/liblava/tree/master/liblava/asset/mesh_loader.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/asset/scope_image.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/asset/texture_loader.hpp) +[](https://github.com/liblava/liblava/tree/master/liblava/asset/mesh_loader.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/asset/scope_image.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/asset/texture_loader.hpp) #### lava [resource](https://github.com/liblava/liblava/tree/master/liblava/resource) -[](https://github.com/liblava/liblava/tree/master/liblava/resource/buffer.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/format.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/image.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/mesh.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/texture.hpp) +[](https://github.com/liblava/liblava/tree/master/liblava/resource/buffer.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/format.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/image.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/mesh.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/resource/texture.hpp) #### lava [base](https://github.com/liblava/liblava/tree/master/liblava/base) -[](https://github.com/liblava/liblava/tree/master/liblava/base/base.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/device.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/instance.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/memory.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/physical_device.hpp) +[](https://github.com/liblava/liblava/tree/master/liblava/base/base.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/device.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/instance.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/memory.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/base/physical_device.hpp) + +<br /> #### lava [file](https://github.com/liblava/liblava/tree/master/liblava/file) @@ -367,13 +424,21 @@ int main(int argc, char* argv[]) { [](https://github.com/liblava/liblava/tree/master/liblava/core/data.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/core/id.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/core/math.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/core/time.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/core/types.hpp) [](https://github.com/liblava/liblava/tree/master/liblava/core/version.hpp) +<br /> + ## Guide *WIP* +<br /> + ## Tests -Run the **lava** executable to test the [Tutorial examples](tests/tests.cpp). Let it simply flow... +Run the **lava** executable to test the [Tutorial examples](tests/tests.cpp) + +Let it simply flow... + +<br /> ##### List all tests: @@ -390,13 +455,19 @@ lava -t 7. gamepad 8. [imgui demo](#8-imgui-demo) +<br /> + ##### Run test 2 for example: ```bash lava 2 ``` -The **driver** starts the last test with no command line arguments. +<br /> + +The **driver** starts the last test when you provide *no* command line arguments + +<br /> ## Build @@ -413,11 +484,15 @@ cmake .. make ``` +<br /> + ## Install -You can use **liblava** as a *git submodule* in your project. For example like the [starter template](https://git.io/liblava-template). +You can use **liblava** as a *git submodule* in your project ⇒ Like in the [starter template](https://git.io/liblava-template) and [demo](https://git.io/liblava-demo) + +<br /> -Alternatively, you can compile and install a specific version for multiple projects: +Alternatively - You can compile and install a specific version for multiple projects: ```bash mkdir build @@ -427,9 +502,11 @@ cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=../lava-install .. cmake --build . --target install ``` +<br /> + #### Project setup -First, find the package in your *CMakeLists.txt*: +First find the package in your *CMakeLists.txt* ```cmake find_package(lava 0.5.3 REQUIRED) @@ -440,7 +517,9 @@ add_executable(test main.cpp) target_link_libraries(test lava::app) ``` -And then build your project with install path *lava_DIR*: +<br /> + +And then build your project with install path ⇒ *lava_DIR* ```bash mkdir build @@ -450,4 +529,6 @@ cmake -D lava_DIR=path/to/lava-install/lib/cmake/lava .. cmake --build . ``` +<br /> + <a href="https://lava-block.com"><img src="https://github.com/liblava.png" width="50"></a> diff --git a/README.md b/README.md index 7805c8b03343fbb26863c1c0c68f34e4272bd692..dc1387425389f7cc5dfa5f910dd68f828ba72719 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ <a href="https://lava-block.com"><img align="right" src="https://github.com/liblava.png" width="220"></a> -**[liblava](https://git.io/liblava) is a modern and easy-to-use library for the <a href="https://www.khronos.org/vulkan/" target="_blank">Vulkan</a>® API** +🌋 **[liblava](https://git.io/liblava) A modern and easy-to-use library for the <a href="https://www.khronos.org/vulkan/" target="_blank">Vulkan</a>® API** -**lava** • lean framework that provides **essentials** for **low-level graphics**<br />specially well suited for **prototyping**, **tooling** and **education** +**lava** is a lean framework that provides **essentials** for **low-level graphics**<br />and is specially well suited for **prototyping**, **tooling** and **education** <br /> -**C++20** • **Modular** • **Windows** • **Linux** • **<a href="https://git.io/liblava-demo">demo</a>** • <a href="https://git.io/liblava-template">template</a> +**C++20** **Modular** **Windows** **Linux** **<a href="https://git.io/liblava-demo">demo</a>** <a href="https://git.io/liblava-template">template</a> -[](https://git.io/liblava) [](LICENSE) [](https://www.codefactor.io/repository/github/liblava/liblava) [](https://discord.lava-block.com) [](https://paypal.me/liblava) [](https://twitter.com/liblava) +[](https://git.io/liblava) [](LICENSE) [](https://www.codefactor.io/repository/github/liblava/liblava) [](https://discord.lava-block.com) [](https://paypal.me/liblava) [](https://twitter.com/liblava) <br /> @@ -18,7 +18,7 @@ * **[run loop](DOCS.md/#run-loop)** **abstraction** for **[window](DOCS.md/#window)** and **[input](DOCS.md/#input) handling** * **plain** **[renderer](DOCS.md/#renderer)** and **[command buffer model](DOCS.md/#command-buffer-model)** * **[texture](DOCS.md/#texture)** and **[mesh](DOCS.md/#mesh)** **loading** from **virtual [file system](DOCS.md/#file-system)** -* **[camera](DOCS.md/#camera)**, **[gui](DOCS.md/#gui)**, **[logging](DOCS.md/#logging)**, **test driver** and much more... +* **[camera](DOCS.md/#camera)** + **[gui](DOCS.md/#gui)** + **[logging](DOCS.md/#logging)** + **test driver** and much more <br /> @@ -26,17 +26,17 @@ ### Docs - **[Tutorial](DOCS.md/#tutorial)** • **[Guide](DOCS.md/#guide)** • [Tests](DOCS.md/#tests) • [Build](DOCS.md/#build) • [Install](DOCS.md/#install) + **[Tutorial](DOCS.md/#tutorial)** **[Guide](DOCS.md/#guide)** [Tests](DOCS.md/#tests) [Build](DOCS.md/#build) [Install](DOCS.md/#install) <br /> -#### [Modules](DOCS.md/#modules) +### [Modules](DOCS.md/#modules) -[](https://github.com/liblava/liblava/tree/master/liblava/core) [](https://github.com/liblava/liblava/tree/master/liblava/util) [](https://github.com/liblava/liblava/tree/master/liblava/file) [](https://github.com/liblava/liblava/tree/master/liblava/base) [](https://github.com/liblava/liblava/tree/master/liblava/resource) [](https://github.com/liblava/liblava/tree/master/liblava/asset) [](https://github.com/liblava/liblava/tree/master/liblava/frame) [](https://github.com/liblava/liblava/tree/master/liblava/block) [](https://github.com/liblava/liblava/tree/master/liblava/app) [](https://git.io/liblava-engine) +[](https://github.com/liblava/liblava/tree/master/liblava/core) [](https://github.com/liblava/liblava/tree/master/liblava/util) [](https://github.com/liblava/liblava/tree/master/liblava/file) [](https://github.com/liblava/liblava/tree/master/liblava/base) [](https://github.com/liblava/liblava/tree/master/liblava/resource) [](https://github.com/liblava/liblava/tree/master/liblava/asset) [](https://github.com/liblava/liblava/tree/master/liblava/frame) [](https://github.com/liblava/liblava/tree/master/liblava/block) [](https://github.com/liblava/liblava/tree/master/liblava/app) [](https://git.io/liblava-engine) <br /> -##### Download latest **<a href="https://github.com/liblava/liblava-demo/releases">demo</a>** (Feb. 20, 2020) +##### ⇓ Download latest **<a href="https://github.com/liblava/liblava-demo/releases">demo</a>** (Feb. 20, 2020) <a href="https://github.com/liblava/liblava-demo/#readme"><img src="res/demo.png"></a> @@ -44,38 +44,46 @@ [](https://ci.appveyor.com/project/TheLavaBlock/liblava) [](https://travis-ci.com/liblava/liblava) +<br /> + ## Requirements * **C++20** compatible compiler * CMake **3.15+** * [Vulkan SDK](https://vulkan.lunarg.com) +<br /> + ## Third-Party -* [argh](https://github.com/adishavit/argh) • 3-clause BSD -* [bitmap](https://github.com/ArashPartow/bitmap) • MIT -* [glfw](https://github.com/glfw/glfw) • zlib -* [gli](https://github.com/g-truc/gli) • MIT -* [glm](https://github.com/g-truc/glm) • MIT -* [imgui](https://github.com/ocornut/imgui) • MIT -* [json](https://github.com/nlohmann/json) • MIT -* [physfs](https://github.com/Didstopia/physfs) • zlib -* [selene](https://github.com/kmhofmann/selene) • MIT -* [spdlog](https://github.com/gabime/spdlog) • MIT -* [stb](https://github.com/nothings/stb) • MIT -* [tinyobjloader](https://github.com/syoyo/tinyobjloader) • MIT -* [volk](https://github.com/zeux/volk) • MIT -* [Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) • Apache 2.0 -* [VulkanMemoryAllocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator) • MIT +* [argh](https://github.com/adishavit/argh) 3-clause BSD +* [bitmap](https://github.com/ArashPartow/bitmap) MIT +* [glfw](https://github.com/glfw/glfw) zlib +* [gli](https://github.com/g-truc/gli) MIT +* [glm](https://github.com/g-truc/glm) MIT +* [imgui](https://github.com/ocornut/imgui) MIT +* [json](https://github.com/nlohmann/json) MIT +* [physfs](https://github.com/Didstopia/physfs) zlib +* [selene](https://github.com/kmhofmann/selene) MIT +* [spdlog](https://github.com/gabime/spdlog) MIT +* [stb](https://github.com/nothings/stb) MIT +* [tinyobjloader](https://github.com/syoyo/tinyobjloader) MIT +* [volk](https://github.com/zeux/volk) MIT +* [Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) Apache 2.0 +* [VulkanMemoryAllocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator) MIT <br /> ## Collaborate -You can use the [issue tracker](https://github.com/liblava/liblava/issues) to report any bug or compatibility issue. +You can use the [issue tracker](https://github.com/liblava/liblava/issues) to report any bug or compatibility issue + +<br /> :heart: Thanks to all **[contributors](https://github.com/liblava/liblava/graphs/contributors)** making **liblava** flow... +<br /> + ### Support If you want to contribute, we suggest the following: @@ -88,17 +96,21 @@ If you want to contribute, we suggest the following: ## License -<a href="https://opensource.org" target="_blank"><img align="right" src="http://opensource.org/trademarks/opensource/OSI-Approved-License-100x137.png"></a> +<a href="https://opensource.org" target="_blank"><img align="right" width="80" src="http://opensource.org/trademarks/opensource/OSI-Approved-License-100x137.png" style="margin:0px 0px 0px 20px"></a> + +**liblava** is licensed under [MIT License](LICENSE.md) which allows you to use the software for any purpose you might like, including commercial and for-profit use! -**liblava** is licensed under [MIT License](LICENSE.md) which allows you to use the software for any purpose you might like, including commercial and for-profit use. +<br /> -However, this library includes several third-party **Open Source** libraries, which are licensed under their own respective licenses. They all allow static linking with closed source software. +However, this library includes several third-party **Open Source** libraries, which are licensed under their own respective licenses ⇒ They all allow static linking with closed source software -**All copies of liblava must include a copy of the MIT License terms and the copyright notice.** +**All copies of liblava must include a copy of the MIT License terms and the copyright notice** <br /> ##### Vulkan and the Vulkan logo are trademarks of the <a href="http://www.khronos.org" target="_blank">Khronos Group Inc.</a> ##### Copyright (c) 2018-present, <a href="https://lava-block.com">Lava Block OÜ</a> +<br /> + <a href="https://lava-block.com"><img src="https://github.com/liblava.png" width="50"></a>