셰이더젠 툴

셰이더젠 툴은 Qt Quick 3D 의 에셋 컨디셔닝 파이프라인의 일부인 명령줄 애플리케이션입니다. 프로젝트별로 활성화하거나 명령줄에서 수동으로 실행할 수 있습니다. 런타임에 머티리얼 셰이더를 생성하는 프로세스는 비용이 많이 들 수 있으므로 미리 생성하면 시작 시간에 상당한 영향을 미치거나 런타임에 원치 않는 멈춤을 방지할 수 있습니다.

오프라인 셰이더 생성기의 가장 큰 장애물 중 하나는 머티리얼 속성 자체뿐만 아니라 씬의 나머지 구성 방식(예: 광원 수, 광원 유형, 그림자 등)에 따라 생성할 수 있는 다양한 머티리얼의 양이 달라진다는 점입니다. 동적 프로퍼티까지 고려하면 머티리얼 셰이더 퍼뮤테이션의 공유량으로 인해 빌드 시점에 모든 셰이더를 생성하는 것이 불가능할 수 있습니다. 툴이 생성해야 하는 셰이더의 양을 제한하기 위해 툴은 애플리케이션에 필요하다고 생각되는 셰이더만 생성하려고 시도합니다. 툴에 사용되는 휴리스틱이 어떤 머티리얼을 생성해야 하는지 항상 감지하지 못할 수 있으며, 특히 런타임에 변경되는 프로퍼티의 경우 더욱 그렇습니다. 머티리얼 셰이더가 성공적으로 올바르게 생성되었는지 확인하려면 툴에서 .qsbc 파일을 생성해야 하며, 이 파일을 검사하여 콘텐츠가 애플리케이션에서 사용하는 머티리얼과 일치하는지 확인할 수 있습니다. 또한 환경 변수 QT_RHI_SHADER_DEBUG=1을 설정하고 디버그 출력에서 엔진이 미리 생성된 셰이더를 성공적으로 로드했다는 언급을 확인하여 머티리얼이 사전 빌드된 캐시에서 로드되었는지 확인할 수 있습니다.

알려진 제한 사항은 다음과 같습니다:

• 하나 이상의 씬이 View3D.
• 머티리얼 생성 사용 시 라이트의 동적 추가 또는 제거는 지원되지 않습니다.
• 생성된 셰이더는 렌더러의 내부에 대한 종속성으로 인해 사용되는 Qt 버전에 엄격하게 묶여 있습니다. 따라서 생성된 셰이더의 호환성은 버전 간에 보장할 수 없습니다.

사용법

프로젝트에서 머티리얼 셰이더의 오프라인 생성을 활성화하려면 프로젝트 파일에 다음을 추가하세요:

CMake:

qt6_add_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        ${qml_resource_files}
)

또는 다음과 같이 명령줄에서 셰이더젠 툴을 수동으로 호출할 수 있습니다:

shadergen main.qml Material.qml

일반적으로 셰이더젠 도구는 애플리케이션의 프로젝트 폴더에서 실행해야 하지만 -C 인수를 통해 현재 작업 디렉터리를 변경하도록 도구에 지시할 수도 있습니다.

출력 경로를 지정하지 않으면 생성된 파일을 현재 디렉터리에 씁니다. 출력 경로는 -o 옵션을 사용하여 변경할 수 있습니다.

툴이 예상되는 머티리얼을 생성하려면 머티리얼뿐만 아니라 전체 씬에 대해 알아야 합니다(예: 씬의 조명 수 또한 머티리얼 생성 방식에 영향을 미치므로 툴이 처리해야 하는 파일 목록에 모든 관련 qml 파일을 추가해야 합니다).

명령줄 인수

생성된 콘텐츠

셰이더젠 도구의 기본 출력 파일은 .qsbc 파일입니다. .qsbc 파일에는 각 머티리얼의 고유 속성 문자열과 같은 다양한 머티리얼 셰이더에 대한 메타 데이터와 함께 .qsb 파일 모음이 포함되어 있습니다.

.qsbc 파일은 -d 인수를 사용하여 셰이더젠 툴을 호출하여 검사할 수 있습니다:

shadergen -d qtappshaders.qsbc

동적 프로퍼티

이 도구는 빌드 타임에 실행되므로 런타임에 어떤 프로퍼티가 변경될 수 있는지 추론하는 기능이 제한적입니다. 예를 들어 러프니스 값과 같이 속성 범위 내에서만 값이 변경되는 속성은 생성된 머티리얼 셰이더에 영향을 미치지 않지만, 런타임에 이미지 맵을 설정하는 것과 같이 켜지거나 꺼지는 속성은 다른 유형의 머티리얼을 생성해야 할 수 있습니다. 따라서 머티리얼 또는 씬의 기능을 활성화 또는 비활성화하는 머티리얼의 모든 배리언트를 개별 구성 요소로 선언하면 툴에서 올바른 머티리얼 셰이더를 생성하는 데 도움이 됩니다.

다음 예시는 런타임에 머티리얼에 기본 색상 맵을 추가하려는 머티리얼의 인위적인 예시입니다. MaterialRedExtended 컴포넌트는 이 예제에서 사용되지 않으며, 순전히 셰이더 도구가 런타임에 baseColorMap 을 동적으로 설정하는 데 필요한 셰이더를 생성하는 데 도움을 주기 위해 정의된 것임을 참고하세요.

MaterialRed.qml

PrincipledMaterial {
    baseColor: "red"
    lighting: PrincipledMaterial.NoLighting
}

MaterialRedExtended.qml

MaterialRed {
    baseColorMap: Texture {
        source: "maps/metallic/basecolor.jpg"
    }
}

main.qml

Model {
    position: Qt.vector3d(0, -30, 0)
    scale: Qt.vector3d(4, 4, 4)
    source: "#Sphere"
    materials: MaterialRed {
        id: redMaterial
    }
MouseArea {
    anchors.fill: parent
    onClicked: {
    if (redMaterial.baseColorMap === null)
        redMaterial.baseColorMap = baseColorMap
    else
        redMaterial.baseColorMap = null
    }
}