ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
10357 Commits
21 Branches
19 Tags
70 MiB
Tree: bbfa5aeccf
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'bbfa5aeccf'
${ noResults }
magnum/src/Magnum/Vk/Device.h

522 lines
23 KiB
Raw Normal View History Unescape

Vk: expose all extensions for version 1.2. Also provide compile-time info with them, a runtime list and everything else similar to what's done for GL.
6 years ago
#ifndef Magnum_Vk_Device_h
#define Magnum_Vk_Device_h
/*
This file is part of Magnum.
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
Updated copyright year.
4 years ago
2020, 2021, 2022 Vladimír Vondruš <mosra@centrum.cz>
Vk: expose all extensions for version 1.2. Also provide compile-time info with them, a runtime list and everything else similar to what's done for GL.
6 years ago
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
*/
/** @file
Vk: put CreateInfo structures to dedicated headers. After I implemented the render pass wrapper, seeing how the RenderPassCreateInfo structure and its dependencies were HUGE compared to the actual tiny and lean RenderPass, I felt uneasy dragging their definition along to every place where a RenderPass gets used. It's not as bad with the others, but as new extensions are implemented I expect that to get the same. This change makes it easier for me to accept that Image.h / Buffer.h depends on Memory.h. There isn't a real measurable difference when building Magnum itself (50 ms out of 7 seconds for the Vk library alone), but that's because most of the code (and tests) needs the CreateInfo structures anyway.
5 years ago
* @brief Class @ref Magnum::Vk::Device
Vk: expose all extensions for version 1.2. Also provide compile-time info with them, a runtime list and everything else similar to what's done for GL.
6 years ago
* @m_since_latest
*/
#include <cstddef>
Vk: implement Device feature enablement. This was way more pain that initially expected, especially in regards to preserving externally-specified pNext chains without writing to them in any way.
5 years ago
#include <Corrade/Containers/BigEnumSet.h>
Vk: device creation.
6 years ago
#include <Corrade/Containers/Pointer.h>
#include "Magnum/Tags.h"
Math: rename BoolVector to BitVector. Because it somewhat confusingly may have implied that it's really composed of 8-bit bools, and not bits. The same reasoning was used to pick the name for Corrade's Containers::BitArray. Backwards compatibility aliases are in place as usual, however the internal BoolVectorConverter is now BitVectorConverter and there unfortunately cannot be any backwards compatibility. This breaks only GLM and Eigen integration in the magnum-integration repo, which I'm fixing immediately. I don't expect any user code to use this internal helper. For regular vectors maybe, for this one definitely not.
4 years ago
#include "Magnum/Math/BitVector.h"
Vk: device creation.
6 years ago
#include "Magnum/Vk/TypeTraits.h"
#include "Magnum/Vk/Vk.h"
#include "Magnum/Vk/Vulkan.h"
#include "Magnum/Vk/visibility.h"
Vk: expose all extensions for version 1.2. Also provide compile-time info with them, a runtime list and everything else similar to what's done for GL.
6 years ago
namespace Magnum { namespace Vk {
namespace Implementation {
external: expose VK_KHR_copy_commands2. At this point it's getting easier to say which commands *don't* have a "V2" yet.
5 years ago
enum: std::size_t { ExtensionCount = 96 };
Vk: device creation.
6 years ago
struct DeviceState;
Vk: expose all extensions for version 1.2. Also provide compile-time info with them, a runtime list and everything else similar to what's done for GL.
6 years ago
}
Vk: device creation.
6 years ago
/**
@brief Device
@m_since_latest
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Wraps a @type_vk_keyword{Device} and stores device-specific Vulkan function
Vk: add a short human-readable description to each Vulkan object.
5 years ago
pointers. A device provides an abstraction over a physical GPU or a CPU with
Vulkan capabilities.
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
doc: cnsistently reference all Magnum CLI tools from related APIs.
5 years ago
@m_class{m-note m-success}
@par
There's also the @ref magnum-vk-info "magnum-vk-info" tool that provides
access to Vulkan instance and device version, layer, extension and feature
information through a command line interface.
Vk: rethink "creation" docs. Although the APIs don't look like that right now, in many cases creation of a particular Vulkan object isn't all that's there for it. So change the section names from a generic "Usage" to "Creation".
5 years ago
@section Vk-Device-creation Device creation
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
With an @ref Instance ready, a device has to be picked first. Commonly it's
done by calling @ref pickDevice() and letting the library choose. This
selection is affected by the `--magnum-device`
@ref Vk-Device-command-line "command-line option", giving the end users an
ability to pick a particular device, choose a discrete or integrated GPU or
even a software implementation. If the application needs something specific,
you can use @ref enumerateDevices() instead, pick a device from the list
manually, provide the users with a list to choose from etc.
Vk: DeviceCreateInfo::addQueues() overload taking QueueFlags directly. More convenient to use since one doesn't have to explicitly store a DeviceProperties instance to call pickQueueFamily() on it and then move it to DeviceCreateInfo to keep it efficient. This required a slight redesign of how DeviceProperties are stored in DeviceCreateInfo, now we need the instance to be always valid (but it can get never used). The wrap() API isn't doing any extra work so this won't add any inefficiency.
6 years ago
The picked device is then passed to @ref DeviceCreateInfo. At the very least
you'll also need to set up queues, as every Vulkan device needs at least one.
That's done by creating an empty @ref Queue instance and then referencing it
from @ref DeviceCreateInfo::addQueues(). After the device is constructed, the
queue gets populated and is ready to be used.
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Vk: rethink "creation" docs. Although the APIs don't look like that right now, in many cases creation of a particular Vulkan object isn't all that's there for it. So change the section names from a generic "Usage" to "Creation".
5 years ago
@snippet MagnumVk.cpp Device-creation-construct-queue
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Vk: DeviceCreateInfo::addQueues() overload taking QueueFlags directly. More convenient to use since one doesn't have to explicitly store a DeviceProperties instance to call pickQueueFamily() on it and then move it to DeviceCreateInfo to keep it efficient. This required a slight redesign of how DeviceProperties are stored in DeviceCreateInfo, now we need the instance to be always valid (but it can get never used). The wrap() API isn't doing any extra work so this won't add any inefficiency.
6 years ago
In the above snippet, we requested a graphics queue via a convenience API. The
information about available queues and other device properties is stored in a
@ref DeviceProperties that got returned from @ref pickDevice() and
@ref DeviceCreateInfo called @ref DeviceProperties::pickQueueFamily() for us.
As with device picking, you can also iterate through all
@ref DeviceProperties::queueFamilyCount() and choose one manually.
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Same as with @ref Instance, the above won't enable any additional extensions
Vk: doc++
5 years ago
except for what the engine itself needs or what's supplied on the command line.
Use @ref DeviceCreateInfo::addEnabledExtensions() to enable them, you can use
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
both string names as well as predefined *device* extensions from the
@ref Extensions namespace. Later on, presence of predefined extensions can be
checked with @ref isExtensionEnabled().
Vk: rethink "creation" docs. Although the APIs don't look like that right now, in many cases creation of a particular Vulkan object isn't all that's there for it. So change the section names from a generic "Usage" to "Creation".
5 years ago
@snippet MagnumVk.cpp Device-creation-extensions
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Vk: implement Device feature enablement. This was way more pain that initially expected, especially in regards to preserving externally-specified pNext chains without writing to them in any way.
5 years ago
In addition to extensions, you'll be usually enabling features as well. These
are all exposed in a giant @ref DeviceFeatures enum and you can simply OR them
together. Internally, those get translated to @type_vk{PhysicalDeviceFeatures2}
and related structures, features that are not exposed in the enum can be
enabled by adding a corresponding structure to the `pNext` chain. As with
extensions, the set of enabled features can be later checked with
@ref enabledFeatures().
@snippet MagnumVk.cpp Device-creation-features
However, usually you'll be checking for extension and feature availability
first, which is doable through
@ref DeviceProperties::enumerateExtensionProperties() and
@ref ExtensionProperties::isSupported() for extensions, and
@ref DeviceProperties::features() for features. In case of features you can
make use of the enum set operations and simply mask away features that are not
available --- however note that some features also require an extension to be
explicitly enabled.
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Vk: rethink "creation" docs. Although the APIs don't look like that right now, in many cases creation of a particular Vulkan object isn't all that's there for it. So change the section names from a generic "Usage" to "Creation".
5 years ago
@snippet MagnumVk.cpp Device-creation-check-supported
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
With both @ref Instance and @ref Device created, you can proceed to setting up
VK: doc++
5 years ago
a @ref CommandPool and a @ref Pipeline, which will then need a
@ref ShaderSet and a @ref PipelineLayout. For rasterization pipelines, you'll
additionally need a @ref MeshLayout and a @ref RenderPass.
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
Vk: expose and implement KHR_portability_subset.
5 years ago
@subsection Vk-Device-portability-subset Vulkan portability subset
To simplify porting to platforms with the Portability Subset, Magnum implicitly
enables the @vk_extension{KHR,portability_subset} extension on all devices that
advertise it, as required by the spec, so you don't need to handle that part.
This behavior can be disabled with
@ref DeviceCreateInfo::Flag::NoImplicitExtensions.
For portability-related @ref DeviceFeatures, on conformant Vulkan
implementations (which don't advertise @vk_extension{KHR,portability_subset})
these are all implicitly marked as supported in @ref DeviceProperties::features()
and then implicitly marked as enabled in @ref Device::enabledFeatures(),
independently of whether you enable them or not. On devices having only the
Portability Subset, the supported features are listed in
@ref DeviceProperties::features() but you're expected to manually enable them
on device creation --- that part is *not done implicitly* by the engine.
A workflow that supports both conformant and Portability Subset devices with a
single code path is outlined in the following snippet --- on device creation
you request features that you want (which is a no-op on conformant
implementations), and at runtime you query those features in appropriate cases
(which will be always @cpp true @ce on conformant implementations). As with
other features, all APIs that require a particular Portability Subset feature
are marked as such and also listed among others at @ref requires-vk-feature.
@snippet MagnumVk.cpp Device-creation-portability-subset
doc: property retrieval optimization isn't essentially needed. Thus it has no place in the general overview docs of Vk::Instance and Vk::Device. Better to put it into the VUlkan wrapping docs, where it also makes sense to have both the device and instance side together.
6 years ago
@see @ref vulkan-wrapping-optimizing-properties
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
@section Vk-Device-command-line Command-line options
The @ref Device inherits a subset of the
@ref Vk-Instance-command-line "Instance command-line options", in particular
the following. If the @ref Instance didn't get `argc` / `argv` passed, only the
environment variables are used.
Vk: add driver workaround scaffolding and the first one for SwiftShader. Yay? It's funny, what produces correct result causes validation errors. I suppose this will be very similar for all other workarounds.
5 years ago
- `--magnum-disable-workarounds LIST` --- Vulkan driver workarounds to
disable (see @ref vulkan-workarounds for detailed info) (environment:
`MAGNUM_DISABLE_WORKAROUNDS`)
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
- `--magnum-disable-extensions LIST` --- Vulkan instance or device extensions
to disable, meaning @ref DeviceCreateInfo::addEnabledExtensions() will skip
them (environment: `MAGNUM_DISABLE_EXTENSIONS`)
- `--magnum-enable-extensions LIST` --- Vulkan device extensions to enable in
addition to @ref DeviceCreateInfo defaults and what the application
requests (environment: `MAGNUM_ENABLE_EXTENSIONS`)
- `--magnum-vulkan-version X.Y` --- force @ref Device Vulkan version instead
of using what the device reports as supported, affecting what entrypoints
and extensions get used (environment: `MAGNUM_VULKAN_VERSION`)
- `--magnum-log default|quiet|verbose` --- console logging (environment:
`MAGNUM_LOG`) (default: `default`)
- `--magnum-device ID|integrated|discrete|virtual|cpu` --- device ID or kind
to pick in @ref pickDevice(); if a device is selected through
@ref enumerateDevices() or any other way, this option has no effect
(environment: `MAGNUM_DEVICE`)
@section Vk-Device-raw Interaction with raw Vulkan code
In addition to the common properties explained in @ref vulkan-wrapping-raw,
the @ref Device contains device-level Vulkan function pointers, accessible
through @ref operator->():
@snippet MagnumVk.cpp Device-function-pointers
These functions are by default not accessible globally (and neither there is a
global "current instance"), which is done in order to avoid multiple
independent instances affecting each other. Sometimes it is however desirable
to have global function pointers --- for example when a 3rd party code needs to
operate on the same instance, or when writing quick prototype code --- and then
it's possible to populate those using @ref populateGlobalFunctionPointers().
Compared to the above, the same custom code would then look like this:
@snippet MagnumVk.cpp Device-global-function-pointers
Similarly you can use @ref Instance::populateGlobalFunctionPointers() to
populate instance-level global function pointers.
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
@section Vk-Device-disabled-move Disabled move and delayed device creation
Due to the way @ref Queue instances are populated on device creation, and
for safety reasons as all device-dependent objects internally have to keep a
pointer to the originating @ref Device to access Vulkan function pointers, the
@ref Device class is not movable. This leads to a difference compared to other
Vulkan object wrappers, where you can use the @ref NoCreate tag to construct an
empty instance (for example as a class member) and do a delayed creation by
moving a new instance over the empty one. Here you have to use the
@ref create() function instead:
@snippet MagnumVk.cpp Device-delayed-creation
Similar case is with @ref wrap() --- instead of being @cpp static @ce, you have
Vk: make the Instance immovable as well.
5 years ago
to call it on a @ref Device(NoCreateT) "NoCreate"'d instance. The @ref Instance
class behaves equivalently.
Vk: device creation.
6 years ago
*/
class MAGNUM_VK_EXPORT Device {
public:
/**
* @brief Wrap existing Vulkan handle
Vk: pass VkPhysicalDevice to Device::wrap(). It's needed in order to access Device::properties(), which is mandatory for the driver workarounds happening in the next commit.
5 years ago
* @param instance Vulkan instance the device is created on
* @param physicalDevice Physical device the @type_vk{VkDevice} was
* created from. Used to populate @ref properties().
* @param handle The @type_vk{Device} handle
* @param version Vulkan version that's assumed to be used on
* the device
Vk: device creation.
6 years ago
* @param enabledExtensions Extensions that are assumed to be enabled
Vk: doc++
5 years ago
* on the device
Vk: pass VkPhysicalDevice to Device::wrap(). It's needed in order to access Device::properties(), which is mandatory for the driver workarounds happening in the next commit.
5 years ago
* @param enabledFeatures Features that are assumed to be enabled on
Vk: implement Device feature enablement. This was way more pain that initially expected, especially in regards to preserving externally-specified pNext chains without writing to them in any way.
5 years ago
* the device
Vk: pass VkPhysicalDevice to Device::wrap(). It's needed in order to access Device::properties(), which is mandatory for the driver workarounds happening in the next commit.
5 years ago
* @param flags Handle flags
Vk: device creation.
6 years ago
*
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
* <b></b>
*
* @m_class{m-note m-warning}
*
* @par
* Unlike with other Vulkan object wrappers, this isn't a
* @cpp static @ce function returning a new @ref Device, instead
* it's expected to be called on a @ref NoCreate "NoCreate"'d
* instance. See @ref Vk-Device-disabled-move for more
* information.
*
Vk: pass VkPhysicalDevice to Device::wrap(). It's needed in order to access Device::properties(), which is mandatory for the driver workarounds happening in the next commit.
5 years ago
* The @p handle is expected to be originating from @p instance and
* @p physicalDevice. The @p version, @p enabledExtensions and
* @p enabledFeatures parameters populate internal info about supported
* version, enabled extensions and enabled features and will be
* reflected in @ref isVersionSupported(), @ref isExtensionEnabled()
* and @ref enabledFeatures(), among other things. If
* @p enabledExtensions / @p enabledFeatures is empty, the device will
* behave as if no extensions / no features were enabled.
Vk: device creation.
6 years ago
*
Vk: add driver workaround scaffolding and the first one for SwiftShader. Yay? It's funny, what produces correct result causes validation errors. I suppose this will be very similar for all other workarounds.
5 years ago
* @m_class{m-note m-danger}
*
* @par
* Due to the extension / feature list being outside of library
* control here, driver bug workarounds are not detected and
* enabled when using this function. Depending on bug severity,
* that may lead to crashes and unexpected behavior that wouldn't
* otherwise happen with a @ref Device created the usual way.
*
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
* Note that this function retrieves all device-specific Vulkan
* function pointers, which is a relatively costly operation. It's thus
* not recommended to call this function repeatedly for creating
* short-lived device instances, even though it's technically correct.
*
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
* Unlike a device created using the constructor or @ref create(), the
* Vulkan device is by default not deleted on destruction. Use @p flags
* for different behavior.
Vk: device creation.
6 years ago
* @see @ref release()
*/
Vk: use StringIterable for all extension/layer/workaround lists. No backwards compatibility headers as the whole Vulkan wrapper is still considered experimental. So people should expect pain and suffering.
4 years ago
void wrap(Instance& instance, VkPhysicalDevice physicalDevice, VkDevice handle, Version version, const Containers::StringIterable& enabledExtensions, const DeviceFeatures& enabledFeatures, HandleFlags flags = {});
Vk: device creation.
6 years ago
/**
* @brief Constructor
*
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
* Equivalent to calling @ref Device(NoCreateT) followed by
* @ref create(Instance&, const DeviceCreateInfo&).
Vk: device creation.
6 years ago
*/
explicit Device(Instance& instance, const DeviceCreateInfo& info);
Vk: it's inevitable, DeviceProperties are going to stay forever. I have more and more cases where I need to query device properties later down the road (memory capabilities, device name, ...) and leaving all this up to the user / making this impossible to do in the library internals is complicating everything too much. Since there's a shitton of device properties with a new bag of props coming with every other new extension, I expect the queries to get quite involved / complicated over time (chaining 100s structs and such), so let's design this upfront in a way that can avoid reqpeatedly querying the same thing just because we needlessly discarded a fully populated instance before. It also means the users don't need to drag their own DeviceProperties instance along anymore and can just let the Device take care of that. Unfortunately the only nice way to make this work with DeviceCreateInfo method chaining is to add & and && overloads for each. But it's quite easy to test that all of them work and properly return a r-value reference so it shouldn't be too much of a maintenance nightmare.
6 years ago
/**
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
* @brief Construct, reusing already populated device properties
Vk: it's inevitable, DeviceProperties are going to stay forever. I have more and more cases where I need to query device properties later down the road (memory capabilities, device name, ...) and leaving all this up to the user / making this impossible to do in the library internals is complicating everything too much. Since there's a shitton of device properties with a new bag of props coming with every other new extension, I expect the queries to get quite involved / complicated over time (chaining 100s structs and such), so let's design this upfront in a way that can avoid reqpeatedly querying the same thing just because we needlessly discarded a fully populated instance before. It also means the users don't need to drag their own DeviceProperties instance along anymore and can just let the Device take care of that. Unfortunately the only nice way to make this work with DeviceCreateInfo method chaining is to add & and && overloads for each. But it's quite easy to test that all of them work and properly return a r-value reference so it shouldn't be too much of a maintenance nightmare.
6 years ago
*
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
* Equivalent to calling @ref Device(NoCreateT) followed by
* @ref create(Instance&, DeviceCreateInfo&&).
Vk: it's inevitable, DeviceProperties are going to stay forever. I have more and more cases where I need to query device properties later down the road (memory capabilities, device name, ...) and leaving all this up to the user / making this impossible to do in the library internals is complicating everything too much. Since there's a shitton of device properties with a new bag of props coming with every other new extension, I expect the queries to get quite involved / complicated over time (chaining 100s structs and such), so let's design this upfront in a way that can avoid reqpeatedly querying the same thing just because we needlessly discarded a fully populated instance before. It also means the users don't need to drag their own DeviceProperties instance along anymore and can just let the Device take care of that. Unfortunately the only nice way to make this work with DeviceCreateInfo method chaining is to add & and && overloads for each. But it's quite easy to test that all of them work and properly return a r-value reference so it shouldn't be too much of a maintenance nightmare.
6 years ago
*/
explicit Device(Instance& instance, DeviceCreateInfo&& info);
Vk: device creation.
6 years ago
/**
* @brief Construct without creating the device
*
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
* Use @ref create() or @ref tryCreate() to create the device.
Vk: device creation.
6 years ago
*/
explicit Device(NoCreateT);
/** @brief Copying is not allowed */
Device(const Device&) = delete;
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
/**
* @brief Moving is not allowed
*
* See @ref Vk-Device-disabled-move for more information.
*/
Device(Device&& other) = delete;
Vk: device creation.
6 years ago
/**
* @brief Destructor
*
* Destroys associated @type_vk{Device} handle, unless the instance
* was created using @ref wrap() without @ref HandleFlag::DestroyOnDestruction
* specified.
* @see @fn_vk_keyword{DestroyDevice}, @ref release()
*/
~Device();
/** @brief Copying is not allowed */
Device& operator=(const Device&) = delete;
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
/**
* @brief Moving is not allowed
*
* See @ref Vk-Device-disabled-move for more information.
*/
Device& operator=(Device&&) = delete;
Vk: device creation.
6 years ago
/** @brief Underlying @type_vk{Device} handle */
VkDevice handle() { return _handle; }
/** @overload */
operator VkDevice() { return _handle; }
/** @brief Handle flags */
HandleFlags handleFlags() const { return _flags; }
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
/**
* @brief Create a device
* @param instance Vulkan instance to create the device on
* @param info Device creation info
*
* Meant to be called on a @ref Device(NoCreateT) "NoCreate"'d
* instance. After creating the device populates device-level
* function pointers and runtime information about enabled extensions
* and features based on @p info, and finally requests device queues
* added via @ref DeviceCreateInfo::addQueues(), populating the
* @ref Queue references.
*
* If device creation fails, a message is printed to error output and
* the application exits --- if you need a different behavior, use
* @ref tryCreate() instead.
* @see @ref Device(Instance&, const DeviceCreateInfo&),
* @fn_vk_keyword{CreateDevice}, @fn_vk_keyword{GetDeviceQueue2},
* @fn_vk_keyword{GetDeviceQueue}
* @todoc link to a concrete addQueues() overload above once doxygen
* finally GROWS UP and can link to &-qualified functions FFS
*/
void create(Instance& instance, const DeviceCreateInfo& info);
/**
* @brief Create a device, reusing already populated device properties
*
* Compared to @ref create(Instance&, const DeviceCreateInfo&), it can
* take ownership of the @ref DeviceProperties added to @p info earlier
* via @ref DeviceCreateInfo::DeviceCreateInfo(DeviceProperties&&, const ExtensionProperties*, Flags)
* or any of the other r-value-taking constructors.
*
* With that, the @ref properties() getter and any APIs relying on it
* can reuse what was possibly already queried without having to repeat
* the potentially complex queries second time.
* @see @ref Device(Instance&, DeviceCreateInfo&&),
* @ref tryCreate(Instance&, DeviceCreateInfo&&)
*/
void create(Instance& instance, DeviceCreateInfo&& info);
/**
* @brief Try to create a device
*
* Unlike @ref create(Instance&, const DeviceCreateInfo&), instead of
* exiting on error, prints a message to error output and returns a
* corresponding result value. On success returns @ref Result::Success.
*/
Result tryCreate(Instance& instance, const DeviceCreateInfo& info);
/**
* @brief Try to create a device, reusing already populated device properties
*
* Unlike @ref create(Instance&, DeviceCreateInfo&&), instead of
* exiting on error, prints a message to error output and returns a
* corresponding result value. On success returns @ref Result::Success.
*/
Result tryCreate(Instance& instance, DeviceCreateInfo&& info);
Vk: it's inevitable, DeviceProperties are going to stay forever. I have more and more cases where I need to query device properties later down the road (memory capabilities, device name, ...) and leaving all this up to the user / making this impossible to do in the library internals is complicating everything too much. Since there's a shitton of device properties with a new bag of props coming with every other new extension, I expect the queries to get quite involved / complicated over time (chaining 100s structs and such), so let's design this upfront in a way that can avoid reqpeatedly querying the same thing just because we needlessly discarded a fully populated instance before. It also means the users don't need to drag their own DeviceProperties instance along anymore and can just let the Device take care of that. Unfortunately the only nice way to make this work with DeviceCreateInfo method chaining is to add & and && overloads for each. But it's quite easy to test that all of them work and properly return a r-value reference so it shouldn't be too much of a maintenance nightmare.
6 years ago
/**
* @brief Device properties
*
* If a r-value @ref DeviceProperties instance was propagated to
* @ref DeviceCreateInfo and then to @ref Device, it's reused here.
* Otherwise the contents are populated on first use.
*/
DeviceProperties& properties() { return *_properties; }
Vk: document relation among various version queries.
6 years ago
/**
* @brief Version supported by the device
*
Fix typos
5 years ago
* Unless overridden using `--magnum-vulkan-version` on the
Vk: document relation among various version queries.
6 years ago
* @ref Vk-Device-command-line "command line", corresponds to
Vk: rework device property fetching. Today I spent six hours wrongly convincing myself that it's a driver bug when vkGetPhysicalDeviceProperties2() is null on a 1.1 instance for a 1.0 physical device. It's not a bug, it's me not reading specs carefully. This commit thus basically moves all Instance-level extension-dependent state to DeviceProperties, because it's actually device-dependent. Which makes the DeviceProperties class quite heavy and thus it's good it was readied to be transferred all the way to a Device instance a few commits back -- I don't really want to do all the dispatch, string processing, sorting and other mess more times than strictly necessary. In addition, DeviceProperties::apiVersion() got renamed to version() and a new isVersionSupported() API got added, mirroring what's on Device itself; plus thanks to the chicken-and-egg problem of having to call vkGetPhysicalDeviceProperties() twice, the device version and other things can now be retrieved in a slightly more efficient way.
6 years ago
* @ref DeviceProperties::version().
Vk: document relation among various version queries.
6 years ago
*/
Vk: device creation.
6 years ago
Version version() const { return _version; }
Vk: document relation among various version queries.
6 years ago
/**
* @brief Whether given version is supported on the device
*
* Compares @p version against @ref version().
*/
Vk: device creation.
6 years ago
bool isVersionSupported(Version version) const {
return _version >= version;
}
/**
* @brief Whether given extension is enabled
*
* Accepts device extensions from the @ref Extensions namespace, listed
* also in the @ref vulkan-support "Vulkan support tables". Search
* complexity is @f$ \mathcal{O}(1) @f$. Example usage:
*
* @snippet MagnumVk.cpp Device-isExtensionEnabled
*
* Note that this returns @cpp true @ce only if given extension is
Vk: doc++ Buncha brainfarts in there.
5 years ago
* supported by the driver *and* it was enabled via
* @ref DeviceCreateInfo::addEnabledExtensions(). For querying
Vk: device creation.
6 years ago
* extension support before creating a device use
* @ref ExtensionProperties::isSupported().
*/
template<class E> bool isExtensionEnabled() const {
static_assert(Implementation::IsExtension<E>::value, "expected a Vulkan device extension");
Vk: rename private Device member for clarity.
5 years ago
return _enabledExtensions[E::Index];
Vk: device creation.
6 years ago
}
/** @overload */
bool isExtensionEnabled(const Extension& extension) const;
Vk: implement Device feature enablement. This was way more pain that initially expected, especially in regards to preserving externally-specified pNext chains without writing to them in any way.
5 years ago
/**
* @brief Features enabled on the device
*
Vk: doc++ Buncha brainfarts in there.
5 years ago
* @see @ref DeviceCreateInfo::setEnabledFeatures(),
* @ref DeviceProperties::features()
Vk: implement Device feature enablement. This was way more pain that initially expected, especially in regards to preserving externally-specified pNext chains without writing to them in any way.
5 years ago
*/
const DeviceFeatures& enabledFeatures() const { return _enabledFeatures; }
Vk: device creation.
6 years ago
/**
* @brief Device-specific Vulkan function pointers
*
* Function pointers are implicitly stored per-device, use
* @ref populateGlobalFunctionPointers() to populate the global `vk*`
* functions.
*/
const FlextVkDevice& operator*() const { return _functionPointers; }
/** @overload */
const FlextVkDevice* operator->() const { return &_functionPointers; }
/**
* @brief Release the underlying Vulkan device
*
* Releases ownership of the Vulkan device and returns its handle so
* @fn_vk{DestroyDevice} is not called on destruction. The internal
* state is then equivalent to moved-from state.
* @see @ref wrap()
*/
VkDevice release();
/**
* @brief Populate global device-level function pointers to be used with third-party code
*
* Populates device-level global function pointers so third-party
Vk: start writing some actual docs. Because I put this on hold for two months and almost forgot what design guidelines I wanted to follow and how the heck is the whole thing used.
6 years ago
* code is able to call global device-level `vk*` functions. See
* @ref Vk-Device-raw for more information.
Vk: device creation.
6 years ago
*
* @attention This operation is changing global state. You need to
Typo: simultaenous -> simultaneous.
5 years ago
* ensure that this function is not called simultaneously from
Vk: device creation.
6 years ago
* multiple threads and code using those function points is
* calling them with the same device as the one returned by
* @ref handle().
*/
void populateGlobalFunctionPointers();
#ifdef DOXYGEN_GENERATING_OUTPUT
private:
#endif
Implementation::DeviceState& state() { return *_state; }
private:
Vk: a non-error-prone way to retrieve queues after device creation. I wonder why this couldn't be done this way in the Vulkan API directly.
6 years ago
friend Implementation::DeviceState;
Vk: make the Device immovable. There was a nasty issue when moving the Device -- because the Queue instances are populated with the Device pointer in the constructor, moving the Device makes the Queue device pointer invalid and those instances are useless. Discovered this when using VulkanTester to test an upcoming Queue::submit() -- until then, the Device pointer in the Queue wasn't really used for anything and so this wasn't known. Making the Device immovable is thus the only sane way to keep the current Queue retrieval workflow, which I'd say is much cleaner than having to manually query the device for queues later using some error-prone indices and whatnot. On the other hand, this finally makes it possible to have a failable device creation, instead of the device creation failing on an assert (or failing silently when CORRADE_NO_ASSERT is defined). This is consistent with how the GL wrapper works. Also, because all device-dependent objects need to keep a pointer to the originating Device in order to access Vulkan function pointers, having it immovable makes it considerably faster. I'll make Instance immovable with tryCreate() next because it seems like a good thing to do there as well.
5 years ago
/* Common guts for tryCreate(Instance&, DeviceCreateInfo&) and
tryCreate(Instance&, DeviceCreateInfo&&) */
Result tryCreateInternal(Instance& isntance, const DeviceCreateInfo&, DeviceProperties&&);
Vk: it's inevitable, DeviceProperties are going to stay forever. I have more and more cases where I need to query device properties later down the road (memory capabilities, device name, ...) and leaving all this up to the user / making this impossible to do in the library internals is complicating everything too much. Since there's a shitton of device properties with a new bag of props coming with every other new extension, I expect the queries to get quite involved / complicated over time (chaining 100s structs and such), so let's design this upfront in a way that can avoid reqpeatedly querying the same thing just because we needlessly discarded a fully populated instance before. It also means the users don't need to drag their own DeviceProperties instance along anymore and can just let the Device take care of that. Unfortunately the only nice way to make this work with DeviceCreateInfo method chaining is to add & and && overloads for each. But it's quite easy to test that all of them work and properly return a r-value reference so it shouldn't be too much of a maintenance nightmare.
6 years ago
Vk: port away from std::pair in various internals. Among other things this makes it possible to use Utility::copy() instead of a manual loop and grow arrays with std::realloc() instead of always new'ing-copy-deleting because Containers::Pair is trivially copyable.
3 years ago
MAGNUM_VK_LOCAL void initialize(Instance& instance, Version version, const Containers::StringIterable& enabledExtensions, Containers::Array<Containers::Pair<Containers::StringView, bool>>& encounteredWorkarounds, const DeviceFeatures& enabledFeatures);
Vk: device creation.
6 years ago
Vk: a non-error-prone way to retrieve queues after device creation. I wonder why this couldn't be done this way in the Vulkan API directly.
6 years ago
MAGNUM_VK_LOCAL static void getQueueImplementationDefault(Device& self, const VkDeviceQueueInfo2& info, VkQueue& queue);
MAGNUM_VK_LOCAL static void getQueueImplementation11(Device& self, const VkDeviceQueueInfo2& info, VkQueue& queue);
Vk: device creation.
6 years ago
VkDevice _handle;
HandleFlags _flags;
Version _version;
Math: rename BoolVector to BitVector. Because it somewhat confusingly may have implied that it's really composed of 8-bit bools, and not bits. The same reasoning was used to pick the name for Corrade's Containers::BitArray. Backwards compatibility aliases are in place as usual, however the internal BoolVectorConverter is now BitVectorConverter and there unfortunately cannot be any backwards compatibility. This breaks only GLM and Eigen integration in the magnum-integration repo, which I'm fixing immediately. I don't expect any user code to use this internal helper. For regular vectors maybe, for this one definitely not.
4 years ago
Math::BitVector<Implementation::ExtensionCount> _enabledExtensions;
Vk: implement Device feature enablement. This was way more pain that initially expected, especially in regards to preserving externally-specified pNext chains without writing to them in any way.
5 years ago
DeviceFeatures _enabledFeatures;
Vk: it's inevitable, DeviceProperties are going to stay forever. I have more and more cases where I need to query device properties later down the road (memory capabilities, device name, ...) and leaving all this up to the user / making this impossible to do in the library internals is complicating everything too much. Since there's a shitton of device properties with a new bag of props coming with every other new extension, I expect the queries to get quite involved / complicated over time (chaining 100s structs and such), so let's design this upfront in a way that can avoid reqpeatedly querying the same thing just because we needlessly discarded a fully populated instance before. It also means the users don't need to drag their own DeviceProperties instance along anymore and can just let the Device take care of that. Unfortunately the only nice way to make this work with DeviceCreateInfo method chaining is to add & and && overloads for each. But it's quite easy to test that all of them work and properly return a r-value reference so it shouldn't be too much of a maintenance nightmare.
6 years ago
Containers::Pointer<DeviceProperties> _properties;
Vk: device creation.
6 years ago
Containers::Pointer<Implementation::DeviceState> _state;
/* This member is bigger than you might think */
FlextVkDevice _functionPointers;
};
Vk: expose all extensions for version 1.2. Also provide compile-time info with them, a runtime list and everything else similar to what's done for GL.
6 years ago
}}
#endif