Vulkan specific initialization parameters. 更多...
| 头： | #include <QRhiVulkanInitParams> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.6 |
| 继承： | QRhiInitParams |
| QByteArrayList | deviceExtensions |
| QVulkanInstance * | inst |
| QWindow * | window |
| QByteArrayList | preferredExtensionsForImportedDevice () |
| QByteArrayList | preferredInstanceExtensions () |
注意： This is a RHI API with limited compatibility guarantees, see QRhi 了解细节。
A Vulkan-based QRhi needs at minimum a valid QVulkanInstance . It is up to the user to ensure this is available and initialized. This is typically done in main() similarly to the following:
int main(int argc, char **argv)
{
...
QVulkanInstance inst;
inst.setLayers({ "VK_LAYER_KHRONOS_validation" }); // for debugging only, not for release builds
inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
if (!inst.create())
qFatal("Vulkan not available");
...
}
This example enables the Vulkan validation layers , when they are available, and also enables the instance-level extensions QRhi reports as desirable (such as, VK_KHR_get_physical_device_properties2), as long as they are supported by the Vulkan implementation at run time.
The former is optional, and is useful during the development phase QVulkanInstance conveniently redirects messages and warnings to qDebug . Avoid enabling it in production builds, however. The latter is strongly recommended, and is important in order to make certain features functional (for example, QRhi::CustomInstanceStepRate ).
Once this is done, a Vulkan-based QRhi can be created by passing the instance and a QWindow with its surface type set to QSurface::VulkanSurface :
QRhiVulkanInitParams params; params.inst = vulkanInstance; params.window = window; rhi = QRhi::create(QRhi::Vulkan, ¶ms);
The window is optional and can be omitted. This is not recommended however because there is then no way to ensure presenting is supported while choosing a graphics queue.
注意： Even when a window is specified, QRhiSwapChain objects can be created for other windows as well, as long as they all have their QWindow::surfaceType () 设为 QSurface::VulkanSurface .
To request additional extensions to be enabled on the Vulkan device, list them in deviceExtensions . This can be relevant when integrating with native Vulkan rendering code.
It is expected that the backend's desired list of instance extensions will be queried by calling the static function preferredInstanceExtensions () before initializing a QVulkanInstance . The returned list can be safely passed to QVulkanInstance::setExtensions () as-is, because unsupported extensions are filtered out automatically. If this is not done, certain features, such as QRhi::CustomInstanceStepRate may be reported as unsupported even when the Vulkan implementation on the system has support for the relevant functionality.
For full functionality the QVulkanInstance needs to have API 1.1 enabled, when available. This means calling QVulkanInstance::setApiVersion () with 1.1 or higher whenever QVulkanInstance::supportedApiVersion () reports that at least Vulkan 1.1 is supported. If this is not done, certain features, such as QRhi::RenderTo3DTextureSlice may be reported as unsupported even when the Vulkan implementation on the system supports Vulkan 1.1 or newer.
When interoperating with another graphics engine, it may be necessary to get a QRhi instance that uses the same Vulkan device. This can be achieved by passing a pointer to a QRhiVulkanNativeHandles to QRhi::create ().
The physical device must always be set to a non-null value. If the intention is to just specify a physical device, but leave the rest of the VkDevice and queue creation to QRhi , then no other members need to be filled out in the struct. For example, this is the case when working with OpenXR.
To adopt an existing
VkDevice
, the device field must be set to a non-null value as well. In addition, the graphics queue family index is required. The queue index is optional, as the default of 0 is often suitable.
Optionally, an existing command pool object can be specified as well. Also optionally, vmemAllocator can be used to share the same Vulkan memory allocator between two QRhi 实例。
The QRhi does not take ownership of any of the external objects.
Applications are encouraged to query the list of desired device extensions by calling the static function preferredExtensionsForImportedDevice (), and enable them on the VkDevice. Otherwise certain QRhi features may not be available.
[static]
QByteArrayList
QRhiVulkanInitParams::
preferredExtensionsForImportedDevice
()
Returns the list of device extensions that are expected to be enabled on the
VkDevice
when creating a Vulkan-based
QRhi
with an externally created
VkDevice
对象。
[static]
QByteArrayList
QRhiVulkanInitParams::
preferredInstanceExtensions
()
Returns the list of instance extensions that are expected to be enabled on the QVulkanInstance that is used for the Vulkan-based QRhi .
The returned list can be safely passed to QVulkanInstance::setExtensions () as-is, because unsupported extensions are filtered out automatically.
Optional, empty by default. The list of Vulkan device extensions to enable. Unsupported extensions are ignored gracefully.
The QVulkanInstance that has already been successfully created , required.
Optional, but recommended when targeting a QWindow .