Effect QML Type

後処理効果を作成するための基本コンポーネント。詳細...

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

プロパティ

• passes : list

詳細説明

「エフェクト」タイプを使用すると、QtQuick3D 向けに独自のポストプロセッシングエフェクトを実装できます。

ポストプロセッシングエフェクト

ポストプロセッシングエフェクトは、概念的にはQt Quick の「ShaderEffect 」項目と非常に似ています。エフェクトが設定されている場合、シーンはまず別のテクスチャにレンダリングされます。その後、View3D のrender mode に応じて、テクスチャ化されたクワッドをメインのレンダリングターゲットに描画することで、エフェクトが適用されます。エフェクトは、頂点シェーダー、フラグメントシェーダー、あるいはその両方を提供できます。 エフェクトは、View3D に従い、常にシーン全体に適用されます。

エフェクトは、SceneEnvironment::effects プロパティ内のSceneEnvironment に関連付けられます。このプロパティはリスト形式であり、エフェクトを連鎖させることができます。エフェクトはリスト内の順序通りに適用され、前のステップの出力が次のステップの入力として使用されます。最後のエフェクトの出力が、View3D の内容を定義します。

エフェクトは多くの点でcustom materials と似ています。ただし、カスタムマテリアルはモデルに関連付けられ、その特定のメッシュのシェーディングを担当します。一方、エフェクトの頂点シェーダーは常にクワッド（例えば、2つの三角形）を入力として受け取り、そのフラグメントシェーダーはシーンの内容を含むテクスチャをサンプリングします。

カスタムマテリアルとは異なり、エフェクトは複数のパスをサポートしています。多くのエフェクトではこれは必要ありませんが、複数のエフェクトを適用する必要がある場合でも、the SceneEnvironment で複数のエフェクトを連鎖させることで、多くの場合同じ結果を得ることができます。これは「カスタムエフェクト」の例でも示されています。 しかし、パスでは追加のカラーバッファ（テクスチャ）を要求し、それらの追加バッファのうちどれに出力するかを指定することが可能です。これにより、後続のパスがこれらの追加バッファの1つ以上と、元のシーンの内容を入力として使用できるようになるため、より複雑な画像処理技術を実装することが可能になります。 必要に応じて、これらの追加バッファの有効期間を延長することが可能です。つまり、フレーム間でその内容が保持されるため、モーションブラーなど、複数のフレームからの内容を蓄積することに依存するエフェクトを実装できるようになります。

Qt Quick の2DShaderEffect と比較すると、3Dポストプロセッシングエフェクトには、深度バッファデータを使用できることや、中間バッファを使用して複数のパスを実装できるという利点があります。 さらに、テクスチャ関連の機能も拡張されています。Qt Quick 3D では、フィルタリングモードをよりきめ細かく制御できるほか、RGBA8 以外のテクスチャ形式（例えば、浮動小数点形式）でもエフェクトを適用できるようになっています。

シェーダーへのデータの公開

CustomMaterial やShaderEffect と同様に、Effectオブジェクトの動的プロパティは、通常のQMLおよびQt Quick 機能を使用して変更・アニメーション化でき、その値は自動的にシェーダーに公開されます。以下のリストは、プロパティのマッピングを示しています：

• bool、int、real → bool、int、float
• QColor、color → vec4、また、QMLで指定された色値がsRGB色空間であると仮定して、色はリニアに変換されます。"green" などのQtの組み込み色もsRGB色空間にあり、DefaultMaterialおよびPrincipledMaterial のすべての色プロパティに対しても同様の変換が行われるため、Effectのこの動作はそれらと一致しています。
• QRect、QRectF 、rect → vec4
• QPoint、QPointF 、point 、QSize 、QSizeF 、size → vec2
• QVector2D,vector2d → vec3
• QVector3D,vector3d → vec3
• QVector4D,vector4d -> vec4
• QMatrix4x4,matrix4x4 -> mat4
• QQuaternion,quaternion → vec4、スカラー値はw
• TextureInput -> sampler2D または samplerCube となります（TextureInput のtextureプロパティでTexture またはCubeMapTexture のどちらが使用されているかによって異なります）。enabled プロパティをfalseに設定すると、シェーダーに対してダミーのテクスチャが公開されます。つまり、シェーダーは引き続き機能しますが、不透明な黒の画像コンテンツを持つテクスチャをサンプリングすることになります。 サンプラーのプロパティは、常にTextureInput オブジェクトを参照する必要があり、Texture を直接参照してはならない点に注意してください。Texture のプロパティに関しては、ソース、タイリング、フィルタリングに関連するプロパティのみがエフェクトで暗黙的に考慮されます。それ以外（UV変換など）は、カスタムシェーダーが適切と判断する方法で実装する必要があります。

ユーザー定義エフェクトの入門

カスタム後処理エフェクトには、少なくとも Effect オブジェクトとフラグメントシェーダーのスニペットが必要です。一部のエフェクトでは、カスタマイズされた頂点シェーダーも必要になる場合があります。

簡単な例として、シーンの内容と画像を合成し、さらに赤チャンネルの値をアニメーション形式で変更するエフェクトを作成してみましょう：

Effect {
    id: simpleEffect
    property TextureInput tex: TextureInput {
        texture: Texture { source: "image.png" }
    }
    property real redLevel
    NumberAnimation on redLevel { from: 0; to: 1; duration: 5000; loops: -1 }
    passes: Pass {
       shaders: Shader {
           stage: Shader.Fragment
           shader: "effect.frag"
       }
    }
}

void MAIN()
{
    vec4 c = texture(tex, TEXTURE_UV);
    c.r *= redLevel;
    FRAGCOLOR = c * texture(INPUT, INPUT_UV);
}

ここでは、画像image.png を含むテクスチャが、tex という名前でシェーダーに公開されています。redLevelの値は、シェーダー内のfloat ユニフォームで同名の変数として利用可能です。

フラグメントシェーダーには、MAIN という関数が含まれている必要があります。最終的なフラグメントの色は、FRAGCOLOR によって決定されます。View3D のシーンの内容を含むメインの入力テクスチャは、sampler2D 内のINPUT という名前でアクセス可能です。 クワッドからのUV座標は、INPUT_UV にあります。これらのUV値は、実行時の基盤となるグラフィックスAPIに関係なく（したがって、Qt Quick 3Dによって必要な調整が自動的に適用されるため、画像内のY軸の方向に関係なく）、常にINPUT のサンプリングに適しています。 外部画像を用いたテクスチャのサンプリングは、TEXTURE_UV を使用して行われます。INPUT_UV は、前述の座標系の違いに対応するために V を反転させる必要があり、画像ベースのテクスチャとレンダリングターゲットとして使用されるテクスチャでロジックが異なるため、クロスプラットフォームアプリケーションには適していません。幸いなことに、これらはすべてエンジンによって処理されるため、シェーダー側でこれに関する追加のロジックは必要ありません。

simpleEffectが利用可能になると、View3D のSceneEnvironment のエフェクトリストに関連付けることができます：

environment: SceneEnvironment {
    effects: [ simpleEffect ]
}

結果は、左側が元のシーン、右側がエフェクトを適用したもので、次のようなものになります：

void MAIN()
{
    vec4 c = texture(tex, TEXTURE_UV);
    c.r *= redLevel;
#if QSHADER_VIEW_COUNT >= 2
    FRAGCOLOR = c * texture(INPUT, vec3(INPUT_UV, VIEW_INDEX));
#else
    FRAGCOLOR = c * texture(INPUT, INPUT_UV);
#endif
}

頂点シェーダーによるエフェクト

頂点シェーダーが存在する場合、MAIN という関数を提供する必要があります。ほとんどの場合、カスタム頂点シェーダーではホモジニアスな頂点位置を独自に計算する必要はありませんが、POSITION 、VERTEX 、およびMODELVIEWPROJECTION_MATRIX を使用することで可能です。カスタムシェーダーコードにPOSITION が含まれていない場合、Qt Quick 3DによってPOSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0); に相当するステートメントが自動的に挿入されます。

頂点シェーダーとフラグメントシェーダー間でデータを渡すには、VARYING キーワードを使用します。これにより、内部的には適切な頂点出力またはフラグメント入力の宣言に変換されます。フラグメントシェーダーでは同じ宣言を使用でき、これにより現在のフラグメントに対する補間値を読み取ることができます。

組み込みの DistortionSpiral エフェクトと実質的に非常に似た例を見てみましょう：

VARYING vec2 center_vec;
void MAIN()
{
    center_vec = INPUT_UV - vec2(0.5, 0.5);
    center_vec.y *= INPUT_SIZE.y / INPUT_SIZE.x;
}

VARYING vec2 center_vec;
void MAIN()
{
    float radius = 0.25;
    float dist_to_center = length(center_vec) / radius;
    vec2 texcoord = INPUT_UV;
    if (dist_to_center <= 1.0) {
        float rotation_amount = (1.0 - dist_to_center) * (1.0 - dist_to_center);
        float r = radians(360.0) * rotation_amount / 4.0 * FRAMEBUFFER_Y_UP;
        mat2 rotation = mat2(cos(r), sin(r), -sin(r), cos(r));
        texcoord = vec2(0.5, 0.5) + rotation * (INPUT_UV - vec2(0.5, 0.5));
    }
    FRAGCOLOR = texture(INPUT, texcoord);
}

Effectオブジェクトのpasses リストには、次のように頂点シェーダーとフラグメントシェーダーの両方のスニペットを指定する必要があります：

passes: Pass {
   shaders: [
       Shader {
           stage: Shader.Vertex
           shader: "effect.vert"
       },
       Shader {
           stage: Shader.Fragment
           shader: "effect.frag"
       }
    ]
}

最終結果は以下のようになります：

エフェクトシェーダーにおける特別なキーワード

• VARYING - 現在のシェーダーのタイプに応じて、頂点出力またはフラグメント入力を宣言します。
• MAIN - この関数は、エフェクトシェーダーには必ず含まれている必要があります。
• FRAGCOLOR - `vec4 ` - 最終的なフラグメントの色。フラグメントシェーダーの出力。（フラグメントシェーダーのみ）
• POSITION -vec4 - 頂点シェーダーで計算されたホモジニアス座標。（頂点シェーダーのみ）
• MODELVIEWPROJECTION_MATRIX -mat4 - スクリーンクワッドの変換行列。
• VERTEX -vec3 - クワッドの頂点。頂点シェーダーへの入力。（頂点シェーダーのみ）
• INPUT -sampler2D またはsampler2DArray - シーンがレンダリングされた入力テクスチャ用のサンプラー。ただし、パスがBufferInput オブジェクトを介して入力をリダイレクトしている場合は、INPUT はBufferInput によって参照される追加の色バッファのテクスチャを指します。 VR/ARアプリケーションなどで関連するマルチビューレンダリングが有効になっている場合、これはsampler2DArrayとなり、入力テクスチャは2Dテクスチャ配列になります。
• INPUT_UV -vec2 - `INPUT` をサンプリングするための UV 座標。
• TEXTURE_UV -vec2 - 画像ファイルから読み込まれたコンテンツを持つテクスチャをサンプリングするのに適したUV座標。
• INPUT_SIZE -vec2 - `INPUT ` テクスチャのサイズ（ピクセル単位）。
• OUTPUT_SIZE -vec2 - 出力バッファのサイズ（ピクセル単位）。パスがサイズ乗数を持つ追加のバッファに出力する場合を除き、多くの場合INPUT_SIZE と同じです。
• FRAME -float - フレームカウンタ。View3D 内の各フレーム終了後にインクリメントされます。
• DEPTH_TEXTURE -sampler2D またはsampler2DArray - シーン内の不透明オブジェクトを含む深度バッファの内容を格納した深度テクスチャ。CustomMaterial と同様に、シェーダーにこのキーワードが含まれていると、深度テクスチャが自動的に生成されます。
• NORMAL_ROUGHNESS_TEXTURE -sampler2D - シーンの現在可視領域内にある不透明オブジェクトのワールド空間法線およびマテリアルの粗さを格納したテクスチャです。CustomMaterial と同様に、シェーダー内にこのキーワードが含まれている場合、法線テクスチャを生成するための追加のレンダリングパスが実行されます。
• VIEW_INDEX -uint -マルチビューレンダリングが有効な場合、これは現在のビューインデックスであり、頂点シェーダーとフラグメントシェーダーの両方で利用可能です。マルチビューレンダリングが使用されていない場合は常に 0 になります。
• PROJECTION_MATRIX -mat4 ：投影行列。マルチビューレンダリングが有効な場合、これは行列の配列となる点に注意してください。
• INVERSE_PROJECTION_MATRIX -mat4 ：逆投影行列。マルチビューレンダリングでは、これは行列の配列であることに注意してください。
• VIEW_MATRIX ->mat4 ：ビュー（カメラ）行列。マルチビューレンダリングでは、これは行列の配列となることに注意してください。
• floatNDC_Y_UP - 正規化されたデバイス座標空間で Y 軸が上を向いている場合は1 、Y 軸が下を向いている場合は-1 となります。Vulkan でのレンダリングでは、Y 軸が下を向いている状態が採用されます。
• floatFRAMEBUFFER_Y_UP - フレームバッファ（テクスチャ）の座標系でY軸が上を向いている場合、値は1 となり、(0, 0) が左下隅となります。Y軸が下を向いている場合、値は-1 となり、(0, 0) が左上隅となります。
• floatNEAR_CLIP_VALUE - クリッピングプレーンの範囲が-1 から1 までである場合、この値は-1 となります。これは、OpenGL を使用してレンダリングする場合に当てはまります。その他のレンダリングバックエンドでは、このプロパティの値は0 となり、クリッピングプレーンの範囲は0 から1 までとなります。

マルチパスエフェクトの構築

マルチパスエフェクトでは、多くの場合、複数のシェーダーセットが使用され、「output 」および「commands 」プロパティが利用されます。パスリストの各エントリは、エフェクトの入力テクスチャ、および必要に応じて他のテクスチャもサンプリングしながら、そのパスの出力テクスチャにクワッドを描画するレンダリングパスに対応します。

マルチパスエフェクトの典型的な構成は、以下のようになります：

passes: [
    Pass {
        shaders: [
            Shader {
                stage: Shader.Vertex
                shader: "pass1.vert"
            },
            Shader {
                stage: Shader.Fragment
                shader: "pass1.frag"
            }
            // This pass outputs to the intermediate texture described
            // by the Buffer object.
            output: intermediateColorBuffer
        ],
    },
    Pass {
        shaders: [
            Shader {
                stage: Shader.Vertex
                shader: "pass2.vert"
            },
            Shader {
                stage: Shader.Fragment
                shader: "pass2.frag"
            }
            // The output of the last pass needs no redirection, it is
            // the final result of the effect.
        ],
        commands: [
            // This pass reads from the intermediate texture, meaning
            // INPUT in the shader will refer to the texture associated
            // with the Buffer.
            BufferInput {
                buffer: intermediateColorBuffer
            }
        ]
    }
]

intermediateColorBuffer とは何ですか？

Buffer {
    id: intermediateColorBuffer
    name: "tempBuffer"
    // format: Buffer.RGBA8
    // textureFilterOperation: Buffer.Linear
    // textureCoordOperation: Buffer.ClampToEdge
}

希望する値がデフォルト値と一致する場合、コメントアウトされているプロパティは不要です。

内部的には、このBufferオブジェクトが存在し、Passのoutput プロパティからそれを参照することで、View3D と一致するサイズのテクスチャが作成され、それにより暗黙的な入力および出力テクスチャのサイズも決定されます。 これを望まない場合は、sizeMultiplier プロパティを使用して、異なるサイズの中間テクスチャを取得することができます。これにより、シェーダー内のINPUT_SIZE およびOUTPUT_SIZE ユニフォームの値が異なる場合があります。

デフォルトでは、エフェクトはテクスチャがフレーム間でその内容を保持することを期待できません。新しい中間テクスチャが作成されると、そのテクスチャは `vec4(0.0)` にクリアされます。その後、同じテクスチャを別の目的で再利用することができます。 したがって、エフェクトパスは、パスの開始時点でのテクスチャの内容について仮定を立てることなく、常にテクスチャ全体に書き込む必要があります。これには例外があります。それは、bufferFlags がBuffer.SceneLifetimeに設定されているバッファオブジェクトです。これは、そのテクスチャがエフェクトのパスに恒久的に関連付けられており、他の目的で再利用されないことを示しています。 このようなカラーバッファの内容は、フレーム間で保持されます。これは通常、モーションブラーのようなエフェクトで「ピンポン方式」として使用されます。つまり、最初のパスはエフェクトのメイン入力テクスチャに加えて、永続的なバッファを入力として受け取り、別の中間バッファに出力します。一方、2番目のパスは永続的なバッファに出力します。 これにより、最初のフレームでは第1パスが空（透明）のテクスチャをサンプリングしますが、それ以降のフレームでは、前のフレームからの第2パスの出力をサンプリングします。その後、第3パスでエフェクトの入力と第2パスの出力をブレンドすることができます。

BufferInput コマンドタイプは、カスタムテクスチャバッファをレンダリングパスに公開するために使用されます。

たとえば、レンダリングパスシェーダー内で「mySampler 」という名前で「someBuffer 」にアクセスするには、コマンドリストに以下を追加します。

BufferInput { buffer: someBuffer; sampler: "mySampler" }

sampler の名前が指定されていない場合、デフォルトとしてINPUT が使用されます。

バッファは、レンダーパス間で中間結果を共有するのに役立ちます。

プリロードされたテクスチャをエフェクトで利用できるようにするには、代わりに「TextureInput 」を使用する必要があります。これらはエフェクト自体のプロパティとして定義でき、プロパティ名によってシェーダーから自動的にアクセス可能になります。

property TextureInput tex: TextureInput {
    texture: Texture { source: "image.png" }
}

ここで、tex は、エフェクトのすべてのパスのすべてのシェーダーにおいて有効なサンプラーとなります。

プロパティからのユニフォーム値に関しては、エフェクト内のすべてのパスで、それぞれのシェーダーが同じ値を読み取ります。必要に応じて、特定のパスに対してのみユニフォームの値を上書きすることが可能です。これは、そのパスのコマンドリストに `SetUniformValue ` コマンドを追加することで実現されます。

パフォーマンスに関する注意事項

ポストプロセッシングエフェクトを使用する際は、リソース使用量の増加やパフォーマンス低下の可能性があることに注意してください。Qt Quick レイヤーやShaderEffect と同様に、シーンをテクスチャとしてレンダリングし、それをクワッドのテクスチャとして適用する処理は、特にフラグメント処理能力が限られているローエンドのハードウェアでは、負荷の高い操作となります。 追加で必要なグラフィックスメモリの量やGPU負荷の増加は、いずれもView3D のサイズに依存します（ウィンドウシステムを持たない組み込みデバイスでは、このサイズが画面解像度と同じくらい大きくなることもよくあります）。マルチパスエフェクトや複数のエフェクトを適用すると、リソースとパフォーマンスの要件はさらに高まります。

したがって、開発ライフサイクルの早い段階で、対象となるデバイスとグラフィックススタックが、最終製品の画面解像度において、3D シーンの設計に含まれるエフェクトに対応できることを確認しておくことを強くお勧めします。

DEPTH_TEXTURE は、それを必要とする技術では避けられないものの、そのテクスチャの内容を生成するために追加のレンダリングパスを必要とし、性能の低いハードウェアではパフォーマンスの低下を招く可能性があります。したがって、DEPTH_TEXTURE は、どうしても必要な場合にのみ、エフェクトのシェーダーで使用してください。

シェーダー内の演算の複雑さも重要な要素です。「CustomMaterial 」と同様に、最適化されていないフラグメントシェーダーは、レンダリングパフォーマンスの低下を容易に招く可能性があります。

sizeMultiplier in Buffer を使用する際は、値が 1 を超える場合、注意が必要です。例えば、乗数が 4 の場合、View3D の 4 倍のサイズのテクスチャを作成し、そこにレンダリングすることになります。シャドウマップやマルチサンプリング、スーパーサンプリングと同様に、GPU 性能が限られているシステムでは、リソースやパフォーマンスのコスト増が、画質向上のメリットを上回ってしまう可能性があります。

VR/ARに関する考慮事項

Qt Quick 3D XRを使用して仮想現実（VR）や拡張現実（AR）向けのアプリケーションを開発する場合、ポストプロセスエフェクトは機能し、利用可能です。ただし、デザイナーや開発者は、仮想現実環境においてどのエフェクトが適切で、どのような種類のエフェクトが有効であるかを十分に理解するよう、特に注意を払う必要があります。ExtendedSceneEnvironment に組み込まれているエフェクトの一部や、非推奨となったEffectsモジュールに含まれるエフェクトなど、一部のエフェクトはVR環境において良好な視覚体験をもたらさず、場合によってはユーザーに身体的な影響（例えば、モーションシックネスやめまいなど）を及ぼす可能性さえあります。

VR/ARアプリケーションでより効率的なマルチビューレンダリングモードが有効になっている場合、左目と右目のコンテンツに対して個別のレンダリングパスは行われません。 その代わりに、2つの独立した2Dテクスチャの代わりに、2つのレイヤーを持つ2Dテクスチャ配列を使用して、すべてが1回のパスで行われます。これはまた、このモードでは、色や深度テクスチャといった多くの中間バッファをテクスチャ配列に変換する必要があることを意味します。これにより、カスタムマテリアルやポストプロセッシングエフェクトに影響が生じます。 入力テクスチャ（INPUT ）や深度テクスチャ（DEPTH_TEXTURE ）などのテクスチャは2Dテクスチャ配列となり、シェーダー内ではsampler2D ではなくsampler2DArray として公開されます。これは、texture()、textureLod()、textureSize()などのGLSL関数に影響を及ぼします。 その結果、UV座標はvec2ではなくvec3となります。一方、textureSize()はvec2ではなくvec3を返します。レンダリングモードに関係なく機能するように意図されたエフェクトは、適切なifdefを使用して記述できます：

#if QSHADER_VIEW_COUNT >= 2
    vec4 c = texture(INPUT, vec3(INPUT_UV, VIEW_INDEX));
#else
    vec4 c = texture(INPUT, INPUT_UV);
#endif

また、両方のケースに対応するマクロを定義しておくのも有用です。例えば：

#if QSHADER_VIEW_COUNT >= 2
#define SAMPLE_INPUT(uv) texture(INPUT, vec3(uv, VIEW_INDEX))
#define SAMPLE_DEPTH(uv) texture(DEPTH_TEXTURE, vec3(uv, VIEW_INDEX)).r
#define PROJECTION PROJECTION_MATRIX[VIEW_INDEX]
#define INVERSE_PROJECTION INVERSE_PROJECTION_MATRIX[VIEW_INDEX]
#else
#define SAMPLE_INPUT(uv) texture(INPUT, uv)
#define SAMPLE_DEPTH(uv) texture(DEPTH_TEXTURE, uv).r
#define PROJECTION PROJECTION_MATRIX
#define INVERSE_PROJECTION INVERSE_PROJECTION_MATRIX
#endif

ただし、これは `NORMAL_ROUGHNESS_TEXTURE ` には適用されません。これは、マルチビューレンダリングが有効な場合でも常に 2D テクスチャとなるためです：

#define SAMPLE_NORMAL(uv) normalize(texture(NORMAL_ROUGHNESS_TEXTURE, uv).rgb)

関連項目： Shader 、Pass 、Buffer 、BufferInput 、およびQt Quick 3D - カスタムエフェクトの例。

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

passes : list [read-only]

このエフェクトによって実装されているレンダリングpasses の一覧が含まれています。