mirror of
https://github.com/charles-lunarg/vk-bootstrap.git
synced 2024-11-25 16:24:35 +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) {
|
||||
// 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.
|
||||
@ -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 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
|
||||
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");
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
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
|
||||
|
||||
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();
|
||||
```
|
||||
|
||||
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()`.
|
||||
```cpp
|
||||
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) {
|
||||
// Find the first queue family with graphics operations supported
|
||||
queue_descriptions.push_back (vkb::CustomQueueDescription (
|
||||
i, queue_families[i].queueCount,
|
||||
std::vector<float> (queue_families[i].queueCount, 1.0f)));
|
||||
}
|
||||
}
|
||||
|
Loading…
Reference in New Issue
Block a user