QShader Class
複数のシェーディング言語に翻訳されたシェーダーの複数のバージョンと、リフレクションメタデータが含まれています。詳細...
| ヘッダー: | #include <qshader.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| 以下のように: | Qt 6.6 |
- 継承されたメンバーを含むすべてのメンバーの一覧
- QShaderは、「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, HdrCapableFragmentShader } |
パブリック関数
| 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 &key, 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 を入力として受け取ります。
警告: Qt GUIモジュールにあるQRhi クラスファミリー （QShaderやQShaderDescription を含む）は 、互換性の保証が限定的です。これらのクラスについては、ソースやバイナリの互換性が保証されていません。つまり、APIが動作することが保証されるのは、アプリケーションの開発に使用されたQtのバージョンでのみです。 ただし、ソース互換性を損なう変更は最小限に抑えるよう努めており、マイナーリリース（6.7、6.8など）でのみ行われます。アプリケーションでこれらのクラスを使用するには、（CMakeを使用している場合は）Qt::GuiPrivate をリンクし、rhi というプレフィックスが付いたヘッダー（例：#include <rhi/qshader.h> ）をインクルードしてください。
QShaderのインスタンスはデフォルトでは空であり、したがって無効です。有用なインスタンスを取得するには、主に以下の2つの方法があります：
qsbコマンドラインツールを使用して、ビルド時またはそれ以前にオフラインで内容を生成します。その結果として生成されるバイナリファイルはアプリケーションに同梱され、QIODevice::readAll() によって読み込まれ、fromSerialized() によってデシリアライズされます。詳細については、QShaderBaker を参照してください。- QShaderBaker を使用して実行時に生成します。これは負荷の高い操作ですが、アプリケーションがユーザー提供の、または動的に生成されたシェーダーソース文字列を使用できるようになります。
Qt Rendering Hardware Interface およびQRhiGraphicsPipeline などのそのクラスと併用する場合、グラフィックスパイプラインの特定のステージでシェーダーを指定する必要があるときはいつでも、これらのクラスが QShader を受け入れる準備ができているため、アプリケーション側で追加の操作を行う必要はありません。
あるいは、アプリケーションは
- QShaderに含まれる任意のシェーディング言語バージョンのソースまたはバイトコード、
- シェーダのエントリポイント名、
- シェーダーの入力、出力、およびユニフォーム・ブロックなどのリソースに関する記述を含むリフレクション・メタデータ。これは、アプリケーションやフレームワークが、シェーダーが使用する頂点属性やユニフォーム・バッファのレイアウトを事前に把握していないために、実行時にシェーダーの入力を検出する必要がある場合に不可欠です。
QShaderは、そこに含まれるさまざまなバージョンやバリアントを生成するためのソースとして使用されたシェーディング言語について、いかなる仮定も行いません。
QShaderは、多くのQt Core型と同様に暗黙的な共有を使用しているため、値として返したり渡したりすることができます。セットタを呼び出すと、暗黙的にデタッチが行われます。
参考までに、典型的な移植性の高い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 1.2 以降に対応した Metal Shading Language 1.2 ソースコード、または対応するバイトコード
QShaderBakerも参照してください 。
メンバ型のドキュメント
[alias] QShader::NativeResourceBindingMap
QMap<int, std::pair<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 になることがあります。 （たとえば、uniformブロックが宣言されているものの、シェーダーコード内で使用されていない場合など）このマップは常に完全であり、宣言されたすべてのuniformブロック、ストレージブロック、画像オブジェクト、および複合サンプラーに対するエントリが存在しますが、シェーダー関数内で実際に参照されていないものについては、その値は-1となります。
[alias] QShader::SeparateToCombinedImageSamplerMappingList
QList<QShader::SeparateToCombinedImageSamplerMapping> の同義語。
enum class QShader::SerializedFormatVersion
QShader をシリアライズする際の、希望する出力形式を指定します。
serialized() のversion 引数のデフォルト値はLatest です。これは、ほとんどの場合で十分です。別の値を指定する必要があるのは、以前の Qt バージョンで読み込めるシリアライズデータを生成したい場合のみです。たとえば、qsb ツールでは、--qsbversion コマンドライン引数が指定された場合に、これらの列挙型値を使用します。
注： 以前のバージョンをターゲットにすると 、生成されたアセットにおいて特定の機能が動作しなくなる場合があります。 指定された古いQtバージョンでアセットを使用する場合、そのQtバージョンに、QShader やシリアライズされたデータストリームで生成される追加データに依存する新しいQtバージョンの新機能が含まれていない限り、これは問題にはなりません。しかし、生成されたアセットをその後、新しい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 | Metalシェーディング言語 |
QShader::DxilShader | 5 | Direct3D バイトコード（dxc によってコンパイルされた HLSL） |
QShader::MetalLibShader | 6 | プリコンパイル済みの Metal バイトコード |
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 を使用している場合など）に依存する可能性があるため、3 つの専用のバリアントが必要となります。 |
QShader::UInt32IndexedVertexAsComputeShader | 3 | uint32 インデックスバッファからインデックスデータを取得するインデックス付きドローコールと組み合わせて、テッセレーションを伴う Metal パイプラインで使用することを目的とした頂点シェーダー。 Metalのテッセレーションパイプラインをサポートするため、頂点シェーダーはコンピュートシェーダーに変換されます。このコンピュートシェーダーは、ドローコールにおけるインデックスバッファの使用状況（例えば、シェーダーがgl_VertexIndexを使用している場合など）に依存する可能性があるため、3つの専用のバリアントが必要となります。 |
QShader::NonIndexedVertexAsComputeShader | 4 | テッセレーションを伴う Metal パイプラインで、インデックスなしのドローコールと組み合わせて使用することを目的とした頂点シェーダー。 Metalのテッセレーションパイプラインをサポートするため、頂点シェーダーはコンピュートシェーダーに変換されますが、このコンピュートシェーダーは、ドローコールにおけるインデックスバッファの使用状況（例：シェーダーがgl_VertexIndexを使用している場合）に依存する可能性があるため、3つの専用バリアントが必要となります。 |
QShader::HdrCapableFragmentShader (since Qt 6.10) | 5 | Qt Quick のシーングラフにおけるハイダイナミックレンジ（HDR）レンダリングをサポートするために書き直されたフラグメントシェーダー。 |
メンバ関数のドキュメント
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 を返します。
警告： ファイルシステム上の.qsb ファイルを含むシェーダー パッケージは 、信頼できるコンテンツであるとみなされます。アプリケーション開発者は、アプリケーションの一部ではないユーザー提供のコンテンツの読み込みを許可する前に、潜在的な影響を慎重に検討することを推奨します。
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
QShader が保持するすべてのデータのシリアル化されたバイナリ形式を返します。これは、ファイルやその他のI/Oデバイスへの書き込みに適しています。
デフォルトでは、最新のシリアライズ形式が使用されます。互換性のある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)
key に関連付けられた、指定されたネイティブシェーダーinfo を保存します。
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)
other をこのQShader インスタンスに割り当てます。
注： 移動元のオブジェクト other は 、部分的に形成された状態になります。この状態では、有効な操作は破棄と新しい値への代入のみです。
この関数は Qt 6.7 で導入されました。
QShader &QShader::operator=(const QShader &other)
このオブジェクトにother を割り当てます。
関連する非メンバー
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
`key` のハッシュ値を、計算のシードとして `seed ` を使用して返します。
[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 を返します。
© 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.
