QSGMaterialShader Class

QSGMaterialShaderクラスは、グラフィックスAPIに依存しないシェーダープログラムを表します。詳細...

ヘッダー	`#include <QSGMaterialShader>`
CMake：	`find_package(Qt6 REQUIRED COMPONENTS Quick)` `target_link_libraries(mytarget PRIVATE Qt6::Quick)`
qmake：	`QT += quick`

継承メンバを含む全メンバ一覧
QSGMaterialShader はQt Quick Scene Graph Material Classes の一部です。

パブリックタイプ

struct	GraphicsPipelineState
class	RenderState
enum	Flag { UpdatesGraphicsPipelineState }
flags	Flags

パブリック関数

	QSGMaterialShader()
`(since 6.4)` int	combinedImageSamplerCount(int binding) const
QSGMaterialShader::Flags	flags() const
void	setFlag(QSGMaterialShader::Flags flags, bool on = true)
void	setFlags(QSGMaterialShader::Flags flags)
virtual bool	updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState ps, QSGMaterial newMaterial, QSGMaterial *oldMaterial)
virtual void	updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual bool	updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

保護された関数

void	setShader(QSGMaterialShader::Stage stage, const QShader &shader)
void	setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)
`(since 6.8)` void	setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

詳細説明

QSGMaterialShader は、頂点シェーダとフラグメントシェーダ、グラフィックスパイプラインの状態変化を定義するデータ、およびユニフォームバッファやテクスチャなどのグラフィックスリソースを更新するロジックの組み合わせを表します。

注意: QSG 接頭辞を持つすべてのクラスは、シーングラフのレンダリングスレッドでのみ使用する必要があります。詳しくはシーングラフとレンダリングを参照してください。

QSGMaterial と QSGMaterialShader は、緊密な関係を形成しています。1つのシーングラフ（ネストされたグラフを含む）に対して、シーングラフがそのマテリアルでオブジェクトをレンダリングするために使用するシェーダと他のデータをカプセル化する、1つのユニークなQSGMaterialShaderインスタンスがあります。各QSGGeometryNode は、ノードの描画中にグラフィックパイプラインがどのように設定されなければならないかを定義する一意のQSGMaterial を持つことができます。QSGMaterialShaderのインスタンスは、ユーザーによって明示的に作成されることはなく、QSGMaterial::createShader （）を通してシーングラフによってオンデマンドで作成されます。シーングラフは、QSGMaterial::createShader （）メソッドを呼び出すことによってQSGMaterialShaderのインスタンスを作成し、各シェーダー実装のインスタンスが1つだけ存在することを保証します。

Qt 5 では、QSGMaterialShader は OpenGL と結びついていました。Qt 5では、QSGMaterialShaderはOpenGLと連携しており、QOpenGLShaderProgram で直接ビルドされ、updateState() のように任意のOpenGLコマンドを発行できる関数を持っていました。Qt 6 ではこのようなことはなくなりました。QSGMaterialShaderは厳密にはデータ指向ではありません。つまり、データ（シェーダーと希望するパイプライン状態の変更）を、統一されたバッファ内のデータを更新するロジックとともに提供します。グラフィックスAPIへのアクセスは提供されません。これは、QSGMaterialShaderがそれ自身でOpenGL、Vulkan、Metal、またはDirect 3Dの呼び出しを行えないことを意味します。統一されたシェーダー管理と合わせて、これによってQSGMaterialShaderを一度書くだけで、サポートされているグラフィックスAPIのどれでも実行時に機能させることができます。

保護されたsetShaderFileName() 関数を呼び出すことによって設定されたシェーダは、ジオメトリからの頂点データでマテリアルが何を行うか、そしてフラグメントがどのようにシェーディングされるかを制御します。QSGMaterialShader は通常、構築時に頂点シェーダとフラグメントシェーダを設定します。後からシェーダを変更すると、期待した効果が得られないことがあるので、避ける必要があります。

Qt 6 では、デフォルトのアプローチとして、.qsb ファイルをアプリケーションと一緒に出荷します。通常はリソースシステム経由で埋め込まれ、setShaderFileName() を呼び出すときに参照されます。.qsb ファイルは、QtShader Tools モジュールのqsb ツールを使用して、Vulkan スタイルの GLSL ソースコードからオフラインで、または遅くともアプリケーションのビルド時に生成されます。

オーバーライドできるバーチャルは3つあります。これらは、均一なバッファ、テクスチャ、パイプラインの状態変更のためのデータ、またはデータを生成するロジックを提供します。

updateUniformData() は、サブクラスで最もよく再実装される関数です。この関数は、QByteArray の内容を更新し、ユニフォームバッファとしてシェーダに公開します。頂点シェーダまたはフラグメントシェーダにユニフォームブロックを持つ QSGMaterialShader は、updateUniformData() を再実装する必要があります。

updateSampledImage() は、シェーダコードがテクスチャをサンプリングするときに関連します。この関数は、各サンプラー（または関連する API では、組み合わせたイメージサンプラー）に対して呼び出され、どのQSGTexture をシェーダに公開するかを指定するオプションを与えます。

シェーダパイプラインの状態変更は、あまり使用されません。使用例としては、特定のブレンドモードを使用したいマテリアルがあります。関連する関数はupdateGraphicsPipelineState() です。この関数は、QSGMaterialShader がフラグUpdatesGraphicsPipelineState を設定してオプトインしていない限り呼び出されません。この関数のタスクは、渡されたGraphicsPipelineState 構造体インスタンスを希望する変更で更新することです。現在のところ、ブレンディングとカリング関連の機能のみが利用可能で、その他の状態はマテリアルによって制御できません。

テクスチャのサポートも含む最小限の例としては、次のようなものがあります。ここでは、Material がcreateShader() で Shader のインスタンスを作成するQSGMaterial であり、フラグメントシェーダでサンプリングしたいQSGTexture を保持していると仮定します。頂点シェーダはモデルビュー投影行列にのみ依存します。

class Shader : public QSGMaterialShader
{
public:
    Shader()
    {
        setShaderFileName(VertexStage, QLatin1String(":/materialshader.vert.qsb"));
        setShaderFileName(FragmentStage, QLatin1String(":/materialshader.frag.qsb"));
    }

    bool updateUniformData(RenderState &state, QSGMaterial *, QSGMaterial *)
    {
        bool changed = false;
        QByteArray *buf = state.uniformData();
        if (state.isMatrixDirty()) {
            const QMatrix4x4 m = state.combinedMatrix();
            memcpy(buf->data(), m.constData(), 64);
            changed = true;
        }
        return changed;
    }

    void updateSampledImage(RenderState &, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *)
    {
        Material *mat = static_cast<Material *>(newMaterial);
        if (binding == 1)
            *texture = mat->texture();
    }
};

シェーダ用の Vulkan スタイルの GLSL ソースコードは以下のようになります。これらは、Shader() コンストラクタで参照される.qsb ファイルを生成するqsb ツールを使用してオフラインで前処理されることが期待されます。

#version 440
layout(location = 0) in vec4 aVertex;
layout(location = 1) in vec2 aTexCoord;
layout(location = 0) out vec2 vTexCoord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
} ubuf;
out gl_PerVertex { vec4 gl_Position; };
void main() {
    gl_Position = ubuf.qt_Matrix * aVertex;
    vTexCoord = aTexCoord;
}

#version 440
layout(location = 0) in vec2 vTexCoord;
layout(location = 0) out vec4 fragColor;
layout(binding = 1) uniform sampler2D srcTex;
void main() {
    vec4 c = texture(srcTex, vTexCoord);
    fragColor = vec4(c.rgb * 0.5, 1.0);
}

注意： QSG接頭辞を持つすべてのクラスは、シーングラフのレンダリングスレッドでのみ使用する必要があります。詳しくはScene Graph and Renderingを参照してください。

QSGMaterial 、Scene Graph - Custom Material、Scene Graph - Two Texture Providers、Scene Graph - Graphも参照してください。

メンバータイプドキュメント

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

特別なマテリアルプロパティを示すフラグ値。

定数	値	説明
`QSGMaterialShader::UpdatesGraphicsPipelineState`	`0x0001`	このフラグを設定すると、updateGraphicsPipelineState() を呼び出すことができます。

Flags 型はQFlags<Flag> の typedef です。Flag値のORの組み合わせを格納する。

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

QSGMaterialShader::QSGMaterialShader()

新しい QSGMaterialShader を構築します。

`[since 6.4]` int QSGMaterialShader::combinedImageSamplerCount(int binding) const

binding における結合イメージサンプラー変数の要素数を返します。この値はシェーダーコードからイントロスペクトされます。変数は配列で、複数の次元を持つことができます。

カウントは、変数内の結合イメージサンプラー項目の総数を反映します。次の例では、srcA のカウントは 1、srcB のカウントは 4、srcC のカウントは 6 です。

layout (binding = 0) uniform sampler2D srcA;
layout (binding = 1) uniform sampler2D srcB[4];
layout (binding = 2) uniform sampler2D srcC[2][3];

このカウントは、QSGMaterialShader::updateSampledImage の texture パラメータ内のQSGTexture ポインタの数です。

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

QSGMaterialShader::updateSampledImageも参照してください。

QSGMaterialShader::Flags QSGMaterialShader::flags() const

このマテリアルシェーダに現在設定されているフラグを返します。

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

void QSGMaterialShader::setFlag(QSGMaterialShader::Flags flags, bool on = true)

on が真の場合、このマテリアルシェーダにflags を設定します。そうでない場合、指定されたフラグをクリアします。

void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)

このマテリアルシェーダのflags を設定します。

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

`[protected]` void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)

指定されたstage のshader を設定する。

`[protected]` void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)

指定されたstage のシェーダーのfilename を設定します。

ファイルには、シリアライズされたQShader が含まれることが期待されます。

`[protected, since 6.8]` void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

指定されたstage のシェーダーのfilename を設定します。

ファイルには、シリアライズされたQShader が含まれることが期待されます。

このオーバーロードは、multiview レンダリングを有効にするとき、特にビルドシステムの MULTIVIEW 便利オプションが使用されるときに使用されます。

viewCount は2、3、または4でなければならない。はこれに基づいて自動的に調整されます。filename

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

`[virtual]` bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial **newMaterial*, QSGMaterial **oldMaterial*)

この関数はシーングラフによって呼び出され、マテリアルがグラフィック状態のカスタムセットを提供できるようにします。マテリアルによってカスタマイズ可能なステートのセットは、ブレンドと関連する設定に限定されます。

注意： この関数は、setFlags （）を介してUpdatesGraphicsPipelineState フラグが有効になっている場合にのみ呼び出されます。デフォルトでは設定されていないため、この関数が呼び出されることはありません。

ps のメンバのいずれかに変更が加えられるたびに、戻り値はtrue でなければならない。

注意: ps の内容は、この関数の呼び出し間で永続化されません。

現在のレンダリングstate はシーングラフから渡される。

サブクラス固有の状態は、newMaterial から抽出できます。oldMaterial が NULL の場合、このシェーダはちょうどアクティブになったところです。

`[virtual]` void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture ***texture*, QSGMaterial **newMaterial*, QSGMaterial **oldMaterial*)

この関数はシーングラフによって呼び出され、シェーダでサンプリング画像を使用する準備をします。

binding はサンプラーのバインディング番号です。この関数は、に関連するシェーダーコードの各複合イメージサンプラー変数に対して呼び出されます。QSGMaterialShader

texture はポインタの配列です。配列の要素数は、シェーダーコードで指定されたイメージサンプラー変数の要素数と一致します。この変数は配列であってもよく、複数の次元を有してもよい。配列の要素数は、次の方法で求めることができます。QSGTexture QSGMaterialShader::combinedImageSamplerCount

texture の要素が NULL の場合、リターンする前に有効なQSGTexture ポインタに設定する必要があります。nullでない場合、新しいQSGTexture * を格納するか、すでに知られているQSGTexture のパラメータを更新するかは、素材次第である。QSGTexture の所有権は移譲されない。

現在のレンダリングstate はシーングラフから渡される。関連性がある場合、QSGTexture::commitTextureOperations （）を介してテクスチャデータのアップロードをエンキューするトリガーはマテリアル次第です。

サブクラス固有の状態は、newMaterial から抽出できます。

oldMaterial を使用すると、変更を最小限に抑えることができます。が NULL の場合、このシェーダはアクティベートされただけです。oldMaterial

QSGMaterialShader::combinedImageSamplerCountも参照してください。

`[virtual]` bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial **newMaterial*, QSGMaterial **oldMaterial*)

この関数は、シェーダプログラムのユニフォームバッファの内容を更新するために、シーングラフによって呼び出されます。この実装は、実際のグラフィックス操作を実行することは期待されておらず、単にRenderState::uniformData() から返されたQByteArray にデータをコピーする責任を負うだけです。シーングラフは、シェーダーでそのバッファが見えるようにする面倒を見る。

現在のレンダリングstate は、シーングラフから渡される。状態が関連する状態がダーティであることを示す場合、実装は、RenderState::uniformData （）を介してアクセス可能なバッファデータ内の適切な領域を更新する必要があります。行列や不透明度などの状態がダーティでない場合、データは永続的であるため、対応する領域に触れる必要はない。

一様なデータに何らかの変更が加えられるたびに、戻り値はtrue でなければならない。

フラットカラー素材の色など、サブクラス固有の状態は、それに応じてバッファ内の関連領域を更新するために、newMaterial から抽出する必要があります。

oldMaterial を使用すると、マテリアルの状態を更新する際のバッファの変更（通常はmemcpy呼び出し）を最小限に抑えることができます。が NULL の場合、このシェーダは起動されたばかりです。oldMaterial

© 2025 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.

QSGMaterialShader Class

パブリックタイプ

パブリック関数

保護された関数

詳細説明

メンバータイプ ドキュメント

enum QSGMaterialShader::Flagflags QSGMaterialShader::Flags

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

QSGMaterialShader::QSGMaterialShader()

[since 6.4] int QSGMaterialShader::combinedImageSamplerCount(int binding) const

QSGMaterialShader::Flags QSGMaterialShader::flags() const

void QSGMaterialShader::setFlag(QSGMaterialShader::Flags flags, bool on = true)

void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)

[protected] void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)

[protected] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)

[protected, since 6.8] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

[virtual] bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

[virtual] void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

[virtual] bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

メンバータイプドキュメント

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

`[since 6.4]` int QSGMaterialShader::combinedImageSamplerCount(int binding) const

`[protected]` void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)

`[protected]` void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)

`[protected, since 6.8]` void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

`[virtual]` bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial **newMaterial*, QSGMaterial **oldMaterial*)

`[virtual]` void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture ***texture*, QSGMaterial **newMaterial*, QSGMaterial **oldMaterial*)

`[virtual]` bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial **newMaterial*, QSGMaterial **oldMaterial*)