QRhiVulkanInitParams Struct

Descripción detallada

Un QRhi basado en Vulkan necesita como mínimo un QVulkanInstance válido. Depende del usuario asegurarse de que está disponible e inicializado. Esto se hace típicamente en main() de forma similar a la 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 reporta como deseables (tales como, VK_KHR_get_physical_device_properties2), siempre y cuando sean soportadas por la implementación de Vulkan en tiempo de ejecución.

El primero es opcional, y es útil durante la fase de desarrollo QVulkanInstance redirige convenientemente los mensajes y advertencias a qDebug. Sin embargo, evite activarlo en las compilaciones de producción. La segunda es muy recomendable, y es importante para que ciertas características sean funcionales (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, &params);

La ventana es opcional y puede omitirse. Sin embargo, esto no es recomendable porque entonces no hay manera de asegurarse de que la presentación es compatible al elegir una cola de gráficos.

Para solicitar que se habiliten extensiones adicionales en el dispositivo Vulkan, enumérelas en deviceExtensions. Esto puede ser relevante cuando se integra con el código de renderizado nativo de Vulkan.

Se espera que la lista deseada de extensiones de instancia del backend sea consultada llamando a la función estática preferredInstanceExtensions() antes de inicializar un QVulkanInstance. La lista devuelta puede ser pasada con seguridad a QVulkanInstance::setExtensions() tal cual, porque las extensiones no soportadas son filtradas automáticamente. Si esto no se hace, ciertas características, como QRhi::CustomInstanceStepRate pueden ser reportadas como no soportadas incluso cuando la implementación de Vulkan en el sistema tiene soporte para la funcionalidad relevante.

Para una funcionalidad completa, QVulkanInstance necesita tener habilitada la API 1.1, cuando esté disponible. Esto significa llamar a QVulkanInstance::setApiVersion() con 1.1 o superior siempre que QVulkanInstance::supportedApiVersion() informe de que al menos Vulkan 1.1 está soportado. Si esto no se hace, ciertas características, como QRhi::RenderTo3DTextureSlice pueden ser reportadas como no soportadas incluso cuando la implementación de Vulkan en el sistema soporta Vulkan 1.1 o más reciente.

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 conseguir pasando un puntero a QRhiVulkanNativeHandles a QRhi::create().

El dispositivo físico debe ser siempre un valor no nulo. Si la intención es sólo especificar un dispositivo físico, pero dejar el resto del VkDevice y la creación de colas a QRhi, entonces no es necesario rellenar ningún otro miembro en la struct. Por ejemplo, este es el caso cuando se trabaja con OpenXR.

Para adoptar un VkDevice existente, el campo de dispositivo también debe establecerse en un valor no nulo. Además, se requiere el índice de la familia de colas de gráficos. El índice de cola es opcional, ya que el valor predeterminado 0 suele ser adecuado.

Opcionalmente, también se puede especificar un objeto de pool de comandos existente. También opcionalmente, se puede utilizar vmemAllocator para compartir el mismo asignador de memoria Vulkan entre dos instancias de QRhi.

QRhi no se apropia de ninguno de los objetos externos.

Se recomienda a las aplicaciones consultar la lista de extensiones de dispositivo deseadas llamando a la función estática preferredExtensionsForImportedDevice(), y habilitarlas en el VkDevice. De lo contrario, algunas funciones de QRhi podrían no estar disponibles.