QRhiTextureSubresourceUploadDescription Class
Beschreibt die Quelle für eine Mip-Stufe in einer Ebene bei einem Textur-Upload. Mehr...
| Header: | #include <rhi/qrhi.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake: | QT += gui-private |
| Seit: | Qt 6.6 |
Öffentliche Funktionen
| 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 |
Detaillierte Beschreibung
Der Quellinhalt wird entweder als „ QImage “ oder als „raw blob“ angegeben. Ersteres ist nur für unkomprimierte Texturen mit einem Format zulässig, das auf „ QImage “ abgebildet werden kann, während Letzteres für alle Formate unterstützt wird, einschließlich Gleitkomma- und komprimierter Formate.
destinationTopLeft() gibt die obere linke Ecke des Zielrechtecks an. Der Standardwert ist (0, 0).
Ein leeres ` sourceSize()` (Standard) bedeutet, dass die Größe als die Größe der Unterressource angenommen wird. Bei Uploads auf Basis von ` QImage` bedeutet dies, dass die Größe des Quell-` image()` mit der Unterressource übereinstimmen muss. Wenn stattdessen Rohdaten bereitgestellt werden, muss in ` data()` eine ausreichende Anzahl von Bytes angegeben werden.
sourceTopLeft() wird nur bei Uploads auf Basis von QImage unterstützt und gibt die obere linke Ecke des Quellrechtecks an.
Hinweis: Die Einstellung von ` sourceSize()` oder ` sourceTopLeft()` kann je nach Format und Backend intern eine Kopie von ` QImage ` auslösen.
Bei der Bereitstellung von Rohdaten, bei denen der Schritt nicht über ` setDataStride()` festgelegt wird, muss der Schritt (Zeilenabstand, Zeilenlänge in Byte) der bereitgestellten Daten gleich ` width * pixelSize ` sein, wobei ` pixelSize ` die Anzahl der für ein Pixel verwendeten Bytes ist, und es darf kein zusätzliches Auffüllung zwischen den Zeilen geben. Es gibt keine Anforderungen an die Ausrichtung des Zeilenanfangs.
Wenn am Ende jeder Zeile in den eingehenden Rohdaten ungenutzte Daten vorhanden sind, rufen Sie ` setDataStride()` mit der Gesamtanzahl der Bytes pro Zeile auf. Der Zeilenschritt muss stets ein Vielfaches der Byteanzahl für ein Pixel sein. Der Zeilenschritt gilt nur für Bilddaten von Texturen im unkomprimierten Format.
Hinweis: Das Format der Quelldaten muss mit dem Texturformat kompatibel sein. Bei vielen Grafik-APIs werden die Daten unverändert in einen Zwischenpuffer kopiert; eine Konvertierung in ein Zwischenformat durch ` QRhi` findet nicht statt. Dies gilt auch für Gleitkommaformate, wobei beispielsweise RGBA16F Half-Floats in den Quelldaten erfordert.
Hinweis: Die Festlegung des Strides über ` setDataStride()` funktioniert nur, wenn ` QRhi::ImageDataStride ` als ` supported` gemeldet wird. In der Praxis ist davon auszugehen, dass dies überall außer bei OpenGL ES 2.0 unterstützt wird.
Hinweis: Wenn ein ` QImage ` angegeben wird, wird der von ` QImage::bytesPerLine()` zurückgegebene Stride automatisch berücksichtigt.
Warnung: Wenn ein ` QImage ` angegeben wird und der ` QImage ` nicht Eigentümer der zugrunde liegenden Pixeldaten ist, muss der Aufrufer sicherstellen, dass die zugehörigen Daten bis zum Ende des Frames gültig bleiben. (Das bloße Übermitteln des Ressourcen-Update-Batches reicht nicht aus; die Daten müssen bis zum Aufruf von ` QRhi::endFrame()` gültig bleiben, um über alle Backends hinweg portierbar zu sein.) Kann dies nicht gewährleistet werden, wird dem Aufrufer dringend empfohlen, `QImage::detach()` für das Bild aufzurufen, bevor es an `uploadTexture()` übergeben wird.
Hinweis: Hierbei handelt es sich um eine RHI-API mit eingeschränkten Kompatibilitätsgarantien; weitere Informationen finden Sie unter QRhi.
Siehe auch QRhiTextureUploadDescription.
Dokumentation der Mitgliedsfunktionen
[noexcept default] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
Erstellt eine leere Subressourcenbeschreibung.
Hinweis: Eine leere „QRhiTextureSubresourceUploadDescription“ ist für sich genommen nutzlos und sollte nicht an einen „ QRhiTextureUploadEntry “ übermittelt werden. Es müssen mindestens zuerst ein Bild oder Daten festgelegt werden.
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)
Erstellt eine Mip-Level-Beschreibung anhand der Bilddaten, die unter data angegeben sind. Dies eignet sich auch für Gleitkomma- und komprimierte Formate.
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)
Erstellt eine Mip-Level-Beschreibung mit einem „ image “.
Die „ size “ von „ image “ muss mit der Größe der Mip-Stufe übereinstimmen. Für Stufe 0 ist dies die „ texture size “.
Die Bittiefe von ` image ` muss mit der von ` texture format` kompatibel sein.
Um einen teilweisen Upload zu beschreiben, rufen Sie anschließend setSourceSize(), setSourceTopLeft() oder setDestinationTopLeft() auf.
QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
Erstellt eine Mip-Level-Beschreibung mit den Bilddaten, die durch data und size angegeben sind. Dies eignet sich auch für Gleitkomma- und komprimierte Formate.
data kann nach der Rückgabe dieser Funktion bedenkenlos zerstört oder geändert werden.
QByteArray QRhiTextureSubresourceUploadDescription::data() const
Gibt die aktuell eingestellten Rohpixeldaten zurück.
Siehe auch „ setData()“.
quint32 QRhiTextureSubresourceUploadDescription::dataStride() const
Gibt den aktuell eingestellten Datenschritt zurück.
Siehe auch setDataStride().
QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const
Gibt die aktuell festgelegte Position des Ziels oben links zurück. Der Standardwert ist (0, 0).
Siehe auch „ setDestinationTopLeft()“.
QImage QRhiTextureSubresourceUploadDescription::image() const
Gibt die aktuell festgelegte „ QImage “ zurück.
Siehe auch setImage().
void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)
Setzt „ data “.
Siehe auch ` data()`.
void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)
Legt den Daten stride us in Byte fest. Standardmäßig ist dieser Wert 0 und nicht immer relevant. Wenn Roh data() bereitgestellt werden und der Schritt nicht über setDataStride() festgelegt wurde, muss der Schritt (Zeilenabstand, Zeilenlänge in Byte) der bereitgestellten Daten gleich width * pixelSize sein, wobei pixelSize die Anzahl der für ein Pixel verwendeten Byte ist und es keine zusätzliche Auffüllung zwischen den Zeilen geben darf. Andernfalls, wenn zusätzlicher Abstand zwischen den Zeilen vorhanden ist, setzen Sie „ stride “ auf einen Wert ungleich Null. All dies gilt nur, wenn Rohbilddaten bereitgestellt werden, und ist bei der Arbeit mit „ QImage “ nicht erforderlich, da dieses über einen eigenen Wert für „ stride “ verfügt.
Hinweis: Wenn ein von Null verschiedener Wert für ` stride ` festgelegt wird, stellen Sie sicher, dass die Daten auch die abschließende Auffüllung für die letzte Zeile enthalten, d. h. insgesamt mindestens ` stride * height ` Bytes. Zwar könnte die Bereitstellung der Daten ohne die Auffüllung der letzten Zeile (d. h. die Interpretation, dass der „stride“ für die letzte Zeile nicht gilt) sicher sein und ist dies bei Vulkan auch tatsächlich der Fall, OpenGL und D3D12 sicher ist, kann dies nicht für alle Backends garantiert werden; daher ist es am sichersten, dies zu vermeiden und die letzte Zeile wie alle anderen zu behandeln.
Hinweis: Die Festlegung des Strides über `setDataStride()` funktioniert nur, wenn ` QRhi::ImageDataStride ` als ` supported` gemeldet wird.
Hinweis: Wenn ein ` QImage ` angegeben wird, wird der von ` QImage::bytesPerLine()` zurückgegebene Schritt automatisch berücksichtigt, sodass es nicht erforderlich ist, den Datenschritt manuell festzulegen.
Siehe auch dataStride().
void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
Legt die Position der oberen linken Ecke des Ziels fest p.
Hinweis: Im häufigsten Fall, bei dem die Bilddaten aus einem ` QImage` bezogen werden, führt Qt eine Begrenzung ungültiger Textur-Upload-Größen durch, wenn die Zielposition plus die Quellgröße die Größe der Ziel-Textur-Subressource (d. h. die Größe auf der angegebenen Mip-Stufe) überschreitet. In diesem Fall wird außerdem die Meldung „ qWarning()“ in der Debug-Ausgabe ausgegeben. Dies geschieht, um Verwirrung zu vermeiden, wenn die zugrunde liegenden 3D-APIs abstürzen und zu einem späteren Zeitpunkt beim Übermitteln der Befehle zum Entfernen von GPU-Geräten führen. Unabhängig davon wird Entwicklern empfohlen, Anwendungen stets mit aktivierten Validierungs-/Debug-Ebenen für Vulkan, D3D12 oder Metal zu testen, da diese ein wesentlich breiteres Spektrum an Überprüfungen der API-Nutzung bieten.
Siehe auch destinationTopLeft().
void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)
Setzt „ image “. Beim Laden von Texturen werden die Bilddaten unverändert gelesen, ohne dass eine Formatkonvertierung erfolgt.
Siehe auch image().
void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)
Legt die Quell size en in Pixeln fest.
Hinweis: Das Festlegen von ` sourceSize()` oder ` sourceTopLeft()` kann je nach Format und Backend intern eine Kopie mit ` QImage ` auslösen.
Siehe auch ` sourceSize()`.
void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)
Legt die Position der Quelle oben links fest: p.
Hinweis: Die Einstellung von ` sourceSize()` oder ` sourceTopLeft()` kann je nach Format und Backend intern eine Kopie von ` QImage ` auslösen.
Siehe auch sourceTopLeft().
QSize QRhiTextureSubresourceUploadDescription::sourceSize() const
Gibt die Größe der Quelle in Pixeln zurück. Standardmäßig wird ein standardmäßig konstruiertes ` QSize` zurückgegeben, das die gesamte Subressource angibt.
Siehe auch ` setSourceSize()`.
QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const
Gibt die aktuell festgelegte Position der Quelle in der oberen linken Ecke zurück. Der Standardwert ist (0, 0).
Siehe auch „ 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.
