mirror of
https://github.com/charles-lunarg/vk-bootstrap.git
synced 2024-11-10 02:41:47 +00:00
Update getting_started.md
Include reference to add_required_extension_features and per-version feature enables. Fix type with CustomQueueDescription.
This commit is contained in:
parent
a330227666
commit
3849dafadb
@ -141,7 +141,7 @@ auto physical_device_selector_return = phys_device_selector
|
|||||||
if (!physical_device_selector_return) {
|
if (!physical_device_selector_return) {
|
||||||
// Handle error
|
// Handle error
|
||||||
}
|
}
|
||||||
auto phys_device = phys_device_ret.value ();
|
auto phys_device = physical_device_selector_return.value ();
|
||||||
```
|
```
|
||||||
|
|
||||||
To select a physical device, call `select()` on the `vkb::PhysicalDeviceSelector` object.
|
To select a physical device, call `select()` on the `vkb::PhysicalDeviceSelector` object.
|
||||||
@ -151,9 +151,11 @@ No cleanup is required for `vkb::PhysicalDevice`.
|
|||||||
|
|
||||||
The `vkb::PhysicalDeviceSelector` will look for the first device in the list that satisfied all the specified criteria, and if none is found, will return the first device that partially satisfies the criteria.
|
The `vkb::PhysicalDeviceSelector` will look for the first device in the list that satisfied all the specified criteria, and if none is found, will return the first device that partially satisfies the criteria.
|
||||||
|
|
||||||
The various "require" and "desire" pairs of functions indicate to `vk-bootstrap` what features and capabilities are necessary for an application and what are simply preferred. A "require" function will fail any `VkPhysicalDevice` that doesn't satisfy the constraint, while any criteria that doesn't satisfy the "desire" functions will make the `VkPhysicalDevice` only 'partially satisfy'.
|
The various "require" functions indicate to `vk-bootstrap` what features and capabilities are necessary for an application. A "require" function will fail any `VkPhysicalDevice` that doesn't satisfy the constraint.
|
||||||
|
|
||||||
```c
|
For example, "requiring" certain device extensions to be supported is done as follows:
|
||||||
|
|
||||||
|
```cpp
|
||||||
// Application cannot function without this extension
|
// Application cannot function without this extension
|
||||||
phys_device_selector.add_required_extension("VK_KHR_timeline_semaphore");
|
phys_device_selector.add_required_extension("VK_KHR_timeline_semaphore");
|
||||||
|
|
||||||
@ -161,10 +163,51 @@ phys_device_selector.add_required_extension("VK_KHR_timeline_semaphore");
|
|||||||
phys_device_selector.add_desired_extension("VK_KHR_imageless_framebuffer");
|
phys_device_selector.add_desired_extension("VK_KHR_imageless_framebuffer");
|
||||||
```
|
```
|
||||||
|
|
||||||
|
While requiring that certain features are available is as follows:
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
VkPhysicalDeviceFeatures required_features{};
|
||||||
|
required_features.multiViewport = true;
|
||||||
|
|
||||||
|
phys_device_selector.set_required_features(required_features);
|
||||||
|
```
|
||||||
|
|
||||||
|
To enable features for newer versions of Vulkan, use `set_required_features_11()`, `set_required_features_12()`, and `set_required_features_13()` and follow the same pattern as `set_required_features()` of passing in the features struct, corresponding to the version.
|
||||||
|
|
||||||
|
Note that `set_required_features_11()` was released with 1.2, so it cannot be used for 1.1 only capable Vulkan devices.
|
||||||
|
|
||||||
|
Features only available through extensions need to use `add_required_extension_features()`. For example:
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
VkPhysicalDeviceDescriptorIndexingFeatures descriptor_indexing_features{};
|
||||||
|
descriptor_indexing_features.<features_used> = true;
|
||||||
|
|
||||||
|
phys_device_selector.add_required_extension_features(&descriptor_indexing_features);
|
||||||
|
```
|
||||||
|
|
||||||
|
The features and extensions used as selection criteria in `vkb::PhysicalDeviceSelector` automatically propagate into `vkb::DeviceBuilder`. That means the application only needs to state the feature requirement once, and `vk-bootstrap` will handle enabling it on the resulting device.
|
||||||
|
|
||||||
Note:
|
Note:
|
||||||
|
|
||||||
Because `vk-bootstrap` does not manage creating a `VkSurfaceKHR` handle, it is explicitly passed into the `vkb::PhysicalDeviceSelector` for proper querying of surface support details. Unless the `vkb::InstanceBuilder::set_headless()` function was called, the physical device selector will emit `no_surface_provided` error. If an application does intend to present but cannot create a `VkSurfaceKHR` handle before physical device selection, use `defer_surface_initialization()` to disable the `no_surface_provided` error.
|
Because `vk-bootstrap` does not manage creating a `VkSurfaceKHR` handle, it is explicitly passed into the `vkb::PhysicalDeviceSelector` for proper querying of surface support details. Unless the `vkb::InstanceBuilder::set_headless()` function was called, the physical device selector will emit `no_surface_provided` error. If an application does intend to present but cannot create a `VkSurfaceKHR` handle before physical device selection, use `defer_surface_initialization()` to disable the `no_surface_provided` error.
|
||||||
|
|
||||||
|
## Physical Device
|
||||||
|
|
||||||
|
The `vkb::PhysicalDevice` represents a chosen physical device, along with all the necessary details about how to create a `VkDevice` from it with the requested features and extensions. While most use cases will simply give the `vkb::PhysicalDevice` to `vkb::DeviceBuilder`, there are a handful of useful things that can be done with it.
|
||||||
|
|
||||||
|
Adding optional extensions. It is occasionally useful to enable features if they are present but not require that they be available on the physical device.
|
||||||
|
|
||||||
|
This is done using `enable_extension_if_present()` as follows.
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
bool supported = phys_device.enable_extension_if_present("VK_KHR_timeline_semaphore");
|
||||||
|
if (supported){
|
||||||
|
// allows easy feedback whether an extension is supported or not.
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `enable_extensions_if_present()` to check if a group of extensions are available, and enable all of them if they are all present. This will *not* enable any extension unless they are all present, useful for handling dependencies between extensions, where one extension requires another one to be enabled.
|
||||||
|
|
||||||
## Device Creation
|
## Device Creation
|
||||||
|
|
||||||
Once a `VkPhysicalDevice` has been selected, a `VkDevice` can be created. Facilitating that is the `vkb::DeviceBuilder`. Creation and usage follows the forms laid out by `vkb::InstanceBuilder`.
|
Once a `VkPhysicalDevice` has been selected, a `VkDevice` can be created. Facilitating that is the `vkb::DeviceBuilder`. Creation and usage follows the forms laid out by `vkb::InstanceBuilder`.
|
||||||
@ -178,17 +221,6 @@ if (!dev_ret) {
|
|||||||
vkb::Device vkb_device = dev_ret.value();
|
vkb::Device vkb_device = dev_ret.value();
|
||||||
```
|
```
|
||||||
|
|
||||||
The features and extensions used as selection criteria in `vkb::PhysicalDeviceSelector` automatically propagate into `vkb::DeviceBuilder`. Because of this, there is no way to enable features or extensions that were not specified during `vkb::PhysicalDeviceSelector`. This is by design as any feature or extension enabled in a device *must* have support from the `VkPhysicalDevice` it is created with.
|
|
||||||
|
|
||||||
The common method to extend Vulkan functionality in existing API calls is to use the pNext chain. This is accounted for `VkDevice` creation with the `add_pNext` member function of `vkb::DeviceBuilder`. Note: Any structures added to the pNext chain must remain valid until `build()` is called.
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
VkPhysicalDeviceDescriptorIndexingFeatures descriptor_indexing_features{};
|
|
||||||
|
|
||||||
auto dev_ret = device_builder.add_pNext(&descriptor_indexing_features)
|
|
||||||
.build ();
|
|
||||||
```
|
|
||||||
|
|
||||||
To destroy a `vkb::Device`, call `vkb::destroy_device()`.
|
To destroy a `vkb::Device`, call `vkb::destroy_device()`.
|
||||||
```cpp
|
```cpp
|
||||||
vkb::destroy_device(vkb_device);
|
vkb::destroy_device(vkb_device);
|
||||||
@ -222,7 +254,6 @@ for (uint32_t i = 0; i < static_cast<uint32_t>(queue_families.size ()); i++) {
|
|||||||
if (queue_families[i].queueFlags & VK_QUEUE_GRAPHICS_BIT) {
|
if (queue_families[i].queueFlags & VK_QUEUE_GRAPHICS_BIT) {
|
||||||
// Find the first queue family with graphics operations supported
|
// Find the first queue family with graphics operations supported
|
||||||
queue_descriptions.push_back (vkb::CustomQueueDescription (
|
queue_descriptions.push_back (vkb::CustomQueueDescription (
|
||||||
i, queue_families[i].queueCount,
|
|
||||||
std::vector<float> (queue_families[i].queueCount, 1.0f)));
|
std::vector<float> (queue_families[i].queueCount, 1.0f)));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
Loading…
Reference in New Issue
Block a user