Back to Qt.io
Contact Us Blog Download Qt

MultiEffect QML Type

항목에 후처리 효과를 적용합니다. 더 보기...

Import Statement: import QtQuick.Effects
Inherits:

Item

속성

신호

상세 설명

Qt 5에서 더 이상 사용되지 않는 Qt Graphical Effects 의 후속인 MultiEffect 유형은 source 항목에 후처리 효과를 적용합니다. Qt Graphical Effects 모듈과 비교했을 때 멀티이펙트는 여러 효과(블러, 그림자, 색상화 등)를 단일 항목과 셰이더로 결합하여 여러 효과에 더 적합합니다. 여러 가지 셰이더 변형이 있으며 사용된 기능에 따라 가장 최적의 셰이더가 선택됩니다.

멀티이펙트는 가장 일반적인 효과를 위해 특별히 설계되었으며 쉽게 애니메이션을 적용할 수 있습니다. 멀티효과에 필요한 효과가 포함되어 있지 않은 경우 사용자 정의 효과를 구현하려면 Qt Quick Effect Maker. 셰이더 효과에 대한 자세한 내용은 ShaderEffect 참조 문서를 참조하세요.

멀티효과 유형은 소스 항목과 함께 새로운 시각적 항목을 렌더링합니다. 소스 항목에 효과를 적용하려면 새 멀티효과 항목을 소스 항목의 위치에 배치해야 합니다. 소스 항목과 멀티효과 항목이 불투명하지 않으면 두 항목이 모두 표시될 수 있으므로 원하는 효과를 얻지 못할 수 있습니다. 소스 항목을 숨기려면 다음 중 하나를 수행합니다:

  • 소스 항목에 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 속성이 거짓이 되는 점에 유의하세요.

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)는 항상 활성화되어 있으므로 사용해도 오버헤드가 추가되지 않습니다.
  • 셰이더 또는 효과 항목 크기를 변경할 수 있는 속성의 성능 노트를 참조하고 애니메이션 중에는 수정하지 마세요.
  • 멀티효과를 사용하지 않는 경우 백그라운드에서 효과가 렌더링되지 않도록 visible 속성을 false로 설정하는 것을 잊지 마세요.
  • 블러와 그림자는 가장 무거운 효과입니다. 이러한 효과의 경우 blurMax 보다 blurMultiplier 를 늘리고 애니메이션이 적용되는 source 항목을 사용하지 않도록 하여 매 프레임마다 블러를 다시 생성할 필요가 없도록 하세요.
  • 픽셀이 많을수록 GPU의 작업량이 많아지므로 최적의 크기의 QML 요소에 효과를 적용하세요. 전체 배경에 흐림 효과를 적용할 때는 autoPaddingEnabled 거짓으로 설정해야 하며, 그렇지 않으면 효과가 창/화면 "바깥쪽"으로 커집니다.

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 을 생성하면 참을 반환하고 source 항목을 그대로 사용하면 거짓을 반환합니다. 예를 들어 소스가 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)을 가리켜야 합니다. 소스 항목의 알파 채널은 마스킹에 사용됩니다.

마스크소스와 소스의 크기가 다른 경우 마스크소스 이미지가 소스 크기에 맞게 늘어납니다.


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 이 참이고 paddingRect가 설정되지 않은 경우 blurMax 및 blurMultiplier 을 기준으로 최대 흐리게 처리된 항목에 맞게 항목이 패딩됩니다. 그림자를 활성화할 때는 일반적으로 shadowHorizontalOffset 및 shadowVerticalOffset 을 고려하여 이 paddingRect를 적절히 조정해야 합니다.

아래는 그림자가 MultiEffect 항목 내부에 맞도록 autoPaddingEnabled 을 false로 설정하여 paddingRect를 조정하는 예시입니다.

성능 참고: 최적의 성능을 위해 아이템 크기는 가능한 한 작게 설정해야 합니다.

성능 참고: 항목의 크기가 조정되므로 애니메이션 중에는 이 속성을 변경하지 마세요.

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 도 적절히 늘려야 할 수 있습니다.


그림자 수직 오프셋: 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도 참조하세요 .


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