ShaderEffect QML Type

矩形にカスタムシェーダーを適用します。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• blending : bool
• cullMode : enumeration
• fragmentShader : url
• log : string
• mesh : variant
• status : enumeration
• supportsAtlasTextures : bool (since QtQuick 2.4)
• vertexShader : url

詳細な説明

ShaderEffect 型は、矩形に対してカスタムvertex およびfragment (pixel) シェーダーを適用します。これにより、QMLシーンにドロップシャドウ、ぼかし、色付け、ページのカールなどの効果を追加することができます。

シェーダー

Qt 5 では、エフェクトは GLSL (OpenGL シェーディング言語) のソースコードの形で提供され、多くの場合、QML 内に文字列として埋め込まれていました。Qt 5.8 以降では、ローカルファイルや Qt リソースシステム内のファイルを参照することも可能になりました。

Qt 6では、Qt Quick がVulkan、Metal、Direct3D 11などのグラフィックスAPIもサポートしています。 そのため、GLSLソース文字列を用いた作業はもはや現実的ではありません。代わりに、新しいシェーダーパイプラインでは、Vulkan互換のGLSLコードをSPIR-Vにコンパイルし、その後、リフレクション情報を収集して、HLSL、Metal Shading Language、および各種GLSLバージョンといった他のシェーディング言語に変換する仕組みを採用しています。 その結果生成されたアセットは単一のパッケージにまとめられ、通常は拡張子が.qsb のファイルに保存されます。この処理はオフラインで、あるいは遅くともアプリケーションのビルド時に実行されます。 実行時には、シーングラフおよび基盤となるグラフィックス抽象化層が、これらの.qsb ファイルを消費します。そのため、ShaderEffectは、インラインシェーダーコードの代わりに、Qt 6内のファイル（ローカルまたはqrc）への参照を期待します。

vertexShader およびfragmentShader プロパティはQt 6におけるURLであり、例えばImage.source と非常に同様に機能します。ただし、ShaderEffectではfile およびqrc スキームのみがサポートされています。また、file スキームを省略することも可能で、これにより便利な方法で相対パスを指定できます。このようなパスは、コンポーネント（.qml ファイル）の場所を基準として解決されます。

シェーダーの入力とリソース

vertexShader への入力には、ユニフォームと頂点入力の2種類があります。

以下の入力が事前定義されています：

• vec4 qt_Vertex（位置 0） - 頂点座標。左上の頂点の座標は (0, 0)、右下の頂点の座標は (width,height) です。
• vec2 qt_MultiTexCoord0（位置 1） - テクスチャ座標。左上の座標は (0, 0)、右下は (supportsAtlasTextures, ) です。 が true の場合、座標は代わりにアトラス内の位置に基づいて計算されます。

以下のユニフォームが事前定義されています：

• mat4 qt_Matrix - 結合変換行列。ルート項目からこの ShaderEffect までの各行列と、直交投影行列の積です。
• float qt_Opacity - 統合された不透明度。ルート項目からこの ShaderEffect までの各不透明度の積です。

さらに、GLSL 型にマッピング可能なプロパティはすべて、シェーダーから利用可能です。以下のリストは、プロパティのマッピング方法を示しています。

• bool, int, qreal → bool, int, float - シェーダー内の型がQMLの型と異なる場合、値は自動的に変換されます。
• QColor -> vec4 - 色がシェーダーに渡される場合、まずプリ乗算されます。 したがって、たとえば Qt.rgba(0.2, 0.6, 1.0, 0.5) は、シェーダー内では vec4(0.1, 0.3, 0.5, 0.5) になります。
• QRect、QRectF -> vec4 - Qt.rect(x, y, w, h) は、シェーダー内では vec4(x, y, w, h) になります。
• QPoint、QPointF 、QSize 、QSizeF → vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4、スカラー値はw です。
• Image -> sampler2D - 原点は左上隅にあり、色値にはプリマルチプライが適用されています。テクスチャは、Image項目のfillModeを除いて、そのままの状態で提供されます。fillModeを含めるには、ShaderEffectSource またはImage::layer::enabledを使用してください。
• ShaderEffectSource -> sampler2D - 原点は左上隅にあり、色値はプリマルチプライされています。

サンプラーは、シェーダーコード内では依然として個別のユニフォーム変数として宣言されます。シェーダーでは、0 を除き、これらに対して任意のバインディングポイントを選択できます。 はユニフォームブロック用に予約されているためです。

一部のシェーディング言語やAPIでは、画像オブジェクトとサンプラーオブジェクトを区別する概念があります。Qt Quick は、SPIR-Vでサポートされているように、シェーダー内では常に統合された画像サンプラーオブジェクトを扱います。したがって、ShaderEffect用に提供されるシェーダーでは、常にlayout(binding = 1) uniform sampler2D tex; 形式のサンプラー宣言を使用する必要があります。 基盤となる抽象化レイヤーとシェーダーパイプラインが、アプリケーションに対して透過的に、サポートされているすべてのAPIおよびシェーディング言語でこれが機能するように処理を行います。

QML シーングラフのバックエンドは、テクスチャアトラス内にテクスチャを割り当てることを選択する場合があります。 アトラスに割り当てられたテクスチャが ShaderEffect に渡された場合、デフォルトでは、テクスチャ座標が 0 から 1 までになるよう、テクスチャアトラスから独立したテクスチャにコピーされ、期待通りのラップモードが得られます。ただし、これによりメモリ使用量が増加します。 テクスチャのコピーを回避するには、qt_MultiTexCoord0 を使用する単純なシェーダーに対して `supportsAtlasTextures ` を設定するか、各「uniform sampler2D <name>」に対して「uniform vec4 qt_SubRect_<name>」を宣言し、そこにテクスチャの正規化されたソース矩形を割り当てます。 単体のテクスチャの場合、ソース矩形は [0, 1]x[0, 1] です。アトラス内のテクスチャの場合、ソース矩形は、そのテクスチャが格納されているテクスチャアトラスの領域に対応します。 テクスチャアトラス内の「source」というテクスチャのテクスチャ座標を計算する正しい方法は、「qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0」です。

fragmentShader からの出力は、プリマルチプライされた状態である必要があります。blending が有効になっている場合、ソースオーバーブレンドが使用されます。ただし、アルファチャンネルにゼロを出力することで、加法ブレンドを実現することも可能です。

import QtQuick 2.0

Rectangle {
    width: 200; height: 100
    Row {
        Image { id: img;
                sourceSize { width: 100; height: 100 } source: "qt-logo.png" }
        ShaderEffect {
            width: 100; height: 100
            property variant src: img
            vertexShader: "myeffect.vert.qsb"
            fragmentShader: "myeffect.frag.qsb"
        }
    }
}

この例では、myeffect.vert およびmyeffect.frag にVulkan形式のGLSLコードが含まれており、qsb ツールによって処理されて.qsb ファイルが生成されることを前提としています。

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb, vec3(0.344, 0.5, 0.156))), tex.a) * qt_Opacity;
}

シェーダーを1つだけ使用する場合

vertexShader とfragmentShader の両方を指定する必要はありません。実際には、多くのShaderEffectの実装では、デフォルトの組み込み頂点シェーダーに依存しつつ、フラグメントシェーダーのみを提供することを望むでしょう。

デフォルトの頂点シェーダーは、テクスチャ座標をvec2 qt_TexCoord0 として、0 の位置でフラグメントシェーダーに渡します。

デフォルトのフラグメントシェーダーは、頂点シェーダーからテクスチャ座標が0 の位置にあるvec2 qt_TexCoord0 として渡されることを想定しており、バインディングポイント1 にあるsource という名前の sampler2D からサンプリングを行います。

ShaderEffect とアイテムレイヤー

ShaderEffect タイプは、layered items と組み合わせることができます。

エフェクトが無効なレイヤー

エフェクトが有効なレイヤー

Item { id: layerRoot layer.enabled: true layer.effect: ShaderEffect { fragmentShader: "effect.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D source; void main() { vec4 p = texture(source, qt_TexCoord0); float g = dot(p.xyz, vec3(0.344, 0.5, 0.156)); fragColor = vec4(g, g, g, p.a) * qt_Opacity; }

また、複数のレイヤー化されたアイテムを組み合わせることも可能です:

Rectangle { id: gradientRect; width: 10 height: 10 gradient: Gradient { GradientStop { position: 0; color: "white" } GradientStop { position: 1; color: "steelblue" } } visible: false; // should not be visible on screen. layer.enabled: true; layer.smooth: true } Text { id: textItem font.pixelSize: 48 text: "Gradient Text" anchors.centerIn: parent layer.enabled: true // This item should be used as the 'mask' layer.samplerName: "maskSource" layer.effect: ShaderEffect { property var colorSource: gradientRect; fragmentShader: "mask.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D colorSource; layout(binding = 2) uniform sampler2D maskSource; void main() { fragColor = texture(colorSource, qt_TexCoord0) * texture(maskSource, qt_TexCoord0).a * qt_Opacity; }

その他の注意事項

デフォルトでは、ShaderEffect は 4 つの頂点（各角に 1 つずつ）で構成されます。ページのカールのような非線形の頂点変換を行う場合は、mesh の解像度を指定することで、頂点の細かいグリッドを指定できます。

Qt 5からの移行

ShaderEffect アイテムを含む Qt 5 アプリケーションから Qt 6 への移行には、以下の手順が必要です：

• シェーダーコードを個別の.vert ファイルおよび.frag ファイルに移行すること、
• シェーダーを Vulkan 互換の GLSL に更新する、
• それらに対してqsb ツールを実行し、
• 生成された.qsb ファイルを実行ファイルにQtリソースシステムで組み込み、
• さらに、vertexShader およびfragmentShader のプロパティでそのファイルを参照します。

Qt XMLShader Toolsモジュールで説明されているように、ビルド時に CMake にqsb ツールを呼び出させることで、これらの手順の一部を自動化できます。詳細や例については、qt_add_shaders()を参照してください。

シェーダーコードの更新に関しては、以下に一般的に必要となる変更点の概要を示します。

attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 coord;
uniform highp mat4 qt_Matrix;
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

変換プロセスでは、主にGL_KHR_vulkan_glsl と互換性を持つようにコードを更新します。Qt Quick は GLSL および Vulkan が提供する機能の一部のみを使用しているため、一般的な ShaderEffect シェーダーの変換プロセスは通常、比較的簡単である点に留意してください。

• version ディレクティブには、440 または450 を指定する必要があります。ただし、GL_KHR_vulkan_glsl拡張機能は GLSL 140 以降向けに記述されているため、他の GLSL バージョンを指定しても動作する可能性があります。
• 入力および出力には、最新のGLSLキーワードであるin およびout を使用する必要があります。さらに、ロケーションの指定が必須です。入力と出力のロケーションネームスペースは別々であるため、両方に0から始まるロケーションを割り当てても問題ありません。
• 頂点シェーダーの入力に関しては、ShaderEffect を使用する場合、頂点位置用のロケーション `0 `（従来は `qt_Vertex` と呼ばれていました）と、テクスチャ座標用のロケーション `1 `（従来は `qt_MultiTexCoord0` と呼ばれていました）のみが使用可能です。
• 頂点シェーダーの出力およびフラグメントシェーダーの入力については、シェーダーコードで定義します。フラグメントシェーダーには、ロケーション 0 にvec4 出力（通常はfragColor と呼ばれます）が必要です。 移植性を最大限に高めるためには、頂点出力とフラグメント入力は、同じ位置番号と名前を使用する必要があります。フラグメントシェーダーのみを指定する場合、テクスチャ座標は、上記のサンプルコードに示されているように、組み込みの頂点シェーダーから位置0 にあるvec2 qt_TexCoord0 として渡されます。
• uniformブロック外のuniform変数は許可されません。代わりに、uniformデータは、バインディングポイント0 を持つuniformブロック内で宣言する必要があります。
• uniformブロックでは、std140修飾子の使用が想定されています。
• 実行時、頂点シェーダーとフラグメントシェーダーは、バインディングポイント 0 にバインドされた同一のユニフォームバッファを取得します。したがって、一般的なルールとして、シェーダー間でユニフォームブロックの宣言は同一でなければなりません。これには、いずれかのシェーダーで使用されないメンバも含まれます。 一部のグラフィックス API では、アプリケーションに対して透過的にユニフォームブロックが従来の struct ユニフォームに変換されるため、メンバ名は一致している必要があります。
• いずれか一方のシェーダーのみを指定する場合は、組み込みシェーダーがユニフォームブロックの先頭（より正確には、それぞれオフセット 0 および 64 の位置）に `qt_Matrix ` および `qt_Opacity ` を期待している点に注意してください。原則として、これらを常にブロックの 1 番目と 2 番目のメンバーとして含めるようにしてください。
• この例では、uniformブロックでブロック名buf が指定されています。この名前は自由に変更できますが、各シェーダー間で一致している必要があります。layout(...) uniform buf { ... } instance_name; のようなインスタンス名の使用は任意です。指定した場合、メンバーへのアクセスはすべてinstance_nameを修飾子として付ける必要があります。

varying highp vec2 coord;
uniform lowp float qt_Opacity;
uniform sampler2D src;
void main() {
    lowp vec4 tex = texture2D(src, coord);
    gl_FragColor = vec4(vec3(dot(tex.rgb,
                        vec3(0.344, 0.5, 0.156))),
                             tex.a) * qt_Opacity;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb,
                     vec3(0.344, 0.5, 0.156))),
                          tex.a) * qt_Opacity;
}

• 精度修飾子（lowp 、mediump 、highp ）は、現在使用されていません。
• 組み込みの GLSL 関数を呼び出す際は、最新の GLSL 命名規則に従う必要があります。特に、texture2D() の代わりにtexture() を使用する必要があります。
• サンプラーは、1 から始まるバインディングポイントを使用する必要があります。
• Qt Quick がmultiview を有効にしてレンダリングする場合、たとえば、左右の目のコンテンツが 1 回のパスで生成される VR/AR 環境で 3D シーンをレンダリングする場合など、ShaderEffect のシェーダーはこれを考慮して記述する必要があります。 例えば、ビュー数が2の場合、2 個の行列が存在することになります（qt_Matrixは2つの要素を持つmat4の配列です）。頂点シェーダーでは、gl_ViewIndex を考慮に入れる必要があります。マルチビュー対応のシェーダーの作成に関する一般的な情報については、QSBマニュアルの「Multiview 」セクションを参照してください。

Item Layers 、QSBマニュアル、およびqt_add_shadersも参照してください 。

プロパティのドキュメント

blending : bool

このプロパティが true の場合、fragmentShader の出力は、ブレンドモード「source-over」を使用して背景と合成されます。false の場合、背景は無視されます。合成処理はパフォーマンスを低下させるため、合成が必要ない場合は、このプロパティを false に設定してください。デフォルト値は true です。

cullMode : enumeration

このプロパティは、アイテムのどの側面を表示するかを定義します。

デフォルトは NoCulling です。

fragmentShader : url

このプロパティには、前処理済みのフラグメントシェーダーパッケージを含むファイルへの参照が含まれます。通常、このファイルの拡張子は.qsb です。この値は、Imageなどの他のQML型と同様に、URL として扱われます。ローカルファイルであるか、qrcスキーマを使用してQtリソースシステム経由で埋め込まれたファイルにアクセスする必要があります。 URLは絶対パスでも、コンポーネントのURLを基準とした相対パスでも構いません。

「vertexShader」も参照してください 。

log : string [read-only]

このプロパティには、シェーダーの最新のコンパイル試行における警告およびエラーのログが保持されます。これは、status が「Compiled」または「Error」に設定されたと同時に更新されます。

statusも参照してください 。

mesh : variant

このプロパティは、ShaderEffect を描画するために使用されるメッシュを定義します。任意のGridMesh オブジェクトを格納できます。このプロパティにサイズ値が割り当てられた場合、ShaderEffect は暗黙的に、その値をmesh resolution として持つGridMesh を使用します。デフォルトでは、このプロパティのサイズは1x1です。

GridMeshも参照してください 。

status : enumeration [read-only]

このプロパティは、シェーダーの現在の状態を示します。

フラグメントシェーダーまたは頂点シェーダーのソースコードを設定すると、ステータスは「未コンパイル」になります。新しいシェーダーソースコードを使用してShaderEffect が初めてレンダリングされると、シェーダーがコンパイルおよびリンクされ、ステータスは「コンパイル済み」または「エラー」に更新されます。

ランタイムコンパイルが使用されておらず、シェーダーのプロパティがバイトコードを含むファイルを参照している場合、ステータスは常に「コンパイル済み」となります。 シェーダーの内容は（頂点入力要素や定数バッファデータを検出するための基本的なリフレクションを除き）、レンダリングパイプラインの後半まで検査されないため、潜在的なエラー（レイアウトやルートシグネチャの不一致など）は後になって初めて検出されます。

logも参照してください 。

supportsAtlasTextures : bool [since QtQuick 2.4]

このプロパティを true に設定すると、シェーダーコードが、メッシュを基準として (0,0) から (1,1) の範囲にある qt_MultiTexCoord0 に依存していないことを確認できます。 この場合、qt_MultiTexCoord0の範囲は、アトラス内のテクスチャの位置に基づいて決定されます。現在、シェーダーの入力として使用されるサンプラーユニフォームが1つ未満、または1つを超える場合、このプロパティは効果を持ちません。

これは、qt_SubRect_<name> ユニフォームを指定する場合とは異なります。後者は、単一の `ShaderEffect ` 項目でアトラスから 1 つ以上のテクスチャを描画できるのに対し、`supportsAtlasTextures` を使用すると、アトラス内の異なるソース画像を使用する `ShaderEffect ` コンポーネントの複数のインスタンスを、1 回の描画でバッチ処理することができます。 どちらも、ShaderEffect によって参照された際に、テクスチャがアトラスからコピーされるのを防ぎます。

デフォルト値は false です。

このプロパティは QtQuick 2.4 で導入されました。

vertexShader : url

このプロパティには、前処理済みの頂点シェーダーパッケージを含むファイルへの参照が含まれます。通常、このファイルの拡張子は.qsb です。この値は、Imageなどの他のQML型と同様に、URL として扱われます。ローカルファイルであるか、qrcスキーマを使用してQtリソースシステム経由で埋め込まれたファイルにアクセスする必要があります。 URLは絶対パスでも、コンポーネントのURLを基準とした相対パスでも構いません。

「fragmentShader」も参照してください 。