QRhiVulkanInitParams Struct

Description détaillée

Un QRhi basé sur Vulkan nécessite au minimum un QVulkanInstance valide. C'est à l'utilisateur de s'assurer qu'il est disponible et initialisé. Cela se fait typiquement dans main() de manière similaire à ce qui suit :

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");

    ...
}

Cet exemple active les couches de validation Vulkan, lorsqu'elles sont disponibles, et active également les extensions au niveau de l'instance QRhi si cela est souhaitable (comme VK_KHR_get_physical_device_properties2), tant qu'elles sont prises en charge par l'implémentation Vulkan au moment de l'exécution.

La première est optionnelle et est utile pendant la phase de développement QVulkanInstance redirige commodément les messages et les avertissements vers qDebug. Évitez toutefois de l'activer dans les versions de production. La seconde est fortement recommandée et est importante pour rendre certaines fonctionnalités fonctionnelles (par exemple, QRhi::CustomInstanceStepRate).

Une fois que cela est fait, un QRhi basé sur Vulkan peut être créé en passant l'instance et un QWindow avec son type de surface défini à QSurface::VulkanSurface:

QRhiVulkanInitParams params;
params.inst = vulkanInstance;
params.window = window;
rhi = QRhi::create(QRhi::Vulkan, &params);

La fenêtre est facultative et peut être omise. Cela n'est cependant pas recommandé car il n'y a alors aucun moyen de s'assurer que la présentation est prise en charge lors du choix d'une file d'attente graphique.

Pour demander que des extensions supplémentaires soient activées sur le périphérique Vulkan, listez-les dans deviceExtensions. Cela peut s'avérer utile lors de l'intégration avec le code de rendu Vulkan natif.

Il est prévu que la liste des extensions d'instance souhaitées par le backend soit demandée en appelant la fonction statique preferredInstanceExtensions() avant d'initialiser un QVulkanInstance. La liste renvoyée peut être transmise telle quelle à QVulkanInstance::setExtensions() en toute sécurité, car les extensions non prises en charge sont filtrées automatiquement. Si cela n'est pas fait, certaines fonctionnalités, telles que QRhi::CustomInstanceStepRate, peuvent être signalées comme non prises en charge, même si l'implémentation Vulkan sur le système prend en charge la fonctionnalité concernée.

Pour une fonctionnalité complète, le site QVulkanInstance doit avoir l'API 1.1 activée, lorsqu'elle est disponible. Cela signifie qu'il faut appeler QVulkanInstance::setApiVersion() avec 1.1 ou plus chaque fois que QVulkanInstance::supportedApiVersion() signale qu'au moins Vulkan 1.1 est pris en charge. Dans le cas contraire, certaines fonctionnalités, telles que QRhi::RenderTo3DTextureSlice, peuvent être signalées comme non prises en charge, même si l'implémentation Vulkan sur le système prend en charge Vulkan 1.1 ou une version plus récente.

Travailler avec des dispositifs Vulkan existants

Lors de l'interopérabilité avec un autre moteur graphique, il peut être nécessaire d'obtenir une instance QRhi qui utilise le même périphérique Vulkan. Cela peut être réalisé en passant un pointeur vers un QRhiVulkanNativeHandles à QRhi::create().

Le périphérique physique doit toujours être défini sur une valeur non nulle. Si l'intention est juste de spécifier un périphérique physique, mais de laisser le reste de la création de VkDevice et de file d'attente à QRhi, alors aucun autre membre n'a besoin d'être rempli dans la structure. C'est par exemple le cas lorsque l'on travaille avec OpenXR.

Pour adopter une version existante de VkDevice, le champ device doit également être défini sur une valeur non nulle. En outre, l'index de la famille de la file d'attente graphique est requis. L'index de la file d'attente est facultatif, car la valeur par défaut de 0 convient souvent.

Il est également possible de spécifier un objet de pool de commandes existant. En option également, vmemAllocator peut être utilisé pour partager le même allocateur de mémoire Vulkan entre deux instances QRhi.

Le site QRhi n'est propriétaire d'aucun des objets externes.

Les applications sont encouragées à demander la liste des extensions de périphérique souhaitées en appelant la fonction statique preferredExtensionsForImportedDevice(), et à les activer sur le VkDevice. Dans le cas contraire, certaines fonctionnalités de QRhi pourraient ne pas être disponibles.