ShaderEffect QML Type

직사각형에 사용자 정의 셰이더를 적용합니다. 더 보기...

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

속성

• blending : bool
• cullMode : enumeration
• fragmentShader : url
• log : string
• mesh : variant
• status : enumeration
• supportsAtlasTextures : bool (since QtQuick 2.4)
• vertexShader : url

상세 설명

ShaderEffect 유형은 사각형에 사용자 정의 vertex 및 fragment (pixel) 셰이더를 적용합니다. 이를 통해 QML 씬에 드롭 섀도우, 블러, 색상 입히기, 페이지 컬링과 같은 효과를 추가할 수 있습니다.

셰이더

Qt 5에서는 효과가 GLSL(OpenGL 셰이딩 언어) 소스 코드 형태로 제공되었으며, 대개 QML에 문자열로 삽입되었습니다. Qt 5.8부터는 로컬 파일이든 Qt 리소스 시스템에 있는 파일이든 상관없이 파일을 참조하는 것도 가능해졌습니다.

Qt 6에서는 Qt Quick 가 Vulkan, Metal, Direct3D 11과 같은 그래픽 API도 지원합니다. 따라서 더 이상 GLSL 소스 문자열을 사용하는 것은 불가능합니다. 대신, 새로운 셰이더 파이프라인은 Vulkan 호환 GLSL 코드를 SPIR-V로 컴파일한 다음, 리플렉션 정보를 수집하여 HLSL, Metal 셰이딩 언어, 다양한 GLSL 버전과 같은 다른 셰이딩 언어로 변환하는 방식을 기반으로 합니다. 결과 자산은 단일 패키지로 묶여, 일반적으로 .qsb 확장자를 가진 파일에 저장됩니다. 이 과정은 오프라인에서 수행되거나 늦어도 애플리케이션 빌드 시점에 완료됩니다. 실행 시, 씬 그래프와 그 기반이 되는 그래픽 추상화 계층은 이러한 ` .qsb ` 파일을 사용합니다. 따라서 ShaderEffect는 인라인 셰이더 코드 대신 Qt 6의 파일(로컬 또는 qrc) 참조를 기대합니다.

vertexShader 및 fragmentShader 속성은 Qt 6의 URL이며, 예를 들어 Image.source 과 매우 유사하게 작동합니다. 다만 ShaderEffect에서는 file 및 qrc 스키마만 지원됩니다. 또한 file 스키마를 생략하여 편리한 방식으로 상대 경로를 지정할 수도 있습니다. 이러한 경로는 컴포넌트( .qml 파일)의 위치를 기준으로 해결됩니다.

셰이더 입력 및 리소스

vertexShader 에는 유니폼(uniforms)과 버텍스 입력(vertex inputs)이라는 두 가지 유형의 입력이 있습니다.

다음과 같은 입력들이 미리 정의되어 있습니다:

• 위치 0의 vec4 qt_Vertex - 정점 위치. 왼쪽 상단 정점의 위치는 (0, 0)이며, 오른쪽 하단 정점의 위치는 (width, height)입니다.
• vec2 qt_MultiTexCoord0 (위치 1) - 텍스처 좌표. 왼쪽 상단 좌표는 (0, 0), 오른쪽 하단은 ( supportsAtlasTextures, )입니다. 가 true인 경우, 좌표는 대신 아틀라스 내의 위치를 기준으로 합니다.

다음과 같은 유니폼이 미리 정의되어 있습니다:

• mat4 qt_Matrix - 결합된 변환 행렬로, 루트 항목에서 이 ShaderEffect까지의 행렬들과 직교 투영 행렬의 곱입니다.
• float qt_Opacity - 결합된 불투명도. 루트 항목에서 이 ShaderEffect에 이르는 불투명도들의 곱입니다.

또한, GLSL 유형에 매핑될 수 있는 모든 속성은 셰이더에서 사용할 수 있습니다. 다음 목록은 속성이 어떻게 매핑되는지 보여줍니다:

• bool, int, qreal -> bool, int, float - 셰이더의 유형이 QML의 유형과 다를 경우, 값이 자동으로 변환됩니다.
• QColor -> vec4 - 색상이 셰이더로 전달될 때, 먼저 사전 곱셈이 수행됩니다. 따라서 예를 들어 Qt.rgba(0.2, 0.6, 1.0, 0.5)는 셰이더에서 vec4(0.1, 0.3, 0.5, 0.5)가 됩니다.
• QRect, QRectF -> vec4 - Qt.rect(x, y, w, h)는 셰이더에서 vec4(x, y, w, h)가 됩니다.
• QPoint, QPointF, QSize, QSizeF -> vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4, 스칼라 값은 w 입니다.
• Image -> sampler2D - 원점은 왼쪽 상단 모서리에 있으며, 색상 값은 미리 곱해진 상태입니다. 텍스처는 Image 항목의 fillMode를 제외하고 있는 그대로 제공됩니다. fillMode를 포함하려면 ShaderEffectSource 또는 Image::layer::enabled를 사용하십시오.
• ShaderEffectSource -> sampler2D - 원점은 왼쪽 상단 모서리에 있으며, 색상 값에는 프리멀티플라이가 적용되어 있습니다.

샘플러는 여전히 셰이더 코드에서 별도의 유니폼 변수로 선언됩니다. 0 는 유니폼 블록 전용이므로 이를 제외하고, 셰이더는 이러한 변수에 대해 어떤 바인딩 지점이라도 자유롭게 선택할 수 있습니다.

일부 셰이딩 언어와 API에는 이미지와 샘플러 객체를 별도로 구분하는 개념이 있습니다. Qt Quick 는 SPIR-V에서 지원하는 대로 셰이더 내에서 항상 결합된 이미지-샘플러 객체를 사용합니다. 따라서 ShaderEffect에 제공되는 셰이더는 항상 layout(binding = 1) uniform sampler2D tex; 형식의 샘플러 선언을 사용해야 합니다. 기본이 되는 추상화 계층과 셰이더 파이프라인은 애플리케이션에 투명하게 처리되면서, 지원되는 모든 API 및 셰이딩 언어에서 이 기능이 작동하도록 처리합니다.

QML 씬 그래프 백엔드는 텍스처를 텍스처 아틀라스에 할당할 수 있습니다. 아틀라스에 할당된 텍스처가 ShaderEffect로 전달되면, 기본적으로 텍스처 아틀라스에서 독립된 텍스처로 복사되어 텍스처 좌표가 0에서 1까지 범위를 가지게 되며, 예상되는 랩 모드를 얻을 수 있습니다. 그러나 이로 인해 메모리 사용량이 증가합니다. 텍스처 복사를 피하려면, qt_MultiTexCoord0을 사용하는 단순 셰이더의 경우 supportsAtlasTextures 를 설정하거나, 각 "uniform sampler2D <name>"에 대해 텍스처의 정규화된 소스 사각형이 할당될 "uniform vec4 qt_SubRect_<name>"을 선언하십시오. 단독 텍스처의 경우, 소스 직사각형은 [0, 1]x[0, 1]입니다. 텍스처 아틀라스 내의 텍스처에 대해서는, 소스 직사각형이 텍스처 아틀라스에서 해당 텍스처가 저장된 부분에 해당합니다. 텍스처 아틀라스 내에서 "source"라고 불리는 텍스처의 텍스처 좌표를 계산하는 올바른 방법은 "qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0"입니다.

fragmentShader 의 출력은 사전 곱셈(premultiplied) 처리되어야 합니다. blending 가 활성화된 경우, 소스 오버(source-over) 블렌딩이 사용됩니다. 그러나 알파 채널에 0을 출력함으로써 가산 블렌딩(additive blending)을 구현할 수 있습니다.

import QtQuick 2.0

Rectangle {
    width: 200; height: 100
    Row {
        Image { id: img;
                sourceSize { width: 100; height: 100 } source: "qt-logo.png" }
        ShaderEffect {
            width: 100; height: 100
            property variant src: img
            vertexShader: "myeffect.vert.qsb"
            fragmentShader: "myeffect.frag.qsb"
        }
    }
}

이 예제는 myeffect.vert 및 myeffect.frag 에 Vulkan 스타일의 GLSL 코드가 포함되어 있으며, 이 코드가 qsb 도구를 통해 처리되어 .qsb 파일을 생성한다고 가정합니다.

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb, vec3(0.344, 0.5, 0.156))), tex.a) * qt_Opacity;
}

셰이더 하나만 사용하는 경우

vertexShader 와 fragmentShader 를 모두 지정해야 하는 것은 아닙니다. 실제로 많은 ShaderEffect 구현체는 기본 제공되는 내장 버텍스 셰이더에 의존하면서 프래그먼트 셰이더만 제공하고자 할 것입니다.

기본 버텍스 셰이더는 텍스처 좌표를 vec2 qt_TexCoord0 로 지정하여 0 위치에서 프래그먼트 셰이더로 전달합니다.

기본 프래그먼트 셰이더는 텍스처 좌표가 버텍스 셰이더로부터 vec2 qt_TexCoord0 로 위치 0 에 전달될 것으로 예상하며, 바인딩 지점 1 에서 source 라는 sampler2D를 통해 샘플링합니다.

ShaderEffect 및 아이템 레이어

ShaderEffect 유형은 layered items 와 결합할 수 있습니다.

효과가 비활성화된 레이어

효과가 활성화된 레이어

Item { id: layerRoot layer.enabled: true layer.effect: ShaderEffect { fragmentShader: "effect.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D source; void main() { vec4 p = texture(source, qt_TexCoord0); float g = dot(p.xyz, vec3(0.344, 0.5, 0.156)); fragColor = vec4(g, g, g, p.a) * qt_Opacity; }

여러 레이어 항목을 결합하는 것도 가능합니다:

Rectangle { id: gradientRect; width: 10 height: 10 gradient: Gradient { GradientStop { position: 0; color: "white" } GradientStop { position: 1; color: "steelblue" } } visible: false; // should not be visible on screen. layer.enabled: true; layer.smooth: true } Text { id: textItem font.pixelSize: 48 text: "Gradient Text" anchors.centerIn: parent layer.enabled: true // This item should be used as the 'mask' layer.samplerName: "maskSource" layer.effect: ShaderEffect { property var colorSource: gradientRect; fragmentShader: "mask.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D colorSource; layout(binding = 2) uniform sampler2D maskSource; void main() { fragColor = texture(colorSource, qt_TexCoord0) * texture(maskSource, qt_TexCoord0).a * qt_Opacity; }

기타 참고 사항

기본적으로 ShaderEffect는 네 개의 정점(각 모서리마다 하나씩)으로 구성됩니다. 페이지 말림과 같은 비선형 정점 변환의 경우, ` mesh ` 해상도를 지정하여 정점의 미세한 격자를 설정할 수 있습니다.

Qt 5에서 마이그레이션

ShaderEffect 항목을 사용하는 Qt 5 애플리케이션의 경우, Qt 6으로의 마이그레이션은 다음 단계를 포함합니다:

• 셰이더 코드를 별도의 ` .vert ` 및 ` .frag ` 파일로 분리하고,
• 셰이더를 Vulkan 호환 GLSL로 업데이트하고,
• 해당 파일들에 대해 qsb 도구를 실행하고,
• 생성된 .qsb 파일을 Qt 리소스 시스템을 통해 실행 파일에 포함시키고,
• vertexShader 및 fragmentShader 속성에서 해당 파일을 참조하는 과정을 거칩니다.

Qt XML Shader Tools 모듈에 설명된 바와 같이, 빌드 시점에 CMake가 qsb 도구를 호출하도록 설정하여 이러한 단계 중 일부를 자동화할 수 있습니다. 자세한 내용과 예제는 qt_add_shaders() 를 참조하십시오.

셰이더 코드를 업데이트할 때 일반적으로 필요한 변경 사항에 대한 개요는 다음과 같습니다.

attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 coord;
uniform highp mat4 qt_Matrix;
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

변환 과정은 주로 GL_KHR_vulkan_glsl과 호환되도록 코드를 업데이트하는 것을 포함합니다. Qt Quick 는 GLSL과 Vulkan이 제공하는 기능의 일부만 사용하므로, 일반적인 ShaderEffect 셰이더의 변환 과정은 대개 간단하다는 점을 유의해야 합니다.

• version 지시문은 440 또는 450 로 명시해야 하지만, GL_KHR_vulkan_glsl 확장은 GLSL 140 이상용으로 작성되었기 때문에 다른 GLSL 버전을 지정해도 작동할 수 있습니다.
• 입력 및 출력에는 최신 GLSL 키워드인 in 및 out 을 사용해야 합니다. 또한, 위치를 지정해야 합니다. 입력 및 출력 위치 네임스페이스는 서로 분리되어 있으므로, 양쪽 모두 0부터 시작하는 위치를 할당해도 안전합니다.
• 버텍스 셰이더 입력의 경우, ShaderEffect를 사용할 때 가능한 유일한 옵션은 버텍스 위치용 위치 0 (기존 명칭: qt_Vertex)와 텍스처 좌표용 위치 1 (기존 명칭: qt_MultiTexCoord0)뿐입니다.
• 버텍스 셰이더의 출력과 프래그먼트 셰이더의 입력은 셰이더 코드에서 정의할 수 있습니다. 프래그먼트 셰이더는 위치 0에 vec4 출력(일반적으로 fragColor 라고 함)을 반드시 가져야 합니다. 이식성을 극대화하려면 버텍스 출력과 프래그먼트 입력은 위치 번호와 이름을 모두 동일하게 사용해야 합니다. 프래그먼트 셰이더만 지정할 경우, 위의 예제 코드 조각에서 볼 수 있듯이 텍스처 좌표는 내장 버텍스 셰이더에서 vec2 qt_TexCoord0 로 위치 0 에 전달됩니다.
• 유니폼 블록 외부에 있는 유니폼 변수는 허용되지 않습니다. 대신, 유니폼 데이터는 바인딩 포인트 0 를 사용하여 유니폼 블록 내에서 선언되어야 합니다.
• 유니폼 블록은 std140 한정자를 사용해야 합니다.
• 실행 시, 버텍스 셰이더와 프래그먼트 셰이더는 바인딩 포인트 0에 바인딩된 동일한 유니폼 버퍼를 받게 됩니다. 따라서 일반적인 규칙으로, 셰이더 간에 유니폼 블록 선언은 동일해야 합니다. 여기에는 한쪽 셰이더에서 사용되지 않는 멤버도 포함됩니다. 일부 그래픽 API에서는 애플리케이션에 노출되지 않은 채 유니폼 블록이 기존의 struct 유니폼으로 변환되므로, 멤버 이름은 일치해야 합니다.
• 셰이더 중 하나만 제공할 때는, 내장 셰이더가 유니폼 블록의 맨 위에 qt_Matrix 와 qt_Opacity 를 기대한다는 점에 유의해야 합니다. (더 정확하게는 각각 오프셋 0과 64 위치에 있습니다.) 일반적인 규칙으로, 이 두 요소를 항상 블록의 첫 번째 및 두 번째 멤버로 포함해야 합니다.
• 이 예제에서 유니폼 블록은 블록 이름 buf 을 지정합니다. 이 이름은 자유롭게 변경할 수 있지만, 셰이더 간에는 일치해야 합니다. layout(...) uniform buf { ... } instance_name; 과 같은 인스턴스 이름을 사용하는 것은 선택 사항입니다. 인스턴스 이름을 지정할 경우, 멤버에 대한 모든 액세스에는 instance_name을 접두사로 붙여야 합니다.

varying highp vec2 coord;
uniform lowp float qt_Opacity;
uniform sampler2D src;
void main() {
    lowp vec4 tex = texture2D(src, coord);
    gl_FragColor = vec4(vec3(dot(tex.rgb,
                        vec3(0.344, 0.5, 0.156))),
                             tex.a) * qt_Opacity;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb,
                     vec3(0.344, 0.5, 0.156))),
                          tex.a) * qt_Opacity;
}

• 정밀도 한정자(lowp, mediump, highp)는 현재 사용되지 않습니다.
• 내장 GLSL 함수를 호출할 때는 최신 GLSL 명명 규칙을 따라야 하며, 특히 texture2D() 대신 texture() 을 사용해야 합니다.
• 샘플러는 1부터 시작하는 바인딩 포인트를 사용해야 합니다.
• 예를 들어, 왼쪽과 오른쪽 눈의 콘텐츠가 단일 패스에서 생성되는 VR/AR 환경에서 3D 씬 렌더링의 일부로 Qt Quick 가 multiview 가 활성화된 상태에서 렌더링되는 경우, ShaderEffect의 셰이더는 이 점을 고려하여 작성되어야 합니다. 예를 들어 뷰 수가 2인 경우, 2 개의 행렬이 생성됩니다(qt_Matrix는 두 개의 요소를 가진 mat4 배열입니다). 버텍스 셰이더는 gl_ViewIndex 를 고려해야 합니다. 멀티뷰를 지원하는 셰이더를 만드는 방법에 대한 일반적인 정보는 QSB 매뉴얼의 ‘ Multiview ’ 섹션을 참조하십시오.

Item Layers, QSB 매뉴얼 및 qt_add_shaders도 참조하십시오 .

속성 설명서

blending : bool

이 속성이 true인 경우, ‘ fragmentShader ’의 출력 결과가 ‘source-over’ 블렌드 모드를 사용하여 배경과 혼합됩니다. false인 경우 배경은 무시됩니다. 블렌딩은 성능을 저하시키므로, 블렌딩이 필요하지 않을 때는 이 속성을 false로 설정해야 합니다. 기본값은 true입니다.

cullMode : enumeration

이 속성은 항목의 어느 면이 표시되어야 하는지를 정의합니다.

기본값은 NoCulling입니다.

fragmentShader : url

이 속성은 전처리된 프래그먼트 셰이더 패키지가 포함된 파일에 대한 참조를 포함하며, 일반적으로 확장자는 .qsb 입니다. 이 값은 Image와 같은 다른 QML 유형과 마찬가지로 URL 로 처리됩니다. 이 값은 로컬 파일이어야 하거나, qrc 스키마를 사용하여 Qt 리소스 시스템을 통해 임베드된 파일에 접근해야 합니다. URL은 절대 경로이거나 컴포넌트의 URL을 기준으로 한 상대 경로일 수 있습니다.

vertexShader도 참조하십시오 .

log : string [read-only]

이 속성은 셰이더를 마지막으로 컴파일하려고 시도했을 때 발생한 경고 및 오류 로그를 보관합니다. 이 속성은 ` status `가 ‘Compiled’ 또는 ‘Error’로 설정될 때 동시에 업데이트됩니다.

status도 참조하십시오 .

mesh : variant

이 속성은 ShaderEffect 를 그리는 데 사용되는 메쉬를 정의합니다. 이 속성에는 어떤 GridMesh 객체든 지정할 수 있습니다. 이 속성에 크기 값이 할당되면, ShaderEffect 는 해당 값을 mesh resolution 로 설정된 GridMesh 를 암시적으로 사용합니다. 기본적으로 이 속성의 크기는 1x1입니다.

GridMesh도 참조하십시오 .

status : enumeration [read-only]

이 속성은 셰이더의 현재 상태를 나타냅니다.

프래그먼트 또는 버텍스 셰이더 소스 코드를 설정하면 상태가 ‘컴파일되지 않음(Uncompiled)’으로 바뀝니다. 새로운 셰이더 소스 코드로 ‘ ShaderEffect ’가 처음 렌더링될 때 셰이더가 컴파일 및 링크되며, 상태는 ‘컴파일됨(Compiled)’ 또는 ‘오류(Error)’로 업데이트됩니다.

런타임 컴파일을 사용하지 않고 셰이더 속성이 바이트코드가 포함된 파일을 참조하는 경우, 상태는 항상 '컴파일됨'으로 표시됩니다. 셰이더의 내용은(버텍스 입력 요소 및 상수 버퍼 데이터를 파악하기 위한 기본적인 리플렉션을 제외하고) 렌더링 파이프라인의 후반 단계에서야 검사되므로, 잠재적인 오류(레이아웃 또는 루트 시그니처 불일치 등)는 그 이후에야 감지됩니다.

log도 참조하십시오 .

supportsAtlasTextures : bool [since QtQuick 2.4]

이 속성을 true로 설정하면 셰이더 코드가 메시에 상대적인 (0,0)부터 (1,1)까지의 범위를 갖는 qt_MultiTexCoord0에 의존하지 않는지 확인할 수 있습니다. 이 경우 qt_MultiTexCoord0의 범위는 아틀라스 내 텍스처의 위치를 기준으로 결정됩니다. 현재 이 속성은 셰이더의 입력으로 사용되는 샘플러 유니폼이 하나보다 적거나 많을 경우 아무런 영향을 미치지 않습니다.

이는 qt_SubRect_<name> 유니폼을 제공하는 것과는 다른데, 후자는 단일 ` ShaderEffect ` 항목에서 아틀라스의 하나 이상의 텍스처를 그릴 수 있도록 하는 반면, `supportsAtlasTextures`는 아틀라스의 서로 다른 소스 이미지를 사용하는 ` ShaderEffect ` 컴포넌트의 여러 인스턴스를 단일 드로우에서 일괄 처리할 수 있도록 합니다. 두 방법 모두 ShaderEffect 에 의해 참조될 때 텍스처가 아틀라스 밖으로 복사되는 것을 방지합니다.

기본값은 false입니다.

이 속성은 QtQuick 2.4에서 도입되었습니다.

vertexShader : url

이 속성은 전처리된 버텍스 셰이더 패키지가 포함된 파일에 대한 참조를 포함하며, 일반적으로 확장자는 .qsb 입니다. 이 값은 Image와 같은 다른 QML 유형과 마찬가지로 URL 로 처리됩니다. 이 값은 로컬 파일이어야 하거나, qrc 스키마를 사용하여 Qt 리소스 시스템을 통해 임베드된 파일에 접근해야 합니다. URL은 절대 경로이거나 컴포넌트의 URL을 기준으로 한 상대 경로일 수 있습니다.

fragmentShader도 참조하십시오 .