qt_add_shaders

셰이더를 컴파일하고 Qt 리소스에 추가합니다.

이 명령은 Qt6 패키지의 ShaderTools 구성 요소에 정의되어 있으며, 다음 명령으로 불러올 수 있습니다:

find_package(Qt6 REQUIRED COMPONENTS ShaderTools)

사용법

qt_add_shaders(<target> <resource_name>
               PREFIX <path>
               FILES <file,...>
               [BASE <path>]
               [GLSL <version,...>]
               [NOGLSL]
               [HLSL <version,...>]
               [NOHLSL]
               [MSL <version,...>]
               [NOMSL]
               [BATCHABLE]
               [ZORDER_LOC <number>]
               [PERTARGETCOMPILE]
               [TESSELLATION]
               [TESSELLATION_VERTEX_COUNT <count>]
               [TESSELLATION_MODE <mode>]
               [VIEW_COUNT <count>]
               [MULTIVIEW]
               [PRECOMPILE]
               [OPTIMIZED]
               [DEBUGINFO]
               [QUIET]
               [DEFINES <name=value,...>]
               [OUTPUTS <file,...>]
               [ORIGINAL_FILES <file,...>]
               [OUTPUT_TARGETS <variable>]
               [MEDIUMP])

버전 정보가 없는 명령어가 비활성화된 경우, 대신 qt6_add_shaders() 를 사용하십시오. 이 명령어는 본 명령어와 동일한 인자 집합을 지원합니다.

설명

빌드 시점에 FILES 에 나열된 각 셰이더 소스 파일에 대해 qsb 도구를 호출하고, 그 결과로 생성된 .qsb 파일을 PREFIX 에서 지정한 리소스 접두사 아래의 Qt 리소스 시스템에 추가합니다.

생성된 리소스의 이름은 qt_add_resources()와 마찬가지로 resource_name 입니다.

기본적으로 qt_add_shaders 는 다음과 같이 qsb 를 호출합니다:

qsb --glsl "100 es,120,150" --hlsl 50 --msl 12 -o <output>.qsb <input>

이를 통해 SPIR-V(Vulkan 1.0용), GLSL ES 100(OpenGL ES 2.0 이상용), GLSL 120(비코어 프로파일 OpenGL용), GLSL 150(코어 프로파일 OpenGL용), 셰이더 모델 5.0(Direct3D 11.1)용 HLSL, Metal 셰이딩 언어 1.2(Metal)가 포함된 패키지가 생성됩니다.

WebAssembly에서는 기본값이 다음과 같이 변경됩니다:

qsb --glsl "100 es,300 es" -o <output>.qsb <input>

이는 WebGL 1 및 WebGL 2와 호환되는 셰이더를 생성합니다.

원본 셰이더 소스 파일은 애플리케이션 실행 파일에 포함되지 않으며 배포할 필요도 없습니다. glslang 컴파일러에서 발생한 빌드 오류는 빌드 시점에 보고되며, 빌드는 실패합니다. 셰이더 소스 파일의 변경 사항은 다른 소스 파일과 마찬가지로 다음 빌드 시 자동으로 반영됩니다.

셰이더 유형

셰이더의 유형은 파일 확장자로부터 추론됩니다:

• .vert — 버텍스 셰이더
• .tesc — 테셀레이션 제어 셰이더
• .tese — 테셀레이션 평가 셰이더
• .geom — 지오메트리 셰이더
• .frag — 프래그먼트(픽셀) 셰이더
• .comp — 컴퓨트 셰이더

대상 언어 옵션

• GLSL — 쉼표로 구분된 버전 목록에 대한 GLSL 소스 코드를 요청합니다. 예를 들어, 컴퓨트 셰이더는 일반적으로 기본값 대신 "310 es,430" 를 필요로 합니다. es 접미사 앞의 공백은 선택 사항입니다.
• NOGLSL — GLSL 소스 생성을 비활성화합니다. OpenGL을 전혀 대상으로 하지 않는 애플리케이션에 적합합니다.
• HLSL — 지정된 셰이더 모델 버전 목록에 대한 HLSL 소스 코드를 요청합니다. qsb 은 GLSL 스타일의 번호 체계를 사용합니다. 즉, 50 은 셰이더 모델 5.0이고, 51 은 5.1입니다.
• NOHLSL — HLSL 소스 생성을 비활성화합니다. Direct 3D를 전혀 대상으로 하지 않는 애플리케이션에 적합합니다.
• MSL — 지정된 버전에 대한 Metal Shading Language 소스 생성을 요청합니다. 12 은 MSL 1.2에, 20 은 2.0에 해당합니다.
• NOMSL — MSL 소스 생성을 비활성화합니다. Metal을 전혀 대상으로 하지 않는 애플리케이션에 적합합니다.

예시 — OpenGL 3.x 기능을 사용하는 셰이더의 GLSL 버전을 높이는 경우:

qt_add_shaders(exampleapp "res_gl3shaders"
    GLSL "300es,330"
    PREFIX
        "/shaders"
    FILES
        shaders/ssao.vert
        shaders/ssao.frag
        shaders/skybox.vert
        shaders/skybox.frag
)

Qt Quick 옵션

• BATCHABLE — ShaderEffect 또는 QSGMaterialShader 에서 Qt Quick 와 함께 사용되는 버텍스 셰이더에 필수입니다. 프래그먼트 셰이더나 컴퓨트 셰이더에는 영향을 미치지 않습니다. 이 키워드는 .vert 파일에만 적용되므로, 서로 다른 셰이더 유형을 동일한 FILES 목록에 안전하게 혼합할 수 있습니다. qsb 의 -b 인자와 동일합니다.
• ZORDER_LOC — ` BATCHABLE `가 지정되면 기본적으로 ` 7 ` 위치에 추가 버텍스 입력이 삽입됩니다. 기존 입력과 충돌하지 않도록 위치를 변경하려면 이 키워드를 사용하십시오.

테셀레이션 옵션

• TESSELLATION — 셰이더가 테셀레이션 파이프라인에 속함을 나타냅니다. MSL 생성이 비활성화되지 않은 경우에만 버텍스 셰이더에 적용되며, Metal을 대상으로 할 때 해당 셰이더에 대한 특수 처리 및 변환을 활성화합니다.

  이 옵션은 Qt 6.5에서 도입되었습니다.

• TESSELLATION_VERTEX_COUNT — 테셀레이션 제어 단계에서 출력되는 정점 수를 지정합니다. Metal을 대상으로 하는 테셀레이션 평가 셰이더의 경우 필수입니다. 기본값은 ` 3`입니다. 이 값이 제어 단계와 일치하지 않으면 생성된 MSL 코드가 올바르게 작동하지 않습니다.

  이 옵션은 Qt 6.5에서 도입되었습니다.

• TESSELLATION_MODE — 테셀레이션 모드를 지정합니다: "triangles" (기본값) 또는 "quads". FILES 에 테셀레이션 제어 셰이더가 나열된 경우 반드시 설정해야 하며, 테셀레이션 평가 단계와 일치해야 합니다.

  이 옵션은 Qt 6.5에서 도입되었습니다.

다중 뷰 옵션

• VIEW_COUNT — 멀티뷰 렌더링(GL_OVR_multiview2, VK_KHR_multiview, D3D12 뷰 인스턴싱 등)에 사용되는 뷰의 수를 지정합니다. 관련 버텍스 셰이더가 올바른 GLSL 출력을 생성하도록 하려면 이 값을 2 이상으로 설정해야 합니다. VIEW_COUNT 로 설정하면 QSHADER_VIEW_COUNT 전처리기 정의가 삽입되며, 값이 2 이상일 경우 버텍스 셰이더에 #extension GL_EXT_multiview : require 이 자동으로 추가됩니다. 멀티뷰 사용 시 필요한 최소 언어 버전은 GLSL 330 및 300 es, HLSL 61입니다. 멀티뷰를 사용하지 않는 버텍스 셰이더에서는 VIEW_COUNT 설정을 피하고, 대신 별도의 qt_add_shaders() 호출로 그룹화하십시오.

  이 옵션은 Qt 6.7에서 도입되었습니다.

• MULTIVIEW — 멀티뷰가 아닌 셰이더 세트와 뷰 카운트가 2인 셰이더 세트를 모두 생성합니다. 이는 적절한 GLSL/HLSL/MSL/VIEW_COUNT 인수를 사용하여 두 개의 별도 ` qt_add_shaders() ` 호출을 수행하는 것과 동등한 편의 기능입니다. 멀티뷰 변형에 대한 암시적 설정은 GLSL의 경우 330,300es, HLSL의 경우 61, MSL의 경우 21, VIEW_COUNT의 경우 2 입니다. 멀티뷰 변형은 .qsb 파일 이름 뒤에 .mv2qsb 접미사가 추가된 형태로 저장됩니다.

  이 옵션은 Qt 6.8에서 도입되었습니다.

외부 도구 옵션

• PRECOMPILE — Windows에서(HLSL이 비활성화되지 않은 경우), 런타임이 아닌 빌드 시점에 HLSL 소스를 DXBC 바이트코드로 컴파일하기 위해 Windows SDK의 fxc 를 호출합니다. 결과 .qsb 파일에는 원본 HLSL 소스 대신 컴파일된 중간 바이트코드가 포함됩니다. qsb 의 -c 인자와 동일합니다. Windows 이외의 플랫폼에서는 효과가 없습니다.
• OPTIMIZED — Vulkan SDK의 ` spirv-opt `를 호출하여 SPIR-V 바이트코드에 대한 최적화를 수행합니다. ` qsb`의 ` -O ` 인자와 동일합니다.

기타 옵션

• BASE — 생성된 .qsb 파일의 별칭(리소스 내 이름)을 계산하는 데 사용되는 경로 접두사입니다. BASE 가 설정되면 각 출력 경로는 있는 그대로 유지되지 않고 BASE 를 기준으로 상대 경로로 변환됩니다. 이는 qt_add_resources()의 BASE 인자와 유사합니다.
• DEFINES — 셰이더 컴파일 중에 활성화될 매크로를 "name1=value1;name2=value2" 형식으로 정의합니다. 또는 FILES 와 마찬가지로 항목을 줄바꿈으로 구분할 수도 있습니다. 이는 qsb 의 -D 인자와 동일합니다.
• OUTPUTS — 생성된 .qsb 파일 이름이 소스 파일 이름과 달라야 하는 경우(예를 들어, 하나의 셰이더 파일이 DEFINES 로 구분되는 여러 .qsb 파일의 소스로 사용되는 경우), FILES 의 각 항목에 대해 하나의 출력 파일 이름을 지정합니다. 각 이름은 소스 파일 이름에 .qsb 를 추가하는 대신, -o 인수를 통해 qsb 에 전달됩니다.
• ORIGINAL_FILES — .qsb 파일이 FILES 에 있는 것과는 다른 셰이더 소스 파일에 의존해야 하는 경우, 여기에서 FILES 항목당 하나의 항목을 지정하십시오. 이 항목이 존재하면, 해당 ORIGINAL_FILES 항목이 --orig-file 를 통해 CMake 의존성 파일에 기록되며, 기본 add_custom_command() 의 DEPENDS 절에 추가됩니다. 이는 qt_add_shaders() 에 전달된 파일이 중간 생성 자산이고, 최종 .qsb 파일이 원본 소스 파일을 추적해야 할 때 유용합니다.
• PERTARGETCOMPILE — SPIR-V로 컴파일한 후, 대상 언어별로 한 번씩 각각 별도의 출력 언어 버전으로 변환합니다. 이는 기본 단일 패스 방식보다 속도가 느리지만, QSHADER_<LANG>[_VERSION] 전처리기 매크로를 통해 조건부 컴파일을 허용합니다. 이는 qsb 의 -p 인자와 동일합니다.
• DEBUGINFO — SPIR-V에 대한 전체 디버그 정보를 생성하여, RenderDoc과 같은 도구가 파이프라인을 검사하거나 버텍스/프래그먼트 디버깅을 수행할 때 전체 소스 코드를 표시할 수 있도록 합니다. PRECOMPILE 도 설정된 경우, fxc 에 생성된 DXBC 바이트코드에 디버그 정보를 삽입하도록 지시합니다. qsb 의 -g 인자와 동일합니다.
• QUIET — qsb 에서 발생하는 디버그 및 경고 출력을 억제합니다. 치명적인 오류만 출력됩니다. qsb 의 -s 인자와 동일합니다.
• OUTPUT_TARGETS — qt_add_shaders 를 정적 라이브러리와 함께 사용할 경우, 하나 이상의 특수 타깃이 생성됩니다. 변수 이름을 전달하여 해당 타깃을 가져와 추가 처리를 수행할 수 있습니다.
• MEDIUMP — GLSL ES 프래그먼트 셰이더에서 기본값으로 중정밀도 부동소수점 수치를 요청합니다. 비-ES GLSL을 포함한 다른 타깃에는 영향을 미치지 않습니다.

수작업으로 제작된 셰이더 대체

FILES 목록은 .qsb 패키지의 특정 셰이더 변형을 수작업으로 제작한 파일로 대체하기 위한 특수 구문을 지원합니다. 이는 qsb 의 -r 옵션과 동일합니다:

FILES
    "shaders/externalsampler.frag@glsl,100es,shaders/externalsampler_gles.frag"

파일명 뒤에는 @ 로 구분된 대체 사양을 원하는 개수만큼 나열할 수 있습니다. 각 사양은 쉼표로 구분된 셰이딩 언어, 버전 및 읽을 파일을 지정합니다. 파일명이나 디렉터리 경로 내의 @ 문자는 올바르게 처리되며 구문 분석에 영향을 미치지 않습니다. 자세한 내용은 QSB 매뉴얼을 참조하십시오.

예시

기본 사용법

find_package(Qt6 COMPONENTS ShaderTools)

qt6_add_executable(exampleapp main.cpp)

qt6_add_shaders(exampleapp "exampleapp_shaders"
    PREFIX
        "/"
    FILES
        "wobble.frag"
)

이렇게 하면 실행 시점에 :/wobble.frag.qsb 를 사용할 수 있게 됩니다. 원본 wobble.frag 소스 파일은 실행 파일에 포함되지 않습니다.

테셀레이션

버텍스(vertex.vert), 테셀레이션 제어(tess.tesc), 테셀레이션 평가(tess.tese), 프래그먼트(fragment.frag)의 네 단계로 구성된 그래픽 파이프라인을 다음과 같이 설정할 수 있습니다.

버텍스 및 프래그먼트 셰이더는 먼저 컴파일됩니다. ` TESSELLATION `는 버텍스 셰이더에 대한 특수한 Metal 변환을 활성화하며, 테셀레이션에는 OpenGL 4.x 또는 ES 3.2가 필요하기 때문에 GLSL 버전이 상향 조정됩니다.

qt6_add_shaders(project "shaders_tessellation_part1"
    PREFIX
        "/shaders"
    GLSL
        "410,320es"
    TESSELLATION
    FILES
        "vertex.vert"
        "fragment.frag"
)

테셀레이션 셰이더는 별도의 호출에 나열되어 있는데, 이는 해당 셰이더에 NOHLSL 가 필요하기 때문입니다. HLSL 테셀레이션 셰이더는 수동으로 작성하여 삽입해야 합니다. Metal 테셀레이션 매개변수는 명시적으로 지정됩니다.

qt6_add_shaders(project "shaders_tessellation_part2"
    PREFIX
        "/shaders"
    NOHLSL
    GLSL
        "410,320es"
    TESSELLATION_VERTEX_COUNT
        3
    TESSELLATION_MODE
        "triangles"
    FILES
        "tess.tesc@hlsl,50,tess_hull.hlsl"
        "tess.tese@hlsl,50,tess_domain.hlsl"
)