QRhiVulkanInitParams Struct
Parámetros de inicialización específicos de Vulkan. Más información...
| Encabezado: | #include <rhi/qrhi.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake: | QT += gui-private |
| Desde: | Qt 6.6 |
| Heredado de: | QRhiInitParams |
Variables públicas
| QByteArrayList | deviceExtensions |
| QVulkanInstance * | inst |
| QWindow * | window |
Miembros públicos estáticos
| QByteArrayList | preferredExtensionsForImportedDevice() |
| QByteArrayList | preferredInstanceExtensions() |
Descripción detallada
Nota: Se trata de una API de RHI con garantías de compatibilidad limitadas; consulta QRhi para obtener más detalles.
Un ` QRhi ` basado en Vulkan necesita, como mínimo, un ` QVulkanInstance` válido. Es responsabilidad del usuario asegurarse de que esté disponible e inicializado. Esto se suele hacer en `main()`, de forma similar a lo siguiente:
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");
...
}Este ejemplo habilita las capas de validación de Vulkan, cuando están disponibles, y también habilita las extensiones a nivel de instancia que QRhi indica como recomendables (como, por ejemplo, VK_KHR_get_physical_device_properties2), siempre que sean compatibles con la implementación de Vulkan en tiempo de ejecución.
Lo primero es opcional y resulta útil durante la fase de desarrollo, ya qu QVulkanInstance redirige convenientemente los mensajes y las advertencias a qDebug. Sin embargo, se recomienda evitar habilitarlo en las compilaciones de producción. Lo segundo es muy recomendable y resulta importante para que determinadas funciones sean operativas (por ejemplo, QRhi::CustomInstanceStepRate).
Una vez hecho esto, se puede crear un ` QRhi ` basado en Vulkan pasando la instancia y un ` QWindow ` con su tipo de superficie establecido en ` QSurface::VulkanSurface`:
QRhiVulkanInitParams params;
params.inst = vulkanInstance;
params.window = window;
rhi = QRhi::create(QRhi::Vulkan, ¶ms);La ventana es opcional y puede omitirse. Sin embargo, esto no es recomendable, ya que entonces no hay forma de garantizar que la presentación sea compatible al elegir una cola gráfica.
Nota: Incluso cuando se especifica una ventana, se pueden crear objetos ` QRhiSwapChain ` también para otras ventanas, siempre y cuando todas tengan su ` QWindow::surfaceType()` establecido en ` QSurface::VulkanSurface`.
Para solicitar que se habiliten extensiones adicionales en el dispositivo Vulkan, enuméralas en ` deviceExtensions`. Esto puede resultar relevante a la hora de integrar código de renderizado nativo de Vulkan.
Se espera que la lista deseada de extensiones de instancia del backend se consulte llamando a la función estática ` preferredInstanceExtensions()` antes de inicializar un ` QVulkanInstance`. La lista devuelta puede pasarse de forma segura a ` QVulkanInstance::setExtensions()` tal cual, ya que las extensiones no compatibles se filtran automáticamente. Si no se hace así, es posible que ciertas características, como QRhi::CustomInstanceStepRate, se consideren no compatibles, incluso cuando la implementación de Vulkan en el sistema admita la funcionalidad en cuestión.
Para disfrutar de todas las funcionalidades, el ` QVulkanInstance ` debe tener habilitada la API 1.1, cuando esté disponible. Esto implica llamar a ` QVulkanInstance::setApiVersion()` con 1.1 o superior siempre que ` QVulkanInstance::supportedApiVersion()` indique que se admite al menos Vulkan 1.1. Si no se hace así, es posible que ciertas características, como QRhi::RenderTo3DTextureSlice, se indiquen como no compatibles, incluso cuando la implementación de Vulkan en el sistema admita Vulkan 1.1 o una versión posterior.
Trabajar con dispositivos Vulkan existentes
Al interoperar con otro motor gráfico, puede ser necesario obtener una instancia de ` QRhi ` que utilice el mismo dispositivo Vulkan. Esto se puede lograr pasando un puntero a un ` QRhiVulkanNativeHandles ` a ` QRhi::create()`.
El dispositivo físico siempre debe establecerse en un valor distinto de nulo. Si la intención es simplemente especificar un dispositivo físico, pero dejar el resto de la creación de VkDevice y de la cola en manos de ` QRhi`, entonces no es necesario rellenar ningún otro miembro de la estructura. Por ejemplo, este es el caso cuando se trabaja con OpenXR.
Para adoptar un objeto ` VkDevice` ya existente, el campo «device» también debe establecerse en un valor distinto de nulo. Además, es obligatorio indicar el índice de la familia de colas gráficas. El índice de la cola es opcional, ya que el valor predeterminado (0) suele ser adecuado.
Opcionalmente, también se puede especificar un objeto de grupo de comandos ya existente. Asimismo, de forma opcional, se puede utilizar vmemAllocator para compartir el mismo asignador de memoria Vulkan entre dos instancias de QRhi.
QRhi no asume la propiedad de ninguno de los objetos externos.
Se recomienda a las aplicaciones que consulten la lista de extensiones de dispositivo deseadas llamando a la función estática preferredExtensionsForImportedDevice(), y que las habiliten en el VkDevice. De lo contrario, es posible que ciertas funciones de « QRhi » no estén disponibles.
Documentación de las funciones miembro
[static] QByteArrayList QRhiVulkanInitParams::preferredExtensionsForImportedDevice()
Devuelve la lista de extensiones de dispositivo que se espera que estén habilitadas en el « VkDevice » al crear un « QRhi » basado en Vulkan con un objeto « VkDevice » creado externamente.
[static] QByteArrayList QRhiVulkanInitParams::preferredInstanceExtensions()
Devuelve la lista de extensiones de instancia que se espera que estén habilitadas en el « QVulkanInstance » que se utiliza para la « QRhi » basada en Vulkan.
La lista devuelta se puede pasar sin problemas a ` QVulkanInstance::setExtensions()` tal cual, ya que las extensiones no compatibles se filtran automáticamente.
Documentación de las variables de miembro
QByteArrayList QRhiVulkanInitParams::deviceExtensions
Opcional, vacío por defecto. La lista de extensiones de dispositivos Vulkan que se van a habilitar. Las extensiones no compatibles se ignoran de forma controlada.
QVulkanInstance *QRhiVulkanInitParams::inst
El « QVulkanInstance », que ya se ha publicado con éxito en created, es obligatorio.
QWindow *QRhiVulkanInitParams::window
Opcional, pero recomendable cuando se dirige a QWindow.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.