QVulkanWindow Class
La classe `QVulkanWindow` est une sous-classe pratique de ` QWindow ` permettant d'effectuer un rendu Vulkan. En savoir plus...
| En-tête : | #include <QVulkanWindow> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake : | QT += gui |
| Hérite de : | QWindow |
Types publics
(since 6.7) | EnabledFeatures2Modifier |
| EnabledFeaturesModifier | |
| enum | Flag { PersistentResources } |
| flags | Flags |
| QueueCreateInfoModifier |
Fonctions publiques
| QVulkanWindow(QWindow *parent = nullptr) | |
| virtual | ~QVulkanWindow() |
| QList<VkPhysicalDeviceProperties> | availablePhysicalDevices() |
| QMatrix4x4 | clipCorrectionMatrix() |
| VkFormat | colorFormat() const |
| int | concurrentFrameCount() const |
| virtual QVulkanWindowRenderer * | createRenderer() |
| VkCommandBuffer | currentCommandBuffer() const |
| int | currentFrame() const |
| VkFramebuffer | currentFramebuffer() const |
| int | currentSwapChainImageIndex() const |
| VkRenderPass | defaultRenderPass() const |
| VkFormat | depthStencilFormat() const |
| VkImage | depthStencilImage() const |
| VkImageView | depthStencilImageView() const |
| VkDevice | device() const |
| uint32_t | deviceLocalMemoryIndex() const |
| QVulkanWindow::Flags | flags() const |
| void | frameReady() |
| QImage | grab() |
| VkCommandPool | graphicsCommandPool() const |
| VkQueue | graphicsQueue() const |
| uint32_t | graphicsQueueFamilyIndex() const |
| uint32_t | hostVisibleMemoryIndex() const |
| bool | isValid() const |
| VkImage | msaaColorImage(int idx) const |
| VkImageView | msaaColorImageView(int idx) const |
| VkPhysicalDevice | physicalDevice() const |
| const VkPhysicalDeviceProperties * | physicalDeviceProperties() const |
| VkSampleCountFlagBits | sampleCountFlagBits() const |
| void | setDeviceExtensions(const QByteArrayList &extensions) |
(since 6.7) void | setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier) |
(since 6.7) void | setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier) |
| void | setFlags(QVulkanWindow::Flags flags) |
| void | setPhysicalDeviceIndex(int idx) |
| void | setPreferredColorFormats(const QList<VkFormat> &formats) |
| void | setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier) |
| void | setSampleCount(int sampleCount) |
| QVulkanInfoVector<QVulkanExtension> | supportedDeviceExtensions() |
| QList<int> | supportedSampleCounts() |
| bool | supportsGrab() const |
| VkImage | swapChainImage(int idx) const |
| int | swapChainImageCount() const |
| QSize | swapChainImageSize() const |
| VkImageView | swapChainImageView(int idx) const |
Signaux
| void | frameGrabbed(const QImage &image) |
Membres publics statiques
| const int | MAX_CONCURRENT_FRAME_COUNT |
Description détaillée
QVulkanWindow est une interface « QWindow » compatible avec Vulkan qui gère un périphérique Vulkan, une file d’attente graphique, un pool de commandes et un tampon, une image de profondeur-stencil et une chaîne d’échange FIFO à double tampon, tout en assurant un comportement correct face à des événements tels que le redimensionnement, des situations particulières comme l’absence d’une file d’attente de périphérique prenant en charge à la fois le graphisme et la présentation, les scénarios de perte de périphérique, ainsi que des fonctionnalités supplémentaires telles que la relecture du contenu rendu. D'un point de vue conceptuel, il s'agit de l'équivalent de l'QOpenGLWindow dans l'univers Vulkan.
Remarque : QVulkanWindow ne dispense pas toujours de l’implémentation d’une sous-classe entièrement personnalisée de ` QWindow `, car elle ne sera pas nécessairement suffisante dans les cas d’utilisation avancés.
QVulkanWindow peut être intégré dans des interfaces utilisateur basées sur ` QWidget` via ` QWidget::createWindowContainer()`. Cette approche présente toutefois un certain nombre de limitations. Veillez à consulter au préalable la documentation « documentation ».
Une application type utilisant QVulkanWindow peut se présenter comme suit :
class VulkanRenderer : public QVulkanWindowRenderer
{
public:
VulkanRenderer(QVulkanWindow*w): m_window(w), m_devFuncs(nullptr) { }
void initResources() override
{
m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device());
// ..
}
void initSwapChainResources() override { /* ... */ }
void releaseSwapChainResources() override { /* ... */ }
void releaseResources() override { /* ... */ }
void startNextFrame() override
{
VkCommandBuffer cmdBuf = m_window->currentCommandBuffer();
// ...
m_devFuncs->vkCmdBeginRenderPass(commandBuffer, renderPassBegin, contents);
// ...
m_window->frameReady();
}
private:
QVulkanWindow*m_window;
QVulkanDeviceFunctions*m_devFuncs;
};
class VulkanWindow : public QVulkanWindow
{
public:
QVulkanWindowRenderer*createRenderer() override {
return new VulkanRenderer(this);
}
};
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
// active les couches de validation standard, lorsqu'elles sont disponibles
inst.setLayers({ "VK_LAYER_KHRONOS_validation" });
if (!inst.create())
qFatal("Failed to create Vulkan instance: %d", inst.errorCode());
VulkanWindow w;
w.setVulkanInstance(&inst);
w.showMaximized();
return app.exec();
}Comme le montre cet exemple, les principaux schémas d’utilisation de QVulkanWindow sont les suivants :
- L'QVulkanInstance est associé via QWindow::setVulkanInstance(). Il est ensuite accessible via QWindow::vulkanInstance() depuis n'importe où, sur n'importe quel thread.
- À l’instar de ` QVulkanInstance`, les extensions du périphérique peuvent être interrogées via ` supportedDeviceExtensions()` avant l’initialisation proprement dite. La demande d’activation d’une extension s’effectue via ` setDeviceExtensions()`. Ces appels doivent être effectués avant que la fenêtre ne devienne visible, c’est-à-dire avant d’appeler ` show()` ou des fonctions similaires. Les demandes d’extension non prises en charge sont ignorées de manière gracieuse.
- Le moteur de rendu est implémenté dans une sous-classe de ` QVulkanWindowRenderer `, dont une instance est créée dans la fonction fabrique ` createRenderer()`.
- Les commandes Vulkan de base sont exposées via l’objet ` QVulkanFunctions `, accessible en appelant ` QVulkanInstance::functions()`. Les fonctions au niveau du périphérique sont disponibles après la création d’un `VkDevice` en appelant ` QVulkanInstance::deviceFunctions()`.
- La construction des appels de dessin pour l’image suivante s’effectue dans QVulkanWindowRenderer::startNextFrame(). L’implémentation doit ajouter des commandes au tampon de commandes renvoyé par currentCommandBuffer(). Le retour de la fonction n’indique pas que les commandes sont prêtes à être soumises. Un appel explicite à frameReady() est au contraire requis. Cela permet la génération asynchrone de commandes, éventuellement sur plusieurs threads. Les implémentations simples se contenteront d’appeler ` frameReady()` à la fin de leur ` QVulkanWindowRenderer::startNextFrame()`.
- Les ressources Vulkan de base (périphérique physique, file d’attente graphique, pool de commandes, tampon de commandes principal de la fenêtre, formats d’image, etc.) sont exposées sur la classe `QVulkanWindow` via des fonctions getter légères. Certaines d’entre elles ne sont fournies que pour des raisons de commodité, et les applications sont toujours libres d’interroger, de créer et de gérer des ressources supplémentaires directement via l’API Vulkan.
- Le moteur de rendu réside dans le thread « gui/main », tout comme la fenêtre elle-même. Ce thread est alors limité à la fréquence de rafraîchissement, de la même manière qu’OpenGL se comporterait avec un intervalle de rafraîchissement (swap interval) égal à 1. Cependant, l’implémentation du moteur de rendu est libre d’utiliser plusieurs threads comme bon lui semble. Les accesseurs tels que vulkanInstance(), currentCommandBuffer(), etc. peuvent être appelés depuis n’importe quel thread. La soumission du tampon de commandes principal, la mise en file d’attente de la commande « present » et la construction de l’image suivante ne démarrent pas tant que la fonction frameReady() n’a pas été invoquée sur le thread GUI/principal.
- Lorsque la fenêtre est affichée, son contenu est mis à jour automatiquement. D'autres mises à jour peuvent être demandées en appelant QWindow::requestUpdate(). Pour effectuer un rendu en continu, appelez requestUpdate() après frameReady().
Pour le dépannage, activez la catégorie de journalisation « qt.vulkan ». Les erreurs critiques sont automatiquement affichées via la fonction qWarning().
Différences entre les systèmes de coordonnées d’OpenGL et de Vulkan
Il existe deux différences notables à prendre en compte : premièrement, avec Vulkan, l’axe Y pointe vers le bas de l’écran dans l’espace de découpage, tandis qu’OpenGL utilise un axe Y pointant vers le haut. Deuxièmement, la matrice de projection OpenGL standard suppose des valeurs de plan proche et lointain de -1 et 1, tandis que Vulkan privilégie 0 et 1.
Afin de faciliter la migration des applications depuis un code basé sur OpenGL sans avoir à inverser les coordonnées Y dans les données de sommets, et de permettre l’utilisation de fonctions d’ QMatrix4x4 s telles que ` QMatrix4x4::perspective()` tout en conservant les paramètres `minDepth` et `maxDepth` de la fenêtre d’affichage Vulkan réglés sur 0 et 1, `QVulkanWindow` fournit une matrice de correction accessible via l’appel à la fonction ` clipCorrectionMatrix()`.
Multisampling
Bien qu’il soit désactivé par défaut, l’anticrénelage par suréchantillonnage est entièrement pris en charge par QVulkanWindow. Les tampons de couleur supplémentaires et la résolution dans les tampons non suréchantillonnés de la chaîne d’échange sont gérés automatiquement.
Pour connaître le nombre d'échantillons pris en charge, appelez la fonction ` supportedSampleCounts()`. Lorsque l'ensemble renvoyé contient 4, 8, …, le fait de passer l'une de ces valeurs à la fonction ` setSampleCount()` déclenche le rendu multisample.
Remarque : contrairement à QSurfaceFormat::setSamples(), la liste des nombres d’échantillons pris en charge est communiquée à l’avance aux applications et il n’y a pas de repli automatique vers des nombres d’échantillons inférieurs dans setSampleCount(). Si la valeur demandée n’est pas prise en charge, un avertissement s’affiche et aucun multisampling n’est utilisé.
Lecture des images
Lorsque la fonction supportsGrab() renvoie « true », QVulkanWindow peut effectuer des lectures depuis le tampon de couleurs vers une fonction QImage. La fonction grab() est une opération lente et inefficace ; il convient donc d’éviter de l’utiliser fréquemment. Elle reste néanmoins utile, car elle permet aux applications de réaliser des captures d’écran, ou aux outils et tests de traiter et de vérifier le résultat du rendu GPU.
Prise en charge du sRGB
Bien que de nombreuses applications s’accommodent du comportement par défaut de `QVulkanWindow` en matière de formats d’image de la chaîne d’échange, la fonction ` setPreferredColorFormats()` permet de demander un format prédéfini. Cela s’avère particulièrement utile lorsque l’on travaille dans l’espace colorimétrique sRGB. Le passage d’un format tel que ` VK_FORMAT_B8G8R8A8_SRGB ` entraîne le choix d’un format sRGB, lorsqu’il est disponible.
Couches de validation
Lors du développement d’une application, il peut s’avérer extrêmement utile d’activer les couches de validation Vulkan. Comme le montre l’exemple de code ci-dessus, l’appel de ` QVulkanInstance::setLayers()` sur ` QVulkanInstance ` avant ` QVulkanInstance::create()` active la validation, à condition que la pile de pilotes Vulkan du système contienne les couches nécessaires.
Remarque : tenez compte des différences spécifiques à chaque plateforme. Sur les plateformes de bureau, l’installation du SDK Vulkan est généralement suffisante. En revanche, Android, par exemple, nécessite le déploiement de bibliothèques partagées supplémentaires avec l’application et impose également une liste différente de noms de couches de validation. Consultez les pages de développement Vulkan pour Android pour plus d’informations.
Remarque : QVulkanWindow n'expose pas les couches de périphériques, car cette fonctionnalité est obsolète depuis la version 1.0.13 de l'API Vulkan.
Couches, fonctionnalités des périphériques et extensions
Pour activer les couches d'instance, appelez QVulkanInstance::setLayers() avant de créer l'QVulkanInstance. Pour connaître les couches d'instance disponibles, appelez QVulkanInstance::supportedLayers().
Pour activer les extensions de périphérique, appelez setDeviceExtensions() dès le début de la configuration de la QVulkanWindow. Pour connaître les extensions de périphérique disponibles, appelez supportedDeviceExtensions().
La spécification d’une couche ou d’une extension non prise en charge est gérée de manière souple : cela n’entraînera pas l’échec de la création de l’instance ou du périphérique, mais la demande de couche ou d’extension sera simplement ignorée.
En ce qui concerne les fonctionnalités du périphérique, QVulkanWindow active toutes les fonctionnalités Vulkan 1.0 signalées comme prises en charge par la fonction `vkGetPhysicalDeviceFeatures()`. À titre d’exception à cette règle, la fonction ` robustBufferAccess ` n’est jamais activée. Utilisez le mécanisme de rappel décrit ci-dessous si vous souhaitez activer cette fonctionnalité.
Cela n’est pas toujours souhaitable et peut s’avérer insuffisant avec Vulkan 1.1 et les versions ultérieures. Par conséquent, il est également possible d’exercer un contrôle total sur les VkPhysicalDeviceFeatures utilisées pour la création de périphériques en enregistrant une fonction de rappel avec ` setEnabledFeaturesModifier()`. Une fois définie, la fonction de rappel est appelée, ce qui lui permet de modifier les VkPhysicalDeviceFeatures ou les VkPhysicalDeviceFeatures2.
Considérations de sécurité
Toutes les données utilisées par QVulkanWindow sont censées provenir d’une source fiable. Cela inclut les noms d’extensions de périphérique transmis à ` setDeviceExtensions()`, les paramètres de création de périphérique définis par les fonctions de rappel enregistrées via ` setEnabledFeaturesModifier()` et ` setQueueCreateInfoModifier()`, ainsi que l’ensemble du contenu de rendu et des paramètres de commande Vulkan générés par l’implémentation de ` QVulkanWindowRenderer `. L’implémentation Vulkan elle-même est une dépendance de plateforme fiable et intégrée au processus ; voir QVulkanInstance pour plus de détails.
Avertissement : il est conseillé aux développeursd’applications d’examiner attentivement les implications potentielles avant d’autoriser l’intégration de contenu fourni par l’utilisateur qui ne fait pas partie de l’application et n’est pas sous leur contrôle.
Voir également QVulkanInstance et QWindow.
Documentation sur les types de membres
[since 6.7] QVulkanWindow::EnabledFeatures2Modifier
Fonction appelée lors de l'initialisation graphique pour modifier les propriétés `VkPhysicalDeviceFeatures2` qui sont ensuite intégrées à l'objet `VkDeviceCreateInfo`.
Par défaut, ` QVulkanWindow ` active toutes les fonctionnalités principales de Vulkan 1.0 que le périphérique physique signale comme prises en charge, à quelques exceptions près. En particulier, ` robustBufferAccess ` est toujours désactivé afin d’éviter des baisses de performances inattendues.
Cela n’est toutefois pas toujours suffisant lorsque l’on utilise les fonctionnalités et extensions de Vulkan 1.1, 1.2 ou 1.3. D’où ce mécanisme de rappel. Si seul Vulkan 1.0 est pertinent au moment de l’exécution, utilisez plutôt ` setEnabledFeaturesModifier()`.
La référence VkPhysicalDeviceFeatures2 transmise à la fonction de rappel comporte la propriété sType définie, mais les autres propriétés sont mises à zéro. Il appartient à la fonction de définir les membres sur true ou de configurer des chaînes d’ pNext s comme elle le juge opportun.
pNext Remarque : lors de la mise en place de chaînes d’ QVulkanWindow, assurez-vous que les objets référencés ont une durée de vie suffisamment longue, par exemple en les stockant en tant que variables membres dans la sous-classe d’ .
Ce typedef a été introduit dans Qt 6.7.
Voir également ` setEnabledFeaturesModifier()`.
QVulkanWindow::EnabledFeaturesModifier
Fonction appelée lors de l'initialisation graphique afin de modifier les propriétés `VkPhysicalDeviceFeatures` transmises lors de la création d'un objet périphérique Vulkan.
Par défaut, ` QVulkanWindow ` active toutes les fonctionnalités de base de Vulkan 1.0 que le périphérique physique signale comme prises en charge, à quelques exceptions près. En particulier, ` robustBufferAccess ` est toujours désactivé afin d’éviter des baisses de performances inattendues.
La référence VkPhysicalDeviceFeatures transmise est entièrement remise à zéro au moment où la fonction est appelée. Il appartient à la fonction de modifier les éléments comme elle le juge bon.
Remarque : pour contrôler les fonctionnalités de Vulkan 1.1, 1.2 ou 1.3, utilisez plutôt ` EnabledFeatures2Modifier `.
Voir également setEnabledFeaturesModifier().
enum QVulkanWindow::Flag
flags QVulkanWindow::Flags
Cette énumération décrit les indicateurs pouvant être transmis à la fonction ` setFlags()`.
| Constante | Valeur | Description |
|---|---|---|
QVulkanWindow::PersistentResources | 0x01 | Garantit qu’aucune ressource graphique n’est libérée lorsque la fenêtre devient masquée. Le comportement par défaut consiste à tout libérer, puis à réinitialiser ultérieurement lorsque la fenêtre redevient visible. |
Le type Flags est un typedef de QFlags<Flag>. Il stocke une combinaison OR de valeurs Flag.
QVulkanWindow::QueueCreateInfoModifier
Fonction appelée lors de l'initialisation graphique afin d'ajouter des files d'attente supplémentaires à créer.
À définir si le moteur de rendu a besoin de files d'attente supplémentaires en plus de la file d'attente graphique par défaut (par exemple, une file d'attente de transfert). Les propriétés de la famille de files d'attente fournies peuvent être utilisées pour sélectionner les indices des files d'attente supplémentaires. Le moteur de rendu peut ensuite demander la file d'attente effective dans initResources().
Remarque : lors de la demande de files d'attente graphiques supplémentaires, Qt demande toujours lui-même une file d'attente graphique. Vous devrez rechercher l'entrée appropriée dans `queueCreateInfo` et la manipuler pour obtenir la file d'attente supplémentaire.
Voir également setQueueCreateInfoModifier().
Documentation des fonctions membres
[explicit] QVulkanWindow::QVulkanWindow(QWindow *parent = nullptr)
Crée une nouvelle instance de `QVulkanWindow` avec le type de surface spécifié ` parent`.
Le type de surface est défini sur « QSurface::VulkanSurface ».
[virtual noexcept] QVulkanWindow::~QVulkanWindow()
Destructeur.
QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()
Renvoie la liste des propriétés des périphériques physiques pris en charge par le système.
Remarque : cette fonction peut être appelée avant de rendre la fenêtre visible.
QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()
Renvoie une matrice de conversion ( QMatrix4x4 ) permettant de corriger les différences entre les systèmes de coordonnées d'OpenGL et de Vulkan.
En multipliant au préalable la matrice de projection par cette matrice, les applications peuvent continuer à considérer que l’axe Y est orienté vers le haut, et définir minDepth et maxDepth dans la fenêtre d’affichage respectivement à 0 et 1, sans avoir à effectuer d’autres corrections sur les positions Z des sommets. La géométrie provenant d’applications OpenGL peut alors être utilisée telle quelle, à condition que l’état de rastérisation corresponde aux paramètres de culling et de face avant d’OpenGL.
VkFormat QVulkanWindow::colorFormat() const
Renvoie le format de tampon de couleur utilisé par la chaîne d'échange.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
Voir également setPreferredColorFormats().
int QVulkanWindow::concurrentFrameCount() const
Renvoie le nombre de trames pouvant potentiellement être actives simultanément.
Remarque : cette valeur reste constante pendant toute la durée de vie de l'QVulkanWindow.
class Renderer {
void startNextFrame();
// ...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
QVulkanWindow *m_window = nullptr;
};
void Renderer::startNextFrame()
{
const int count = m_window->concurrentFrameCount();
// for (int i = 0; i < count; ++i)
// m_uniformBufInfo[i] = ...
// ...
}Voir aussi currentFrame().
[virtual] QVulkanWindowRenderer *QVulkanWindow::createRenderer()
Renvoie une nouvelle instance de ` QVulkanWindowRenderer`.
Cette fonction virtuelle est appelée une seule fois au cours du cycle de vie de la fenêtre, à un moment donné après sa première apparition à l'écran.
L'implémentation par défaut renvoie null ; ainsi, aucun rendu n'est effectué, hormis l'effacement des tampons.
La fenêtre prend possession de l’objet de rendu renvoyé.
VkCommandBuffer QVulkanWindow::currentCommandBuffer() const
Renvoie le tampon de commandes actif pour l'image de la chaîne de swap actuelle. Les implémentations de la fonction ` QVulkanWindowRenderer::startNextFrame()` sont censées ajouter des commandes à ce tampon de commandes.
Remarque : cette fonction ne doit être appelée qu’à partir de la fonction `startNextFrame()` et, en cas de génération asynchrone de commandes, jusqu’à l’appel à ` frameReady()`.
int QVulkanWindow::currentFrame() const
Renvoie l'index de l'image actuelle dans l'intervalle [0, concurrentFrameCount() - 1].
Les implémentations du moteur de rendu devront s'assurer que les données uniformes et autres ressources dynamiques existent en plusieurs exemplaires, afin d'empêcher que l'image N ne modifie les données utilisées par les images encore actives N - 1, N - 2, … N - concurrentFrameCount() + 1.
Pour éviter de dépendre de la taille dynamique des tableaux, les applications peuvent utiliser MAX_CONCURRENT_FRAME_COUNT lors de la déclaration des tableaux. Cette valeur est garantie d’être toujours égale ou supérieure à celle renvoyée par concurrentFrameCount(). Ces tableaux peuvent alors être indexés à l’aide de la valeur renvoyée par cette fonction.
class Renderer {
void startNextFrame();
// ...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
QVulkanWindow *m_window = nullptr;
};
void Renderer::startNextFrame()
{
VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]);
// ...
}Remarque : cette fonction ne doit être appelée qu’à partir de startNextFrame() et, en cas de génération asynchrone de commandes, jusqu’à l’appel à frameReady().
Voir également concurrentFrameCount().
VkFramebuffer QVulkanWindow::currentFramebuffer() const
Renvoie un VkFramebuffer pour l'image de la chaîne d'échange actuelle en utilisant le passage de rendu par défaut.
Le framebuffer comporte deux attachements (couleur, profondeur-stencil) lorsque le multisampling n’est pas utilisé, et trois (résolution de couleur, profondeur-stencil, couleur multisample) lorsque sampleCountFlagBits() est supérieur à VK_SAMPLE_COUNT_1_BIT. Les moteurs de rendu doivent en tenir compte, par exemple lorsqu’ils fournissent des valeurs de vidage.
Remarque : les applications ne sont pas tenues d’utiliser ce framebuffer si elles fournissent leur propre passe de rendu au lieu d’utiliser celle renvoyée par defaultRenderPass().
Remarque : cette fonction ne doit être appelée qu’à partir de `startNextFrame()` et, en cas de génération asynchrone de commandes, jusqu’à l’appel à ` frameReady()`.
Voir également defaultRenderPass().
int QVulkanWindow::currentSwapChainImageIndex() const
Renvoie l'index actuel de l'image de la chaîne de swap, compris dans l'intervalle [0, swapChainImageCount() - 1].
Remarque : cette fonction ne doit être appelée qu'à partir de la fonction startNextFrame() et, en cas de génération asynchrone de commandes, au plus tard avant l'appel à la fonction frameReady().
VkRenderPass QVulkanWindow::defaultRenderPass() const
Renvoie un passage de rendu standard comportant un sous-pass.
Remarque : les applications ne sont pas tenues d’utiliser ce passage de rendu. Cependant, elles doivent alors veiller à ce que la chaîne d’échange actuelle et les images de profondeur-stencil soient transférées de VK_IMAGE_LAYOUT_UNDEFINED vers VK_IMAGE_LAYOUT_PRESENT_SRC_KHR et VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, soit via le passage de rendu personnalisé de l’application, soit par d’autres moyens.
Remarque : la lecture/écrituredu stencil n’est pas activée dans ce passage de rendu.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
Voir également currentFramebuffer().
VkFormat QVulkanWindow::depthStencilFormat() const
Renvoie le format utilisé par le ou les tampons de profondeur-stencil.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
VkImage QVulkanWindow::depthStencilImage() const
Renvoie l'image de profondeur-stencil.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
VkImageView QVulkanWindow::depthStencilImageView() const
Renvoie la vue de l'image de profondeur-stencil.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
VkDevice QVulkanWindow::device() const
Renvoie le périphérique logique actif.
Remarque : l'appel de cette fonction n'est valable qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
uint32_t QVulkanWindow::deviceLocalMemoryIndex() const
Renvoie un index de type de mémoire locale du périphérique adapté à un usage général.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
Remarque : il n'est pas garanti que ce type de mémoire soit toujours adapté. La solution correcte, valable pour toutes les implémentations — en particulier pour les images locales de périphériques —, consiste à choisir manuellement un type de mémoire après avoir vérifié le masque renvoyé par ` vkGetImageMemoryRequirements`.
QVulkanWindow::Flags QVulkanWindow::flags() const
Renvoie les indicateurs demandés.
Voir aussi setFlags().
[signal] void QVulkanWindow::frameGrabbed(const QImage &image)
Ce signal est émis lorsque l'image e est prêt.
void QVulkanWindow::frameReady()
Cette fonction doit être appelée exactement une fois en réponse à chaque appel de l’implémentation de ` QVulkanWindowRenderer::startNextFrame()`. Au moment de cet appel, le tampon de commandes principal, accessible via ` currentCommandBuffer()`, doit contenir toutes les commandes de rendu nécessaires, car cette fonction déclenche l’envoi des commandes et la mise en file d’attente de la commande actuelle.
Remarque : cette fonction ne doit être appelée qu’à partir du thread gui/main, qui est celui où les fonctions de QVulkanWindowRenderer sont invoquées et où réside l’instance QVulkanWindow.
Voir également QVulkanWindowRenderer::startNextFrame().
QImage QVulkanWindow::grab()
Construit et génère l'image suivante sans l'afficher, puis effectue une lecture bloquante du contenu de l'image.
Renvoie l’image si l’implémentation de la méthode ` startNextFrame()` du moteur de rendu appelle directement ` frameReady()`. Sinon, renvoie une image incomplète, qui a la taille correcte mais dont le contenu n’est pas encore disponible. Dans ce dernier cas, le contenu sera transmis via le signal ` frameGrabbed()`.
L’ QImage renvoyée a toujours le format QImage::Format_RGBA8888. Si le signal colorFormat() est VK_FORMAT_B8G8R8A8_UNORM, les canaux rouge et bleu sont automatiquement permutés, car ce format est couramment utilisé comme choix par défaut pour les tampons de couleur de la chaîne de permutation. Avec tout autre format de tampon de couleur, aucune conversion n’est effectuée par cette fonction.
Remarque : cette fonction ne doit pas être appelée lorsqu’une image est en cours de traitement (c’est-à-dire lorsque l’ frameReady() n’a pas encore été appelée en retour par l’application).
Remarque : cette fonction peut s’avérer coûteuse en ressources en raison de la lecture supplémentaire bloquante.
Remarque : cette fonction nécessite actuellement que la chaîne d’échange (swapchain) prenne en charge l’utilisation en tant que source de transfert (VK_IMAGE_USAGE_TRANSFER_SRC_BIT), faute de quoi elle échouera.
VkCommandPool QVulkanWindow::graphicsCommandPool() const
Renvoie le pool de commandes graphiques actif.
Remarque : l'appel de cette fonction n'est valable qu'entre l'appel de la fonction ` QVulkanWindowRenderer::initResources()` et celui de la fonction ` QVulkanWindowRenderer::releaseResources()`.
VkQueue QVulkanWindow::graphicsQueue() const
Renvoie la file d'attente graphique active.
Remarque : l'appel de cette fonction n'est valable qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const
Renvoie l'index de la famille de la file d'attente graphique active.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`. Les implémentations de `QVulkanWindowRenderer::updateQueueCreateInfo()` peuvent également appeler cette fonction.
uint32_t QVulkanWindow::hostVisibleMemoryIndex() const
Renvoie un index de type mémoire visible par l'hôte, adapté à un usage général.
Le type de mémoire renvoyé sera à la fois visible par l’hôte et cohérent. De plus, il sera mis en cache, si possible.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
bool QVulkanWindow::isValid() const
Renvoie « true » si cette fenêtre a réussi à initialiser toutes les ressources Vulkan, y compris la chaîne d'échange (swapchain).
Remarque : l'initialisation a lieu lors du premier événement « expose » après que la fenêtre est devenue visible.
VkImage QVulkanWindow::msaaColorImage(int idx) const
Renvoie l'image couleur à échantillonnage multiple spécifiée, ou VK_NULL_HANDLE si l'échantillonnage multiple n'est pas utilisé.
idx doit être compris dans l'intervalle [0, swapChainImageCount() - 1].
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
VkImageView QVulkanWindow::msaaColorImageView(int idx) const
Renvoie la vue de l'image couleur à échantillonnage multiple spécifiée, ou VK_NULL_HANDLE si l'échantillonnage multiple n'est pas utilisé.
idx doit être compris dans l'intervalle [0, swapChainImageCount() - 1].
Remarque : l’appel de cette fonction n’est valide qu’entre l’appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
VkPhysicalDevice QVulkanWindow::physicalDevice() const
Renvoie le périphérique physique actif.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::preInitResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const
Renvoie un pointeur vers les propriétés du périphérique physique actif.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::preInitResources()` et celui de ` QVulkanWindowRenderer::releaseResources()`.
VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const
Renvoie le nombre d'échantillons actuel sous la forme d'une valeur de type « VkSampleCountFlagBits ».
Lorsque la cible de rendu par défaut est utilisée, le champ « rasterizationSamples » de VkPipelineMultisampleStateCreateInfo doit être défini sur cette valeur.
Voir également setSampleCount() et supportedSampleCounts().
void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)
Définit la liste des extensions de périphériques à activer. extensions.
Les extensions non prises en charge sont ignorées.
L'extension « swapchain » est toujours ajoutée automatiquement ; il n'est donc pas nécessaire de l'inclure dans cette liste.
Remarque : cette fonction doit être appelée avant que la fenêtre ne soit rendue visible ou, au plus tard, dans la fonction ` QVulkanWindowRenderer::preInitResources()`, et n’a aucun effet si elle est appelée par la suite.
[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)
Définit la fonction de modification des fonctionnalités activées de l'appareil : modifier.
Remarque : pour contrôler les fonctionnalités de Vulkan 1.1, 1.2 ou 1.3, utilisez plutôt la surcharge prenant un paramètre de type ` EnabledFeatures2Modifier `.
Remarque : modifier est transmis à la fonction de rappel avec tous ses membres définis sur false. Il appartient à la fonction de modifier ces membres comme elle le juge opportun.
Cette fonction a été introduite dans Qt 6.7.
Voir aussi EnabledFeaturesModifier.
[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier)
Définit la fonction de modification des fonctionnalités activées de l'appareil modifier.
Il s'agit d'une fonction surchargée.
Cette fonction a été introduite dans Qt 6.7.
Voir également EnabledFeatures2Modifier.
void QVulkanWindow::setFlags(QVulkanWindow::Flags flags)
Configure le comportement en fonction de l'flags fourni.
Remarque : cette fonction doit être appelée avant que la fenêtre ne soit rendue visible ou, au plus tard, dans QVulkanWindowRenderer::preInitResources(), et n'a aucun effet si elle est appelée après.
Voir également flags().
void QVulkanWindow::setPhysicalDeviceIndex(int idx)
Demande l'utilisation du périphérique physique dont l'index est idx. Cet index correspond à la liste renvoyée par la fonction availablePhysicalDevices().
Par défaut, le premier périphérique physique est utilisé.
Remarque : cette fonction doit être appelée avant que la fenêtre ne soit rendue visible ou, au plus tard, dans QVulkanWindowRenderer::preInitResources(), et n’a aucun effet si elle est appelée après.
void QVulkanWindow::setPreferredColorFormats(const QList<VkFormat> &formats)
Définit l'formats préférée de la chaîne d'échange.
Par défaut, aucun format préféré par l'application n'est défini. Dans ce cas, le format préféré de la surface sera utilisé ou, à défaut, le format VK_FORMAT_B8G8R8A8_UNORM.
La liste contenue dans ` formats ` est triée. Si le premier format n’est pas pris en charge, le deuxième sera pris en compte, et ainsi de suite. Lorsqu’aucun format de la liste n’est pris en charge, le comportement est identique à celui du cas par défaut.
Pour connaître le format effectif après l’initialisation, appelez colorFormat().
Remarque : cette fonction doit être appelée avant que la fenêtre ne soit rendue visible ou, au plus tard, dans QVulkanWindowRenderer::preInitResources(), et n’a aucun effet si elle est appelée par la suite.
Remarque : la réimplémentation de QVulkanWindowRenderer::preInitResources() permet d’examiner dynamiquement la liste des formats pris en charge, si nécessaire. Dans ce cas, la surface est accessible via QVulkanInstance::surfaceForWindow(), tandis que cette fonction peut toujours être appelée en toute sécurité pour modifier les étapes ultérieures de l’initialisation.
Voir également colorFormat().
void QVulkanWindow::setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier)
Définit la fonction de modification des informations de création de file d'attente modifier.
Voir également QueueCreateInfoModifier.
void QVulkanWindow::setSampleCount(int sampleCount)
Demande un anticrénelage multi-échantillonnage avec le paramètre ` sampleCount` spécifié. Les valeurs valides sont 1, 2, 4, 8, … jusqu’à la valeur maximale prise en charge par le périphérique physique.
Lorsque le nombre d’échantillons est supérieur à 1, la fonction QVulkanWindow crée un tampon de couleur multi-échantillonnage au lieu de cibler simplement les images de la chaîne d’échange. Le rendu dans le tampon multi-échantillonnage sera converti en tampons non multi-échantillonnage à la fin de chaque image.
Pour consulter la liste des nombres d'échantillons pris en charge, appelez ` supportedSampleCounts()`.
Lors de la configuration du pipeline de rendu, appelez sampleCountFlagBits() pour interroger le nombre d'échantillons actif en tant que valeur « VkSampleCountFlagBits ».
Remarque : cette fonction doit être appelée avant que la fenêtre ne soit rendue visible ou, au plus tard, dans QVulkanWindowRenderer::preInitResources(), et n’a aucun effet si elle est appelée par la suite.
Voir également supportedSampleCounts() et sampleCountFlagBits().
QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()
Renvoie la liste des extensions prises en charge par les périphériques logiques créés à partir du périphérique physique sélectionné par la fonction ` setPhysicalDeviceIndex()`.
Remarque : cette fonction peut être appelée avant de rendre la fenêtre visible.
QList<int> QVulkanWindow::supportedSampleCounts()
Renvoie, sous forme de liste triée, l'ensemble des nombres d'échantillons pris en charge lors de l'utilisation du périphérique physique sélectionné par la fonction ` setPhysicalDeviceIndex()`.
Par défaut, la fonction ` QVulkanWindow ` utilise un nombre d'échantillons égal à 1. En appelant la fonction ` setSampleCount()` avec une valeur différente (2, 4, 8, …) de celles renvoyées par cette fonction, il est possible de demander un anti-aliasing multi-échantillons.
Remarque : cette fonction peut être appelée avant de rendre la fenêtre visible.
Voir également setSampleCount().
bool QVulkanWindow::supportsGrab() const
Renvoie « true » si la swapchain prend en charge son utilisation en tant que source de transfert, ce qui signifie que la fonction grab() est opérationnelle.
Remarque : l'appel de cette fonction n'est valable qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
VkImage QVulkanWindow::swapChainImage(int idx) const
Renvoie l'image de la chaîne de swap spécifiée.
idx Doit être comprise dans l'intervalle [0, swapChainImageCount() - 1].
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
int QVulkanWindow::swapChainImageCount() const
Renvoie le nombre d'images contenues dans la chaîne d'échange.
Remarque : l'accès à cette fonction est nécessaire lors de la fourniture d'un passage de rendu et d'un tampon d'image personnalisés. Le tampon d'image est spécifique à l'image actuelle de la chaîne d'échange ; l'application doit donc fournir plusieurs tampons d'image.
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
QSize QVulkanWindow::swapChainImageSize() const
Renvoie la taille de l'image de la chaîne d'échange.
Celle-ci correspond généralement à la taille de la fenêtre, mais peut également différer si vkGetPhysicalDeviceSurfaceCapabilitiesKHR signale une taille fixe.
De plus, il a été observé sur certaines plateformes que la taille de surface indiquée par Vulkan diffère lorsque la mise à l'échelle DPI élevée est activée, ce qui signifie que le résultat de ` size()` (indiqué par ` QWindow`) multiplié par ` devicePixelRatio()` était inférieur ou supérieur d'un pixel par rapport à la valeur renvoyée ici, vraisemblablement en raison de différences d'arrondi. Le code de rendu doit en tenir compte, et toute logique de rendu associée doit se baser sur la valeur renvoyée par cette fonction, et en aucun cas sur la taille rapportée par QWindow. Quelle que soit la taille de pixel théoriquement correcte, le rendu Vulkan doit toujours et uniquement s’appuyer sur la taille de surface rapportée par l’API Vulkan. Sinon, des erreurs de validation peuvent se produire, par exemple lors de la configuration de la fenêtre d’affichage, car les valeurs fournies par l’application peuvent se retrouver hors limites du point de vue de Vulkan.
Remarque : l’appel de cette fonction n’est valide qu’entre l’appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
VkImageView QVulkanWindow::swapChainImageView(int idx) const
Renvoie la vue de l'image de la chaîne de swap spécifiée.
idx Doit être comprise dans l'intervalle [0, swapChainImageCount() - 1].
Remarque : l'appel de cette fonction n'est valide qu'entre l'appel de ` QVulkanWindowRenderer::initSwapChainResources()` et celui de ` QVulkanWindowRenderer::releaseSwapChainResources()`.
Documentation sur les variables membres
const int QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT
Cette variable contient une valeur constante qui est toujours égale ou supérieure à la valeur maximale de la fonction ` concurrentFrameCount()`.
© 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.
