QRhi Class

Documentation des fonctions membres

[noexcept] QRhi::~QRhi()

Destructeur. Détruit le backend et libère les ressources.

void QRhi::addCleanupCallback(const QRhi::CleanupCallback &callback)

Enregistre une fonction ` callback ` qui sera appelée lors de la destruction de l'QRhi.

La fonction de rappel s’exécutera alors que la ressource graphique est encore disponible, ce qui permet à l’application de libérer proprement les instances de ` QRhiResource ` appartenant à l’ QRhi. Ceci est particulièrement utile pour gérer la durée de vie des ressources stockées dans des objets de type ` cache `, où le cache contient des `QRhiResources` ou des objets contenant des `QRhiResources`.

Voir également ~QRhi().

void QRhi::addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)

Enregistre la fonction de rappel callback, qui sera appelée lors de la destruction de l'QRhi. Cette surcharge prend un pointeur opaque, key, qui sert à garantir qu'un rappel donné ne soit enregistré (et donc appelé) qu'une seule fois.

Voir également removeCleanupCallback().

QRhi::Implementation QRhi::backend() const

Renvoie le type de backend associé à cette QRhi.

const char *QRhi::backendName() const

Renvoie le type du backend sous forme de chaîne de caractères pour cette QRhi.

[static] const char *QRhi::backendName(QRhi::Implementation impl)

Renvoie un nom descriptif pour le backend impl, généralement le nom de l'API 3D utilisée.

QRhi::FrameOpResult QRhi::beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})

Lance une nouvelle image en ciblant le prochain tampon disponible de swapChain.

Une trame se compose de mises à jour des ressources et d’un ou plusieurs passages de rendu et de calcul.

flags peut indiquer certains cas particuliers.

Le schéma général du rendu dans une chaîne de swap ( QWindow ) à l’aide d’une swapchain :

• Créez une chaîne d’échange.
• Appeler ` QRhiSwapChain::createOrResize()` chaque fois que la taille de la surface diffère de la précédente.
• Appeler ` QRhiSwapChain::destroy()` sur ` QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed`.
• Puis, à chaque image :

  beginFrame(sc);
  updates = nextResourceUpdateBatch();
  updates->...
  QRhiCommandBuffer *cb = sc->currentFrameCommandBuffer();
  cb->beginPass(sc->currentFrameRenderTarget(), colorClear, dsClear, updates);
  ...
  cb->endPass();
  ... // more passes as necessary
  endFrame(sc);

Renvoie ` QRhi::FrameOpSuccess ` en cas de succès, ou une autre valeur de ` QRhi::FrameOpResult ` en cas d’échec. Certaines de ces erreurs doivent être considérées comme des erreurs « légères », du type « réessayer plus tard » : lorsque ` QRhi::FrameOpSwapChainOutOfDate ` est renvoyé, la swapchain doit être redimensionnée ou mise à jour en appelant ` QRhiSwapChain::createOrResize()`. L’application doit alors tenter de générer une nouvelle image. La valeur « QRhi::FrameOpDeviceLost » signifie que le périphérique graphique est perdu, mais il est parfois possible de le récupérer en libérant toutes les ressources, y compris l’ QRhi e lui-même, puis en recréant toutes les ressources. Voir isDeviceLost() pour plus de détails.

Voir également endFrame(), beginOffscreenFrame() et isDeviceLost().

QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})

Lance une nouvelle image hors écran. Fournit un tampon de commandes permettant d’enregistrer les commandes de rendu dans ` cb`. La valeur ` flags ` est utilisée pour signaler certains cas particuliers, tout comme avec la fonction ` beginFrame()`.

Le rendu sans swapchain est également possible. Le cas d’utilisation typique consiste à l’utiliser dans des applications entièrement hors écran, par exemple pour générer des séquences d’images en effectuant un rendu puis une relecture sans jamais afficher de fenêtre.

L’utilisation dans des applications à l’écran (c’est-à-dire beginFrame, endFrame, beginOffscreenFrame, endOffscreenFrame, beginFrame, etc.) est également possible.

Lorsqu’une lecture texture ou buffer est programmée, les images hors écran empêchent le processeur de générer une autre image pendant que le GPU traite encore la précédente. Cela a pour effet secondaire que, si des lectures sont programmées, les résultats sont garantis d’être disponibles dès que endOffscreenFrame() renvoie une valeur. Ce n’est pas le cas avec les images ciblant une chaîne d’échange : dans ce cas, le GPU est potentiellement mieux exploité, mais l’utilisation des opérations de relecture nécessite davantage de précautions de la part de l’application, car la fonction endFrame(), contrairement à endOffscreenFrame(), ne garantit pas que les résultats de la relecture soient disponibles à ce moment-là.

Le schéma de base pour afficher une image sans swapchain, puis relire son contenu, pourrait ressembler à ceci :

QRhiReadbackResult rbResult;
QRhiCommandBuffer *cb;
rhi->beginOffscreenFrame(&cb);
cb->beginPass(rt, colorClear, dsClear);
// ...
u = nextResourceUpdateBatch();
u->readBackTexture(rb, &rbResult);
cb->endPass(u);
rhi->endOffscreenFrame();
// image data available in rbResult

Voir également endOffscreenFrame() et beginFrame().

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

Renvoie une matrice permettant aux applications de continuer à utiliser des données de sommets et des matrices de projection en perspective destinées à OpenGL (telles que celles générées par QMatrix4x4::perspective()), quel que soit le backend QRhi actif.

Dans un moteur de rendu classique, dès lors que ` this_matrix * mvp ` est utilisé à la place de ` mvp`, les données de sommets avec l’axe Y vers le haut et les fenêtres d’affichage avec une plage de profondeur comprise entre 0 et 1 peuvent être utilisées sans se soucier du backend (et donc de l’API graphique) qui sera utilisé lors de l’exécution. De cette manière, on peut éviter les branchements basés sur isYUpInNDC() et isClipDepthZeroToOne() (même si une telle logique peut encore s’avérer nécessaire lors de la mise en œuvre de certaines techniques graphiques avancées).

Consultez cette page pour une analyse de ce sujet du point de vue de Vulkan.

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)

Renvoie une nouvelle instance de ` QRhi ` avec un backend pour l’API graphique spécifiée par ` impl `, ainsi que le ` flags` indiqué. Renvoie ` nullptr ` en cas d’échec de la fonction.

params doit pointer vers une instance de l’une des sous-classes spécifiques au backend de ` QRhiInitParams`, telles que ` QRhiVulkanInitParams`, ` QRhiMetalInitParams`, ` QRhiD3D11InitParams`, ` QRhiD3D12InitParams` ou ` QRhiGles2InitParams`. Consultez ces classes pour obtenir des exemples de création d’un ` QRhi`.

QRhi Par conception, aucune logique de repli n’est implémentée : si l’API spécifiée ne peut pas être initialisée, la méthode create() échouera et des avertissements seront affichés dans la sortie de débogage par les backends. Les clients de QRhi, par exemple Qt Quick, peuvent toutefois fournir une logique supplémentaire permettant de se rabattre sur une API différente de celle qui a été demandée, en fonction de la plateforme. Si l’intention est simplement de tester si l’initialisation aboutirait en appelant `create()` ultérieurement, il est préférable d’utiliser ` probe()` plutôt que `create()`, car avec certains backends, la détection peut être implémentée de manière plus légère, contrairement à `create()`, qui effectue une initialisation complète de l’infrastructure et constitue un gaspillage si cette instance de ` QRhi ` est ensuite immédiatement supprimée.

importDevice Permet d’utiliser un périphérique graphique déjà existant, sans que ` QRhi ` ne crée le sien. Lorsqu’il n’est pas nul, ce paramètre doit pointer vers une instance de l’une des sous-classes de ` QRhiNativeHandles` : ` QRhiVulkanNativeHandles`, ` QRhiD3D11NativeHandles`, ` QRhiD3D12NativeHandles`, ` QRhiMetalNativeHandles`, ` QRhiGles2NativeHandles`. Les détails précis et la sémantique dépendent du backend et de l’API graphique sous-jacente.

La spécification d’un « QRhiAdapter » dans ` adapter ` offre une alternative transparente et indépendante de l’API au passage d’un « VkPhysicalDevice » via ` QRhiVulkanNativeHandles` ou d’un «adapter LUID» via ` QRhiD3D12NativeHandles`. La propriété de ` adapter ` n’est pas prise en charge. Voir ` enumerateAdapters()` pour plus d’informations sur cette approche.

Voir également probe().

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)

Équivalent à create(impl, params, flags, importDevice, nullptr).

int QRhi::currentFrameSlot() const

Renvoie l'index de l'emplacement de l'image en cours lors de l'enregistrement d'une image. Non spécifié lorsqu'il est appelé en dehors d'une image active (c'est-à-dire lorsque isRecordingFrame() est false).

Avec des backends tels que Vulkan ou Metal, il incombe au backend QRhi de se bloquer chaque fois qu’une nouvelle image est lancée et qu’il constate que le CPU a déjà FramesInFlight - 1 d’images d’avance sur le GPU (car le tampon de commandes soumis dans l’image n° current - FramesInFlight n’est pas encore terminé).

Les ressources susceptibles de changer d’une image à l’autre (telles que l’objet tampon natif sous-jacent à un QRhiBuffer de type QRhiBuffer::Dynamic) existent en plusieurs versions, de sorte que chaque image, qui peut être soumise alors qu’une précédente est encore en cours de traitement, fonctionne avec sa propre copie, évitant ainsi de bloquer le pipeline lors de la préparation de l’image. (Le contenu d’une ressource pouvant encore être utilisée par le GPU ne doit pas être modifié, mais se contenter d’attendre systématiquement la fin de l’image précédente réduirait l’utilisation du GPU et, en fin de compte, les performances et l’efficacité.)

D’un point de vue conceptuel, cela s’apparente quelque peu aux mécanismes de « copie à l’écriture » (copy-on-write) utilisés par certains conteneurs C++ et d’autres types de données. Cela peut également s’apparenter à ce qu’une implémentation OpenGL ou Direct 3D 11 effectue en interne pour certains types d’objets.

En pratique, ce double (ou triple) tampon de ressources est mis en œuvre dans les backends Vulkan, Metal et d’ QRhi s similaires en plaçant un nombre fixe d’ slots s de ressources natives (telles que VkBuffer) derrière une QRhiResource. Celles-ci peuvent ensuite être indexées par un index de créneau d’image allant de 0, 1, …, FramesInFlight-1, puis recommençant depuis le début.

Tout cela est géré de manière transparente pour les utilisateurs de QRhi. Cependant, les applications qui intègrent un rendu effectué directement via l’API graphique peuvent souhaiter mettre en place un double ou triple buffering similaire pour leurs propres ressources graphiques. Le moyen le plus simple d’y parvenir consiste à connaître le nombre maximal d’images en cours de traitement (accessible via resourceLimit()) et l’index de l’image (emplacement) actuelle (renvoyé par cette fonction).

Voir également isRecordingFrame(), beginFrame() et endFrame().

QRhiDriverInfo QRhi::driverInfo() const

Renvoie les métadonnées relatives au périphérique graphique utilisé par cette instance d'QRhi, dont l'initialisation a réussi.

QRhi::FrameOpResult QRhi::endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})

Termine, valide et présente un cadre qui avait été lancé lors du dernier appel à beginFrame() sur swapChain.

La gestion de la mise en mémoire tampon double (ou triple) est assurée en interne par les fonctions QRhiSwapChain et QRhi.

flags peut être utilisé de manière facultative pour modifier le comportement de certaines façons. Le passage de QRhi::SkipPresent permet d’éviter la mise en file d’attente de la commande Present ou l’appel de swapBuffers.

Renvoie QRhi::FrameOpSuccess en cas de succès, ou une autre valeur QRhi::FrameOpResult en cas d’échec. Certaines de ces valeurs doivent être considérées comme des erreurs « légères », du type « réessayer plus tard » : lorsque QRhi::FrameOpSwapChainOutOfDate est renvoyé, la chaîne de swap doit être redimensionnée ou mise à jour en appelant QRhiSwapChain::createOrResize(). L’application doit alors tenter de générer une nouvelle image. La valeur « QRhi::FrameOpDeviceLost » signifie que le périphérique graphique est perdu, mais il est parfois possible de le récupérer en libérant toutes les ressources, y compris l’ QRhi e elle-même, puis en recréant toutes les ressources. Voir isDeviceLost() pour plus de détails.

Voir également beginFrame() et isDeviceLost().

QRhi::FrameOpResult QRhi::endOffscreenFrame(QRhi::EndFrameFlags flags = {})

Termine, envoie et attend éventuellement l'image hors écran.

Contrairement à ` endFrame()`, cette fonction se bloque et attend la fin du travail côté GPU lorsqu'il y a des relectures actives de tampons ou de textures.

flags N’est pas utilisée actuellement.

Voir également beginOffscreenFrame().

[static, since 6.10] QRhi::AdapterList QRhi::enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)

Renvoie la liste des adaptateurs (périphériques physiques) présents, ou une liste vide lorsque cette fonctionnalité n'est pas disponible avec l'API graphique donnée.

Dans les backends où ce niveau de contrôle n'est pas disponible, la liste renvoyée est toujours vide. Ainsi, une liste vide n'indique pas qu'il n'y a pas de périphériques graphiques dans le système, mais que le contrôle fin permettant de sélectionner celui à utiliser n'est pas disponible.

On peut s'attendre à ce que les backends pour Direct 3D 11, Direct 3D 12 et Vulkan prennent entièrement en charge l'énumération des adaptateurs. Ce n'est pas forcément le cas des autres. Le backend est spécifié par ` impl`. Un objet ` QRhiAdapter ` renvoyé par cette fonction ne doit être utilisé que dans un appel à ` create()` avec le même ` impl`. Certaines API sous-jacentes peuvent présenter des limitations supplémentaires ; avec Vulkan en particulier, l’ QRhiAdapter est spécifié par ` QVulkanInstance ` (VkInstance).

L’appelant est censé détruire les objets QRhiAdapter figurant dans la liste. Hormis l’interrogation de info(), le seul but de ces objets est d’être transmis à create(), ou aux fonctions correspondantes dans les couches supérieures telles que Qt Quick.

L’extrait de code suivant, écrit spécifiquement pour Vulkan, montre comment énumérer les périphériques physiques disponibles et demander la création d’un ` QRhi ` pour celui choisi. En pratique, cela revient à transmettre un ` VkPhysicalDevice ` via un ` QRhiVulkanNativeHandles ` à ` create()`, mais cela implique moins de code spécifique à l’API du côté de l’application :

QRhiVulkanInitParams initParams;
initParams.inst = &vulkanInstance;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::Vulkan, &initParams);
QRhiAdapter*chosenAdapter = nullptr;
for (QRhiAdapter*adapter: adapters) {
    if (looksGood(adapter->info())) {
        chosenAdapter = adapter;
        break;
    }
}
QRhi*rhi = QRhi::create(QRhi::Vulkan, &initParams, {}, nullptr, chosenAdapter);
qDeleteAll(adapters);

La transmission d'un objet ` params ` est obligatoire en raison de la conception de certaines API graphiques sous-jacentes. Avec Vulkan en particulier, l'QVulkanInstance doit être fourni, car l'énumération n'est pas possible sans lui. Les autres champs de l'params, spécifiques au backend, ne seront en réalité pas utilisés par cette fonction.

nativeHandles est facultatif. Lorsqu’il est spécifié, il doit s’agir d’un QRhiD3D11NativeHandles, d’un QRhiD3D12NativeHandles ou d’un QRhiVulkanNativeHandles valide, de la même manière que pour la fonction create(). Cependant, contrairement à la fonction create(), seuls les champs relatifs au périphérique physique (dans le cas de Vulkan) ou au LUID de l’adaptateur (dans le cas de D3D) sont utilisés ; tous les autres champs sont ignorés. Cela permet de limiter les résultats à un adaptateur donné. Dans ce cas, la liste renvoyée contiendra 1 ou 0 élément.

Notez que, dans l’extrait de code précédent, l’implémentation de la fonction looksGood() ne peut effectuer aucun filtrage spécifique à la plateforme basé sur l’identité réelle de l’adaptateur ou du périphérique physique, telle que le LUID de l’adaptateur sous Windows ou le VkPhysicalDevice avec Vulkan. En effet, la fonction QRhiDriverInfo ne contient pas de données spécifiques à la plateforme. Utilisez plutôt ` nativeHandles ` pour obtenir des résultats déjà filtrés au sein même de la fonction `enumerateAdapters()`.

Les deux extraits de code suivants, qui prennent Direct 3D 12 comme exemple, sont équivalents en pratique :

// Approche basée sur `enumerateAdapters` à partir de Qt 6.10
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // LUID récupéré ailleurs, à transmettre maintenant à Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);
if (adapters.isEmpty()) { qWarning("L'adaptateur demandé est introuvable"); }
QRhi*rhi = QRhi::create(QRhi::D3D12, &initParams, {}, nullptr, adapters[0]);
qDeleteAll(adapters);

// traditional approach, more lightweight
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // retrieved a LUID from somewhere, now pass it on to Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi *rhi = QRhi::create(QRhi::D3D12, &initParams, {}, &nativeHandles, nullptr);

Cette fonction a été introduite dans Qt 6.10.

Voir également create().

QRhi::FrameOpResult QRhi::finish()

Attend que toutes les tâches de la file d'attente graphique (le cas échéant) soient terminées, puis exécute toutes les opérations différées, telles que la finalisation des relectures et la libération des ressources. Peut être appelée à l'intérieur ou à l'extérieur d'une image, mais pas à l'intérieur d'un passage. À l'intérieur d'une image, cela implique la soumission de toutes les tâches présentes dans le tampon de commandes.

bool QRhi::isClipDepthZeroToOne() const

Renvoie true si l'API graphique sous-jacente utilise une plage de profondeur [0, 1] dans l'espace de découpage.

En pratique, cette valeur est false uniquement pour OpenGL, car OpenGL utilise une plage de profondeur post-projection comprise entre [-1, 1]. (À ne pas confondre avec le mappage NDC-fenêtre contrôlé par glDepthRange(), qui utilise une plage comprise entre [0, 1], sauf si elle est redéfinie par l’ QRhiViewport.) Dans certaines versions d’OpenGL, la fonction glClipControl() pouvait être utilisée pour modifier cela, mais le backend OpenGL de QRhi n’utilise pas cette fonction, car elle n’est pas disponible dans OpenGL ES ni dans les versions d’OpenGL antérieures à la version 4.5.

bool QRhi::isDeviceLost() const

Renvoie « true » si le périphérique graphique a été perdu.

La perte du périphérique est généralement détectée dans ` beginFrame()`, ` endFrame()` ou ` QRhiSwapChain::createOrResize()`, selon le backend et les API natives sous-jacentes. Le cas le plus courant est ` endFrame()`, car c’est là que s’effectue l’affichage. Avec certains backends, ` QRhiSwapChain::createOrResize()` peut également échouer en raison d’une perte de périphérique. Cette fonction est donc fournie comme moyen générique de vérifier si une perte de périphérique a été détectée par une opération précédente.

Lorsque le périphérique est perdu, aucune autre opération ne doit être effectuée via ` QRhi`. Il convient plutôt de libérer toutes les ressources ` QRhi `, puis de détruire ` QRhi`. On peut alors tenter de créer un nouveau ` QRhi `. En cas de succès, toutes les ressources graphiques doivent être réinitialisées. Dans le cas contraire, réessayer plus tard, à plusieurs reprises.

Si les applications simples peuvent choisir de ne pas tenir compte de la perte d’un périphérique, sur les plateformes de bureau couramment utilisées, une telle perte peut survenir pour diverses raisons, notamment la déconnexion physique de la carte graphique, la désactivation du périphérique ou du pilote, la désinstallation ou la mise à jour du pilote graphique, ou encore à la suite d’erreurs entraînant une réinitialisation du périphérique graphique. Certaines de ces situations peuvent également se produire dans des circonstances tout à fait normales ; par exemple, la mise à jour du pilote graphique vers une version plus récente est une opération courante qui peut survenir à tout moment pendant l’exécution d’une application Qt. Les utilisateurs sont tout à fait en droit de s’attendre à ce que les applications puissent résister à cela, même lorsque l’application utilise activement une API telle qu’OpenGL ou Direct3D.

On peut s’attendre à ce que les frameworks propres à Qt, basés sur QRhi, tels que Qt Quick, gèrent ces situations et prennent les mesures appropriées en cas de perte d’un périphérique. Si les données relatives aux ressources graphiques, telles que les textures et les tampons, sont toujours disponibles côté CPU, un tel événement peut ne pas être perceptible du tout au niveau de l’application, car les ressources graphiques peuvent alors être réinitialisées de manière transparente. Cependant, les applications et bibliothèques fonctionnant directement avec QRhi doivent être préparées à vérifier et à gérer elles-mêmes les situations de perte de périphérique.

bool QRhi::isFeatureSupported(QRhi::Feature feature) const

Renvoie « true » si l'feature spécifiée est prise en charge

bool QRhi::isRecordingFrame() const

Renvoie « true » lorsqu'il existe une trame active, ce qui signifie qu'un appel à ` beginFrame()` (ou ` beginOffscreenFrame()`) a été effectué sans qu'il y ait encore d'appel correspondant à ` endFrame()` (ou ` endOffscreenFrame()`).

Voir également currentFrameSlot(), beginFrame() et endFrame().

bool QRhi::isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const

Renvoie « true » si la texture spécifiée format, modifiée par flags, est prise en charge.

La requête est prise en charge aussi bien pour les formats non compressés que pour les formats compressés.

bool QRhi::isYUpInFramebuffer() const

Renvoie « true » si l'API graphique sous-jacente fait pointer l'axe Y vers le haut dans les tampons d'image et les images.

En pratique, cette valeur est « true » uniquement pour OpenGL.

bool QRhi::isYUpInNDC() const

Renvoie « true » si, dans le système de coordonnées normalisées du périphérique de l'API graphique sous-jacente, l'axe Y est orienté vers le haut.

En pratique, cette fonction renvoie « false » uniquement pour Vulkan.

bool QRhi::makeThreadLocalNativeContextCurrent()

Avec OpenGL, cela rend le contexte OpenGL actif sur le thread actuel. La fonction n'a aucun effet avec d'autres backends.

L'appel de cette fonction est généralement pertinent dans le code du framework Qt, lorsqu'il faut s'assurer que le code OpenGL externe fourni par l'application puisse continuer à s'exécuter comme auparavant avec une utilisation directe d'OpenGL, tant que l'QRhi utilise le backend OpenGL.

Renvoie `false` en cas d'échec, de la même manière que ` QOpenGLContext::makeCurrent()`. Lorsque l'opération a échoué, on peut appeler ` isDeviceLost()` pour déterminer s'il y a eu perte de contexte. Une telle vérification équivaut à celle effectuée via ` QOpenGLContext::isValid()`.

Voir également QOpenGLContext::makeCurrent() et QOpenGLContext::isValid().

[static] int QRhi::mipLevelsForSize(const QSize &size)

Renvoie le nombre de niveaux de mip pour une ` size` donnée.

const QRhiNativeHandles *QRhi::nativeHandles()

Renvoie un pointeur vers la collection, spécifique au backend, d'objets natifs correspondant au périphérique, au contexte et aux concepts similaires utilisés par le backend.

Effectuez un transtypage vers QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiGles2NativeHandles ou QRhiMetalNativeHandles selon le cas.

QRhiBuffer *QRhi::newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)

Renvoie un nouveau tampon avec les paramètres type, usage et size spécifiés.

Voir également QRhiResource::destroy().

QRhiComputePipeline *QRhi::newComputePipeline()

Renvoie une nouvelle ressource de pipeline de calcul.

Voir également QRhiResource::destroy().

QRhiGraphicsPipeline *QRhi::newGraphicsPipeline()

Renvoie une nouvelle ressource de pipeline graphique.

Voir aussi QRhiResource::destroy().

QRhiRenderBuffer *QRhi::newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)

Renvoie un nouveau tampon de rendu avec les paramètres suivants : ` type`, ` pixelSize`, ` sampleCount` et ` flags`.

Lorsque ` backingFormatHint ` est défini sur un format de texture autre que ` QRhiTexture::UnknownFormat`, il peut être utilisé par le backend pour déterminer le format à utiliser pour le support de stockage du tampon de rendu.

Voir également QRhiResource::destroy().

QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)

Renvoie un nouvel échantillonneur avec le filtre de grossissement spécifié magFilter, le filtre de réduction minFilter, le mode de mipmapping mipmapMode, ainsi que les modes d'adressage (bouclage) addressU, addressV et addressW.

Voir également QRhiResource::destroy().

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

Renvoie une nouvelle ressource de collection de liaisons de ressources de shaders.

Voir également QRhiResource::destroy().

[since 6.9] QRhiShadingRateMap *QRhi::newShadingRateMap()

Renvoie un nouvel objet « shading rate map ».

Cette fonction a été introduite dans Qt 6.9.

QRhiSwapChain *QRhi::newSwapChain()

Renvoie une nouvelle chaîne d'échange.

Voir également QRhiResource::destroy() et QRhiSwapChain::createOrResize().

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

Renvoie une nouvelle texture 1D ou 2D avec les paramètres spécifiés pour ` format`, ` pixelSize`, ` sampleCount` et ` flags`.

Une texture 1D doit avoir l'QRhiTexture::OneDimensional défini dans flags. Cette fonction définit implicitement cet indicateur si la hauteur pixelSize est égale à 0.

Voir également QRhiResource::destroy().

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})

Renvoie une nouvelle texture 1D, 2D ou 3D avec les paramètres spécifiés : format, width, height, depth, sampleCount et flags.

Cette surcharge est adaptée aux textures 3D car elle permet de spécifier l’ depth. Une texture 3D doit avoir l’ QRhiTexture::ThreeDimensional défini dans flags, mais avec cette surcharge, cela peut être omis car l’indicateur est défini implicitement dès lors que depth est supérieur à 0. Pour les textures 1D, 2D et cubiques, depth doit être défini sur 0.

Une texture 1D doit avoir le paramètre QRhiTexture::OneDimensional défini dans flags. Cette surcharge définira implicitement ce drapeau si height et depth sont tous deux égaux à 0.

QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

Renvoie un nouveau tableau de textures 1D ou 2D avec les paramètres suivants : format, arraySize, pixelSize, sampleCount et flags.

Cette fonction définit implicitement ` QRhiTexture::TextureArray ` dans ` flags`.

Un tableau de textures 1D doit avoir le drapeau « QRhiTexture::OneDimensional » activé dans « flags ». Cette fonction activera implicitement ce drapeau si la hauteur de l'pixelSize est égale à 0.

Voir également ` newTexture()`.

QRhiTextureRenderTarget *QRhi::newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})

Renvoie une nouvelle cible de rendu de texture avec les annexes de couleur et de profondeur/stencil spécifiées dans ` desc`, ainsi que l'flags` indiquée.

Voir également QRhiResource::destroy().

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

Renvoie un lot disponible et vide dans lequel des opérations de type « copie » peuvent être enregistrées.

Comme elle n’est pas liée à une image en cours d’enregistrement, la séquence suivante est valide, par exemple :

rhi->beginFrame(swapchain);
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... do not commit the batch
rhi->endFrame();
// u stays valid (assuming buf stays valid as well)
rhi->beginFrame(swapchain);
swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
// ... draw with buf
rhi->endFrame();

QByteArray QRhi::pipelineCacheData()

Renvoie un blob de données binaires contenant les données collectées à partir des objets ` QRhiGraphicsPipeline ` et ` QRhiComputePipeline ` créés avec succès pendant la durée de vie de cet objet ` QRhi`.

En enregistrant puis, lors des exécutions suivantes de la même application, en rechargeant les données mises en cache, il est possible de réduire les temps de création des pipelines et des shaders. Le contenu exact du cache et de sa version sérialisée n’est pas spécifié ; il dépend toujours du backend utilisé et, dans certains cas, de l’implémentation particulière de l’API graphique.

Lorsque l’ PipelineCacheDataLoadSave est signalé comme non pris en charge, l’ QByteArray renvoyé est vide.

Si l’indicateur d’ EnablePipelineCacheDataSave n’a pas été spécifié lors de l’appel de create(), l’ QByteArray renvoyé peut être vide, même lorsque la fonctionnalité d’ PipelineCacheDataLoadSave est prise en charge.

Lorsque les données renvoyées ne sont pas vides, elles sont toujours spécifiques à la version de Qt et au backend QRhi. De plus, dans certains cas, il existe une forte dépendance vis-à-vis du périphérique graphique et de la version exacte du pilote utilisé. La fonction ` QRhi ` se charge d’ajouter l’en-tête approprié et les mesures de sécurité garantissant que les données puissent toujours être transmises en toute sécurité à ` setPipelineCacheData()` ; ainsi, toute tentative de chargement de données provenant d’une exécution sur une autre version d’un pilote sera gérée de manière sûre et sans heurts.

Voir EnablePipelineCacheDataSave pour plus de détails sur cette fonctionnalité.

Voir également setPipelineCacheData(), create() et isFeatureSupported().

[static] bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)

Renvoie « true » si l'on peut s'attendre à ce que la fonction create() aboutisse lorsqu'elle est appelée avec les paramètres impl et params fournis.

Pour certains backends, cela équivaut à appeler ` create()`, à vérifier sa valeur de retour, puis à détruire l’ QRhi résultant.

Pour d’autres, en particulier avec Metal, il peut exister une implémentation de sondage spécifique, qui permet d’effectuer des tests de manière plus légère sans polluer la sortie de débogage avec des avertissements en cas d’échec.

Voir également create().

void QRhi::releaseCachedResources()

Tente de libérer des ressources dans les caches du backend. Cela peut concerner aussi bien les ressources CPU que GPU. Seules la mémoire et les ressources pouvant être recréées automatiquement sont concernées. Par exemple, si l'implémentation de ` QRhiGraphicsPipeline ` du backend gère un cache des résultats de compilation des shaders, l'appel de cette fonction entraîne le vidage de ce cache, ce qui peut potentiellement libérer de la mémoire et des ressources graphiques.

L'appel de cette fonction est pertinent dans les environnements aux ressources limitées, où il devient nécessaire, à un certain moment, de garantir une utilisation minimale des ressources, au détriment des performances.

void QRhi::removeCleanupCallback(const void *key)

Désenregistre la fonction de rappel via key. Si aucune fonction de rappel de nettoyage n'a été enregistrée via key, la fonction ne fait rien. Les fonctions de rappel enregistrées sans clé ne peuvent pas être supprimées.

Voir également addCleanupCallback().

int QRhi::resourceLimit(QRhi::ResourceLimit limit) const

Renvoie la valeur de la ressource spécifiée limit.

Les valeurs sont censées être récupérées par les backends lors de l'initialisation, ce qui signifie que l'appel de cette fonction est une opération légère.

void QRhi::setPipelineCacheData(const QByteArray &data)

Charge la fonction data dans le cache du pipeline, le cas échéant.

Lorsque l'PipelineCacheDataLoadSave est signalée comme non prise en charge, la fonction peut être appelée en toute sécurité, mais n'a aucun effet.

Le blob renvoyé par ` pipelineCacheData()` est toujours spécifique à la version de Qt, au backend ` QRhi ` et, dans certains cas, également au périphérique graphique et à une version donnée du pilote graphique. ` QRhi ` se charge d’ajouter l’en-tête approprié et les mesures de sécurité garantissant que les données puissent toujours être transmises en toute sécurité à cette fonction. En cas d'incompatibilité, par exemple parce que le pilote a été mis à jour vers une version plus récente ou parce que les données ont été générées à partir d'un autre backend QRhi, un avertissement est affiché et data est ignorée en toute sécurité.

Avec Vulkan, cela correspond directement à `VkPipelineCache`. L’appel de cette fonction crée un nouvel objet de cache de pipeline Vulkan, dont les données initiales proviennent de ` data`. L’objet de cache de pipeline est ensuite utilisé par tous les objets ` QRhiGraphicsPipeline ` et ` QRhiComputePipeline ` créés par la suite, ce qui peut potentiellement accélérer la création du pipeline.

D'autres API ne disposent pas de véritable cache de pipeline, mais peuvent fournir un cache contenant du bytecode issu de la compilation de shaders (D3D) ou des binaires de programme (OpenGL). Dans les applications qui effectuent de nombreuses compilations de shaders à partir du code source lors de l’exécution, cela peut apporter un gain de performance significatif lors des exécutions suivantes si le « cache de pipeline » est prérempli à partir d’une exécution antérieure à l’aide de cette fonction.

Consultez EnablePipelineCacheDataSave pour plus de détails sur cette fonctionnalité.

Voir également pipelineCacheData() et isFeatureSupported().

[since 6.9] void QRhi::setQueueSubmitParams(QRhiNativeHandles *params)

Avec les backends et les API graphiques concernés, cette fonction permet de fournir des arguments supplémentaires lors de la prochaine soumission de commandes à la file d’attente des commandes graphiques.

En particulier, avec Vulkan, cela permet de transmettre une liste d’objets sémaphores Vulkan que l’ vkQueueSubmit() doit signaler et sur lesquels elle doit attendre. params doit alors être un QRhiVulkanQueueSubmitParams. Cela s’avère essentiel dans certains cas d’utilisation avancés, par exemple lors de l’exécution d’appels Vulkan natifs impliquant de devoir attendre et signaler des VkSemaphores gérés par le code de rendu ou de calcul Vulkan personnalisé de l’application. De plus, cela permet également de spécifier des sémaphores supplémentaires sur lesquels attendre lors de la prochaine vkQueuePresentKHR().

Avec de nombreux autres backends, l’implémentation de cette fonction est une opération sans effet.

Cette fonction a été introduite dans Qt 6.9.

[static] QSize QRhi::sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)

Renvoie la taille de l'image de texture pour un ` mipLevel` donné, calculée à partir de la taille de niveau 0 indiquée dans ` baseLevelSize`.

QRhiStats QRhi::statistics() const

Collecte et renvoie des statistiques sur les durées et les allocations des ressources graphiques.

Les données relatives aux allocations de mémoire ne sont disponibles qu'avec certains backends, où ces opérations sont contrôlées par Qt. Avec les API graphiques ne permettant pas de contrôle de bas niveau sur les allocations de mémoire des ressources, cette fonctionnalité ne sera jamais prise en charge et tous les champs concernés dans les résultats seront à 0.

Avec Vulkan en particulier, les valeurs sont toujours valides et sont extraites de la bibliothèque d’allocation de mémoire sous-jacente. Cela permet d’avoir un aperçu des besoins en mémoire des tampons et textures actifs.

Il en va de même pour Direct 3D 12. Outre les statistiques de la bibliothèque d’allocation de mémoire, le résultat inclut ici également un champ « totalUsageBytes » qui indique la taille totale, y compris les ressources supplémentaires qui ne relèvent pas du contrôle de la bibliothèque d’allocation de mémoire (tampons de swapchain, tas de descripteurs, etc.), telles que rapportées par DXGI.

Les valeurs correspondent à l’ensemble des types de mémoire utilisés (c’est-à-dire mémoire vidéo + mémoire système dans le cas d’un GPU discret).

Des données supplémentaires, telles que le temps total en millisecondes consacré à la création des pipelines graphiques et de calcul (ce qui implique généralement la compilation de shaders ou des recherches dans le cache, ainsi que des traitements potentiellement coûteux), sont disponibles avec la plupart des backends.

QList<int> QRhi::supportedSampleCounts() const

Renvoie la liste des nombres d'échantillons pris en charge.

Un exemple typique serait (1, 2, 4, 8).

Avec certains backends, cette liste de valeurs prises en charge est définie à l’avance, tandis qu’avec d’autres, ce sont les propriétés (physiques) du périphérique qui indiquent ce qui est pris en charge au moment de l’exécution.

Voir également QRhiRenderBuffer::setSampleCount(), QRhiTexture::setSampleCount(), QRhiGraphicsPipeline::setSampleCount() et QRhiSwapChain::setSampleCount().

[since 6.9] QList<QSize> QRhi::supportedShadingRates(int sampleCount) const

Renvoie la liste des taux d'ombrage variables pris en charge pour l'sampleCount spécifiée.

La valeur 1x1 est toujours prise en charge.

Cette fonction a été introduite dans Qt 6.9.

QThread *QRhi::thread() const

Renvoie le thread sur lequel l'QRhi a été initialized.

int QRhi::ubufAligned(int v) const

Renvoie la valeur (généralement un décalage) v alignée selon l'alignement uniforme du tampon spécifié par ubufAlignment().

int QRhi::ubufAlignment() const

Renvoie l'alignement minimal en octets d'un tampon uniforme. Cette valeur est généralement de 256.

Toute tentative de liaison d'une région de tampon uniforme avec un décalage non aligné sur cette valeur entraînera des échecs, selon le backend et l'API graphique sous-jacente.

Voir également ubufAligned().

[static] QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

Génère et renvoie une structure ` QRhiSwapChainProxyData ` contenant des données opaques spécifiques au backend et à l’API graphique spécifiés par ` impl`. ` window ` correspond à l’ QWindow e ciblée par une swapchain.

La structure renvoyée peut être transmise à ` QRhiSwapChain::setProxyData()` (). Cela s’avère utile dans les systèmes de rendu multithread : cette fonction statique est censée être appelée sur le thread principal (GUI), contrairement à toutes les opérations ` QRhi `, puis transférée au thread travaillant avec ` QRhi ` et ` QRhiSwapChain `, avant d’être transmise à la swapchain. Cela permet d’effectuer des requêtes natives de la plateforme qui ne peuvent être appelées en toute sécurité que sur le thread principal, par exemple pour interroger la CAMetalLayer à partir d’une NSView, puis de transmettre les données à l’ QRhiSwapChain, qui réside sur le thread de rendu. Dans l’exemple Metal, l’accès à view.layer sur un thread de rendu dédié déclenche un avertissement dans le Thread Checker de Xcode. Grâce au mécanisme de proxy de données, ce problème est évité.

Lorsque les threads ne sont pas impliqués, il n’est pas nécessaire de générer et de transmettre l’ QRhiSwapChainProxyData: les backends sont garantis de pouvoir interroger eux-mêmes tout ce qui est nécessaire, et si tout réside sur le thread principal (GUI), cela devrait suffire.