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 Member-Funktionen

int QRhiTexture::arrayRangeLength() const

Gibt die Größe des freigegebenen Array-Bereichs zurück, als „ setArrayRange()“ aufgerufen wurde.

Siehe auch ` setArrayRange()`.

int QRhiTexture::arrayRangeStart() const

Gibt die erste Array-Ebene zurück, als „ 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()

Erstellt die entsprechenden nativen Grafikressourcen. Falls aufgrund eines früheren Aufrufs von `create()` bereits Ressourcen vorhanden sind, für die kein entsprechender Aufruf von ` destroy()` vorliegt, wird zunächst implizit ` destroy()` aufgerufen.

Gibt bei Erfolg ` true ` zurück, bei einem Fehler bei einer Grafikoperation ` 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 durch „ src “ angegebenen nativen Texturressourcen verwendet.

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

Gibt „true“ zurück, wenn das angegebene vorhandene native Texturobjekt erfolgreich als nicht-eigene „ QRhiTexture “ verpackt wurde.

Das Gegenteil dieses Vorgangs – nämlich die Bereitstellung eines von 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 Offenlegung der zugrunde liegenden nativen Ressourcen vom Backend nicht unterstützt wird.

Siehe auch ` createFrom()`.

QSize QRhiTexture::pixelSize() const

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

Siehe auch ` setPixelSize()`.

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

Gibt das beim Abtasten der Textur verwendete Ansichtsformat zurück. Wird diese Funktion nicht aufgerufen, wird davon ausgegangen, dass das Ansichtsformat mit dem von ` format()` übereinstimmt.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch ` setReadViewFormat()`.

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

Implementiert neu: ` QRhiResource::resourceType()` const.

Gibt den Ressourcentyp zurück.

int QRhiTexture::sampleCount() const

Gibt die Anzahl der Samples zurück. Der Wert 1 bedeutet, dass kein Multisample-Antialiasing verwendet wird.

Siehe auch setSampleCount().

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

Normalerweise sind alle Array-Ebenen sichtbar, und es obliegt dem Shader, die Ebene über die dritte Koordinate auszuwählen, die bei der Abtastung von ` sampler2DArray` an die GLSL-Funktion ` texture() ` übergeben wird. Wenn ` QRhi::TextureArrayRange ` als unterstützt gemeldet wird, bewirkt der Aufruf von `setArrayRange()` vor ` create()` oder ` createFrom()`, dass nur der angegebene Bereich ausgewählt wird: ` count ` Elemente, beginnend bei ` startIndex`. Die Shader-Logik kann dann unter Berücksichtigung dieser Tatsache 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 beispielsweise Vulkan, erfordert die Integration von benutzerdefiniertem Rendering-Code, der die Grafik-API direkt nutzt, besondere Sorgfalt hinsichtlich der Bildlayouts. Diese Funktion ermöglicht es, die erwartete „ layout “ zu übermitteln, in der sich das Bild befindet, das hinter dem „ QRhiTexture “ steht, nachdem die nativen Rendering-Befehle ausgeführt wurden.

Betrachten wir beispielsweise das direkte Rendern in ein VkImage eines „ QRhiTexture “ mit Vulkan in einem Codeblock, der von „ QRhiCommandBuffer::beginExternal()“ und „ QRhiCommandBuffer::endExternal()“ umschlossen ist, gefolgt von der Verwendung des Bildes für das Textur-Sampling in einem auf „ QRhi “ basierenden Render-Durchlauf. Um potenziell fehlerhafte Übergänge im Bildlayout zu vermeiden, kann diese Funktion verwendet werden, um anzugeben, wie das Bildlayout aussehen wird, sobald die in diesem 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 bei „ QRhi “-Backends, bei denen die zugrunde liegende Grafik-API kein Konzept von Bildlayouts bereitstellt.

void QRhiTexture::setPixelSize(const QSize &sz)

Legt die Texturgröße, angegeben in Pixeln, auf „ sz “ fest.

Siehe auch pixelSize().

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

Legt das Anzeigeformat der Shader-Ressource (bzw. das Format der Ansicht, die für die Texturabtastung verwendet wird) auf „ fmt “ fest. Standardmäßig wird dasselbe Format (und dieselbe sRGB-Einstellung) wie bei der Textur selbst verwendet, sodass diese Funktion in den meisten Fällen nicht aufgerufen werden muss.

Diese Einstellung wird nur berücksichtigt, wenn die Funktion „ QRhi::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 Samples auf „ s “.

Siehe auch sampleCount().

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

Legt das Darstellungsformat des Renderziels auf „ fmt “ fest. Standardmäßig wird dasselbe Format (und derselbe sRGB-Farbraum) wie bei der Textur selbst verwendet, sodass diese Funktion in den meisten Fällen nicht aufgerufen werden muss.

Ein häufiger Anwendungsfall für die Angabe eines Schreibansichtsformats ist die Arbeit mit extern bereitgestellten Texturen, die – außerhalb unserer Kontrolle – ein sRGB-Format mit 3D-APIs wie Vulkan oder Direct 3D verwenden, wobei die Rendering-Engine jedoch bereits darauf vorbereitet ist, die Linearisierung und Konvertierung in sRGB am Ende ihrer Shading-Pipeline durchzuführen. In diesem Fall ist beim Rendern in eine solche Textur eine Render-Target-Ansicht (z. B. VkImageView) erwünscht, die dasselbe, jedoch kein sRGB-Format aufweist. (Wenn man z. B. aus einer OpenXR-Implementierung eine Textur im Format VK_FORMAT_R8G8B8A8_SRGB erhält, ist es wahrscheinlich, dass das Rendern in diese Textur über eine VK_FORMAT_R8G8B8A8_UNORM-Ansicht erfolgen sollte, sofern dies von der Pipeline der Render-Engine gefordert wird; in diesem Beispiel würde man diese Funktion mit einem „ ViewFormat “ aufrufen, dessen Format „ QRhiTexture::RGBA8 “ lautet und bei dem „ srgb “ auf „ false “ gesetzt ist).

Diese Einstellung wird nur berücksichtigt, wenn die Funktion „ QRhi::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. Wird diese Funktion nicht aufgerufen, wird davon ausgegangen, dass das Ansichtsformat mit dem von ` format()` übereinstimmt.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch ` setWriteViewFormat()`.