nvpro-pipeline / vkhlf Goto Github PK

Experimental High Level Framework for Vulkan

License: BSD 3-Clause "New" or "Revised" License

CMake 3.34% C++ 96.66%

vkhlf's Introduction

Vulkan High Level Framework

VkHLF is an experimental high level abstraction library on top of Vulkan. It adds features like transparent suballocation, resource tracking on the CPU & GPU and simplified resource creation while staying as close as possible to the original Vulkan API. In contrast to Vulkan-Hpp, which was carefully designed to be a zero-overhead C++ abstraction for Vulkan, this library adds significant higher-level functionality. Even so, it has been designed for high-performance, but it can cost performance relative to native Vulkan if not employed with the intended usage patterns.

Since this project is in its early stages and under heavy development expect bugs and interface changes for a while. It should not be used for production code yet!

Build instructions

Clone the repository.
Execute git submodule update --init --recursive to get the 3rdparty dependencies. Alternatevely unpack glfw3 in 3rdparty/glfw and glslang in 3rdparty/glslang.
Install Vulkan SDK 1.0.37 or newer.
Run CMake to generate the makefiles of your choice.

VkHLF namespace

All handles and structs which hold handles have been replicated in the vkhlf namespace. For the other structs we simply use Vulkan-Hpp C++ bindings.

VkHLF Reference Counting

Vulkan requires the developer to keep the object hierarchy intact all the time. That is, destroying an object like the vk::Device before any of the objects created from it results in undefined behavior. It is also useful for a vk::CommandPool not to be destroyed if there are any vk::CommandBuffer objects left created by the same pool. To ensure that functionality VkHLF is using std::shared_ptr and std::weak_ptr to keep track of the parents or children of objects, i.e. a vk::DeviceMemory object is a child object of a vk::Device object, so it has to keep a std::shared_ptr to the vk::Device used for creation. This way the vk::Device stays alive as long as any vk::DeviceMemory or other child object exists and the destructor of any object has all the information required to destroy an object.

As a consequence to that structs containing handles or arrays of handles are no longer binary compatible with the native Vulkan API. This means that each time such a struct or array is being passed to Vulkan VkHLF has to copy data into a temporary struct or array and pass this one to Vulkan. Luckily this is not as bad as it seems since most of those copy operations are only at initialization time, but not during vk::CommandBuffer construction.

VkHLF Device Suballocator

Vulkan moves the device suballocation responsibility from the driver to the application. While it is usually possible to do thousands of buffer allocations in OpenGL without any failure it is likely to get a failure on Vulkan when doing one device allocation for each VkBuffer due to OS limitations. Thus application developers now have to implement device suballocators and keep track of the device/offset pair in the application. To simplify application development VkHLF provides the vkhlf::DeviceSuballocator interface which can be used for suballocation. The suballocator returns vkhlf::DeviceMemory objects which always store the offset in addition to the vk::DeviceMemory object. Each location which is using vkhlf::DeviceMemory will use the pair of vk::DeviceMemory and offset completely transparent to the developer.

VkHLF GPU Resource Tracking

Vulkan does not have any automatic resource tracking. It is possible to change or delete resources which are currently in use on the GPU which will most likely result in strange behaviour, or worst case in an application or system crash.

It is essential to ensure that resources do not get destroyed while they are still in use by the GPU. Thus we have implemented a vkhlf::ResourceTracker interface used by vkhlf::CommandBuffer to track all resources used to build up the command buffer.

In its current state resource tracking is an expensive operation if it is done on the fly while building up command buffers. Developers should try to avoid this cost by using one of the following techniques:

If possible, reuse command buffers over multiple frames.
Otherwise, reuse the tracking data. If it is known that the set of resources used by a command buffer does not change over multiple frames one can implement a version of the resource tracking interface which takes the tracking information of another resource tracker to keep the resources alive. In release mode this tracker does nothing, in debug mode it should validate that all used resources are already tracked.

Providing Pull Requests

NVIDIA is happy to review and consider pull requests for merging into the main tree of the nvpro-pipeline for bug fixes and features. Before providing a pull request to NVIDIA, please note the following:

A pull request provided to this repo by a developer constitutes permission from the developer for NVIDIA to merge the provided changes or any NVIDIA modified version of these changes to the repo. NVIDIA may remove or change the code at any time and in any way deemed appropriate.
Not all pull requests can be or will be accepted. NVIDIA will close pull requests that it does not intend to merge.
The modified files and any new files must include the unmodified NVIDIA copyright header seen at the top of all shipping files.

vkhlf's People

Contributors

Stargazers

Watchers

vkhlf's Issues

New SDK Compatibility

I noticed that the newer versions of the Vulkan SDK (1.0.42.1) moved the libraries from Bin/Bin32 -> Lib/Lib32. So people with the newer SDK may need to modify FindVulkan.cmake to account for this. Also had to replace VK_NULL_HANDLE with nullptr.

Missing/Incomplete include path configuration for glslang (Archlinux)

For Example Archlinux has a separate glsllang package.

In /vkhlf/ShaderModule.h it was necessary to change the following:

#include <vkhlf/Config.h>
#include <vkhlf/Types.h>
#include <vkhlf/Reference.h>
-#include <vulkan/../../glslang/glslang/Public/ShaderLang.h>
-#include <vulkan/../../glslang/SPIRV/GlslangToSpv.h>
+#include <glslang/glslang/Public/ShaderLang.h>
+#include <glslang/SPIRV/GlslangToSpv.h>
#include

PushConstants Data Type

Hello,
Why PushConstants are only uint8_t ArrayProxy? Vulkan Hpp version is templated, could you change it?

Thanks.

vkhlf::setImageLayout dont support vk::ImageSubresourceRange

Working with Vulkan for the first time, sorry if i misunderstood the API :)

I'm trying to upload a texture to gpu, but the function vkhlf::setImageLayout don't expose any way to work with mipmaps or layers. I changed function declaration from vk::ImageAspectFlags aspectMask to const vk::ImageSubresourceRange &subResourceRange

Is the correct way to use VkHLF or i missed something?

Thx for all your open source Vk contibutions.

Non C++ compilant sources (VC++)

The source could neither be compiled with GCC 6.3 or Clang 3.9:

Unspecialized members are not allowed.

gcc (GCC) 6.3.1

vulkan/VkHLF/vkhlf/Reference.h:52:16: error: explicit specialization in non-namespace scope 'class vkhlf::Reference<T, Ts ...>'
template<>

clang version 3.9.1

vulkan/VkHLF/vkhlf/Reference.h:53:33: error: cannot specialize a function 'get' within class scope
std::shared_ptr const& get() const { return m_head; };

CMake Project: C++ depends on C++14 compatibility, but cmake project is not configured to require C++14

Can be solved by including the line

set(CMAKE_CXX_STANDARD 14)

into the topmost CMakeLists.txt file.

Is there any future roadmap?

Hi @asuessenbach @mtavenrath , I see that this project hasn't had a lot of activity in quite some time, so I would like to confirm a few things, if possible.

Are there any plans for an upcoming release of any kind (maintenance / new features)?
I see no feedback on open PRs, is it opportune to open new ones if necessary?

Thanks

Build instructions incomplete

The sample solution appears to depend on corresponding locally created builds of the VulkanSDK glslang and spirv-tools projects, but they are not mentioned in the build instructions.

Rename it

My idea is MAGMA, because it fits to Vulkan mich better, how do u guys think about! I mean if it comes to a standardisation?

Dead project?

I like the pitch and the style of the code here, but as a new Vk developer the age of the code and lack of updates, news and communication is giving me bad vibes.

Is this project abandoned, and more importantly, is it outdated?

As a newcomer I don't have the expertise to tell if the tech here has been left behind, nor where else I should look for newer, active alternatives.

Is GLFW still usefull?

I used GLFW a lot for Linux/OpenGL but is it still useful as abstraction mechanism for VK? With the "Create Vulkan instance, connect window, setup device" - Workflow it takes me additional 100 lines to open a window and I don't need choose between GLFW - X11 of GLFW -Wayland libraries which are mutually exclusive under Archlinux.

setImageLayout() uses invalid stages for pipeline barrier

Specs for vkCmdPipelineBarrier state that:

Any given element of pMemoryBarriers, pBufferMemoryBarriers or pImageMemoryBarriers must not have any access flag included in its srcAccessMask member if that bit is not supported by any of the pipeline stages in srcStageMask, as specified in the table of supported access types.

According to the table in Vulkan specs eTopOfPipe is not supported by any access flags.

But at the moment, setImageLayout prepares pipeline barrier with these invalid arguments:

commandBuffer->pipelineBarrier(vk::PipelineStageFlagBits::eTopOfPipe, vk::PipelineStageFlagBits::eTopOfPipe, {}, nullptr, nullptr, imageMemoryBarrier);

Standard validation layers detect this issue on any call to setImageLayout.

CMake project: VULKAN_SDK environment variable

The cmake project uses an environment variable VK_SDK_PATH.

By switching to VULKAN_SDK, the cmake project would be better compatible with the environment variables already provided by the Vulkan-SDK.

Case sensitivity in CMakeLists.txt on Linux systems

samples/01_window/CMakeLists.txt:32 has the line find_package(glfw3 3.2 REQUIRED) which will fail on case sensitive systems because the corresponding file is FindGLFW3.cmake. The easy fix is to change the CMakeLists.txt to use find_package(GLFW3 3.2 REQUIRED). Unfortunately I can't submit pull requests from where I am but when I get to a place where I can I'll throw that up for you.

Image.cpp refers to absolute filesystem path

It contains #include <D:\git\vulkan\src\spec\vulkan_ext.h>

using weak_ptr to cache queues leads to problems

If the queue has a submission pending a fence and gets destroyed the submission info also gets released even if the fence hasn't been triggered.

Then if you get the queue again from the Device the queue will appear to have no submissions:

{
  auto queue = device->getQueue(0,0);
  queue->submit(submit,null_ptr);
}
//queue is destroyed and submit info is lost regardless of whether the fence was triggered
{
  auto queue = device->getQueue(0,0);
  // no submit info available
}

Currently it's not a problem because the information is never used. But if it's never used then why keep it in the first place?

Related to this is that getting the same queue from 2 different threads is not thread-safe due to the lazy initialization.