QShader Class
複数のシェーディング言語に翻訳されたシェーダーの複数のバージョンを、リフレクションのメタデータとともに含んでいます。詳細...
Header: | #include <QShader> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
qmake: | QT += gui |
Since: | Qt 6.6 |
- 継承メンバを含む全メンバのリスト
- QShaderは、Rendering in 3D に含まれます。
パブリックタイプ
struct | NativeShaderInfo |
struct | SeparateToCombinedImageSamplerMapping |
NativeResourceBindingMap | |
SeparateToCombinedImageSamplerMappingList | |
enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader } |
パブリック関数
QShader() | |
QShader(const QShader &other) | |
(since 6.7) | QShader(QShader &&other) |
~QShader() | |
QList<QShaderKey> | availableShaders() const |
QShaderDescription | description() const |
bool | isValid() const |
QShader::NativeResourceBindingMap | nativeResourceBindingMap(const QShaderKey &key) const |
QShader::NativeShaderInfo | nativeShaderInfo(const QShaderKey &key) const |
void | removeNativeShaderInfo(const QShaderKey &key) |
void | removeResourceBindingMap(const QShaderKey &key) |
void | removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key) |
void | removeShader(const QShaderKey &key) |
QShader::SeparateToCombinedImageSamplerMappingList | separateToCombinedImageSamplerMappingList(const QShaderKey &key) const |
QByteArray | serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const |
void | setDescription(const QShaderDescription &desc) |
void | setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info) |
void | setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map) |
void | setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list) |
void | setShader(const QShaderKey &key, const QShaderCode &shader) |
void | setStage(QShader::Stage stage) |
QShaderCode | shader(const QShaderKey &key) const |
QShader::Stage | stage() const |
(since 6.7) void | swap(QShader &other) |
(since 6.7) QShader & | operator=(QShader &&other) |
QShader & | operator=(const QShader &other) |
静的パブリック・メンバー
QShader | fromSerialized(const QByteArray &data) |
関連する非メンバー
size_t | qHash(const QShader &s, size_t seed = 0) |
bool | operator!=(const QShader &lhs, const QShader &rhs) |
bool | operator==(const QShader &lhs, const QShader &rhs) |
詳細説明
QShader は、グラフィックス API に依存しない Qt の世界におけるシェーダコードのエントリポイントです。Qt 5.x での習慣のように GLSL シェーダソースを使用する代わりに、Vulkan、Metal、Direct3D、OpenGL などの複数のグラフィックス API のバックエンドを持つ新しいグラフィックスシステムは、シェーダを指定する必要があるときはいつでも QShader を入力として使用します。
警告 QShader とQShaderDescription を含む Qt Gui モジュールのQRhi クラスファミリーは、限定的な互換性保証を提供します。つまり、API はアプリケーションが開発された Qt のバージョンでのみ動作することが保証されています。ただし、ソース互換性のない変更は最小限に抑えることを目的としており、マイナーリリース(6.7、6.8 など)のみ行われます。アプリケーションでこれらのクラスを使用するには、Qt::GuiPrivate
(CMakeを使用している場合)にリンクし、rhi
のプレフィックスを持つヘッダをインクルードします(例:#include <rhi/qshader.h>
)。
QShader のインスタンスは空であり、デフォルトでは無効です。有用なインスタンスを取得するには、2つの典型的な方法があります:
- ビルド時またはそれ以前に、
qsb
コマンドラインツールを使用してオフラインでコンテンツを生成する。その結果、バイナリ・ファイルがアプリケーションに同梱され、QIODevice::readAll() で読み込まれ、fromSerialized() でデシリアライズされます。詳細については、QShaderBaker を参照のこと。 - QShaderBaker を使って実行時に生成する。これは高価な操作ですが、アプリケーションはユーザーが提供した、または動的に生成されたシェーダーソース文字列を使用することができます。
QRhiGraphicsPipeline のように Qt Rendering Hardware Interface とそのクラスと一緒に使用する場合、グラフィッ クスパイプラインの特定のステージでシェーダを指定する必要があるときはいつでも QShader を消費するようにこれらのクラスが準備されているため、アプリケーション側からのさらなるアクションは必要ありません。
あるいは、アプリケーションは
- QShaderに含まれるシェーディング言語バージョンのソースコードまたはバイトコード、
- シェーダーのエントリーポイントの名前、
- シェーダの入力、出力、およびユニフォームブロックのようなリソースの説明を含むリフレクションメタデータ。これは、アプリケーションやフレームワークが、頂点属性やシェーダが使用するユニフォームバッファのレイアウトに関する事前知識がないために、実行時にシェーダの入力を発見する必要がある場合に不可欠です。
QShader は、その中に含まれる様々なバージョンやバリアントを生成するためのソースとして使用されたシェーディング言語について、何の前提も置きません。
QShader は多くの Qt コア型と同様に暗黙の共有を使用するため、値で返したり渡したりすることができます。デタッチはセッターを呼び出すときに暗黙的に行われます。
参考までに、典型的な移植性の高いQRhi は、すべてのバックエンドに適した QShader が少なくとも以下を含むことを期待しています。(これはコアプロファイルOpenGLコンテキストのサポートを除きます。そのためにはGLSL 150以降を追加してください)
- Vulkan 1.0以降に適したSPIR-V 1.0バイトコード
- OpenGL ES 2.0以降に適したGLSL/ES 100ソースコード
- OpenGL 2.1以降に適したGLSL 120ソースコード
- Direct3D 11/12に適したHLSL Shader Model 5.0のソースコードまたは対応するDXBCバイトコード
- Metal Shading Language 1.2のソースコードまたはMetal 1.2以降に適した対応するバイトコード
QShaderBakerも参照してください 。
メンバ型ドキュメント
[alias]
QShader::NativeResourceBindingMap
QMap<int,QPair<int, int>> の同義語。
QRhi が想定しているリソースバインディングモデルは SPIR-V に基づいています。これは、ユニフォームバッファ、ストレージバッファ、複合イメージサンプラ、ストレージイメージが共通のバインディングポイント空間を共有することを意味します。QShaderDescription とQRhiShaderResourceBinding のバインディング番号は、Vulkan 互換 GLSL シェーダーのbinding
レイアウト修飾子と一致することが期待されます。
Vulkan以外のグラフィックスAPIは、これと完全には互換性のないリソースバインディングモデルを使用する可能性があります。SPIR-V から翻訳されたシェーダコードのジェネレータは、さまざまな理由で SPIR-V バインディング修飾子を考慮しないことを選択する可能性があります。例えば、SPIRV-Cross の Metal バックエンドがそうです。さらに、自動的かつ暗黙的な翻訳が可能な場合でも(例えば、SPIR-V バインディングポイントを HLSL リソースレジスタインデックスとして使用する)、SPIR-V バインディングポイントに制約されることなくリソースバインディングを割り当てることで、より良い結果が得られる可能性があります。
そのため、QShader は、指定された SPIR-V バインディングのネイティブ・バインディング・ポイントを記述する追加のマップを公開することができます。これが関連するQRhi バックエンドは、必要に応じて自動的にこのマップを使用することが期待される。シェーディング言語によっては、結合されたイメージサンプラーが2つのネイティブリソース(テクスチャーとサンプラー)にマッピングされることがあるため、値はペアになります。その場合、2番目の値はサンプラーを指します。
注意: シェーダ内にリソースに対するアクティブなバインディングがない場合、ネイティブバインディングは-1になる可能性があります。(例えば、ユニフォームブロックが宣言されているが、シェーダコードで使用されていない場合など) マップは常に完全であり、宣言されたユニフォームブロック、ストレージブロック、イメージオブジェクト、および複合サンプラのエントリがすべて存在しますが、シェーダ関数で実際に参照されていないものについては値が-1になります。
[alias]
QShader::SeparateToCombinedImageSamplerMappingList
QList<QShader::SeparateToCombinedImageSamplerMapping> の同義語。
enum class QShader::SerializedFormatVersion
QShader をシリアライズする際に希望する出力形式を記述します。
serialized() のversion
引数のデフォルト値はLatest
です。ほとんどの場合、これで十分です。別の値を指定する必要があるのは、以前の Qt バージョンでロードできるシリアライズされたデータを生成する場合だけです。例えば、qsb
ツールは、--qsbversion
コマンドライン引数が与えられたときに、これらの列挙値を使用します。
注意: 以前のバージョンをターゲットにすると、生成されたアセットで特定の機能が機能しなくなります。これは、指定された古い Qt バージョンでアセットを使用する場合は問題ありませんが、新しい Qt バージョンでは、QShader やシリアライズされたデータストリームで生成された追加データに依存する新しい機能がないため、生成されたアセットを新しい Qt バージョンで使用する場合に問題となる可能性があります。
定数 | 値 | 説明 |
---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | 現在の Qt バージョン |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
enum QShader::Source
エントリが含むシェーダーコードの種類を表します。
定数 | 値 | 説明 |
---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D バイトコード (fxc でコンパイルされた HLSL) |
QShader::MslShader | 4 | メタルシェーディング言語 |
QShader::DxilShader | 5 | Direct3D バイトコード (dxc でコンパイルされた HLSL) |
QShader::MetalLibShader | 6 | コンパイル済みメタル バイトコード |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
シェーダが適しているグラフィックスパイプラインのステージを記述します。
定数 | 値 | 説明 |
---|---|---|
QShader::VertexStage | 0 | 頂点シェーダ |
QShader::TessellationControlStage | 1 | テッセレーション制御(ハル)シェーダ |
QShader::TessellationEvaluationStage | 2 | テッセレーション評価(ドメイン)シェーダ |
QShader::GeometryStage | 3 | ジオメトリ・シェーダ |
QShader::FragmentStage | 4 | フラグメント(ピクセル)シェーダ |
QShader::ComputeStage | 5 | 計算シェーダ |
enum QShader::Variant
エントリに含まれるシェーダコードの種類を表します。
定数 | 値 | 説明 |
---|---|---|
QShader::StandardShader | 0 | シェーダーコードの修正されていない通常バージョン。 |
QShader::BatchableVertexShader | 1 | Qt Quick シーングラフのバッチ処理に適したものに書き直された頂点シェーダ。 |
QShader::UInt16IndexedVertexAsComputeShader | 2 | テッセレーションと、uint16インデックスバッファからインデックスデータを取得するインデックスドローコールとの組み合わせで、Metalパイプラインで使用されることを意図した頂点シェーダです。Metalのテッセレーションパイプラインをサポートするために、頂点シェーダは、描画呼び出しにおけるインデックスバッファの使用に依存する可能性のある計算シェーダに変換されます(シェーダがgl_VertexIndexを使用している場合など)。 |
QShader::UInt32IndexedVertexAsComputeShader | 3 | 頂点シェーダは、uint32インデックスバッファからインデックスデータを取得するインデックスドローコールと組み合わせて、テッセレーションとMetalパイプラインで使用されることを意図しています。Metalのテッセレーションパイプラインをサポートするために、頂点シェーダは、描画呼び出しにおけるインデックスバッファの使用に依存する可能性のある計算シェーダに変換されます(例えば、シェーダがgl_VertexIndexを使用している場合)。 |
QShader::NonIndexedVertexAsComputeShader | 4 | 非インデックス描画呼び出しと組み合わせたテッセレーションを持つMetalパイプラインで使用されることを意図した頂点シェーダ。Metalのテッセレーションパイプラインをサポートするために、頂点シェーダは、描画呼び出しにおけるインデックスバッファの使用に依存する可能性のある計算シェーダに変換されます(例えば、シェーダがgl_VertexIndexを使用している場合)。 |
メンバ関数ドキュメント
QShader::QShader()
新しい、空の(したがって無効な) QShader インスタンスを構築します。
QShader::QShader(const QShader &other)
other のコピーを構築します。
[noexcept, since 6.7]
QShader::QShader(QShader &&other)
other から新しい QShader を構築します。
注意: 移動元のオブジェクトother は部分的に形成された状態に置かれ、有効な操作は破壊と新しい値の割り当てのみです。
この関数は Qt 6.7 で導入されました。
[noexcept]
QShader::~QShader()
デストラクタ。
QList<QShaderKey> QShader::availableShaders() const
利用可能なシェーダーのバージョンのリストを返す
QShaderDescription QShader::description() const
シェーダーのリフレクションメタデータを返します。
setDescription()も参照してください 。
[static]
QShader QShader::fromSerialized(const QByteArray &data)
与えられたdata から新しいQShader インスタンスを作成します。
data が正常にデシリアライズできない場合、結果はデフォルトで構築されたQShader となり、isValid() はfalse
を返します。
serialized()も参照 。
bool QShader::isValid() const
QShader に少なくとも 1 つのシェーダー・バージョンが含まれている場合は true を返します。
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
key のネイティブ・バインディング・マップを返します。key で利用可能なマッピングがない場合、マップは空になります(たとえば、マップがkey で記述されている API とシェーディング言語に適用できないため)。
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
key のネイティブ・シェーダー情報構造体、またはkey で利用可能なデータがない場合は空のオブジェクトを返します。たとえば、そのようなマッピングはシェーディング言語またはシェーダー・ステージに適用できないためです。
setNativeShaderInfo()も参照 。
void QShader::removeNativeShaderInfo(const QShaderKey &key)
key のネイティブシェーダ情報を削除します。
void QShader::removeResourceBindingMap(const QShaderKey &key)
key のネイティブ リソース バインディング マップを削除します。
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
key の結合イメージ サンプラー マッピング リストを削除します。
void QShader::removeShader(const QShaderKey &key)
指定されたkey のソースまたはバイナリのシェーダーコードを削除します。見つからない場合は何もしません。
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
key の複合イメージサンプラー・マッピングリストを返すか、key のデータがない場合は空のリストを返します。たとえば、そのようなマッピングはシェーディング言語に適用できないためです。
setSeparateToCombinedImageSamplerMappingList()も参照 。
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
ファイルや他のI/Oデバイスへの書き込みに適した、QShader が保持するすべてのデータのシリアライズされたバイナリバージョンを返します。
デフォルトでは、最新のシリアライズ形式が使用されます。互換性のある Qt バージョンでシリアライズするには、version パラメータを使用します。生成されるデータストリームが、その Qt バージョン以降に導入された機能との互換性を失うことを犠牲にしてでも、古い Qt バージョンとの互換性を確保する必要があることがわかっている場合にのみ、別の値(たとえば、Qt 6.5 の場合はQt_6_5 )を使用する必要があります。
fromSerialized()も参照してください 。
void QShader::setDescription(const QShaderDescription &desc)
リフレクションメタデータをdesc に設定します。
description() も参照して ください。
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
指定されたネイティブシェーダinfo をkey と関連付けて格納します。
nativeShaderInfo()も参照して ください。
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
key に関連付けられた、指定されたネイティブ リソース バインディングmap を格納します。
nativeResourceBindingMap() も参照して ください。
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
key に関連付けられた、指定された複合イメージサンプラーマッピングlist を格納します。
separateToCombinedImageSamplerMappingList()も参照 。
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
key で指定されたシェーダーバージョンのソースまたはバイナリshader コードを格納します。
shader()も参照 。
void QShader::setStage(QShader::Stage stage)
パイプラインstage を設定します。
stage()も参照して ください。
QShaderCode QShader::shader(const QShaderKey &key) const
key で指定されたシェーダー・バージョンのソース・コードまたはバイナリ・コードを返します。
setShader() も参照して ください。
QShader::Stage QShader::stage() const
シェーダが対象とするパイプラインステージを返します。
setStage()も参照 。
[noexcept, since 6.7]
void QShader::swap(QShader &other)
このシェーダとother シェーダを交換します。この操作は非常に高速で、失敗することはありません。
この関数は Qt 6.7 で導入されました。
[noexcept, since 6.7]
QShader &QShader::operator=(QShader &&other)
Move-other をこのQShader インスタンスに割り当てます。
注意: 移動元のオブジェクトother は、部分的に形成された状態に置かれます。この状態で有効な操作は、破壊と新しい値の割り当てだけです。
この関数は Qt 6.7 で導入されました。
QShader &QShader::operator=(const QShader &other)
このオブジェクトにother を割り当てます。
関連する非メンバー
[noexcept]
size_t qHash(const QShader &s, size_t seed = 0)
seed を計算の種として使用して、s のハッシュ値を返します。
[noexcept]
bool operator!=(const QShader &lhs, const QShader &rhs)
2 つのQShader オブジェクトlhs とrhs の値が等しい場合はfalse
を返し、そうでない場合はtrue
を返します。
[noexcept]
bool operator==(const QShader &lhs, const QShader &rhs)
2 つのQShader オブジェクトlhs とrhs が等しい場合、true
を返します。これは、シェーダー ソースまたはバイナリ コードのセットが一致する同じステージのオブジェクトであることを意味します。
本書に含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。