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에서 이펙트는 종종 QML에 문자열로 임베드된 GLSL(OpenGL Shading Language) 소스 코드의 형태로 제공되었습니다. 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 입력에는 유니폼과 버텍스 입력의 두 가지 유형이 있습니다.

다음 입력은 미리 정의되어 있습니다:

• 위치 0 - 버텍스 위치, 왼쪽 상단 버텍스는 위치 (0, 0), 오른쪽 하단 (width, height)을 갖는 vec4 qt_Vertex.
• 위치 1 - 텍스처 좌표, 왼쪽 상단 좌표는 (0, 0), 오른쪽 하단 (1, 1)인 vec2 qt_MultiTexCoord0. supportsAtlasTextures 이 참이면 좌표는 대신 아틀라스 내 위치를 기준으로 합니다.

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

• mat4 qt_Matrix - 결합된 변환 행렬, 루트 항목에서 이 셰이더 이펙트로의 행렬의 곱, 직교 투영입니다.
• float qt_Opacity - 결합된 불투명도, 루트 항목에서 이 셰이더 이펙트로의 불투명도의 곱입니다.

또한 GLSL 유형에 매핑할 수 있는 모든 프로퍼티를 셰이더에서 사용할 수 있습니다. 다음 목록은 프로퍼티가 매핑되는 방법을 보여줍니다:

• 부울, 정수, qreal -> 부울, 정수, 실수 - 셰이더의 유형이 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 -> 샘플러2D - 원점은 왼쪽 상단 모서리에 있으며 색상 값은 미리 곱해집니다. 텍스처는 이미지 항목의 fillMode를 제외하고 그대로 제공됩니다. fillMode를 포함하려면 ShaderEffectSource 또는 Image::layer::enabled.
• ShaderEffectSource -> 샘플러2D - 원점이 왼쪽 상단 모서리에 있고 색상 값이 미리 곱해집니다.

샘플러는 여전히 셰이더 코드에서 별도의 균일 변수로 선언됩니다. 셰이더는 균일 블록을 위해 예약되어 있으므로 0 을 제외하고는 바인딩 포인트를 자유롭게 선택할 수 있습니다.

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

QML 씬 그래프 백엔드는 텍스처 아틀라스에서 텍스처를 할당하도록 선택할 수 있습니다. 아틀라스에 할당된 텍스처가 셰이더이펙트로 전달되면 기본적으로 텍스처 아틀라스에서 독립형 텍스처로 복사되므로 텍스처 좌표가 0에서 1에 걸쳐 있고 예상되는 랩 모드를 얻을 수 있습니다. 그러나 이렇게 하면 메모리 사용량이 증가합니다. 텍스처 복사를 방지하려면 qt_MultiTexCoord0을 사용하는 단순 셰이더에 supportsAtlasTextures 을 설정하거나 각 "균일 샘플러2D <이름>"에 대해 텍스처의 정규화된 소스 직사각형이 할당되는 "균일 vec4 qt_SubRect_<이름>"을 선언합니다. 독립형 텍스처의 경우 소스 사각형은 [0, 1]x[0, 1]입니다. 아틀라스 내 텍스처의 경우 소스 사각형은 텍스처가 저장된 텍스처 아틀라스의 일부에 해당합니다. 텍스처 아틀라스 내에서 "소스"라는 텍스처의 텍스처 좌표를 계산하는 올바른 방법은 "qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0"입니다.

fragmentShader 의 출력을 미리 곱해야 합니다. blending 을 활성화하면 소스 오버 블렌딩이 사용됩니다. 그러나 알파 채널에 0을 출력하여 가산 블렌딩을 수행할 수 있습니다.

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 에 qsb 툴로 처리하여 .qsb 파일을 생성하는 Vulkan 스타일 GLSL 코드가 포함되어 있다고 가정합니다.

#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 구현은 실제로는 기본 내장 버텍스 셰이더에 의존하면서 조각 셰이더만 제공하고자 할 것입니다.

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

기본 조각 셰이더는 버텍스 셰이더에서 텍스처 좌표를 위치 0 에서 vec2 qt_TexCoord0 로 전달할 것으로 예상하고 바인딩 지점 1 에서 source 라는 샘플러2D에서 샘플링합니다.

셰이더 이펙트 및 아이템 레이어

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는 각 모서리마다 하나씩 4개의 버텍스로 구성됩니다. 페이지 컬과 같은 비선형 버텍스 변환의 경우 mesh 해상도를 지정하여 버텍스의 미세한 격자를 지정할 수 있습니다.

Qt 5에서 마이그레이션

셰이더 효과 항목이 있는 Qt 5 애플리케이션의 경우 Qt 6으로 마이그레이션해야 합니다:

• 셰이더 코드를 별도의 .vert 및 .frag 파일로 이동합니다,
• 셰이더를 벌칸 호환 GLSL로 업데이트합니다,
• qsb 툴을 실행합니다,
• 결과물인 .qsb 파일을 Qt 리소스 시스템과 함께 실행 파일에 포함시킵니다,
• 그리고 vertexShader 및 fragmentShader 속성에서 파일을 참조합니다.

Qt Shader Tools 모듈에 설명된 대로 빌드 시 CMake가 qsb 도구를 호출하도록 함으로써 이러한 단계 중 일부를 자동화할 수 있습니다. 자세한 정보와 예제는 Qt Shader Tools 빌드 시스템 통합을 참조하십시오.

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

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부터 시작하는 위치를 지정하는 것이 안전합니다.
• 버텍스 셰이더 입력의 경우, 버텍스 위치(원래 이름은 qt_Vertex)에 대한 위치 0 와 텍스처 좌표(원래 이름은 qt_MultiTexCoord0)에 대한 위치 1 만 ShaderEffect에서 사용할 수 있습니다.
• 버텍스 셰이더 출력과 프래그먼트 셰이더 입력은 셰이더 코드에서 정의할 수 있습니다. 프래그먼트 셰이더는 위치 0에 vec4 출력이 있어야 합니다(일반적으로 fragColor 이라고 함). 이식성을 극대화하려면 버텍스 출력과 프래그먼트 입력은 동일한 위치 번호와 동일한 이름을 사용해야 합니다. 프래그먼트 셰이더만 지정하는 경우, 텍스처 좌표는 위의 예제 코드 조각에서와 같이 위치 0 에서 vec2 qt_TexCoord0 로 내장 버텍스 셰이더에서 전달됩니다.
• 유니폼 블록 외부의 유니폼 변수는 합법적이지 않습니다. 대신 바인딩 포인트가 0 인 균일 블록에 균일 데이터를 선언해야 합니다.
• 유니폼 블록은 std140 한정자를 사용해야 합니다.
• 런타임에 버텍스 및 프래그먼트 셰이더는 바인딩 포인트 0에 바인딩된 동일한 유니폼 버퍼를 얻게 됩니다. 따라서 일반적으로 유니폼 블록 선언은 셰이더 간에 동일해야 합니다. 여기에는 셰이더 중 하나에서 사용되지 않는 멤버도 포함됩니다. 일부 그래픽 API에서는 유니폼 블록이 애플리케이션에 투명하게 기존 구조체 유니폼으로 변환되므로 멤버 이름이 일치해야 합니다.
• 셰이더 중 하나만 제공하는 경우, 내장 셰이더가 유니폼 블록 상단에 qt_Matrix 및 qt_Opacity 을 기대한다는 사실에 주의하세요. (더 정확하게는 각각 오프셋 0과 64에) 일반적으로 항상 블록의 첫 번째와 두 번째 멤버로 포함합니다.
• 예시에서 유니폼 블록은 블록 이름 buf 을 지정합니다. 이 이름은 자유롭게 변경할 수 있지만 셰이더 간에 일치해야 합니다. layout(...) uniform buf { ... } 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 함수를 호출할 때는 texture2D() 대신 texture() 과 같은 최신 GLSL 이름을 따라야 합니다.
• 샘플러는 1부터 시작하는 바인딩 포인트를 사용해야 합니다.
• Qt Quick 예를 들어 multiview 을 활성화하여 렌더링하는 경우(예: 왼쪽 및 오른쪽 눈 콘텐츠가 단일 패스로 생성되는 VR/AR 환경의 3D 씬 렌더링의 일부이므로 ShaderEffect의 셰이더는 이를 염두에 두고 작성해야 합니다. 예를 들어 뷰 수가 2인 경우 2 행렬(qt_Matrix는 두 개의 요소를 가진 mat4 배열)이 필요합니다. 버텍스 셰이더는 gl_ViewIndex 을 고려해야 합니다. 멀티뷰 지원 셰이더 생성에 대한 일반적인 정보는 QSB 매뉴얼의 Multiview 섹션을 참조하십시오.

또한 Item Layers, QSB 매뉴얼 및 Qt Shader Tools 빌드 시스템 통합을참조하십시오 .

프로퍼티 문서