Shadergen 도구

Shadergen 도구는 Qt Quick 3D 의 에셋 컨디셔닝 파이프라인에 포함된 명령줄 애플리케이션입니다. 프로젝트별로 활성화하거나 명령줄에서 수동으로 실행할 수 있습니다. 실행 시점에 머티리얼 셰이더를 생성하는 과정은 상당한 리소스를 소모할 수 있으므로, 머티리얼 셰이더를 미리 생성해 두면 시작 시간을 크게 단축하거나 실행 중 원치 않는 지연을 방지하는 데 도움이 될 수 있습니다.

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

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

• View3D 가 두 개 이상 포함된 씬.
• 마테리얼 생성을 사용할 때 조명을 동적으로 추가하거나 제거하는 기능은 지원되지 않습니다.
• 생성된 셰이더는 렌더러의 내부 구조에 의존하기 때문에 사용된 Qt 버전에 엄격하게 묶여 있습니다. 따라서 버전 간에 생성된 셰이더의 호환성은 보장할 수 없습니다.

사용법

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

CMake:

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

또는 다음과 같이 명령줄에서 shadergen 도구를 수동으로 실행할 수도 있습니다:

shadergen main.qml Material.qml

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

출력 경로가 지정되지 않으면 도구는 생성된 파일을 현재 디렉터리에 저장합니다. 출력 경로는 ` -o ` 옵션을 사용하여 변경할 수 있습니다.

도구가 예상대로 머티리얼을 생성하려면 머티리얼뿐만 아니라 전체 씬에 대한 정보를 파악해야 한다는 점에 유의하십시오. 예를 들어, 씬 내 조명의 개수도 머티리얼 생성 방식에 영향을 미치므로, 도구가 처리해야 할 파일 목록에 모든 관련 qml 파일을 추가해야 합니다.

명령줄 인수

생성된 내용

shadergen 도구의 주요 출력 파일은 .qsbc 파일입니다. .qsbc 파일에는 여러 .qsb 파일 모음과 각 머티리얼에 대한 고유한 속성 문자열 등 다양한 머티리얼 셰이더에 관한 메타데이터가 포함되어 있습니다. .qsbc 파일의 내용을 확인하려면 다음과 같이 shadergen 도구에 -l 인수를 사용할 수 있습니다.

shadergen -l qtappshaders.qsbc

동적 속성

이 도구는 빌드 시점에 실행되므로, 런타임에 어떤 속성이 변경될지 판단하는 능력은 제한적입니다. 예를 들어 거칠기(roughness) 값과 같이 속성 범위 내에서만 값이 변경되는 속성은 생성된 머티리얼 셰이더에 아무런 영향을 미치지 않지만, 실행 시 이미지 맵을 설정하는 것과 같이 켜짐(on) 또는 꺼짐(off) 상태인 속성의 경우, 다른 유형의 머티리얼이 생성되어야 합니다. 따라서 머티리얼이나 씬에서 기능을 활성화하거나 비활성화하는 모든 머티리얼 변형은 개별 컴포넌트로 선언하는 것이 권장되며, 이는 도구가 올바른 머티리얼 셰이더를 생성하는 데 도움이 됩니다.

다음 예제는 런타임에 머티리얼에 기본 색상 맵을 추가하고자 하는 인위적인 머티리얼 예시를 보여줍니다. MaterialRedExtended 컴포넌트는 이 예제에서 전혀 사용되지 않으며, 순전히 shadergen 도구가 런타임에 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
    }
}