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

パブリックタイプ

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 に基づいています。これは、ユニフォームバッファ、ストレージバッファ、複合イメージサンプラ、ストレージイメージが共通のバインディングポイント空間を共有することを意味します。QShaderDescriptionQRhiShaderResourceBinding のバインディング番号は、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::Latest0現在の Qt バージョン
QShader::SerializedFormatVersion::Qt_6_51Qt 6.5
QShader::SerializedFormatVersion::Qt_6_42Qt 6.4

enum QShader::Source

エントリが含むシェーダーコードの種類を表します。

定数説明
QShader::SpirvShader0SPIR-V
QShader::GlslShader1GLSL
QShader::HlslShader2HLSL
QShader::DxbcShader3Direct3D バイトコード (fxc でコンパイルされた HLSL)
QShader::MslShader4メタルシェーディング言語
QShader::DxilShader5Direct3D バイトコード (dxc でコンパイルされた HLSL)
QShader::MetalLibShader6コンパイル済みメタル バイトコード
QShader::WgslShader7WGSL

enum QShader::Stage

シェーダが適しているグラフィックスパイプラインのステージを記述します。

定数説明
QShader::VertexStage0頂点シェーダ
QShader::TessellationControlStage1テッセレーション制御(ハル)シェーダ
QShader::TessellationEvaluationStage2テッセレーション評価(ドメイン)シェーダ
QShader::GeometryStage3ジオメトリ・シェーダ
QShader::FragmentStage4フラグメント(ピクセル)シェーダ
QShader::ComputeStage5計算シェーダ

enum QShader::Variant

エントリに含まれるシェーダコードの種類を表します。

定数説明
QShader::StandardShader0シェーダーコードの修正されていない通常バージョン。
QShader::BatchableVertexShader1Qt Quick シーングラフのバッチ処理に適したものに書き直された頂点シェーダ。
QShader::UInt16IndexedVertexAsComputeShader2テッセレーションと、uint16インデックスバッファからインデックスデータを取得するインデックスドローコールとの組み合わせで、Metalパイプラインで使用されることを意図した頂点シェーダです。Metalのテッセレーションパイプラインをサポートするために、頂点シェーダは、描画呼び出しにおけるインデックスバッファの使用に依存する可能性のある計算シェーダに変換されます(シェーダがgl_VertexIndexを使用している場合など)。
QShader::UInt32IndexedVertexAsComputeShader3頂点シェーダは、uint32インデックスバッファからインデックスデータを取得するインデックスドローコールと組み合わせて、テッセレーションとMetalパイプラインで使用されることを意図しています。Metalのテッセレーションパイプラインをサポートするために、頂点シェーダは、描画呼び出しにおけるインデックスバッファの使用に依存する可能性のある計算シェーダに変換されます(例えば、シェーダがgl_VertexIndexを使用している場合)。
QShader::NonIndexedVertexAsComputeShader4非インデックス描画呼び出しと組み合わせたテッセレーションを持つ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)

指定されたネイティブシェーダinfokey と関連付けて格納します。

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 オブジェクトlhsrhs の値が等しい場合はfalse を返し、そうでない場合はtrue を返します。

[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)

2 つのQShader オブジェクトlhsrhs が等しい場合、true を返します。これは、シェーダー ソースまたはバイナリ コードのセットが一致する同じステージのオブジェクトであることを意味します。

本書に含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。