QRhiTextureSubresourceUploadDescription Class
テクスチャアップロード操作において、レイヤー内の1つのミップレベルのソースについて説明します。詳細...
| ヘッダー: | #include <rhi/qrhi.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake: | QT += gui-private |
| 以下のように: | Qt 6.6 |
パブリック関数
| 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 |
詳細な説明
ソースコンテンツは、QImage または生の blob のいずれかとして指定されます。前者は、QImage にマッピング可能な形式の非圧縮テクスチャでのみ使用できますが、後者は浮動小数点形式や圧縮形式を含むすべての形式でサポートされています。
destinationTopLeft() は、対象矩形の左上隅を指定します。デフォルトは (0, 0) です。
sourceSize() を空に設定すると(デフォルト)、サイズはサブリソースのサイズであるとみなされます。QImage ベースのアップロードの場合、これはソースのimage() のサイズがサブリソースと一致しなければならないことを意味します。代わりに生データを提供する場合は、data() に十分なバイト数を指定する必要があります。
sourceTopLeft() はQImage ベースのアップロードでのみサポートされており、ソース矩形の左上隅を指定します。
注: sourceSize() またはsourceTopLeft()を設定すると 、フォーマットやバックエンドによっては、内部でQImage によるコピーがトリガーされる場合があります。
生データを提供する場合で、setDataStride() を通じてストライドが指定されていないときは、提供されたデータのストライド(行ピッチ、バイト単位の行長)はwidth * pixelSize と等しくする必要があります。ここで、pixelSize は 1 ピクセルに使用されるバイト数であり、行間に追加のパディングがあってはなりません。行の開始位置の整列要件はありません。
入力生データの各行の末尾に未使用のデータがある場合は、行あたりの総バイト数を引数としてsetDataStride()を呼び出してください。ストライドは常に1ピクセルあたりのバイト数の倍数でなければなりません。行ストライドは、非圧縮形式のテクスチャの画像データにのみ適用されます。
注: ソースデータの形式は 、テクスチャ形式と互換性がある必要があります。多くのグラフィックスAPIでは、データはそのままステージングバッファにコピーされるため、QRhi によって中間形式への変換は行われません。これは浮動小数点形式にも適用され、例えばRGBA16Fの場合は、ソースデータにhalf floatが必須となります。
注: setDataStride() によるストライドの設定は 、QRhi::ImageDataStride がsupported と報告された場合にのみ機能します。実際には、OpenGL ES 2.0 を除き、どこでもサポートされていると予想されます。
注: QImage が指定された場合 、QImage::bytesPerLine()から返されるストライドは自動的に考慮されます。
警告: QImage が指定され、QImage が基になるピクセルデータを所有していない場合 、関連するデータがフレームの終了まで有効であり続けることを保証するのは呼び出し側の責任となります。 (リソース更新バッチを送信するだけでは不十分であり、すべてのバックエンドで移植性を確保するためには、QRhi::endFrame() が呼び出されるまでデータが有効なままである必要があります)これを保証できない場合、呼び出し元は、画像を uploadTexture() に渡す前に、その画像に対して QImage::detach() を呼び出すことを強く推奨します。
注:これは 互換性の保証が限定的な RHI API です。詳細については、QRhi を参照してください。
QRhiTextureUploadDescriptionも参照してください 。
メンバ関数のドキュメント
[noexcept default] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
空のサブリソース記述を作成します。
注: 空の QRhiTextureSubresourceUploadDescriptionは それ自体では役に立たず、QRhiTextureUploadEntry に送信すべきではありません。少なくとも、画像またはデータを最初に設定する必要があります。
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)
data で指定された画像データを用いて、ミップレベルの記述を生成します。これは、浮動小数点形式や圧縮形式にも適しています。
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)
image を使用して、ミップレベルの記述を生成します。
`image `の`size `は、ミップレベルのサイズと一致する必要があります。レベル0の場合、それは`texture size`です。
image のビット深度は、texture format と互換性がある必要があります。
部分的なアップロードを記述するには、setSourceSize()、setSourceTopLeft()、またはsetDestinationTopLeft() をその後呼び出してください。
QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
data およびsize で指定された画像データを用いて、ミップレベルの記述を生成します。これは、浮動小数点形式や圧縮形式にも適しています。
data この関数が返った後は、安全に破棄または変更することができます。
QByteArray QRhiTextureSubresourceUploadDescription::data() const
現在設定されている生のピクセルデータを返します。
setData()も参照してください 。
quint32 QRhiTextureSubresourceUploadDescription::dataStride() const
現在設定されているデータストライドを返します。
setDataStride()も参照してください 。
QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const
現在設定されている宛先の左上座標を返します。デフォルトは (0, 0) です。
setDestinationTopLeft()も参照してください 。
QImage QRhiTextureSubresourceUploadDescription::image() const
現在設定されているQImage を返します。
setImage()も参照してください 。
void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)
data を設定します。
data()も参照してください 。
void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)
データstride をバイト単位で設定します。デフォルトでは0であり、必ずしも関連するわけではありません。 生のdata() データを提供する場合、setDataStride() を通じてストライドが指定されていないときは、提供されるデータのストライド(行ピッチ、バイト単位の行長)は、width * pixelSize と等しくなければなりません。ここで、pixelSize は 1 ピクセルに使用されるバイト数であり、行間に余分なパディングがあってはなりません。 それ以外の場合、行間に余分なスペースがある場合は、stride に0以外の値を設定してください。これらはすべて、生の画像データが提供された場合にのみ適用され、QImage を使用する場合は、それ自体にstride 値があるため、必要ありません。
注: stride がゼロ以外で設定されている場合 、データには最後の行の末尾パディングも含まれていることを確認してください。つまり、合計で少なくともstride * height バイトである必要があります。 最後の行のパディングを省いてデータを提供すること(つまり、ストライドを最後の行には適用されないものと解釈すること)は安全である可能性があり、実際、Vulkanや OpenGL、および D3D12 では実際に安全ですが、すべてのバックエンドでこれが保証されるわけではないため、安全なアプローチとしてはこれを避け、最後の行も他の行と同様に扱うことです。
注: setDataStride() によるストライドの設定は 、QRhi::ImageDataStride がsupported として報告されている場合にのみ機能します。
注: QImage が指定された場合 、QImage::bytesPerLine()から返されるストライドが自動的に考慮されるため、データストライドを手動で設定する必要はありません。
dataStride()も参照してください 。
void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
p の左上隅の位置を指定します。
注: QImage から画像データを取得する最も一般的なケースでは 、宛先位置とソースサイズを合わせた値が、対象となるテクスチャ・サブリソースのサイズ(つまり、指定されたミップレベルでのサイズ)を超える場合、Qt は無効なテクスチャアップロードサイズのクリッピングを実行します。 この場合、デバッグ出力に `qWarning()` メッセージも表示されます。これは、基盤となる 3D API がクラッシュし、コマンドの送信後に GPU デバイスが削除されるような状況で、混乱を避けるために行われます。 いずれにせよ、Vulkan、D3D12、またはMetalの検証/デバッグレイヤーを有効にしてアプリケーションを実行し、常に検証を行うことを推奨します。これらのレイヤーは、APIの使用状況についてより広範囲にわたるチェックを提供するからです。
destinationTopLeft()も参照してください 。
void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)
image を設定します。テクスチャの読み込み時に、画像データはフォーマット変換を行わずにそのまま読み込まれます。
image()も参照してください 。
void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)
size をピクセル単位で設定します。
注: sourceSize() またはsourceTopLeft()を設定すると 、フォーマットやバックエンドによっては、内部でQImage のコピーが実行される場合があります。
sourceSize()も参照してください 。
void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)
ソースの左上位置をp に設定します。
注: sourceSize() またはsourceTopLeft()を設定すると 、フォーマットやバックエンドによっては、内部でQImage によるコピーが実行される場合があります。
sourceTopLeft()も参照してください 。
QSize QRhiTextureSubresourceUploadDescription::sourceSize() const
ソースのサイズをピクセル単位で返します。デフォルトでは、デフォルトコンストラクタで生成された `QSize` が返され、これはサブリソース全体を表します。
setSourceSize()も参照してください 。
QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const
現在設定されているソースの左上座標を返します。デフォルトは (0, 0) です。
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.