MultiEffect QML Type

アイテムに後処理効果を適用します。もっと詳しく...

• 継承されたメンバーを含む全メンバーのリスト

プロパティ

• autoPaddingEnabled : bool
• blur : real
• blurEnabled : bool
• blurMax : int
• blurMultiplier : real
• brightness : real
• colorization : real
• colorizationColor : color
• contrast : real
• fragmentShader : string
• hasProxySource : bool
• itemRect : rect
• maskEnabled : bool
• maskInverted : bool
• maskSource : Item
• maskSpreadAtMax : real
• maskSpreadAtMin : real
• maskThresholdMax : real
• maskThresholdMin : real
• paddingRect : rect
• saturation : real
• shadowBlur : real
• shadowColor : color
• shadowEnabled : bool
• shadowHorizontalOffset : real
• shadowOpacity : real
• shadowScale : real
• shadowVerticalOffset : real
• source : Item
• vertexShader : string

信号

• shaderChanged()

詳細説明

Qt 5 のQtGraphical Effectsの後継である MultiEffect タイプは、source アイテムに後処理エフェクトを適用します。QtGraphical Effectsモジュールとは対照的に、MultiEffect では複数のエフェクト（ぼかし、シャドウ、カラー化など）を 1 つのアイテムとシェーダにまとめることができます。追加オーバーヘッドなしで単一のエフェクトだけが必要な場合はMultiEffect を使用できますが、複数のレンダーパスのコストをかけずにアイテムに複数のエフェクトを適用するためにも使用できます。

MultiEffectは、ほとんどの一般的なエフェクトのために特別に設計されており、簡単にアニメーションさせることができます。MultiEffectに必要なエフェクトが含まれていない場合は、Qt Quick Effect Makerを使用してカスタムエフェクトを実装することを検討してください。シェーダーエフェクトの詳細については、ShaderEffect のリファレンスドキュメントを参照してください。

MultiEffect タイプはソースアイテムと一緒に新しいビジュアルアイテムをレンダリングすることに注意してください。ソースアイテムにエフェクトを適用するには、新しい MultiEffect アイテムをソースアイテムの位置に配置する必要があります。ソースアイテムとマルチエフェク トアイテムが不透明でない場合、両方のアイテムが見えてしまい、望みのエ フェクトが得られないことがあります。ソースアイテムを非表示にするには、次のいずれかを実行します：

• ソースアイテムにvisible: false を設定します。この場合、ソース アイテムはまったくレンダリングされず、タッチやクリックの入力を受け取ることができません。
• ソース アイテムにopacity: 0 を設定します。この場合、ソース アイテムは完全に透明になりますが、タッチやクリックの入力を受け取ることはできます。

使用例

次の例では、アイテムに彩度エフェクトを適用する方法を示します：

import QtQuick
import QtQuick.Effects

...
Image {
    id: sourceItem
    source: "qt_logo_green_rgb.png"
    // Hide the source item, otherwise both the source item and
    // MultiEffect will be rendered
    visible: false
    // or you can set:
    // opacity: 0
}
// Renders a new item with the specified effects rendered
// at the same position where the source item was rendered
MultiEffect {
    source: sourceItem
    anchors.fill: sourceItem
    saturation: -1.0
}

次の例は、layered Item に彩度効果を適用する方法を示しています：

import QtQuick
import QtQuick.Effects

...
Image {
    id: sourceItem
    source: "qt_logo_green_rgb.png"
    layer.enabled: true
    // For the layered items, you can assign a MultiEffect directly
    // to layer.effect.
    layer.effect: MultiEffect {
        saturation: -1.0
    }
}

次の例は、複数のエフェクトを同時に適用する方法を示しています：

import QtQuick
import QtQuick.Effects

...
MultiEffect {
    source: sourceItem
    anchors.fill: sourceItem
    brightness: 0.4
    saturation: 0.2
    blurEnabled: true
    blurMax: 64
    blur: 1.0
}

以下は、マスク、カラー化、明るさの効果を一緒に使って、要素をフェードアウトさせる方法の例です。このような要素の非表示／表示は、例えば、スライダーの値や、NumberAnimation のようなアニメーションにバインドすることができます。アイテムが完全にフェードアウトしたときにvisible プロパティが false になるのは、エフェクトの不要なレンダリングを避けるためです。

import QtQuick
import QtQuick.Effects
import QtQuick.Controls.Material

...
MultiEffect {
    property real effectAmount: effectSlider.value
    source: sourceItem
    anchors.fill: sourceItem
    brightness: effectAmount
    colorizationColor: "#ff20d0"
    colorization: effectAmount
    maskEnabled: true
    maskSource: Image {
        source: "mask.png"
    }
    maskSpreadAtMin: 0.2
    maskThresholdMin: effectAmount
    visible: effectAmount < 1.0
}
Slider {
    id: effectSlider
    anchors.bottom: parent.bottom
    anchors.horizontalCenter: parent.horizontalCenter
}

パフォーマンス

最適なパフォーマンスを得るために考慮すべきことがいくつかあります：

• 最適なシェーダを得るには、実際に使用するエフェクトのみを有効にします（blurEnabled,shadowEnabled,maskEnabled を参照）。単純なカラーエフェクト (brightness,contrast,saturation,colorization) は常に有効になっているため、これらを使用しても余分なオーバーヘッドは増えません。
• シェーダやエフェクトアイテムのサイズを変更する可能性のあるプロパティのパフォーマンスノートを参照し、アニメーション中にこれらを変更しないでください。
• MultiEffect を使用しない場合は、visible プロパティを false に設定し、エフェクトがバックグラウンドでレンダリングされないようにします。
• ブラーとシャドウは最も重いエフェクトです。これらのエフェクトでは、blurMax よりもblurMultiplier を増やすことを優先し、アニメーションするsource アイテムの使用は避け、ぼかしをフレームごとに再生成する必要がないようにします。
• ピクセル数が多いほどGPUの負担が増えるので、最適なサイズのQML要素にエフェクトを適用してください。背景全体にぼかしエフェクトを適用するときは、autoPaddingEnabled を false に設定することを忘れないでください。そうしないと、エフェクトはウィンドウやスクリーンの「外側」で成長します。

ShaderEffectSource とMultiEffect を組み合わせることができます：

• 同じソースアイテムを複数のエフェクトで使用し、変更しないようにします。
• ソースアイテムの一部を使用するには、ShaderEffectSource.sourceRect を使用します。
• パフォーマンスを向上させるために、ソースアイテムの解像度を下げるには、ShaderEffectSource.textureSize プロパティを使用します。

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

autoPaddingEnabled : bool

ブラーまたはシャドウ効果が有効で、これが true に設定されている場合（デフォルト）、アイテムのサイズはblurMax とblurMultiplier に基づいて自動的にパディングされます。paddingRect は常にサイズに加算されることに注意してください。

パフォーマンス上の注意：最適なパフォーマンスを得るためには、アイテムのサイズをできるだけ小さくする必要があります。

パフォーマンス上の注意：アイテムのリサイズを引き起こします。アニメーション中にこのプロパティを変更しないでください。

paddingRectも参照してください 。

blur : real

このプロパティは、ソースに適用されるぼかしの量（半径）を定義します。

値の範囲は 0.0（ぼかしなし）から 1.0（完全なぼかし）です。デフォルトでは、このプロパティは0.0 （変更なし）に設定されています。完全なぼかしの量は、blurMax とblurMultiplier によって影響されます。

パフォーマンスに関する注意：ブラーアニメーションのどのポイントでも1.0に近づける必要がない場合は、最適なパフォーマンスを得るためにblurMax またはblurMultiplier を減らすことを検討してください。

blurEnabled : bool

ぼかし効果を有効にする。

パフォーマンスに関する注意：シェーダが変更されます。アニメーション中にこのプロパティを変更しないでください。

blurMax : int

このプロパティは、値 1.0 のぼかしが到達する最大ピクセル半径を定義する。

この値の有効範囲は、2（微妙なぼかし）から64（高いぼかし）である。デフ ォル ト では、 こ のプ ロ パテ ィ は32 に設定 さ れてい ます。最適なパフォーマンスを得るには、必要なだけ小さな値を選択してください。

パフォーマンス上の注意：シェーダの変更を引き起こします。アニメーション中にこのプロパティを変更しないでください。

パフォーマンス上の注意：アイテムのリサイズを引き起こします。アニメーション中にこのプロパティを変更しないでください。

blurMultiplier : real

このプロパティは、ぼかし半径を拡張するための乗数を定義する。

値の範囲は 0.0（乗算されない）から inf までです。デフ ォル ト では、 こ のプ ロパテ ィ は0.0 に設定 さ れてい ます。 乗数を増加 さ せ る と 、 ぼかし半径は拡が り ますが、 ぼかし品質は低下 し ます。これは、テクスチャのルックアップ量を増やさないため、blurMax よりも、ぼかし半径を大きくするためのパフォーマンスが高いオプションです。

アニメーション中にこのプロパティを変更しないでください。

brightness : real

このプロパティは、ソースの明るさの増減を定義する。

値の範囲は -1.0 ～ 1.0 です。デフォルトでは、このプロパティは0.0 （変化なし）に設定されています。

colorization : real

このプロパティは、ソースがcolorizationColor でどの程度カラー化されるかを定義します。

値の範囲は、0.0 (色付けされない) から 1.0 (完全に色付けされる) です。デフォルトでは、このプロパティは0.0 (変更なし) に設定されています。

colorizationColor : color

このプロパティは、ソースのカラー化に使用される RGBA カラー値を定義します。

デフォルトでは、このプロパティはQt.rgba(1.0, 0.0, 0.0, 1.0) (赤) に設定されています。

colorizationも参照してください 。

contrast : real

このプロパティは、ソースのコントラストをどの程度増減させるかを定義する。

値の範囲は -1.0 から 1.0 です。デフォルトでは、このプロパティは0.0 （変化なし）に設定されています。

fragmentShader : string [read-only]

現在使用されているフラグメントシェーダーのファイル名への読み取り専用アクセス。

hasProxySource : bool [read-only]

MultiEffect が内部的にsource 項目に対してShaderEffectSource を作成する場合は true を返し、source 項目がそのまま使用される場合は false を返します。例えば、ソースがImage 要素またはItem でlayer.enabled がtrue に設定されている場合、この追加のプロキシ・ソースは必要ありません。

itemRect : rect [read-only]

エフェクトアイテムの矩形への読み取り専用アクセス。これは例えば、アイテムがカバーする領域を見るために使用することができます。

paddingRect およびautoPaddingEnabledも参照して ください。

maskEnabled : bool

マスク効果を有効にする。

パフォーマンスに関する注意：シェーダが変更されます。アニメーション中にこのプロパティを変更しないでください。

maskInverted : bool

このプロパティは、マスクを反対側に切り替えます。maskThresholdMin とmaskThresholdMax の外側のコンテンツがマスクされる代わりに、それらの間のコンテンツがマスクされます。

デフォルトでは、このプロパティはfalse に設定されています。

maskSource : Item

マスク効果のソースアイテム。ShaderEffectSource 、layer.enabled をtrue に設定したアイテム、またはテクスチャ ソースとして直接使用できるアイテム（たとえば、Image ）を指す必要があります。ソース アイテムのアルファ チャンネルがマスクに使用されます。

maskSource とソースの寸法が異なる場合、maskSource 画像はソースのサイズに合わせて伸張されます。

maskSpreadAtMax : real

このプロパティは、maskThresholdMax 近傍のマスク・エッジの滑らかさを定義します。 より高いスプレッド値を使用すると、透明マスク・ピクセルから不透明マスク・ピクセルへの遷移が、それらの間に補間値を追加することによって柔らかくなります。

値の範囲は0.0（マスクエッジがシャープ）から1.0（マスクエッジがスムーズ）です。デフォルトでは、このプロパティは0.0 に設定されています。

maskSpreadAtMin : real

このプロパティは、maskThresholdMin 近傍のマスクエッジの滑らかさを定義します。スプレッド値を高く設定すると、透明マスクピクセルから不透明マスクピクセルへの遷移が、それらの間に補間値を追加することによって柔らかくなります。

値の範囲は0.0（マスクエッジがシャープ）から1.0（マスクエッジがスムーズ）です。デフォルトでは、このプロパティは0.0 に設定されています。

maskThresholdMax : real

このプロパティは、マスクピクセルの上限しきい値を定義する。このプロパティを下回るアルファ値を持つマスクピクセルは、ソースアイテムから対応するピクセルを完全にマスクするために使用される。より高いアルファ値を持つマスクピクセルは、ソースアイテムをディスプレイにアルファブレンディングするために使用される。

値の範囲は0.0（アルファ値0）から1.0（アルファ値255）である。デフォルトでは、このプロパティは1.0 に設定されています。

maskThresholdMin : real

このプロパティは、マスクピクセルの低いしきい値を定義する。このプロパティより低いアルファ値を持つマスクピクセルは、ソースアイテムから対応するピクセルを完全にマスクするために使用される。より高いアルファ値を持つマスクピクセルは、ソースアイテムをディスプレイにアルファブレンディングするために使用される。

値の範囲は0.0（アルファ値0）から1.0（アルファ値255）である。デフォルトでは、このプロパティは0.0 に設定されています。

paddingRect : rect

アイテムのサイズを手動で大きくして、ぼかしや影が収まるようにするには、これを設定します。autoPaddingEnabled が true で paddingRect が設定されていない場合、アイテムはblurMax とblurMultiplier に基づいて、最大にぼかされたアイテムに合うようにパディングされます。シャドウを有効にする場合、通常、shadowHorizontalOffset とshadowVerticalOffset を考慮に入れ、それに応じてこの paddingRect を調整する必要があります。

以下は、autoPaddingEnabled を false に設定して paddingRect を調整し、シャドウがMultiEffect アイテムの内側に収まるようにした例です。

パフォーマンス上の注意：最適なパフォーマンスを得るためには、アイテムのサイズをできるだけ小さくする必要があります。

パフォーマンス上の注意：アイテムのリサイズを引き起こします。アニメーション中にこのプロパティを変更しないでください。

autoPaddingEnabledも参照してください 。

saturation : real

このプロパティは、ソースの彩度をどの程度増減させるかを定義します。

値の範囲は -1.0（完全に彩度を下げる）から inf までです。デフォルトでは、このプロパティは0.0 （変化なし）に設定されています。

shadowBlur : real

このプロパティは、シャドウに適用されるぼかし（半径）の大きさを定義します。

値の範囲は 0.0（ぼかしなし）から 1.0（完全ぼかし）までです。デフォルトでは、このプロパティは1.0 に設定されています。完全なぼかしの量はblurMax とblurMultiplier によって影響されます。

パフォーマンスに関する注意：シャドウのぼかしを減らす最も最適な方法は、blurMax を小さくすることです（アイテムのぼかしに必要ない場合）。ただ、アニメーション中にblurMax を調整しないことを忘れないでください。

shadowColor : color

このプロパティは、影に使用されるRGBAカラー値を定義します。このプロパティは、影がグロー効果をシミュレートするために使用される場合などに便利です。

デフォルトでは、このプロパティはQt.rgba(0.0, 0.0, 0.0, 1.0) (黒) に設定されています。

shadowEnabled : bool

シャドウ効果を有効にする。

パフォーマンスに関する注意：シェーダが変更されます。アニメーション中にこのプロパティを変更しないでください。

shadowHorizontalOffset : real

このプロパティは、アイテム中心からの影の水平オフセットを定義する。

値の範囲は -inf から inf です。デフォルトでは、このプロパティは0.0 に設定されています。

shadowOpacity : real

このプロパティは、ドロップシャドウの不透明度を定義します。この値はshadowColor アルファ値と乗算される。

値の範囲は 0.0（完全に透明）から 1.0（完全に不透明）です。デフォルトでは、このプロパティは1.0 に設定されています。

shadowScale : real

このプロパティは、シャドウのスケールを定義します。スケーリングはアイテムの中心から適用されます。

値の範囲は 0 から inf です。デフォルトでは、このプロパティは1.0 に設定されています。

shadowVerticalOffset : real

このプロパティは、アイテム中心からの影の垂直オフセットを定義する。

値の範囲は -inf から inf です。デフォルトでは、このプロパティは0.0 に設定されています。

source : Item

このプロパティは、エフェクトのソースとして使用するアイテムを保持します。必要であれば、MultiEffect は内部的にテクスチャソースとしてShaderEffectSource を生成します。

hasProxySourceも参照して ください。

vertexShader : string [read-only]

現在使用されている頂点シェーダーのファイル名への読み取り専用アクセス。

シグナルのドキュメント

shaderChanged()

このシグナルは、使用するシェーダが変更されたときに発行されます。

fragmentShader およびvertexShaderも参照して ください。