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 un callback qui est invoqué lorsque le QRhi est détruit.

Le rappel sera exécuté alors que la ressource graphique est toujours disponible, ce qui permet à l'application de libérer proprement les instances QRhiResource appartenant à QRhi. Cela est particulièrement utile pour gérer la durée de vie des ressources stockées dans des objets de type cache, lorsque 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 callback pour qu'il soit invoqué lorsque QRhi est détruit. Cette surcharge prend un pointeur opaque, key, qui est utilisé pour s'assurer qu'un rappel donné n'est enregistré (et donc appelé) qu'une seule fois.

Voir aussi removeCleanupCallback().

QRhi::Implementation QRhi::backend() const

Retourne le type de backend pour cette QRhi.

const char *QRhi::backendName() const

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

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

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

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

Démarre une nouvelle trame ciblant le prochain tampon disponible sur swapChain.

Une trame se compose de mises à jour de ressources et d'une ou plusieurs passes de rendu et de calcul.

flags peut indiquer certains cas particuliers.

Le modèle de haut niveau du rendu dans un site QWindow à l'aide d'une chaîne d'échange :

• Créez une chaîne d'échange.
• Appelez QRhiSwapChain::createOrResize() chaque fois que la taille de la surface est différente de la précédente.
• Appelez QRhiSwapChain::destroy() sur QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed.
• Ensuite, à 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 QRhi::FrameOpResult en cas d'échec. Certains de ces échecs doivent être traités comme des erreurs légères, du type "réessayez plus tard" : Lorsque QRhi::FrameOpSwapChainOutOfDate est renvoyé, la chaîne d'échange doit être redimensionnée ou mise à jour en appelant QRhiSwapChain::createOrResize(). L'application doit ensuite essayer de générer une nouvelle image. QRhi::FrameOpDeviceLost signifie que le périphérique graphique est perdu, mais cela peut également être récupéré en libérant toutes les ressources, y compris le QRhi 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 = {})

Démarre une nouvelle image hors écran. Fournit un tampon de commande adapté à l'enregistrement des commandes de rendu dans cb. flags est utilisé pour indiquer certains cas particuliers, tout comme avec beginFrame().

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

L'utilisation dans des applications à l'écran (donc beginFrame, endFrame, beginOffscreenFrame, endOffscreenFrame, beginFrame, ...) est également possible, mais elle réduit le parallélisme et ne devrait donc être utilisée que rarement.

Les images hors écran ne permettent pas au CPU de générer potentiellement une autre image alors que le GPU est toujours en train de traiter l'image précédente. Cela a pour effet secondaire que si des retours en arrière sont planifiés, les résultats sont garantis d'être disponibles une fois que endOffscreenFrame() est retourné. Ce n'est pas le cas avec les trames ciblant une chaîne d'échange : là, le GPU est potentiellement mieux utilisé, mais le travail avec les opérations de relecture nécessite plus d'attention de la part de l'application car endFrame(), contrairement à endOffscreenFrame(), ne garantit pas que les résultats de la relecture sont disponibles à ce moment-là.

Le squelette du rendu d'un cadre sans chaîne d'échange, puis de la lecture du contenu du cadre, pourrait ressembler à ce qui suit :

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 qui peut être utilisée pour permettre aux applications de continuer à utiliser les données de vertex et les matrices de projection de perspective ciblées par OpenGL (telles que celles générées par QMatrix4x4::perspective()), quel que soit le backend QRhi actif.

Dans un moteur de rendu typique, une fois que this_matrix * mvp est utilisé au lieu de mvp, les données de vertex avec Y up et les perspectives avec une profondeur de 0 à 1 peuvent être utilisées sans tenir compte du backend (et donc de l'API graphique) qui sera utilisé au moment de l'exécution. De cette manière, les branchements basés sur isYUpInNDC() et isClipDepthZeroToOne() peuvent être évités (bien qu'une telle logique puisse encore être nécessaire lors de la mise en œuvre de certaines techniques graphiques avancées).

Voir cette page pour une discussion sur le 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 QRhi avec un backend pour l'API graphique spécifiée par impl avec le flags spécifié. Retourne nullptr si la fonction échoue.

params doit pointer vers une instance de l'une des sous-classes de QRhiInitParams spécifiques au backend, telles que QRhiVulkanInitParams, QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams, QRhiGles2InitParams. Voir ces classes pour des exemples de création de QRhi.

QRhi ne met en œuvre aucune logique de repli : si l'API spécifiée ne peut pas être initialisée, create() échouera, avec des avertissements imprimés sur 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 revenir à une API différente de celle demandée, en fonction de la plate-forme. Si l'intention est simplement de tester si l'initialisation réussira lors d'un appel ultérieur à create(), il est préférable d'utiliser probe() au lieu de create(), parce qu'avec certains backends, le sondage peut être mis en œuvre d'une manière plus légère que create(), qui effectue une initialisation complète de l'infrastructure et constitue un gaspillage si l'instance de QRhi est ensuite immédiatement jetée.

importDevice permet d'utiliser un périphérique graphique déjà existant, sans que QRhi ne crée son propre périphérique. 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 exacts et la sémantique dépendent du backand et de l'API graphique sous-jacente.

La spécification d'un QRhiAdapter dans adapter offre une alternative transparente et inter-API à la transmission d'un VkPhysicalDevice via QRhiVulkanNativeHandles, ou d'un LUID d'adaptateur via QRhiD3D12NativeHandles. La propriété de adapter n'est pas prise en compte. 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 la trame en cours d'enregistrement d'une trame. 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 lorsqu'il démarre une nouvelle image et constate que le CPU a déjà FramesInFlight - 1 images d'avance sur le GPU (parce que le tampon de commande soumis dans l'image n° current - FramesInFlight ne s'est pas encore achevé).

Les ressources qui ont tendance à changer entre les images (telles que l'objet tampon natif soutenant un QRhiBuffer de type QRhiBuffer::Dynamic) existent en plusieurs versions, de sorte que chaque image, qui peut être soumise alors qu'une image précédente est encore en cours de traitement, fonctionne avec sa propre copie, ce qui évite de bloquer le pipeline lors de la préparation de l'image. (Le contenu d'une ressource encore en cours d'utilisation dans le GPU ne doit pas être touché, mais le fait de toujours attendre que l'image précédente soit terminée réduirait l'utilisation du GPU et, en fin de compte, les performances et l'efficacité).

D'un point de vue conceptuel, ce système est quelque peu similaire aux schémas de copie sur écriture utilisés par certains conteneurs C++ et d'autres types. Il peut également être similaire à ce qu'une implémentation OpenGL ou Direct 3D 11 effectue en interne pour certains types d'objets.

En pratique, cette double (ou triple) mise en mémoire tampon est réalisée dans les backends Vulkan, Metal et autres QRhi similaires en ayant un nombre fixe de ressources natives (telles que VkBuffer) slots derrière un QRhiResource qui peut ensuite être indexé par un index de frame slot allant de 0, 1, ... à FramesInFlight-1, puis en s'enroulant autour de lui.

Tout cela est géré de manière transparente pour les utilisateurs de QRhi. Cependant, les applications qui intègrent le rendu effectué directement avec l'API graphique peuvent vouloir effectuer un double ou triple tamponnage similaire de leurs propres ressources graphiques. Il est alors plus facile d'y parvenir en connaissant les valeurs du nombre maximal de trames en vol (récupérable via resourceLimit()) et l'index de la trame courante (slot) (retourné par cette fonction).

Voir aussi isRecordingFrame(), beginFrame() et endFrame().

QRhiDriverInfo QRhi::driverInfo() const

Renvoie les métadonnées du périphérique graphique utilisé par cette instance QRhi initialisée avec succès.

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

Termine, valide et présente une trame qui a été commencée dans le dernier beginFrame() sur swapChain.

La double (ou triple) mise en mémoire tampon est gérée en interne par les serveurs QRhiSwapChain et QRhi.

flags peut être utilisé de manière optionnelle pour modifier le comportement de certaines manières. Passer QRhi::SkipPresent évite de mettre en file d'attente la commande Present ou d'appeler swapBuffers.

Renvoie QRhi::FrameOpSuccess en cas de succès, ou une autre valeur QRhi::FrameOpResult en cas d'échec. Certaines de ces erreurs doivent être traitées comme des erreurs légères, du type "réessayez plus tard" : Lorsque QRhi::FrameOpSwapChainOutOfDate est renvoyé, la chaîne d'échange doit être redimensionnée ou mise à jour en appelant QRhiSwapChain::createOrResize(). L'application doit ensuite essayer de générer une nouvelle image. QRhi::FrameOpDeviceLost signifie que le périphérique graphique est perdu, mais cela peut également être récupéré en libérant toutes les ressources, y compris le QRhi lui-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, soumet et attend le cadre hors écran.

flags n'est pas utilisé actuellement.

Voir aussi 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 si un tel contrôle n'est pas disponible avec une API graphique donnée.

Pour les backends où un tel 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 qu'il n'y a pas de contrôle fin sur le choix du périphérique à utiliser.

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. D'autres peuvent ne pas le faire. Le backend est spécifié par impl. Un 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 d'autres limitations ; avec Vulkan en particulier, QRhiAdapter est spécifié à QVulkanInstance (VkInstance).

L'appelant est censé détruire les objets QRhiAdapter de la liste. Outre 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 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 le périphérique choisi. En pratique, cela équivaut à 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 de params est nécessaire en raison de la conception de certaines API graphiques sous-jacentes. Avec Vulkan en particulier, QVulkanInstance doit être fourni, car l'énumération n'est pas possible sans lui. D'autres champs dans le params spécifique au backend ne seront pas réellement 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, comme pour create(). Cependant, contrairement à create(), seuls les champs du périphérique physique (dans le cas de Vulkan) ou du LUID de l'adaptateur (dans le cas de D3D) sont utilisés, tous les autres champs sont ignorés. Ceci peut être utilisé pour restreindre les résultats à un adaptateur donné. La liste renvoyée contiendra 1 ou 0 éléments dans ce cas.

Notez que dans l'extrait de code précédent, l'implémentation de la fonction looksGood() ne peut pas effectuer de filtrage spécifique à la plateforme basé sur la véritable identité de l'adaptateur / du périphérique physique, comme le LUID de l'adaptateur sous Windows ou le VkPhysicalDevice avec Vulkan. En effet, QRhiDriverInfo ne contient pas de données spécifiques à la plate-forme. Au lieu de cela, utilisez nativeHandles pour obtenir les résultats filtrés déjà à l'intérieur de enumerateAdapters().

Les deux extraits suivants, qui utilisent Direct 3D 12 comme exemple, sont équivalents dans la pratique :

// approche basée sur l'énumération des adaptateurs depuis Qt  6.10QRhiD3D12InitParams initParams ; QRhiD3D12NativeHandles nativeHandles ; nativeHandles.adapterLuidLow = luid.LowPart ; // a récupéré un LUID quelque part, le transmet maintenant à QtnativeHandles.adapterLuidHigh = luid.HighPart ;QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles) ;if (adapters.isEmpty()) { qWarning("Requested adapter was not found") ; }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 aussi create().

QRhi::FrameOpResult QRhi::finish()

Attend que le travail sur la file d'attente graphique (le cas échéant) soit terminé, puis exécute toutes les opérations différées, comme l'achèvement des relectures et des libérations de ressources. Peut être appelé à l'intérieur et à l'extérieur d'une trame, mais pas à l'intérieur d'une passe. À l'intérieur d'une trame, elle implique la soumission de tout travail sur le tampon de commande.

bool QRhi::isClipDepthZeroToOne() const

Renvoie true si l'API graphique sous-jacente utilise la plage de profondeur [0, 1] dans l'espace clip.

En pratique, c'est false pour OpenGL uniquement, car OpenGL utilise une plage de profondeur post-projection de [-1, 1]. (à ne pas confondre avec la correspondance NDC-fenêtre contrôlée par glDepthRange(), qui utilise une plage de [0, 1], à moins qu'elle ne soit remplacée par QRhiViewport) Dans certaines versions d'OpenGL, glClipControl() pourrait être utilisé pour changer cela, mais le backend OpenGL de QRhi n'utilise pas cette fonction car elle n'est pas disponible dans OpenGL ES ou dans les versions d'OpenGL inférieures à la version 4.5.

bool QRhi::isDeviceLost() const

Retourne vrai 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(), en fonction du backend et des API natives sous-jacentes. Le plus courant est endFrame() car c'est là que la présentation a lieu. Avec certains backends, QRhiSwapChain::createOrResize() peut également échouer en raison d'une perte de périphérique. C'est pourquoi cette fonction est fournie comme un 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 par l'intermédiaire de QRhi. Au contraire, toutes les ressources de QRhi doivent être libérées, suivies de la destruction de QRhi. Un nouveau QRhi peut alors être tenté d'être créé. En cas de succès, toutes les ressources graphiques doivent être réinitialisées. Dans le cas contraire, il faut réessayer plus tard, à plusieurs reprises.

Alors que les applications simples peuvent décider de ne pas se préoccuper de la perte de périphérique, sur les plates-formes de bureau couramment utilisées, une perte de périphérique peut se produire pour diverses raisons, notamment la déconnexion physique de l'adaptateur graphique, la désactivation du périphérique ou du pilote, la désinstallation ou la mise à jour du pilote graphique, ou des erreurs qui entraînent une réinitialisation du périphérique graphique. Par exemple, la mise à jour du pilote graphique vers une version plus récente est une tâche courante qui peut se produire à tout moment lorsqu'une application Qt est en cours d'exécution. Les utilisateurs peuvent très bien s'attendre à ce que les applications soient capables de survivre à cela, même lorsque l'application utilise activement une API comme OpenGL ou Direct3D.

On peut s'attendre à ce que les propres cadres de Qt construits sur QRhi, tels que Qt Quick, gèrent et prennent les mesures appropriées lorsqu'une perte de périphérique se produit. Si les données relatives aux ressources graphiques, telles que les textures et les tampons, sont toujours disponibles du côté de l'unité centrale, un tel événement peut ne pas être perceptible au niveau de l'application puisque les ressources graphiques peuvent être réinitialisées de manière transparente à ce moment-là. Cependant, les applications et les bibliothèques qui travaillent 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'adresse feature spécifiée est prise en charge

bool QRhi::isRecordingFrame() const

Retourne vrai s'il y a un cadre actif, ce qui signifie qu'il y a eu un beginFrame() (ou beginOffscreenFrame()) sans endFrame() (ou endOffscreenFrame()) correspondant.

Voir aussi 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 à la fois pour les formats non compressés et compressés.

bool QRhi::isYUpInFramebuffer() const

Renvoie true si l'API graphique sous-jacente fait pointer l'axe Y vers le haut dans les framebuffers et les images.

En pratique, il s'agit de true pour OpenGL uniquement.

bool QRhi::isYUpInNDC() const

Renvoie true si l'API graphique sous-jacente a l'axe Y orienté vers le haut dans son système de coordonnées normalisé.

En pratique, il s'agit de false pour Vulkan uniquement.

bool QRhi::makeThreadLocalNativeContextCurrent()

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

L'appel à cette fonction est typiquement pertinent dans le code du cadre Qt XML, quand on doit s'assurer que le code OpenGL externe fourni par l'application peut toujours fonctionner comme avant avec l'utilisation directe d'OpenGL, aussi longtemps que QRhi utilise le backend OpenGL.

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

Voir aussi QOpenGLContext::makeCurrent() et QOpenGLContext::isValid().

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

Renvoie le nombre de niveaux de mip pour un size donné.

const QRhiNativeHandles *QRhi::nativeHandles()

Renvoie un pointeur vers la collection d'objets natifs spécifiques au backend pour l'appareil, le contexte et les concepts similaires utilisés par le backend.

Le pointeur peut être converti en 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 adresses type, usage et size spécifiées.

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 valeurs spécifiées 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écider du format à utiliser pour le stockage du tampon de rendu.

Voir aussi 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 d'agrandissement spécifié magFilter, le filtre de minimisation minFilter, le mode mipmapping mipmapMode, et les modes d'adressage (wrap) addressU, addressV, et addressW.

Voir également QRhiResource::destroy().

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

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

Voir aussi QRhiResource::destroy().

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

Renvoie un nouvel objet de carte de taux d'ombrage.

Cette fonction a été introduite dans Qt 6.9.

QRhiSwapChain *QRhi::newSwapChain()

Renvoie une nouvelle chaîne d'échange.

Voir aussi 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 valeurs spécifiées format, pixelSize, sampleCount, et flags.

Pour un tableau de textures 1D, QRhiTexture::OneDimensional doit être défini dans flags. Cette fonction active implicitement ce drapeau si la hauteur de 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 valeurs spécifiées format, width, height, depth, sampleCount, et flags.

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

Pour une texture 1D, QRhiTexture::OneDimensional doit être défini dans flags. Cette surcharge activera implicitement ce drapeau si height et depth valent tous deux 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 valeurs spécifiées format, arraySize, pixelSize, sampleCount, et flags.

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

Pour un tableau de textures 1D, QRhiTexture::OneDimensional doit être défini dans flags. Cette fonction définira implicitement cet indicateur si la hauteur de 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 attachements de couleur et de profondeur/stencil donnés dans desc, et avec la valeur spécifiée flags.

Voir aussi QRhiResource::destroy().

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

Renvoie un lot vide et disponible 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 valable à titre d'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 des données collectées à partir de QRhiGraphicsPipeline et QRhiComputePipeline créées avec succès pendant la durée de vie de ce QRhi.

En sauvegardant puis en rechargeant les données du cache lors des exécutions ultérieures de la même application, il est possible de réduire les temps de création des pipelines et des shaders. Ce que le cache et sa version sérialisée comprennent exactement n'est pas spécifié, est toujours spécifique au backend utilisé et, dans certains cas, dépend également de l'implémentation particulière de l'API graphique.

Lorsque PipelineCacheDataLoadSave est signalé comme n'étant pas pris en charge, le fichier QByteArray renvoyé est vide.

Lorsque l'indicateur EnablePipelineCacheDataSave n'a pas été spécifié lors de l'appel à create(), la page QByteArray renvoyée peut être vide, même si la fonctionnalité PipelineCacheDataLoadSave est prise en charge.

Lorsque les données renvoyées sont non vides, elles sont toujours spécifiques à la version de Qt et au backend QRhi. En outre, dans certains cas, il existe une forte dépendance à l'égard du périphérique graphique et de la version exacte du pilote utilisé. QRhi se charge d'ajouter l'en-tête approprié et les sauvegardes qui garantissent que les données peuvent toujours être transmises en toute sécurité à setPipelineCacheData(), de sorte que les tentatives de chargement de données à partir d'une exécution sur une autre version d'un pilote seront traitées en toute sécurité et avec élégance.

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

Voir aussi setPipelineCacheData(), create() et isFeatureSupported().

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

Retourne vrai si create() est susceptible de réussir lorsqu'il est appelé avec impl et params.

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

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

Voir aussi create().

void QRhi::releaseCachedResources()

Tente de libérer des ressources dans les caches du backend. Il peut s'agir des ressources du processeur et du processeur graphique. Seules la mémoire et les ressources qui peuvent être recréées automatiquement sont concernées. Par exemple, si l'implémentation QRhiGraphicsPipeline du backend maintient un cache des résultats de la compilation des shaders, l'appel à cette fonction conduit à vider ce cache, libérant ainsi potentiellement de la mémoire et des ressources graphiques.

L'appel à cette fonction est utile dans les environnements où les ressources sont limitées et où, à un certain moment, il est nécessaire d'assurer une utilisation minimale des ressources, au détriment des performances.

void QRhi::removeCleanupCallback(const void *key)

Désenregistre le rappel auprès de key. Si aucun rappel de nettoyage n'a été enregistré auprès de key, la fonction ne fait rien. Les rappels enregistrés sans clé ne peuvent pas être supprimés.

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 demandées par les backends lors de l'initialisation, ce qui signifie que l'appel à cette fonction est une opération légère.

void QRhi::setPipelineCacheData(const QByteArray &data)

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

Lorsque PipelineCacheDataLoadSave est signalé comme n'étant pas pris 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 XML, 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 sauvegardes qui garantissent que les données peuvent toujours être transmises en toute sécurité à cette fonction. En cas de non-concordance, par exemple parce que le pilote a été mis à niveau vers une version plus récente ou parce que les données ont été générées à partir d'un backend QRhi différent, un avertissement est imprimé et data est ignoré en toute sécurité.

Avec Vulkan, cela correspond directement à VkPipelineCache. L'appel à 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 ultérieurement, ce qui accélère potentiellement la création du pipeline.

Avec d'autres API, il n'y a pas de véritable cache de pipeline, mais elles peuvent fournir un cache avec du bytecode provenant de compilations de shaders (D3D) ou de binaires de programmes (OpenGL). Dans les applications qui compilent beaucoup de shaders à partir des sources au moment de l'exécution, cela peut donner un coup de pouce significatif lors des exécutions suivantes si le "pipeline cache" est pré-alimenté à partir d'une exécution antérieure à l'aide de cette fonction.

Voir 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, le cas échéant, cette fonction permet de fournir des arguments supplémentaires à la prochaine soumission de commandes à la file d'attente des commandes graphiques.

En particulier, avec Vulkan, elle permet de transmettre une liste d'objets sémaphores Vulkan que vkQueueSubmit() doit signaler et sur lesquels il doit attendre. params doit alors être un QRhiVulkanQueueSubmitParams. Cela devient essentiel dans certains cas d'utilisation avancés, comme lors de l'exécution d'appels Vulkan natifs qui impliquent d'attendre et de signaler des sémaphores VkSemaphores que le code de rendu ou de calcul Vulkan personnalisé de l'application gère. En outre, cette fonction permet également de spécifier des sémaphores supplémentaires sur lesquels attendre dans la prochaine vkQueuePresentKHR().

Avec de nombreux autres backends, l'implémentation de cette fonction n'est pas nécessaire.

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 site mipLevel donné, calculée sur la base de la taille du niveau 0 indiquée dans baseLevelSize.

QRhiStats QRhi::statistics() const

Rassemble et renvoie des statistiques sur les délais et les allocations des ressources graphiques.

Les données sur les allocations de mémoire ne sont disponibles qu'avec certains backends, où de telles opérations sont sous le contrôle de Qt. Avec les API graphiques où il n'y a pas de contrôle de niveau inférieur sur les allocations de mémoire des ressources, cela ne sera jamais pris en charge et tous les champs pertinents dans les résultats sont à 0.

Avec Vulkan en particulier, les valeurs sont toujours valides et sont demandées à la bibliothèque d'allocation de mémoire sous-jacente. Cela donne un aperçu des besoins en mémoire des tampons actifs et des textures.

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 comprend également un champ totalUsageBytes qui indique la taille totale, y compris les ressources supplémentaires qui ne sont pas sous le contrôle de la bibliothèque d'allocation de mémoire (tampons de la chaîne de swap, tas de descripteurs, etc.), comme indiqué par DXGI.

Les valeurs correspondent à tous les types de mémoire utilisés, combinés. (c'est-à-dire vidéo + système dans le cas d'un GPU discret).

Des données supplémentaires, telles que le temps total en millisecondes passé dans la création du pipeline graphique et de calcul (qui implique généralement la compilation des shaders ou la consultation du cache, et un traitement 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 backend, cette liste de valeurs supportées est fixée à l'avance, tandis qu'avec d'autres, les propriétés (physiques) du périphérique indiquent ce qui est supporté au moment de l'exécution.

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

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

Retourne la liste des taux d'ombrage variables pris en charge pour le site sampleCount spécifié.

1x1 est toujours pris en charge.

Cette fonction a été introduite dans Qt 6.9.

QThread *QRhi::thread() const

Renvoie le fil de discussion sur lequel QRhi a été initialized.

int QRhi::ubufAligned(int v) const

Renvoie la valeur (typiquement un offset) v alignée sur l'alignement uniforme du tampon donné par ubufAlignment().

int QRhi::ubufAlignment() const

Renvoie l'alignement minimum du tampon uniforme en octets. Cette valeur est généralement de 256.

Tenter de lier une région de tampon uniforme avec un décalage non aligné sur cette valeur conduira à des échecs en fonction du backend et de l'API graphique sous-jacente.

Voir aussi 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 est le QWindow ciblé par une chaîne d'échange.

La structure renvoyée peut être passée à QRhiSwapChain::setProxyData(). Cela a du sens dans les systèmes de rendu threadés : 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 et transmise à la chaîne d'échange. Cela permet d'effectuer des requêtes sur la plateforme native qui ne peuvent être appelées que sur le thread principal, par exemple pour interroger la CAMetalLayer à partir d'une NSView, puis de transmettre les données à QRhiSwapChain qui se trouve sur le thread de rendu. Avec l'exemple de Metal, l'accès à view.layer sur un thread de rendu dédié provoque un avertissement dans le Thread Checker de Xcode. Avec le mécanisme de proxy de données, ce problème est évité.

Lorsque les threads ne sont pas impliqués, la génération et la transmission de QRhiSwapChainProxyData ne sont pas nécessaires : les backends sont garantis d'être en mesure d'interroger tout ce qui est nécessaire par eux-mêmes, et si tout vit sur le thread principal (gui), cela devrait être suffisant.