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:
Charles Giessen 2024-02-14 14:15:45 -06:00
parent a330227666
commit 3849dafadb

View File

@ -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)));
} }
} }