C

QuickMultiEffect QML Type

Combination of multiple effects in a single item. More...

Import Statement: import "qrc:/quickmultieffect" .
Since: QuickMultiEffect 1.0
Inherits:

Item

Properties

Detailed Description

QuickMultiEffect is an item for adding effects into Qt Quick user interface. Compared to Qt Graphical Effects module, QuickMultiEffect combines multiple effects (blur, shadow, colorize etc.) into a single item and shader. This improves performance in cases where more than one effect per item is desired. QuickMultiEffect is designed especially for animated effects, where performance is more important than absolute rendering quality.

To use QuickMultiEffect in your own application UI, follow these steps:

  1. Copy the quickmultieffect directory into your project.
  2. In your .pro file, add
    include(quickmultieffect/include.pri)

    or do the equivalent with build systems other than qmake.

  3. Add
    import "qrc:/quickmultieffect"

    and

    QuickMultiEffect {
    ...
}

    component into your QML file.

  4. Set the QuickMultiEffect's source property to the item you want to add an effect to.
  5. Enable the QuickMultiEffect features you want to use. These are boolean properties with a suffix Enabled, e.g. blurEnabled, contrastEnabled, colorizeEnabled, and so on. To improve performance, shader code will only be generated for features that are enabled.
  6. Tweak and/or animate the effect properties. Note that some properties are meant to be set beforehand and not during the animations for optimal performance. These are documented with Performance note comments.

Property Documentation

blur : real

This property defines how much blur (radius) is applied to the source.

The value ranges from 0.0 (no blur) to 1.0 (full blur). By default, the property is set to 0.0 (no change). The amount of full blur is affected by blurMax and blurMultiplier.

Performance note: If you don't need to go close to 1.0 at any point of blur animations, consider reducing blurMax or blurMultiplier for optimal performance.


blurEnabled : bool

Enables the blur effect.

Performance note: Causes shader regeneration; do not change this property during animation.


blurMax : int

This property defines the maximum pixel radius that blur with value 1.0 will reach.

Meaningful range of this value is from 2 (subtle blur) to 64 (high blur). By default, the property is set to 32. For the most optimal performance, select as small value as you need.

Note: This affects to both blur and shadow effects.

Performance note: Causes shader regeneration; do not change this property during animation.

Performance note: Causes a resize of the item; do not change this property during animation.


blurMultiplier : real

This property defines a multiplier for extending the blur radius.

The value ranges from 0.0 (not multiplied) to inf. By default, the property is set to 0.0. Incresing the multiplier extends the blur radius, but decreases the blur quality. This is more performant option for a bigger blur radius than blurMax as it doesn't increase the amount of texture lookups.

Note: This affects to both blur and shadow effects.

Performance note: Causes a resize of the item; do not change this property during animation.


brightness : real

This property defines how much the source brightness is increased or decreased.

The value ranges from -1.0 to 1.0. By default, the property is set to 0.0 (no change).


brightnessEnabled : bool

Enables the brightness effect.

Performance note: Causes shader regeneration; do not change this property during animation.


colorize : real

This property defines how much the source is colorized with the colorizeColor.

The value ranges from 0.0 (no colorized) to 1.0 (fully colorized). By default, the property is set to 0.0 (no change).


colorizeColor : color

This property defines the RGBA color value which is used to colorize the source.

By default, the property is set to Qt.rgba(1.0, 0.0, 0.0, 1.0) (red).


colorizeEnabled : bool

Enables the colorize effect.

Performance note: Causes shader regeneration; do not change this property during animation.


contrast : real

This property defines how much the source contrast is increased or decreased.

The value ranges from -1.0 to 1.0. By default, the property is set to 0.0 (no change).


contrastEnabled : bool

Enables the contrast effect.

Performance note: Causes shader regeneration; do not change this property during animation.


hideSource : bool

When enabled, source item is hidden. This is often preferred when the effect item replaces the source item. Another option is to set the source item's visibility property to false, but that disables also user interaction (for example, events from a MouseArea). Therefore, hiding the the source item may be preferred.

By default, this property is set to true.


maskEnabled : bool

Enables the mask effect.

Performance note: Causes shader regeneration; do not change this property during animation.


maskInverted : bool

This property switches the mask to the opposite side; instead of masking away the content outside maskThresholdLow and maskThresholdUp, content between them will get masked away.

By default, the property is set to false.

Performance note: Causes shader regeneration; do not change this property during animation.


maskSource : var

Source item for the mask effect. Should point to ShaderEffectSource, item with layer.enabled set to true, or to an item that can be directly used as a texture source (e.g. Image). The alpha channel of the source item is used for masking.


maskSpreadLow : real

This property defines the smoothness of the mask edges near the maskThresholdLow. Setting higher spread values softens the transition from the transparent mask pixels towards opaque mask pixels by adding interpolated values between them.

The value ranges from 0.0 (sharp mask edge) to 1.0 (smooth mask edge). By default, the property is set to 0.0.


maskSpreadUp : real

This property defines the smoothness of the mask edges near the maskThresholdUp. Using higher spread values softens the transition from the transparent mask pixels towards opaque mask pixels by adding interpolated values between them.

The value ranges from 0.0 (sharp mask edge) to 1.0 (smooth mask edge). By default, the property is set to 0.0.


maskThresholdLow : real

This property defines a lower threshold value for the mask pixels. The mask pixels that have an alpha value below this property are used to completely mask away the corresponding pixels from the source item. The mask pixels that have a higher alpha value are used to alphablend the source item to the display.

The value ranges from 0.0 (alpha value 0) to 1.0 (alpha value 255). By default, the property is set to 0.0.


maskThresholdUp : real

This property defines an upper threshold value for the mask pixels. The mask pixels that have an alpha value below this property are used to completely mask away the corresponding pixels from the source item. The mask pixels that have a higher alpha value are used to alphablend the source item to the display.

The value ranges from 0.0 (alpha value 0) to 1.0 (alpha value 255). By default, the property is set to 1.0.


paddingEnabled : bool

When enabled, item size is padded with paddingRect or automatically based on blurMax. Setting this to false keeps the item size as original, if blur/shadow is not used or the item already contains enough padding to fit all required content after applying the effects.

Performance note: Item size should be as small as possible for optimal performance.

Performance note: Causes a resize of the item; do not change this property during animation.


paddingRect : rect

Set this to increase item size manually so that blur and/or shadows will fit. If paddingEnabled is enabled and paddingRect is not set, the item is padded to fit maximally blurred item based on blurMax. When enabling the shadow, the padding rect typically needs to take shadowHorizontalOffset and shadowVerticalOffset into account.

Performance note: Item size should be as small as possible for optimal performance.

Performance note: Causes a resize of the item; do not change this property during animation.


saturation : real

This property defines how much the source saturation is increased or decreased.

The value ranges from -1.0 (totally desaturated) to inf. By default, the property is set to 0.0 (no change).


saturationEnabled : bool

Enables the saturation effect.

Performance note: Causes shader regeneration; do not change this property during animation.


shadowBlur : real

This property defines how much blur (radius) is applied to the shadow.

The value ranges from 0.0 (no blur) to 1.0 (full blur). By default, the property is set to 1.0. The amount of full blur is affected by blurMax and blurMultiplier.

Performance note: The most optimal way to reduce shadow blurring is to make blurMax smaller (if it isn't needed for item blur). Just remember to not adjust blurMax during animations.


shadowColor : color

This property defines the RGBA color value which is used to colorize the shadow. It is useful for example when a shadow is used for simulating a glow effect.

By default, the property is set to Qt.rgba(0.0, 0.0, 0.0, 1.0) (black).


shadowEnabled : bool

Enables the shadow effect.

Performance note: Causes shader regeneration; do not change this property during animation.


shadowHorizontalOffset : real

This property defines the horizontal offset of the shadow from the item center.

The value ranges from -inf to inf. By default, the property is set to 10.0.

Note: When moving shadow position away from center and adding shadowBlur, you possibly also need to increase the paddingRect accordingly if you want the shadow to not be clipped.


shadowOpacity : real

This property defines the opacity of the drop shadow.

The value ranges from 0.0 (fully transparent) to 1.0 (fully opaque). By default, the property is set to 1.0.


shadowScale : real

This property defines the scale of the shadow. Scaling is applied from the center of the item.

The value ranges from 0 to inf. By default, the property is set to 1.0.

Note: When increasing the shadowScale, you possibly also need to increase the paddingRect accordingly to avoid the shadow from being clipped.


shadowVerticalOffset : real

This property defines the vertical offset of the shadow from the item center.

The value ranges from -inf to inf. By default, the property is set to 10.0.

Note: When moving shadow position away from center and adding shadowBlur, you possibly also need to increase the paddingRect accordingly if you want the shadow to not be clipped.


source : var

Source item for the effect. This does not need to be ShaderEffectSource or have layer.enabled set to true as QuickMultiEffect will internally generate a ShaderEffectSource as the texture source.


Available under certain Qt licenses.
Find out more.