MultiEffect QML Type

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

Import Statement:	`import QtQuick.Effects`
Inherits:	Item

상속된 멤버를 포함한 모든 멤버 목록

속성

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의 Qt Graphical 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 ` 항목의 사용을 피하여 매 프레임마다 블러를 다시 생성할 필요가 없도록 하십시오.
픽셀 수가 많을수록 GPU의 부하가 커지므로, 효과는 최적의 크기로 조정된 QML 요소에 적용하십시오. 배경 전체에 블러 효과를 적용할 때는 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 요소이거나 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로 설정하여 그림자가 MultiEffect 항목 내부에 맞도록 paddingRect를 조정하는 예시입니다.

paddingRect 값을 비교한 그림자가 있는 두 개의 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.

MultiEffect QML Type

속성

신호

상세 설명

사용 예시

성능

속성 설명서

autoPaddingEnabled : bool

blur : real

blurEnabled : bool

blurMax : int

blurMultiplier : real

brightness : real

colorization : real

colorizationColor : color

contrast : real

fragmentShader : string [read-only]

hasProxySource : bool [read-only]

itemRect : rect [read-only]

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 [read-only]

신호 문서

shaderChanged()

fragmentShader : string `[read-only]`

hasProxySource : bool `[read-only]`

itemRect : rect `[read-only]`

vertexShader : string `[read-only]`