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

メンバ関数のドキュメント

int QRhiTexture::arrayRangeLength() const

setArrayRange() が呼び出された際に公開された配列範囲のサイズを返します。

setArrayRange()も参照してください 。

int QRhiTexture::arrayRangeStart() const

setArrayRange() が呼び出された際の最初の配列レイヤーを返します。

setArrayRange()も参照してください 。

int QRhiTexture::arraySize() const

テクスチャ配列のサイズを返します。

setArraySize()も参照してください 。

[pure virtual] bool QRhiTexture::create()

対応するネイティブグラフィックスリソースを作成します。以前にdestroy() を呼び出さずに create() が実行され、すでにリソースが存在する場合、まず暗黙的にdestroy() が呼び出されます。

成功した場合はtrue を返し、グラフィックス操作が失敗した場合はfalse を返します。戻り値にかかわらず、destroy()の呼び出しは常に安全です。

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

create() と似ていますが、新しいネイティブテクスチャが作成されない点が異なります。その代わりに、src で指定されたネイティブテクスチャリソースが使用されます。

これにより、外部のグラフィックスエンジンから既存のネイティブテクスチャオブジェクト（グラフィックスAPIに応じて、同じデバイスまたは共有コンテキストに属している必要がある）をインポートすることができます。

指定された既存のネイティブテクスチャオブジェクトが、非所有型のQRhiTexture として正常にラップされた場合、true を返します。

この操作の逆、つまり `QRhiTexture` で作成されたネイティブテクスチャオブジェクトを外部エンジンに公開することは、`nativeTexture()` によって可能です。

int QRhiTexture::depth() const

3Dテクスチャの深度を返します。

setDepth()も参照してください 。

QRhiTexture::Flags QRhiTexture::flags() const

テクスチャフラグを返します。

setFlags()も参照してください 。

QRhiTexture::Format QRhiTexture::format() const

テクスチャ形式を返します。

setFormat()も参照してください 。

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

このテクスチャの基盤となるネイティブリソースを返します。バックエンドが基盤となるネイティブリソースの公開をサポートしていない場合、戻り値は空になります。

createFrom()も参照してください 。

QSize QRhiTexture::pixelSize() const

サイズをピクセル単位で返します。

setPixelSize()も参照してください 。

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

テクスチャのサンプリングに使用されるビューフォーマットを返します。この関数が呼び出されない場合、ビューフォーマットはformat() と同じであるとみなされます。

この関数は Qt 6.8 で導入されました。

setReadViewFormat()も参照してください 。

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

QRhiResource::resourceType() const を再実装します。

リソースの型を返します。

int QRhiTexture::sampleCount() const

サンプル数を返します。1 は、マルチサンプルアンチエイリアシングが行われないことを意味します。

setSampleCount()も参照してください 。

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

通常、すべての配列レイヤーが公開されており、sampler2DArray をサンプリングする際、texture() GLSL関数に渡される3番目の座標を通じてレイヤーを選択するのはシェーダー側の責任となります。QRhi::TextureArrayRange がサポートされていると報告されている場合、create()またはcreateFrom()を呼び出す前にsetArrayRange()を呼び出すと、指定された範囲（startIndex から始まるcount 個の要素）のみが選択されます。シェーダーのロジックは、この点を考慮して記述することができます。

QRhi::TextureArrayRangeも参照してください 。

void QRhiTexture::setArraySize(int arraySize)

テクスチャ「arraySize 」を設定します。

arraySize()も参照してください 。

void QRhiTexture::setDepth(int depth)

3Dテクスチャのdepth を設定します。

depth()も参照してください 。

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

テクスチャフラグを「f 」に設定します。

flags()も参照してください 。

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

要求されたテクスチャ形式をfmt に設定します。

format()も参照してください 。

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

Vulkanなどの一部のグラフィックスAPIでは、そのAPIを直接使用するカスタムレンダリングコードを統合する際、画像のレイアウトに関して特別な配慮が必要です。この関数を使用すると、ネイティブのレンダリングコマンド実行後に、QRhiTexture が参照する画像がlayout のどの位置にあるかを指定することができます。

例えば、QRhiCommandBuffer::beginExternal() とQRhiCommandBuffer::endExternal() で囲まれたコードブロック内で、Vulkan を使用してQRhiTexture の VkImage に直接レンダリングし、その後、QRhi ベースのレンダリングパスでその画像をテクスチャサンプリングに利用する場合を考えてみましょう。画像レイアウトの遷移が不正確になる可能性を回避するために、この関数を使用して、前述のコードブロックに記録されたコマンドが完了した時点での画像レイアウトを指定することができます。

この関数の呼び出しは、QRhiCommandBuffer::endExternal() の実行後、かつ続くQRhiCommandBuffer::beginPass() の実行前に行われる場合にのみ意味を持ちます。

基盤となるグラフィックスAPIが画像レイアウトの概念を公開していないQRhi バックエンドでは、この関数は効果を持ちません。

void QRhiTexture::setPixelSize(const QSize &sz)

テクスチャサイズ（ピクセル単位）をsz に設定します。

pixelSize()も参照してください 。

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

シェーダーリソースのビュー形式（またはテクスチャのサンプリングに使用されるビューの形式）を「fmt 」に設定します。デフォルトでは、テクスチャ自体と同じ形式（およびsRGB設定）が使用されるため、ほとんどの場合、この関数を呼び出す必要はありません。

この設定は、QRhi::TextureViewFormat 機能がサポートされていると報告されている場合にのみ反映されます。

この関数は Qt 6.8 で導入されました。

readViewFormat()も参照してください 。

void QRhiTexture::setSampleCount(int s)

サンプル数を `s` に設定します。

sampleCount()も参照してください 。

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

レンダリングターゲットのビュー形式をfmt に設定します。デフォルトでは、テクスチャ自体と同じ形式（およびsRGB設定）が使用されるため、ほとんどの場合、この関数を呼び出す必要はありません。

書き込みビュー形式を指定する一般的なユースケースの一つとして、VulkanやDirect 3Dなどの3D APIでsRGB形式を使用している（我々の制御外の）外部から提供されたテクスチャを扱う場合が挙げられます。この場合、レンダリングエンジンは、シェーディングパイプラインの最終段階で線形化およびsRGBへの変換を処理する準備がすでに整っています。 この場合、そのようなテクスチャにレンダリングする際に求められるのは、同じフォーマット（ただしsRGBではない）を持つレンダリングターゲットビュー（例：VkImageView）です。 （例えば、OpenXR実装からVK_FORMAT_R8G8B8A8_SRGBテクスチャを取得した場合、 レンダリングエンジンのパイプラインがそれを必要とする場合、そのテクスチャへのレンダリングはVK_FORMAT_R8G8B8A8_UNORMビューを使用して行うべきである可能性が高い。この例では、フォーマットがQRhiTexture::RGBA8 で、srgb がfalse に設定されたViewFormat を引数として、この関数を呼び出すことになる）。

この設定は、QRhi::TextureViewFormat 機能がサポートされていると報告された場合にのみ考慮されます。

この関数は Qt 6.8 で導入されました。

writeViewFormat()も参照してください 。

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

テクスチャへの書き込み時、および画像の読み込み／保存時に使用されるビュー形式を返します。この関数が呼び出されない場合、ビュー形式はformat() と同じであるとみなされます。

この関数は Qt 6.8 で導入されました。

setWriteViewFormat()も参照してください 。