MultiEffect QML Type

Wendet einen Nachbearbeitungseffekt auf ein Element an. Mehr...

• Liste aller Elemente, einschließlich geerbter Elemente

Eigenschaften

• 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

Signale

• shaderChanged()

Ausführliche Beschreibung

Der Typ „MultiEffect“, der Nachfolger des Qt- Graphical Effects aus Qt 5, wendet einen Nachbearbeitungseffekt auf das Element „ source “ an. Im Gegensatz zum Qt-Modul „ Graphical Effects “ ermöglicht „MultiEffect“ die Kombination mehrerer Effekte (Weichzeichnen, Schatten, Kolorierung usw.) in einem einzigen Element und Shader. Sie können „ MultiEffect “ verwenden, wenn Sie nur einen einzigen Effekt ohne zusätzlichen Overhead benötigen, aber Sie können damit auch mehrere Effekte auf ein Element anwenden, ohne dass dadurch mehrere Render-Durchläufe erforderlich werden.

MultiEffect wurde speziell für die gängigsten Effekte entwickelt und lässt sich leicht animieren. Falls MultiEffect den von Ihnen benötigten Effekt nicht enthält, sollten Sie die Implementierung eines benutzerdefinierten Effekts unter Verwendung von Qt Quick Effect Maker. Weitere Informationen zu Shader-Effekten finden Sie in der Referenzdokumentation zu „ ShaderEffect “.

Beachten Sie, dass der Typ „MultiEffect“ neben dem Quellobjekt ein neues visuelles Objekt rendert. Um den Effekt auf das Quellelement anzuwenden, müssen Sie das neue MultiEffect-Element an der Position des Quellelements platzieren. Wenn das Quellelement und das MultiEffect-Element nicht undurchsichtig sind, können beide Elemente sichtbar sein, sodass Sie möglicherweise nicht den gewünschten Effekt erzielen. Um das Quellelement auszublenden, gehen Sie wie folgt vor:

• Setzen Sie für das Quellelement „ visible: false “. In diesem Fall wird das Quellelement überhaupt nicht gerendert und kann keine Touch- oder Klick-Eingaben empfangen.
• Setzen Sie „ opacity: 0 “ für das Quell-Element. In diesem Fall ist das Quell-Element vollständig transparent, kann aber weiterhin Berührungs- oder Klick-Eingaben empfangen.

Anwendungsbeispiel

Das folgende Beispiel zeigt, wie Sie einen Sättigungseffekt auf ein Element anwenden:

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
}

Das folgende Beispiel zeigt, wie man einen Sättigungseffekt auf ein „ layered Item “ anwendet:

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

Das folgende Beispiel zeigt, wie mehrere Effekte gleichzeitig angewendet werden:

import QtQuick
import QtQuick.Effects

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

Im Folgenden finden Sie ein Beispiel dafür, wie die Effekte „Maske“, „Einfärbung“ und „Helligkeit“ gemeinsam verwendet werden können, um ein Element ausblenden. Diese Art des Ein- und Ausblendens von Elementen kann beispielsweise an einen Schiebereglerwert oder an Animationen wie „ NumberAnimation “ gebunden werden. Beachten Sie, dass die Eigenschaft „ visible “ auf „false“ gesetzt ist, wenn das Element vollständig ausgeblendet ist, um ein unnötiges Rendern des Effekts zu vermeiden.

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
}

Leistung

Für eine optimale Leistung sind einige Punkte zu beachten:

• Um den bestmöglichen Shader zu erhalten, aktivieren Sie nur die Effekte, die Sie tatsächlich verwenden (siehe blurEnabled, shadowEnabled, maskEnabled). Einfache Farbeffekte (brightness, contrast, saturation, colorization) sind immer aktiviert, sodass ihre Verwendung keinen zusätzlichen Overhead verursacht.
• Beachten Sie die Hinweise zur Leistung bei den Eigenschaften, die die Größe des Shaders oder des Effektelements verändern können, und ändern Sie diese während Animationen nicht.
• Wenn „MultiEffect“ nicht verwendet wird, denken Sie daran, die Eigenschaft „ visible “ auf „false“ zu setzen, um zu vermeiden, dass die Effekte im Hintergrund gerendert werden.
• Unschärfe und Schatten sind die rechenintensivsten Effekte. Bei diesen sollten Sie lieber „ blurMultiplier “ erhöhen als „ blurMax “ und die Verwendung von animierten „ source “-Elementen vermeiden, damit die Unschärfe nicht in jedem Frame neu generiert werden muss.
• Wenden Sie Effekte auf QML-Elemente mit optimaler Größe an, da mehr Pixel mehr Arbeit für die GPU bedeuten. Wenn Sie den Unschärfeeffekt auf den gesamten Hintergrund anwenden, denken Sie daran, „ autoPaddingEnabled “ auf „false“ zu setzen, da der Effekt sonst „über den Rand“ des Fensters bzw. Bildschirms hinauswächst.

Sie können „ ShaderEffectSource “ und „ MultiEffect “ kombinieren:

• Um dasselbe Quellelement in mehreren Effekten zu verwenden und es unverändert zu belassen.
• Um einen Teil des Quellelements zu verwenden, nutzen Sie „ ShaderEffectSource.sourceRect “.
• Um die Auflösung des Quellelements zu verringern, beispielsweise zur Verbesserung der Leistung, mithilfe der Eigenschaft „ ShaderEffectSource.textureSize “.

Dokumentation zu den Eigenschaften

autoPaddingEnabled : bool

Wenn Unschärfe- oder Schatteneffekte aktiviert sind und diese Option auf „true“ gesetzt ist (Standardeinstellung), wird die Elementgröße automatisch anhand von blurMax und blurMultiplier aufgefüllt. Beachten Sie, dass paddingRect immer zur Größe hinzugefügt wird.

Hinweis zur Leistung: Die Elementgröße sollte für eine optimale Leistung so klein wie möglich sein.

Hinweis zur Leistung: Führt zu einer Größenänderung des Elements; ändern Sie diese Eigenschaft nicht während einer Animation.

Siehe auch paddingRect.

blur : real

Diese Eigenschaft legt fest, wie stark die Quelle unscharf gezeichnet wird (Radius).

Der Wert reicht von 0,0 (keine Unschärfe) bis 1,0 (volle Unschärfe). Standardmäßig ist die Eigenschaft auf „ 0.0 “ (keine Änderung) gesetzt. Der Grad der vollen Unschärfe wird durch „ blurMax “ und „ blurMultiplier “ beeinflusst.

Hinweis zur Leistung: Wenn Sie zu keinem Zeitpunkt der Unschärfeanimationen Werte nahe 1,0 benötigen, sollten Sie zur Optimierung der Leistung erwägen, „ blurMax “ oder „ blurMultiplier “ zu reduzieren.

blurEnabled : bool

Aktiviert den Unschärfeeffekt.

Hinweis zur Leistung: Führt zu einer Änderung des Shaders; ändern Sie diese Eigenschaft nicht während einer Animation.

blurMax : int

Diese Eigenschaft legt den maximalen Pixelradius fest, den die Unschärfe mit dem Wert 1,0 erreichen wird.

Der sinnvolle Wertebereich reicht von 2 (dezenter Weichzeichner) bis 64 (starker Weichzeichner). Standardmäßig ist die Eigenschaft auf „ 32 “ eingestellt. Wählen Sie für eine optimale Leistung einen möglichst kleinen Wert, der Ihren Anforderungen entspricht.

Hinweis zur Leistung: Führt zu einer Änderung des Shaders; ändern Sie diese Eigenschaft nicht während einer Animation.

Hinweis zur Leistung: Führt zu einer Größenänderung des Elements; ändern Sie diese Eigenschaft nicht während einer Animation.

blurMultiplier : real

Diese Eigenschaft legt einen Multiplikator für die Vergrößerung des Unschärferadius fest.

Der Wert reicht von 0,0 (keine Multiplikation) bis unendlich. Standardmäßig ist die Eigenschaft auf „ 0.0 “ gesetzt. Durch Erhöhen des Multiplikators wird der Unschärferadius vergrößert, die Unschärfequalität nimmt jedoch ab. Dies ist bei einem größeren Unschärferadius die leistungsstärkere Option als „ blurMax “, da dadurch die Anzahl der Textur-Lookups nicht erhöht wird.

Hinweis zur Leistung: Führt zu einer Größenänderung des Elements; ändern Sie diese Eigenschaft nicht während einer Animation.

brightness : real

Diese Eigenschaft legt fest, um wie viel die Helligkeit der Quelle erhöht oder verringert wird.

Der Wert liegt im Bereich von -1,0 bis 1,0. Standardmäßig ist die Eigenschaft auf „ 0.0 “ (keine Änderung) eingestellt.

colorization : real

Diese Eigenschaft legt fest, inwieweit die Quelle mit der Funktion „ colorizationColor “ eingefärbt wird.

Der Wert reicht von 0,0 (nicht eingefärbt) bis 1,0 (vollständig eingefärbt). Standardmäßig ist die Eigenschaft auf „ 0.0 “ (keine Änderung) gesetzt.

colorizationColor : color

Diese Eigenschaft definiert den RGBA-Farbwert, der zur Einfärbung der Quelle verwendet wird.

Standardmäßig ist die Eigenschaft auf „ Qt.rgba(1.0, 0.0, 0.0, 1.0) “ (rot) gesetzt.

Siehe auch „ colorization “.

contrast : real

Diese Eigenschaft legt fest, um wie viel der Quellkontrast erhöht oder verringert wird.

Der Wert liegt zwischen -1,0 und 1,0. Standardmäßig ist die Eigenschaft auf „ 0.0 “ (keine Änderung) gesetzt.

fragmentShader : string [read-only]

Schreibgeschützter Zugriff auf den Dateinamen des derzeit verwendeten Fragment-Shaders.

hasProxySource : bool [read-only]

Gibt „true“ zurück, wenn die „ MultiEffect “ intern „ ShaderEffectSource “ für das „ source “-Element erstellt, und „false“, wenn das „ source “-Element unverändert verwendet wird. Wenn die Quelle beispielsweise das „ Image “-Element oder „ Item “ ist und „ layer.enabled “ auf „ true “ gesetzt ist, wird diese zusätzliche Proxy-Quelle nicht benötigt.

itemRect : rect [read-only]

Schreibgeschützter Zugriff auf das Rechteck des Effektelements. Dies kann beispielsweise genutzt werden, um den Bereich zu sehen, den das Element abdeckt.

Siehe auch paddingRect und autoPaddingEnabled.

maskEnabled : bool

Aktiviert den Maskeneffekt.

Hinweis zur Leistung: Führt zu einer Änderung des Shaders; ändern Sie diese Eigenschaft nicht während einer Animation.

maskInverted : bool

Diese Eigenschaft kehrt die Maske um; statt den Inhalt außerhalb von maskThresholdMin und maskThresholdMax auszublenden, wird nun der Inhalt zwischen diesen beiden Adressen ausgeblendet.

Standardmäßig ist die Eigenschaft auf false gesetzt.

maskSource : Item

Quellobjekt für den Maskeneffekt. Sollte auf ShaderEffectSource verweisen, auf ein Objekt, bei dem „ layer.enabled “ auf true gesetzt ist, oder auf ein Objekt, das direkt als Texturquelle verwendet werden kann (zum Beispiel Image). Der Alphakanal des Quellobjekts wird für die Maskierung verwendet.

Wenn „maskSource“ und die Quelle unterschiedliche Abmessungen haben, wird das „maskSource“-Bild auf die Größe der Quelle gestreckt.

maskSpreadAtMax : real

Diese Eigenschaft legt die Glätte der Maskenkanten im Bereich von maskThresholdMax fest. Durch die Verwendung höherer Spread-Werte wird der Übergang von transparenten zu undurchsichtigen Maskenpixeln weicher, indem dazwischen interpolierte Werte eingefügt werden.

Der Wert reicht von 0,0 (scharfe Maskenkante) bis 1,0 (weiche Maskenkante). Standardmäßig ist die Eigenschaft auf „ 0.0 “ eingestellt.

maskSpreadAtMin : real

Diese Eigenschaft legt die Glättung der Maskenkanten in der Nähe der „ maskThresholdMin “ fest. Durch Festlegen höherer Werte für „Spread“ wird der Übergang von transparenten zu undurchsichtigen Maskenpixeln weicher gestaltet, indem dazwischen interpolierte Werte eingefügt werden.

Der Wert reicht von 0,0 (scharfe Maskenkante) bis 1,0 (glatte Maskenkante). Standardmäßig ist die Eigenschaft auf „ 0.0 “ eingestellt.

maskThresholdMax : real

Diese Eigenschaft definiert einen oberen Schwellenwert für die Maskenpixel. Die Maskenpixel, deren Alpha-Wert unter diesem Schwellenwert liegt, werden verwendet, um die entsprechenden Pixel des Quellelements vollständig auszublenden. Die Maskenpixel mit einem höheren Alpha-Wert werden verwendet, um das Quellelement mit der Anzeige alpha-gemischt darzustellen.

Der Wert reicht von 0,0 (Alpha-Wert 0) bis 1,0 (Alpha-Wert 255). Standardmäßig ist die Eigenschaft auf „ 1.0 “ gesetzt.

maskThresholdMin : real

Diese Eigenschaft definiert einen unteren Schwellenwert für die Maskenpixel. Die Maskenpixel, deren Alpha-Wert unter diesem Schwellenwert liegt, werden verwendet, um die entsprechenden Pixel des Quellelements vollständig auszublenden. Die Maskenpixel mit einem höheren Alpha-Wert werden verwendet, um das Quellelement mit der Anzeige zu überblenden.

Der Wert reicht von 0,0 (Alpha-Wert 0) bis 1,0 (Alpha-Wert 255). Standardmäßig ist die Eigenschaft auf „ 0.0 “ gesetzt.

paddingRect : rect

Stellen Sie diese Option ein, um die Größe des Elements manuell zu vergrößern, damit Unschärfe und/oder Schatten richtig dargestellt werden. Wenn „ autoPaddingEnabled “ auf „true“ gesetzt ist und „paddingRect“ nicht festgelegt wurde, wird das Element so aufgefüllt, dass es dem maximal unscharfen Element entspricht, basierend auf „ blurMax “ und „ blurMultiplier “. Bei Aktivierung des Schattens müssen Sie in der Regel „ shadowHorizontalOffset “ und „ shadowVerticalOffset “ berücksichtigen und „paddingRect“ entsprechend anpassen.

Nachfolgend finden Sie ein Beispiel für die Anpassung von `paddingRect`, wobei ` autoPaddingEnabled ` auf `false` gesetzt ist, sodass der Schatten vollständig innerhalb des Elements unter MultiEffect passt.

Hinweis zur Leistung: Die Elementgröße sollte für optimale Leistung so klein wie möglich sein.

Hinweis zur Leistung: Führt zu einer Größenänderung des Elements; ändern Sie diese Eigenschaft nicht während einer Animation.

Siehe auch „ autoPaddingEnabled “.

saturation : real

Diese Eigenschaft legt fest, um wie viel die Sättigung der Quelle erhöht oder verringert wird.

Der Wert reicht von -1,0 (vollständig entsättigt) bis unendlich. Standardmäßig ist die Eigenschaft auf „ 0.0 “ (keine Änderung) eingestellt.

shadowBlur : real

Diese Eigenschaft legt fest, wie stark der Schatten weichgezeichnet wird (Radius).

Der Wert reicht von 0,0 (keine Unschärfe) bis 1,0 (vollständige Unschärfe). Standardmäßig ist die Eigenschaft auf „ 1.0 “ gesetzt. Der Grad der vollständigen Unschärfe wird durch „ blurMax “ und „ blurMultiplier “ beeinflusst.

Hinweis zur Leistung: Der beste Weg, die Unschärfe von Schatten zu reduzieren, besteht darin, den Wert „ blurMax “ zu verringern (sofern er nicht für die Unschärfe von Elementen benötigt wird). Achten Sie jedoch darauf, „ blurMax “ während Animationen nicht anzupassen.

shadowColor : color

Diese Eigenschaft definiert den RGBA-Farbwert, der für den Schatten verwendet wird. Dies ist beispielsweise nützlich, wenn ein Schatten zur Simulation eines Leuchteffekts verwendet wird.

Standardmäßig ist die Eigenschaft auf „ Qt.rgba(0.0, 0.0, 0.0, 1.0) “ (schwarz) gesetzt.

shadowEnabled : bool

Aktiviert den Schatteneffekt.

Hinweis zur Leistung: Führt zu einer Änderung des Shaders; ändern Sie diese Eigenschaft während einer Animation nicht.

shadowHorizontalOffset : real

Diese Eigenschaft legt den horizontalen Versatz des Schattens von der Mitte des Elements fest.

Der Wert liegt im Bereich von -inf bis inf. Standardmäßig ist die Eigenschaft auf „ 0.0 “ gesetzt.

shadowOpacity : real

Diese Eigenschaft legt die Deckkraft des Schlagschattens fest. Dieser Wert wird mit dem Alpha-Wert von „ shadowColor “ multipliziert.

Der Wert reicht von 0,0 (vollständig transparent) bis 1,0 (vollständig deckend). Standardmäßig ist die Eigenschaft auf „ 1.0 “ gesetzt.

shadowScale : real

Diese Eigenschaft legt den Maßstab des Schattens fest. Die Skalierung erfolgt ausgehend vom Mittelpunkt des Elements.

Der Wert reicht von 0 bis unendlich. Standardmäßig ist die Eigenschaft auf „ 1.0 “ gesetzt.

shadowVerticalOffset : real

Diese Eigenschaft legt den vertikalen Versatz des Schattens gegenüber der Mitte des Elements fest.

Der Wert reicht von -inf bis inf. Standardmäßig ist die Eigenschaft auf „ 0.0 “ gesetzt.

source : Item

Diese Eigenschaft enthält das Element, das als Quelle für den Effekt verwendet werden soll. Bei Bedarf generiert „ MultiEffect “ intern ein „ ShaderEffectSource “ als Texturquelle.

Siehe auch „ hasProxySource “.

vertexShader : string [read-only]

Schreibgeschützter Zugriff auf den Dateinamen des aktuell verwendeten Vertex-Shaders.

Signal-Dokumentation

shaderChanged()

Dieses Signal wird ausgelöst, wenn sich der verwendete Shader ändert.

Siehe auch fragmentShader und vertexShader.