QRhiTextureSubresourceUploadDescription Class
Décrit la source d'un niveau de mip dans un calque lors d'une opération de chargement de texture. En savoir plus...
| En-tête : | #include <rhi/qrhi.h> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake : | QT += gui-private |
| Depuis : | Qt 6.6 |
Fonctions publiques
| QRhiTextureSubresourceUploadDescription() | |
| QRhiTextureSubresourceUploadDescription(const QByteArray &data) | |
| QRhiTextureSubresourceUploadDescription(const QImage &image) | |
| QRhiTextureSubresourceUploadDescription(const void *data, quint32 size) | |
| QByteArray | data() const |
| quint32 | dataStride() const |
| QPoint | destinationTopLeft() const |
| QImage | image() const |
| void | setData(const QByteArray &data) |
| void | setDataStride(quint32 stride) |
| void | setDestinationTopLeft(const QPoint &p) |
| void | setImage(const QImage &image) |
| void | setSourceSize(const QSize &size) |
| void | setSourceTopLeft(const QPoint &p) |
| QSize | sourceSize() const |
| QPoint | sourceTopLeft() const |
Description détaillée
Le contenu source est spécifié soit sous la forme d’un objet ` QImage `, soit sous la forme d’un blob brut. Le premier n’est autorisé que pour les textures non compressées dont le format peut être mappé à ` QImage`, tandis que le second est pris en charge pour tous les formats, y compris les formats à virgule flottante et compressés.
destinationTopLeft() spécifie le coin supérieur gauche du rectangle cible. La valeur par défaut est (0, 0).
Un paramètre sourceSize() vide (valeur par défaut) indique que la taille est supposée correspondre à celle de la sous-ressource. Avec les téléchargements basés sur QImage, cela implique que la taille de la source image() doit correspondre à celle de la sous-ressource. En cas de fourniture de données brutes, un nombre suffisant d’octets doit être indiqué dans data().
sourceTopLeft() n’est pris en charge que pour les téléchargements basés sur QImage et spécifie le coin supérieur gauche du rectangle source.
Remarque : la définition de sourceSize() ou de sourceTopLeft() peut déclencher une copie interne de QImage, selon le format et le backend.
Lorsque vous fournissez des données brutes et que le pas n’est pas spécifié via setDataStride(), le pas (espacement entre les lignes, longueur de ligne en octets) des données fournies doit être égal à width * pixelSize, où pixelSize correspond au nombre d’octets utilisés pour un pixel, et il ne doit y avoir aucun remplissage supplémentaire entre les lignes. Il n’y a aucune exigence d’alignement au début des lignes.
Lorsqu’il y a des données inutilisées à la fin de chaque ligne dans les données brutes d’entrée, appelez setDataStride() en indiquant le nombre total d’octets par ligne. Le pas doit toujours être un multiple du nombre d’octets par pixel. Le pas de ligne ne s’applique qu’aux données d’image pour les textures au format non compressé.
Remarque : le format des données source doit être compatible avec le format de la texture. Avec de nombreuses API graphiques, les données sont copiées telles quelles dans un tampon intermédiaire ; aucune conversion de format intermédiaire n’est fournie par la fonction QRhi. Cela s’applique également aux formats à virgule flottante ; par exemple, le format RGBA16F nécessite des nombres à virgule flottante de type « half-float » dans les données source.
Remarque : la définition du pas via ` setDataStride()` ne fonctionne que lorsque ` QRhi::ImageDataStride ` est défini sur ` supported`. En pratique, cette fonctionnalité devrait être prise en charge partout, sauf dans OpenGL ES 2.0.
Remarque : lorsqu’un QImage est fourni, le pas renvoyé par QImage::bytesPerLine() est automatiquement pris en compte.
Avertissement : lorsqu’un QImage est fourni et que l’ QImage ne détient pas les données de pixels sous-jacentes, il incombe à l’appelant de s’assurer que les données associées restent valides jusqu’à la fin de l’image. (le simple fait de soumettre le lot de mise à jour des ressources n’est pas suffisant ; les données doivent rester valides jusqu’à l’appel de ` QRhi::endFrame()` afin d’assurer la portabilité sur tous les backends) Si cela ne peut être garanti, l’appelant est vivement encouragé à appeler `QImage::detach()` sur l’image avant de la transmettre à `uploadTexture()`.
Remarque : il s’agit d’une API RHI dont la compatibilité n’est pas entièrement garantie ; voir QRhi pour plus de détails.
Voir également QRhiTextureUploadDescription.
Documentation des fonctions membres
[noexcept default] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
Crée une description de sous-ressource vide.
Remarque : une description QRhiTextureSubresourceUploadDescription vide n'est pas utile en soi et ne doit pas être soumise à une requête QRhiTextureUploadEntry. Il faut au minimum définir au préalable une image ou des données.
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)
Crée une description de niveau MIP à partir des données d'image spécifiées par data. Cette méthode convient également aux formats en virgule flottante et compressés.
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)
Crée une description de niveau MIP avec un ` image`.
L'size de image doit correspondre à la taille du niveau de mip. Pour le niveau 0, il s'agit de texture size.
La profondeur de bits de ` image ` doit être compatible avec ` texture format`.
Pour décrire un téléchargement partiel, appelez ensuite setSourceSize(), setSourceTopLeft() ou setDestinationTopLeft().
QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
Crée une description de niveau MIP à partir des données d'image spécifiées par data et size. Cette fonction est également adaptée aux formats en virgule flottante et compressés.
data peut être détruit ou modifié en toute sécurité une fois que cette fonction a renvoyé une valeur.
QByteArray QRhiTextureSubresourceUploadDescription::data() const
Renvoie les données brutes de pixels actuellement définies.
Voir également setData().
quint32 QRhiTextureSubresourceUploadDescription::dataStride() const
Renvoie la longueur de pas actuellement définie.
Voir aussi setDataStride().
QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const
Renvoie la position actuelle de la destination en coin supérieur gauche. La valeur par défaut est (0, 0).
Voir également setDestinationTopLeft().
QImage QRhiTextureSubresourceUploadDescription::image() const
Renvoie l'QImage, actuellement définie.
Voir aussi setImage().
void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)
Définit data.
Voir également data().
void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)
Définit l'stride des données en octets. Par défaut, cette valeur est égale à 0 et n'est pas toujours pertinente. Lorsque vous fournissez des données brutes via ` data()` et que le pas n’est pas spécifié via `setDataStride()`, le pas (espacement entre les lignes, longueur de ligne en octets) des données fournies doit être égal à ` width * pixelSize `, où ` pixelSize ` correspond au nombre d’octets utilisés pour un pixel, et il ne doit y avoir aucun remplissage supplémentaire entre les lignes. Dans le cas contraire, s’il existe un espace supplémentaire entre les lignes, définissez une valeur non nulle pour ` stride`. Tout cela ne s’applique que lorsque des données d’image brutes sont fournies, et n’est pas nécessaire lorsque l’on travaille avec ` QImage `, car celui-ci possède sa propre valeur ` stride `.
Remarque : lorsqu’un stride non nul est défini, assurez-vous que les données contiennent également le remplissage de fin pour la dernière ligne, c’est-à-dire au moins stride * height octets au total. Bien que fournir les données sans le remplissage de la dernière ligne (c’est-à-dire en considérant que la valeur stride ne s’applique pas à la dernière ligne) puisse sembler sans risque, et soit en effet sans risque avec Vulkan, OpenGL et D3D12, cela ne peut être garanti pour tous les backends ; l’approche la plus sûre consiste donc à éviter cette pratique et à traiter la dernière ligne comme toutes les autres.
Remarque : la configuration du stride via `setDataStride()` ne fonctionne que lorsque ` QRhi::ImageDataStride ` est signalé comme ` supported`.
Remarque : lorsqu’un ` QImage ` est fourni, le pas renvoyé par ` QImage::bytesPerLine()` est automatiquement pris en compte ; il n’est donc pas nécessaire de définir manuellement le pas des données.
Voir également dataStride().
void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
Définit la position de destination en haut à gauche p.
Remarque : dans le cas le plus courant où les données d’image proviennent d’un QImage, Qt limite les tailles de chargement de texture non valides lorsque la position de destination + la taille de la source dépasse la taille de la sous-ressource de texture ciblée (c’est-à-dire la taille au niveau de mip donné). Dans ce cas, un message « qWarning() » s’affiche également dans la sortie de débogage. Cette mesure vise à éviter toute confusion lorsque les API 3D sous-jacentes plantent et entraînent la suppression du périphérique GPU à un stade ultérieur lors de l’envoi des commandes. Quoi qu’il en soit, les développeurs sont encouragés à toujours valider leurs applications en les exécutant avec les couches de validation/débogage Vulkan, D3D12 ou Metal activées, car celles-ci offrent un éventail beaucoup plus large de vérifications sur l’utilisation des API.
Voir également destinationTopLeft().
void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)
Définit la valeur « image ». Lors du chargement des textures, les données d'image seront lues telles quelles, sans conversion de format.
Voir également image().
void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)
Définit l'size de la source en pixels.
Remarque : l'appel de la fonction sourceSize() ou sourceTopLeft() peut déclencher en interne une copie de type « QImage », selon le format et le backend.
Voir également sourceSize().
void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)
Définit la position de la source en haut à gauche : p.
Remarque : la définition de ` sourceSize()` ou ` sourceTopLeft()` peut déclencher en interne une copie de type « QImage », selon le format et le backend.
Voir également sourceTopLeft().
QSize QRhiTextureSubresourceUploadDescription::sourceSize() const
Renvoie la taille de la source en pixels. La valeur par défaut est un objet ` QSize` construit par défaut, qui désigne l'intégralité de la sous-ressource.
Voir également setSourceSize().
QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const
Renvoie la position actuelle du coin supérieur gauche de la source. La valeur par défaut est (0, 0).
Voir également setSourceTopLeft().
© 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.
