Back to Qt.io
Contact Us Blog Download Qt
このページでは

MultiEffect QML Type

アイテムに後処理効果を適用します。詳細…

Import Statement: import QtQuick.Effects
Inherits:

Item

プロパティ

信号

詳細説明

Qt 5のQtGraphical Effectsの後継となるMultiEffect型は、source アイテムにポストプロセッシング効果を適用します。Qt XMLのGraphical Effectsモジュールとは対照的に、MultiEffectでは複数のエフェクト（ぼかし、影、色付けなど）を単一のアイテムおよびシェーダーに組み合わせることが可能です。追加のオーバーヘッドなしで単一のエフェクトのみが必要な場合はMultiEffect を使用できますが、複数のレンダリングパスのコストをかけずにアイテムに複数のエフェクトを適用するためにも使用できます。

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

なお、MultiEffect タイプは、ソースアイテムの横に新しいビジュアルアイテムをレンダリングすることに注意してください。 ソースアイテムにエフェクトを適用するには、新しい MultiEffect アイテムをソースアイテムの位置に配置する必要があります。ソースアイテムと MultiEffect アイテムの両方が不透明でない場合、両方のアイテムが表示されてしまい、意図したエフェクトが得られない可能性があります。ソースアイテムを非表示にするには、次のいずれかの操作を行ってください。

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

使用例

次の例は、アイテムに彩度効果を適用する方法を示しています:

彩度を完全に抜いたグレースケールのQtロゴ

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 に彩度効果を適用する方法を示しています：

彩度を完全に抜いたグレースケールのQtロゴ

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
    }
}

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

明るさ、彩度、ぼかし効果が組み合わされた、緑色の輝きを放つQtのロゴ

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になっている点に注意してください。

マスクと着色を用いたQtロゴのフェード効果の4段階。目に見える緑色から、ピンク色の粒子に溶け込んでいく様子まで

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 アイテムの使用は避けてください。そうすることで、毎フレームごとにぼかしを再生成する必要がなくなります。
  • エフェクトは最適なサイズの QML 要素に適用してください。ピクセル数が多いほど、GPU の負荷が高くなります。背景全体にぼかしエフェクトを適用する場合は、autoPaddingEnabled を false に設定することを忘れないでください。そうしないと、エフェクトがウィンドウや画面の「外側」まで広がってしまいます。

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

  • 複数のエフェクトで同じソースアイテムを使用し、その内容を変更せずに維持する場合。
  • ShaderEffectSource.sourceRect を使用して、ソースアイテムの一部のみを使用する場合。
  • ShaderEffectSource.textureSize プロパティを使用して、ソースアイテムの解像度を下げる（例：パフォーマンス向上のため）。

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

autoPaddingEnabled : bool

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

autoPaddingEnabledがtrueの場合（余白がある状態）とfalseの場合（端が切り取られている状態）を比較した、ぼやけた画像

パフォーマンスに関する注意：最適なパフォーマンスを得るためには、アイテムのサイズをできるだけ小さくしてください。

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

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 要素、またはlayer.enabled がtrue に設定されたItem である場合、この追加のプロキシソースは必要ありません。

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に設定し、影がMultiEffect のアイテム内に収まるようにpaddingRectを調整した例です。

パディング矩形（paddingRect）の値を比較した、影付きの2つのQtロゴ。パディングが0のときは影が切り取られ、パディングがあるときは完全な影が表現されている。

パフォーマンスに関する注意：最適なパフォーマンスを得るためには、アイテムのサイズをできるだけ小さくしてください。

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

「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 に設定されています。

注： 影の位置を中央から離し、shadowBlur を追加する場合 、影がクリップされないようにするには、必要に応じてpaddingRect もそれに応じて増やす必要があります。

shadowOpacity : real

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

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

shadowScale : real

このプロパティは、影のスケールを定義します。スケールはアイテムの中心を基準に適用されます。

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

注： shadowScale を増加させる場合 、影が切り取られないようにするため、paddingRect もそれに応じて増加させる必要がある場合があります。

shadowVerticalOffset : real

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

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

注： 影の位置を中央から離して「shadowBlur 」を追加する場合 、影が切り取られないようにするには、必要に応じて「paddingRect 」もそれに応じて増やす必要があります。

source : Item

このプロパティには、エフェクトのソースとして使用されるアイテムが格納されます。必要に応じて、MultiEffect は内部でShaderEffectSource をテクスチャソースとして生成します。

注： エフェクトをその親に設定するなどして、エフェクト自体をソースに含めることはサポートされていません。

注： ソースアイテムの `layer.enabled ` が true に設定されている場合 、そのアイテムが直接使用されます。これはパフォーマンスの面で有利であり、ソースが非表示になっている場合には望ましい動作です。しかし、ソースが表示されたままであり、エフェクトがパディング（`autoPaddingEnabled`、`paddingRect`）を追加する場合、そのパディングがソースアイテムの外観に影響を与える可能性があります。

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

vertexShader : string [read-only]

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

シグナルのドキュメント

shaderChanged()

このシグナルは、使用中のシェーダーが変更された際に発火します。

注： 対応するハンドラは onShaderChanged です。

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

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