QRhiTextureSubresourceUploadDescription Class
Décrit la source d'un niveau de mip dans une couche lors d'une opération de téléchargement de texture. Plus d'informations...
| 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 de la source est spécifié sous la forme d'un QImage ou 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 sourceSize() vide (par défaut) indique que la taille est supposée être celle de la sous-ressource. Pour les téléchargements basés sur QImage, cela implique que la taille de la source image() doit correspondre à celle de la sous-ressource. Lorsque des données brutes sont fournies, 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 de la source.
Remarque : la définition de sourceSize() ou sourceTopLeft() peut déclencher une copie QImage en interne, en fonction du format et du backend.
Lorsque des données brutes sont fournies et que le stride n'est pas spécifié via setDataStride(), le stride (espacement des lignes, longueur des lignes en octets) des données fournies doit être égal à width * pixelSize, où pixelSize est le nombre d'octets utilisés pour un pixel, et il ne doit pas y avoir d'espacement supplémentaire entre les lignes. Il n'y a pas d'exigence d'alignement en début de ligne.
Lorsqu'il y a des données inutilisées à la fin de chaque ligne dans les données brutes d'entrée, appelez setDataStride() avec le nombre total d'octets par ligne. L'intervalle doit toujours être un multiple du nombre d'octets pour un pixel. La longueur 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 de mise à disposition, aucune conversion de format intermédiaire n'est fournie par QRhi. Cela s'applique également aux formats à virgule flottante, RGBA16F nécessitant par exemple des demi-flottants dans les données source.
Remarque : le réglage de la longueur d'onde via setDataStride() n'est fonctionnel que lorsque QRhi::ImageDataStride est déclaré comme supported. En pratique, on peut s'attendre à ce que cela soit supporté partout sauf pour OpenGL ES 2.0.
Note : Lorsqu'un QImage est donné, le stride renvoyé par QImage::bytesPerLine() est automatiquement pris en compte.
Attention : Lorsqu'un QImage est donné et que le QImage ne possède pas les données de pixels sous-jacentes, c'est à l'appelant de s'assurer que les données associées restent valides jusqu'à la fin de la trame. (Il ne suffit pas de soumettre le lot de mise à jour de la ressource, les données doivent rester valides jusqu'à ce que QRhi::endFrame() soit appelé afin d'être portable à travers tous les backends) Si cela ne peut pas être garanti, l'appelant est fortement encouragé à appeler QImage::detach() sur l'image avant de la passer à uploadTexture().
Note : Il s'agit d'une API RHI avec des garanties de compatibilité limitées, voir QRhi pour plus de détails.
Voir également QRhiTextureUploadDescription.
Documentation des fonctions membres
[noexcept] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
Construit une description de sous-ressource vide.
Remarque : une QRhiTextureSubresourceUploadDescription vide n'est pas utile en soi et ne doit pas être soumise à QRhiTextureUploadEntry. Au minimum, l'image ou les données doivent être définies au préalable.
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)
Construit une description de niveau mip avec les données d'image spécifiées par data. Cela convient aussi bien aux formats à virgule flottante qu'aux formats compressés.
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)
Construit une description de niveau mip avec un image.
Le size de image doit correspondre à la taille du niveau du mip. Pour le niveau 0, il s'agit de texture size.
La profondeur de bits de image doit être compatible avec celle de texture format.
Pour décrire un téléchargement partiel, appelez ensuite setSourceSize(), setSourceTopLeft() ou setDestinationTopLeft().
QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
Construit une description de niveau mip avec les données d'image spécifiées par data et size. Cela convient également aux formats à virgule flottante et aux formats compressés.
data La description de niveau mip peut être détruite ou modifiée en toute sécurité une fois que cette fonction est retournée.
QByteArray QRhiTextureSubresourceUploadDescription::data() const
Renvoie les données brutes des pixels actuellement définies.
Voir aussi setData().
quint32 QRhiTextureSubresourceUploadDescription::dataStride() const
Renvoie la ligne de données actuellement définie.
Voir aussi setDataStride().
QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const
Renvoie la position en haut à gauche de la destination actuellement définie. La valeur par défaut est (0, 0).
Voir également setDestinationTopLeft().
QImage QRhiTextureSubresourceUploadDescription::image() const
Renvoie l'adresse 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 les données stride en octets. Par défaut, cette valeur est 0 et n'est pas toujours pertinente. Lorsque vous fournissez des données brutes data(), et que le stride n'est pas spécifié via setDataStride(), le stride (hauteur de ligne, longueur de ligne en octets) des données fournies doit être égal à width * pixelSize où pixelSize est le nombre d'octets utilisés pour un pixel, et il ne doit pas y avoir d'espace supplémentaire entre les lignes. Dans le cas contraire, s'il y a de l'espace supplémentaire entre les lignes, définissez une valeur non nulle pour stride. Tout ceci n'est applicable que lorsque les données brutes de l'image sont fournies, et n'est pas nécessaire lorsque l'on travaille avec QImage, qui a sa propre valeur stride.
Remarque : la définition de l'espacement via setDataStride() ne fonctionne que lorsque QRhi::ImageDataStride est signalé comme supported.
Note : Lorsqu'un QImage est donné, la foulée renvoyée par QImage::bytesPerLine() est prise en compte automatiquement et il n'est donc pas nécessaire de définir la foulée des données manuellement.
Voir également dataStride().
void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
Définit la position de destination en haut à gauche p.
Note : Dans le cas le plus courant d'une source de données d'image à partir d'un QImage, Qt effectue un clampage des tailles de téléchargement de texture invalides lorsque la position de destination + la taille de la source dépasse la taille de la sous-ressource de texture ciblée (c.-à-d. la taille au niveau de mip donné). Il y a également un message qWarning() imprimé sur la sortie de débogage dans ce cas. Ceci afin d'éviter toute confusion lorsque les API 3D sous-jacentes tombent en panne et conduisent à des suppressions de périphériques GPU à un moment ultérieur lors de la soumission des commandes. Quoi qu'il en soit, les développeurs sont encouragés à toujours valider les applications en les exécutant avec les couches de validation/débogage Vulkan, D3D12 ou Metal activées, car elles offrent un éventail beaucoup plus large de contrôles sur l'utilisation de l'API.
Voir également destinationTopLeft().
void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)
Définit image. Lors du chargement des textures, les données de l'image seront lues telles quelles, sans conversion de format.
Voir aussi image().
void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)
Définit la source size en pixels.
Note : La définition de sourceSize() ou sourceTopLeft() peut déclencher une copie de QImage en interne, en fonction du format et du backend.
Voir aussi sourceSize().
void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)
Définit la position haut-gauche de la source p.
Remarque : le fait de définir sourceSize() ou sourceTopLeft() peut déclencher une copie QImage en interne, en fonction du format et du backend.
Voir aussi sourceTopLeft().
QSize QRhiTextureSubresourceUploadDescription::sourceSize() const
Renvoie la taille de la source en pixels. La valeur par défaut est QSize, qui indique la totalité de la sous-ressource.
Voir aussi setSourceSize().
QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const
Renvoie la position supérieure gauche de la source actuellement définie. 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.
