QRhiTexture Class

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512));
if (!texture->create()) { error(); }
QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
QImage image(512, 512, QImage::Format_RGBA8888);
image.fill(Qt::green);
batch->uploadTexture(texture, image);
// ...
commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call

// determine newSize, e.g. based on the swapchain's output size or other factors
if (texture->pixelSize() != newSize) {
    texture->setPixelSize(newSize);
    if (!texture->create()) { error(); }
}
// continue using texture, fill it with new data

Dokumentation der Mitgliedsfunktionen

int QRhiTexture::arrayRangeLength() const

Gibt die exponierte Array-Bereichsgröße zurück, wenn setArrayRange() aufgerufen wurde.

Siehe auch setArrayRange().

int QRhiTexture::arrayRangeStart() const

Gibt die erste Array-Ebene zurück, wenn setArrayRange() aufgerufen wurde.

Siehe auch setArrayRange().

int QRhiTexture::arraySize() const

Gibt die Größe des Textur-Arrays zurück.

Siehe auch setArraySize().

[pure virtual] bool QRhiTexture::create()

Erzeugt die entsprechenden nativen Grafikressourcen. Wenn aufgrund eines früheren create() ohne entsprechende destroy() bereits Ressourcen vorhanden sind, wird destroy() implizit zuerst aufgerufen.

Gibt bei Erfolg true zurück, bei einem fehlgeschlagenen Grafikvorgang false. Unabhängig vom Rückgabewert ist der Aufruf von destroy() immer sicher.

[virtual] bool QRhiTexture::createFrom(QRhiTexture::NativeTexture src)

Ähnlich wie create(), mit dem Unterschied, dass keine neuen nativen Texturen erstellt werden. Stattdessen werden die von src angegebenen nativen Texturressourcen verwendet.

Dies ermöglicht den Import eines vorhandenen nativen Texturobjekts (das je nach Grafik-API zum selben Gerät oder Freigabekontext gehören muss) von einer externen Grafikmaschine.

Gibt true zurück, wenn das angegebene vorhandene native Texturobjekt erfolgreich als nicht-eigenes QRhiTexture gewrappt wurde.

Das Gegenteil dieses Vorgangs, die Freigabe eines QRhiTexture-erstellten nativen Texturobjekts für eine fremde Engine, ist über nativeTexture() möglich.

int QRhiTexture::depth() const

Gibt die Tiefe für 3D-Texturen zurück.

Siehe auch setDepth().

QRhiTexture::Flags QRhiTexture::flags() const

Gibt die Textur-Flags zurück.

Siehe auch setFlags().

QRhiTexture::Format QRhiTexture::format() const

Gibt das Texturformat zurück.

Siehe auch setFormat().

[virtual] QRhiTexture::NativeTexture QRhiTexture::nativeTexture()

Gibt die zugrunde liegenden nativen Ressourcen für diese Textur zurück. Der zurückgegebene Wert ist leer, wenn die zugrundeliegenden nativen Ressourcen vom Backend nicht unterstützt werden.

Siehe auch createFrom().

QSize QRhiTexture::pixelSize() const

Gibt die Größe in Pixel zurück.

Siehe auch setPixelSize().

[since 6.8] QRhiTexture::ViewFormat QRhiTexture::readViewFormat() const

Gibt das beim Sampling der Textur verwendete Ansichtsformat zurück. Wenn sie nicht aufgerufen wird, wird angenommen, dass das Ansichtsformat das gleiche ist wie format().

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch setReadViewFormat().

[override virtual] QRhiResource::Type QRhiTexture::resourceType() const

Reimplements: QRhiResource::resourceType() const.

Gibt den Ressourcentyp zurück.

int QRhiTexture::sampleCount() const

Gibt die Anzahl der Samples zurück. 1 bedeutet kein Multisample-Antialiasing.

Siehe auch setSampleCount().

void QRhiTexture::setArrayRange(int startIndex, int count)

Normalerweise sind alle Array-Ebenen offengelegt, und es obliegt dem Shader, die Ebene über die dritte Koordinate auszuwählen, die beim Abtasten der sampler2DArray an die GLSL-Funktion texture() übergeben wird. Wenn QRhi::TextureArrayRange als unterstützt gemeldet wird, fordert der Aufruf von setArrayRange() vor create() oder createFrom() dazu auf, nur den angegebenen Bereich auszuwählen, also count Elemente ab startIndex. Die Shader-Logik kann dann unter Berücksichtigung dieses Aspekts geschrieben werden.

Siehe auch QRhi::TextureArrayRange.

void QRhiTexture::setArraySize(int arraySize)

Legt die Textur arraySize fest.

Siehe auch arraySize().

void QRhiTexture::setDepth(int depth)

Legt die depth für eine 3D-Textur fest.

Siehe auch depth().

void QRhiTexture::setFlags(QRhiTexture::Flags f)

Setzt die Textur-Flags auf f.

Siehe auch flags().

void QRhiTexture::setFormat(QRhiTexture::Format fmt)

Setzt das angeforderte Texturformat auf fmt.

Siehe auch format().

[virtual] void QRhiTexture::setNativeLayout(int layout)

Bei einigen Grafik-APIs, wie z. B. Vulkan, ist bei der Integration von benutzerdefiniertem Rendering-Code, der die Grafik-API direkt verwendet, besondere Vorsicht geboten, wenn es um Bildlayouts geht. Diese Funktion ermöglicht es, das erwartete layout zu kommunizieren, in dem sich das Bild, das QRhiTexture unterstützt, nach den nativen Rendering-Befehlen befindet.

Denken Sie zum Beispiel an das Rendering in ein QRhiTexture's VkImage direkt mit Vulkan in einem Codeblock, der von QRhiCommandBuffer::beginExternal() und QRhiCommandBuffer::endExternal() eingeschlossen ist, gefolgt von der Verwendung des Bildes für Textur-Sampling in einem QRhi-basierten Rendering-Durchgang. Um potenziell falsche Bildlayout-Übergänge zu vermeiden, kann diese Funktion verwendet werden, um anzugeben, wie das Bildlayout aussehen wird, sobald die im besagten Codeblock aufgezeichneten Befehle abgeschlossen sind.

Der Aufruf dieser Funktion ist nur nach QRhiCommandBuffer::endExternal() und vor einem nachfolgenden QRhiCommandBuffer::beginPass() sinnvoll.

Diese Funktion hat keine Auswirkung auf QRhi Backends, bei denen die zugrundeliegende Grafik-API kein Konzept für Bildlayouts bereitstellt.

void QRhiTexture::setPixelSize(const QSize &sz)

Setzt die in Pixeln angegebene Texturgröße auf sz.

Siehe auch pixelSize().

[since 6.8] void QRhiTexture::setReadViewFormat(const QRhiTexture::ViewFormat &fmt)

Setzt das Format der Shader-Ressourcenansicht (oder das Format der Ansicht, die für das Sampling der Textur verwendet wird) auf fmt. Standardmäßig wird dasselbe Format (und dieselbe sRGB-Eigenschaft) wie für die Textur selbst verwendet, und in den meisten Fällen muss diese Funktion nicht aufgerufen werden.

Diese Einstellung wird nur berücksichtigt, wenn die Funktion TextureViewFormat als unterstützt gemeldet wird.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch readViewFormat().

void QRhiTexture::setSampleCount(int s)

Setzt die Anzahl der Proben auf s.

Siehe auch sampleCount().

[since 6.8] void QRhiTexture::setWriteViewFormat(const QRhiTexture::ViewFormat &fmt)

Setzt das Rendering-Ziel-Ansichtsformat auf fmt. Standardmäßig wird das gleiche Format (und die sRGB-Eigenschaft) wie die Textur selbst verwendet, und in den meisten Fällen muss diese Funktion nicht aufgerufen werden.

Ein häufiger Anwendungsfall für die Bereitstellung eines Schreib-Ansichtsformats ist die Arbeit mit extern bereitgestellten Texturen, die außerhalb unserer Kontrolle ein sRGB-Format mit 3D-APIs wie Vulkan oder Direct 3D verwenden, aber die Rendering-Engine ist bereits darauf vorbereitet, die Linearisierung und Konvertierung in sRGB am Ende ihrer Shading-Pipeline zu handhaben. In diesem Fall wird beim Rendern in eine solche Textur eine Rendering-Zielansicht (z. B. VkImageView) benötigt, die das gleiche, aber nicht das RGB-Format hat. (wenn man z.B. von einer OpenXR-Implementierung eine VK_FORMAT_R8G8B8A8_SRGB-Textur erhält, ist es wahrscheinlich, dass das Rendern in diese Textur mit einer VK_FORMAT_R8G8B8A8_UNORM-Ansicht erfolgen sollte, wenn die Pipeline der Rendering-Engine dies erfordert; in diesem Beispiel würde man diese Funktion mit einer ViewFormat aufrufen, die ein Format von QRhiTexture::RGBA8 hat und srgb auf false gesetzt ist).

Diese Einstellung wird nur berücksichtigt, wenn die Funktion TextureViewFormat als unterstützt gemeldet wird.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch writeViewFormat().

[since 6.8] QRhiTexture::ViewFormat QRhiTexture::writeViewFormat() const

Gibt das Ansichtsformat zurück, das beim Schreiben in die Textur und bei der Verwendung mit image load/store verwendet wird. Wenn sie nicht aufgerufen wird, wird angenommen, dass das Ansichtsformat dasselbe wie format() ist.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch setWriteViewFormat().