QCanvasCustomBrush Class

詳細な説明

QCanvasCustomBrush は、カスタム頂点シェーダーおよび/またはフラグメントシェーダーを持つストローク/塗りつぶしブラシです。

これらのシェーダーは、Qt Quick ShaderEffect のシェーダーと同様に、Vulkan スタイルの GLSL で記述されることが想定されています。これらは常に、"customfrag.glsl" または"customvert.glsl" を含むQC_INCLUDE ステートメントを含まなければなりません。これにより、ユニフォームブロック、画像およびフォントテクスチャ、およびいくつかのヘルパー関数が利用可能になります。

iTime は、組み込みのuniformブロックで一般的に使用されるメンバーの一例です。true を指定してsetAnimationRunning()を呼び出すと、この値は毎フレーム自動的に更新され、アニメーションコンテンツの駆動に使用できます。

組み込みシェーダーの入力、ユニフォーム、およびヘルパー関数

QC_INCLUDE ステートメントは、標準のプリプロセッサ指令ではありません。これは、シェーダーが通常のシェーダーコンパイルパイプラインに渡される前のビルド時に、qt_add_custom_brush_shaders() によって処理されます。 このステートメントは、シェーダーの入力と出力、テクスチャサンプラー、共有ユニフォームブロック、およびフラグメントシェーダーの場合は一連のヘルパー関数を宣言する GLSL ソースコードのブロックに置き換えられます。頂点シェーダーでは `"customvert.glsl" ` を、フラグメントシェーダーでは `"customfrag.glsl" ` を使用してください。

つまり、カスタムブラシシェーダーは、これらの入力、出力、サンプラー、またはユニフォームを自ら宣言する必要はなく、これらはすべて `QC_INCLUDE ` ステートメントによって利用可能になります。

頂点シェーダーのインターフェース

"customvert.glsl" を含む頂点シェーダーでは、以下の入力および出力が宣言されます。

• in vec2 vertex - キャンバス座標系における頂点の位置。
• in vec2 tcoord - 頂点に関連付けられたテクスチャ座標。
• out vec2 texCoord - フラグメントシェーダーに転送されます。通常は `tcoord` に設定されます。
• out vec2 fragCoord - フラグメントシェーダーに渡されます。通常は `vertex` に設定されます。

さらに、以下の変換に関連するユニフォームが利用可能です：

• vec4 viewRect - ビューポートの矩形（(x, y, width, height)）。
• int ndcIsYDown - 一部のグラフィックスAPIの場合のように、正規化されたデバイス座標系のY軸が下向きになっているときは、0以外になります。gl_Position を計算する際は、この点を考慮してください。
• mat3 vertMatrix - 現在の変換行列。

頂点シェーダーは `gl_Position` を書き込む必要があり、`texCoord ` および `fragCoord ` をフラグメントステージに転送することが期待されます。

典型的な頂点シェーダーは次のようになります：

#version 440

QC_INCLUDE "customvert.glsl"

void main()
{
    texCoord = tcoord;
    fragCoord = vertex;
    vec2 v = (vertMatrix * vec3(vertex, 1.0)).xy;
    if (ndcIsYDown != 0)
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           -1.0 + 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
    else
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           1.0 - 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
}

フラグメントシェーダーインターフェース

"customfrag.glsl" を含むフラグメントシェーダーでは、以下の入力と出力が宣言されます。

• in vec2 texCoord - 補間されたテクスチャ座標。
• in vec2 fragCoord - ジオメトリと同じ座標系における、補間されたフラグメント位置。通常、プロシージャルエフェクトの生成に使用されます。
• out vec4 fragColor - 結果としてのフラグメントカラー。シェーダーはこれを書き込む必要があります。期待される出力は、プリマルチプライドアルファを使用します。

利用可能なテクスチャサンプラーは2つあります：

• sampler2D tex - 画像テクスチャ。
• sampler2D fontTex - フォントテクスチャ。グリフの符号付き距離フィールドを保持しています。ブラシを使用してテキストを塗りつぶす場合に適用されます。

また、便利定数TAU （2 * piに等しい）およびSQRT2 も定義されています。

共通のユニフォーム

QC_INCLUDE を使用する頂点シェーダーとフラグメントシェーダーの両方が、共有ユニフォームブロックにアクセスできます。最も一般的に使用されるメンバーは以下の通りです：

• float iTime -isAnimationRunning() がtrue である間、毎フレーム更新される秒単位の時間値。アニメーションの駆動に使用します。setAnimationRunning() を参照してください。
• vec4 data1,vec4 data2,vec4 data3,vec4 data4 - シェーダーに公開されるカスタムデータ。これらはC++からsetData1()、setData2()、setData3()、およびsetData4()を介して設定します。
• float globalAlpha - ペインターの現在のグローバル不透明度。フラグメントシェーダーでは通常、fragColor にこの値を乗算する必要があります。
• vec4 colorEffects - 有効なカラーエフェクトのパラメータ。通常は、直接アクセスするのではなく、applyColorEffects() を通じて適用されます。
• float fontAlphaMin,float fontAlphaMax - グリフのアンチエイリアシングを行う際に使用される、符号付き距離フィールドの閾値。

フラグメントシェーダーのヘルパー関数

フラグメントシェーダーのインクルードには、以下のヘルパー関数が用意されています：

• float clipMask() - 現在のフラグメントに対するクリップ（シザー）カバレッジを [0, 1] の範囲で返します。fragColor にこの値を乗算することで、ペインターのクリッピングを反映させることができます。
• float antialiasingAlpha() - `texCoord` から導出されたアンチエイリアシングカバレッジを [0, 1] の範囲で返します。アンチエイリアシングされたエッジを得るには、`fragColor ` にこの値を乗算してください。
• float sdfFontAlphaRaw() - アンチエイリアシングを適用せずに、fontTex からtexCoord の位置でサンプリングされた生の符号付き距離フィールド値を返します。必要に応じて、smoothstep() を手動で適用してください。
• float sdfFontAlpha() -fontTex からtexCoord でサンプリングされたグリフのアルファ値を返します。この値には、fontAlphaMin およびfontAlphaMax に基づいてデフォルトのアンチエイリアシングが適用されています。
• void applyColorEffects(inout vec4 color) - アクティブなコントラスト、明るさ、彩度エフェクトをcolor にその場で適用します。

一般的なフラグメントシェーダーでは、fragColor を計算し、これにglobalAlpha を乗算します。必要に応じて、クリッピングやアンチエイリアシングに対応するためにclipMask() およびantialiasingAlpha() を乗算し、最後に applyColorEffects() を呼び出します。

テキストが関与する場合は、sdfFontAlpha() も考慮に入れる必要があります。例えば：

#version 440

QC_INCLUDE "customfrag.glsl"

void main()
{
    float a = 0.6 + 0.2 * sin(0.1 * fragCoord.x + 4.0 * iTime);
    vec4 color = vec4(a, a, a, 1.0);
    fragColor = sdfFontAlpha() * globalAlpha * color;
    applyColorEffects(fragColor);
}

プロジェクトへのシェーダーの追加

QCanvasCustomBrushで使用されるシェーダーは、Qt Canvas Painterパッケージが提供するqt_add_custom_brush_shadersCMake関数を介して、必ずアプリケーションプロジェクトに追加する必要があります。この関数は、ビルド時に追加の前処理を実行した後、内部で標準のqt_add_shaders() を呼び出します。

例：

qt_add_custom_brush_shaders(app "app_custombrush_shaders"
    PREFIX
        "/shaders"
    FILES
        brush1.frag
)

ブラシの使用

実行時には、生成された.qsb ファイルを次のように使用できます：

QCanvasCustomBrush customBrush(":/shaders/brush1.frag.qsb"));
customBrush.setAnimationRunning(true); // iTime updates automatically
// expose custom data to the shader in data1
customBrush.setData1(QVector4D(1.0, 2.0, 3.0, 4.0));

その後、QCanvasCustomBrushを塗りつぶしなどで次のように使用できます：

painter->setFillStyle(customBrush);

Shader Tools CMake関数の詳細については `qt_add_custom_brush_shaders`を参照し、Qtでのクロスプラットフォームシェーダーコードの扱いについては、Qt XML-ph-0000@deepl.internalモジュールのドキュメントを参照してください。