QCanvasCustomBrush Class

상세 설명

QCanvasCustomBrush는 사용자 정의 버텍스 및/또는 프래그먼트 셰이더를 사용하는 획/채우기 브러시입니다.

이러한 셰이더는 Qt Quick ShaderEffect 셰이더와 마찬가지로 Vulkan 스타일의 GLSL로 작성되어야 합니다. 이 셰이더에는 항상 "customfrag.glsl" 또는 "customvert.glsl" 중 하나를 포함한 QC_INCLUDE 문이 포함되어야 합니다. 이를 통해 유니폼 블록, 이미지 및 폰트 텍스처, 그리고 몇 가지 보조 함수를 사용할 수 있습니다.

iTime 는 내장 유니폼 블록에서 흔히 사용되는 멤버의 예시입니다. ` true `를 사용하여 ` setAnimationRunning()`를 호출하면 이 값이 매 프레임마다 자동으로 업데이트되며, 이를 통해 애니메이션 콘텐츠를 구동할 수 있습니다.

내장 셰이더 입력, 유니폼 및 보조 함수

QC_INCLUDE 문은 표준 전처리기 지시어가 아닙니다. 이 문은 셰이더가 일반 셰이더 컴파일 파이프라인으로 전달되기 전, 빌드 시점에 qt_add_custom_brush_shaders()에 의해 처리됩니다. 이 문은 셰이더 입력 및 출력, 텍스처 샘플러, 공유 유니폼 블록, 그리고 프래그먼트 셰이더의 경우 일련의 헬퍼 함수를 선언하는 GLSL 소스 코드 블록으로 대체됩니다. 버텍스 셰이더에서는 ` "customvert.glsl" `를, 프래그먼트 셰이더에서는 ` "customfrag.glsl" `를 사용하십시오.

즉, 사용자 정의 브러시 셰이더는 이러한 입력, 출력, 샘플러 또는 유니폼을 직접 선언하지 않으며, 이 모든 것은 ` QC_INCLUDE ` 문에 의해 제공됩니다.

버텍스 셰이더 인터페이스

"customvert.glsl" 를 포함하는 버텍스 셰이더에는 다음과 같은 입력 및 출력이 선언됩니다:

• in vec2 vertex - 캔버스 좌표계에서의 정점 위치.
• in vec2 tcoord - 정점과 연관된 텍스처 좌표.
• out vec2 texCoord - 프래그먼트 셰이더로 전달됩니다. 일반적으로 ` tcoord`로 설정됩니다.
• out vec2 fragCoord - 프래그먼트 셰이더로 전달됩니다. 일반적으로 ` vertex`로 설정됩니다.

또한, 다음과 같은 변환 관련 유니폼을 사용할 수 있습니다:

• vec4 viewRect - 뷰포트 사각형: (x, y, width, height) 형식입니다.
• int ndcIsYDown - 일부 그래픽 API의 경우처럼 정규화된 장치 좌표계의 Y축이 아래쪽을 향할 때 0이 아닌 값을 가집니다. ` gl_Position`를 계산할 때 이 점을 고려해야 합니다.
• mat3 vertMatrix - 현재 변환 행렬.

버텍스 셰이더는 ` gl_Position`를 작성해야 하며, ` texCoord `와 ` fragCoord `를 프래그먼트 단계로 전달해야 합니다.

일반적인 버텍스 셰이더는 다음과 같습니다:

#version 440

QC_INCLUDE "customvert.glsl"

void main()
{
    texCoord = tcoord;
    fragCoord = vertex;
    vec2 v = (vertMatrix * vec3(vertex, 1.0)).xy;
    if (ndcIsYDown != 0)
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           -1.0 + 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
    else
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           1.0 - 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
}

프래그먼트 셰이더 인터페이스

"customfrag.glsl" 를 포함하는 프래그먼트 셰이더에는 다음과 같은 입력 및 출력이 선언되어 있습니다:

• in vec2 texCoord - 보간된 텍스처 좌표.
• in vec2 fragCoord - 지오메트리와 동일한 좌표계에서 보간된 프래그먼트 위치. 일반적으로 절차적 효과를 구현하는 데 사용됩니다.
• out vec4 fragColor - 결과 프래그먼트 색상. 셰이더가 이 값을 출력해야 합니다. 예상되는 출력 값은 사전 곱해진 알파(premultiplied alpha)를 사용합니다.

사용 가능한 텍스처 샘플러는 두 가지입니다:

• sampler2D tex - 이미지 텍스처.
• sampler2D fontTex - 글리프의 부호 있는 거리 필드를 포함하는 폰트 텍스처. 브러시를 사용하여 텍스트를 채울 때 관련이 있습니다.

편의 상수 TAU (2 * pi와 동일) 및 SQRT2 도 정의되어 있습니다.

공통 유니폼

QC_INCLUDE 를 사용하는 버텍스 셰이더와 프래그먼트 셰이더 모두 공유 유니폼 블록에 접근할 수 있습니다. 가장 일반적으로 사용되는 멤버는 다음과 같습니다:

• float iTime - isAnimationRunning()이 true 인 동안 매 프레임마다 업데이트되는 시간 값(초 단위). 애니메이션 구동에 사용합니다. setAnimationRunning()을 참조하십시오.
• vec4 data1, vec4 data2, vec4 data3, vec4 data4 - 셰이더에 노출되는 사용자 정의 데이터입니다. C++에서 setData1(), setData2(), setData3(), setData4()을 통해 이를 설정합니다.
• float globalAlpha - 페인터의 현재 전역 불투명도입니다. 프래그먼트 셰이더는 일반적으로 fragColor 값에 이 값을 곱해야 합니다.
• vec4 colorEffects - 활성화된 색상 효과 매개변수입니다. 일반적으로 직접 액세스하기보다는 applyColorEffects()를 통해 적용됩니다.
• float fontAlphaMin, float fontAlphaMax - 글리프의 앤티앨리어싱에 사용될 부호 있는 거리 필드 임계값입니다.

프래그먼트 셰이더 헬퍼 함수

프래그먼트 셰이더 include 파일은 다음과 같은 보조 함수를 제공합니다:

• float clipMask() - 현재 프래그먼트에 대한 클립(가위) 커버리지를 [0, 1] 범위로 반환합니다. 페인터의 클리핑을 반영하려면 fragColor 에 이 값을 곱해야 합니다.
• float antialiasingAlpha() - ` texCoord`에서 파생된 [0, 1] 범위의 앤티앨리어싱 커버리지를 반환합니다. ` fragColor `에 이 값을 곱하면 앤티앨리어싱이 적용된 에지를 얻을 수 있습니다.
• float sdfFontAlphaRaw() - fontTex 에서 texCoord 위치로 샘플링된, 앤티앨리어싱이 적용되지 않은 원시 부호 있는 거리 필드 값을 반환합니다. 필요에 따라 smoothstep() 를 수동으로 적용하십시오.
• float sdfFontAlpha() - fontTex 의 texCoord 위치에서 샘플링된 글리프 알파를 반환하며, fontAlphaMin 및 fontAlphaMax 에 기반하여 기본 안티앨리어싱이 적용됩니다.
• void applyColorEffects(inout vec4 color) - 활성화된 대비, 밝기 및 채도 효과를 color 에 그대로 적용합니다.

일반적인 프래그먼트 셰이더는 fragColor 를 계산하고, 이를 globalAlpha 와 곱한 뒤, 선택적으로 클리핑 및 앤티앨리어싱을 지원하기 위해 clipMask() 및 antialiasingAlpha() 와 곱한 다음, 마지막으로 applyColorEffects()를 호출합니다.

텍스트가 포함된 경우에는 sdfFontAlpha() 도 고려해야 합니다. 예를 들어:

#version 440

QC_INCLUDE "customfrag.glsl"

void main()
{
    float a = 0.6 + 0.2 * sin(0.1 * fragCoord.x + 4.0 * iTime);
    vec4 color = vec4(a, a, a, 1.0);
    fragColor = sdfFontAlpha() * globalAlpha * color;
    applyColorEffects(fragColor);
}

프로젝트에 셰이더 추가하기

QCanvasCustomBrush와 함께 사용되는 셰이더는 반드시 Qt Canvas Painter 패키지에서 제공하는 qt_add_custom_brush_shaders CMake 함수를 통해 애플리케이션 프로젝트에 추가되어야 합니다. 이 함수는 빌드 시점에 추가적인 전처리를 수행한 후, 내부적으로 표준 qt_add_shaders() 를 호출합니다.

예를 들어:

qt_add_custom_brush_shaders(app "app_custombrush_shaders"
    PREFIX
        "/shaders"
    FILES
        brush1.frag
)

브러시 사용

실행 시, 생성된 ` .qsb ` 파일은 다음과 같이 사용할 수 있습니다:

QCanvasCustomBrush customBrush(":/shaders/brush1.frag.qsb"));
customBrush.setAnimationRunning(true); // iTime updates automatically
// expose custom data to the shader in data1
customBrush.setData1(QVector4D(1.0, 2.0, 3.0, 4.0));

그런 다음 QCanvasCustomBrush를 채우기(fill)에 사용할 수 있습니다. 예를 들면 다음과 같습니다:

painter->setFillStyle(customBrush);

CMake 함수에 대한 자세한 내용은 qt_add_custom_brush_shaders를 참조하고, Qt에서 크로스 플랫폼 셰이더 코드를 다루는 방법에 대해서는 Qt Shader Tools 모듈 문서를 참조하십시오.