QShaderBaker Class

멤버 함수 설명

QShaderBaker::QShaderBaker()

새로운 QShaderBaker 객체를 생성합니다.

[noexcept] QShaderBaker::~QShaderBaker()

소멸자.

QShader QShaderBaker::bake()

컴파일 및 번역 프로세스를 실행합니다.

QShader 인스턴스를 반환합니다. 프로세스가 성공적으로 완료되었는지 확인하려면 QShader::isValid()을 호출하십시오. 해당 함수가 false 를 반환하면, errorMessage()을 호출하여 로그를 가져오십시오.

이 작업은 많은 자원을 소모합니다. 애플리케이션에서 이 메서드를 호출할 때는 별도의 스레드에서 수행하는 것이 좋습니다.

QString QShaderBaker::errorMessage() const

마지막으로 실행된 ` bake()`에서 발생한 오류 메시지를 반환하며, 오류가 없는 경우에는 빈 문자열을 반환합니다.

void QShaderBaker::setBatchableVertexShaderExtraInputLocation(int location)

QShader::BatchableVertexShader 변형을 생성할 때, ` location `은 삽입된 정점 입력의 입력 위치를 지정합니다. 이 값은 기본적으로 7이며, 정점 셰이더가 이미 입력 위치 7을 사용하고 있는 경우에만 재정의해야 합니다.

void QShaderBaker::setBreakOnShaderTranslationError(bool enable)

셰이더 변환(SPIR-V에서 GLSL/HLSL/MSL로)이 실패할 때의 동작을 제어합니다. 기본적으로 이 설정은 true로 되어 있으며, 요청된 셰이더를 생성할 수 없는 경우 ` bake()`가 오류를 반환하게 됩니다. 이를 원하지 않고, 생성 가능한 부분은 생성하되 나머지는 오류 메시지 없이 건너뛰고자 한다면 ` enable `를 false로 설정하십시오.

여러 GLSL 버전을 대상으로 설정할 경우, 특정 기능이 주어진 버전으로 변환될 수 없을 때 오류가 발생할 수 있습니다. 예를 들어, textureSize()를 사용하는 셰이더를 GLSL ES 100으로 변환하려고 시도하면 "textureSize는 ESSL 100에서 지원되지 않습니다"라는 오류 메시지와 함께 bake() 호출 전체가 실패하게 됩니다. 요청된 GLSL ES 100 셰이더가 결과에 포함되지 않는 것이 허용된다면, 이 플래그를 false로 설정하면 bake() 호출이 성공적으로 수행됩니다.

void QShaderBaker::setGeneratedShaderVariants(const QList<QShader::Variant> &v)

생성될 셰이더 변형을 지정합니다. 각 셰이더 버전마다 결과 파일인 QShader 에 여러 개의 변형이 포함될 수 있습니다.

대부분의 경우 v 에는 QShader::StandardShader 라는 단일 항목이 포함됩니다.

void QShaderBaker::setGeneratedShaders(const QList<QShaderBaker::GeneratedShader> &v)

컴파일하거나 변환할 셰이더의 종류를 지정합니다. 기본적으로 아무것도 생성되지 않으므로, ` bake()`를 호출하기 전에 이 함수를 반드시 호출해야 합니다.

예를 들어, 다른 언어로의 추가 변환 없이 SPIR-V로만 베이킹하는 것이 가능한 최소한의 대상입니다. 이를 요청하려면 다음과 같이 하십시오:

baker.setGeneratedShaders({ QShader::SpirvShader, QShaderVersion(100) });

[since 6.9] void QShaderBaker::setGlslOptions(QShaderBaker::GlslOptions options)

생성된 GLSL 및 GLSL ES 소스 코드에 대한 추가 options 를 설정합니다. 기본적으로 플래그는 설정되어 있지 않습니다.

이 함수는 Qt 6.9에서 도입되었습니다.

[since 6.7] void QShaderBaker::setMultiViewCount(int count)

멀티뷰를 사용하여 셰이더를 트랜스파일링할 때(예: GL_OVR_multiview2, VK_KHR_multiview 등을 사용하는 렌더러에서 gl_ViewIndex를 활용하는 버텍스 셰이더), 일부 대상의 경우 셰이더 내에서 뷰의 수를 선언해야 합니다. 이는 Vulkan 스타일의 GLSL 코드에서는 수행되지 않으며, SPIR-V나 HLSL과 같은 타깃에는 관련이 없지만, OpenGL 및 GLSL의 경우 필수적이므로 해당 값을 추가 메타데이터로 제공해야 합니다.

기본값은 0이며, 이 경우 num_views 문이 삽입되지 않습니다. 1로 설정하는 것은 어차피 기본값 num_views 이기 때문에 의미가 없습니다. 따라서 효과를 내기 위해서는 count 을 2 이상으로 설정해야 합니다. 예를 들어 2로 설정하면, 생성된 GLSL 셰이더에 layout(num_views = 2) in; 문이 포함됩니다.

count 을 2 이상으로 설정하면 몇 가지 전처리기 문도 삽입됩니다. QSHADER_VIEW_COUNT 은 count 으로 설정되며, GL_EXT_multiview 확장은 자동으로 활성화됩니다. 따라서 적절한 count 을 설정하는 것은 다른 유형의 셰이더에서도 중요할 수 있습니다. 예를 들어, 버텍스 셰이더와 프래그먼트 셰이더 간에 유니폼 버퍼를 공유하고, 두 셰이더 모두 #if QSHADER_VIEW_COUNT >= 2 와 같은 코드를 작성할 수 있어야 하는 경우입니다.

이 함수는 Qt 6.7에서 도입되었습니다.

void QShaderBaker::setPerTargetCompilation(bool enable)

타겟별 컴파일을 ` enable`로 설정합니다. 기본적으로 이 옵션은 비활성화되어 있으며, 이는 Vulkan/GLSL 소스 코드가 변형(variant)당 한 번씩 SPIR-V로 컴파일됨을 의미합니다. (즉, 기본적으로 한 번 컴파일되며, 버텍스 셰이더이고 요청된 대로 `Batchable` 변형인 경우에는 두 번 컴파일됩니다). 그 결과 생성된 SPIR-V는 이후 다양한 대상 언어(GLSL, HLSL, MSL)로 변환됩니다.

타깃별 컴파일 모드에서는 각 타깃마다 별도의 GLSL-SPIR-V 컴파일 단계가 수행되며, 이는 ` setGeneratedShaders()`를 통해 요청된 각 GLSL/HLSL/MSL 버전에 대해 적용됩니다. 입력 소스는 동일하지만, 타깃별 전처리기 정의가 삽입됩니다. 이 방식은 시간이 훨씬 더 많이 소요되지만, 애플리케이션이 단일 셰이더를 제공하고 #ifdef 블록을 사용하여 구분할 수 있게 해줍니다. 이 모드가 비활성화된 경우, 동일한 결과를 얻으려면 셰이더 파일의 여러 버전을 제공하고, 각각을 별도로 처리하며, 각 버전에 대한 {.qsb} 파일을 배포한 후, 런타임 로직에 따라 올바른 파일을 선택해야 합니다.

이 모드에서는 다음 매크로들이 자동으로 정의됩니다. 이 매크로들은 그래픽 API가 아닌 셰이딩 언어에 항상 연동된다는 점에 유의하십시오.

• QSHADER_SPIRV - SPIR-V를 대상으로 할 때 정의됩니다(일반적으로 Vulkan에서 사용됨).
• QSHADER_SPIRV_VERSION - 대상 SPIR-V 버전 번호(예: 100).
• QSHADER_GLSL - GLSL 또는 GLSL ES를 대상으로 할 때 정의됩니다(일반적으로 OpenGL 또는 OpenGL ES에서 사용됨).
• QSHADER_GLSL_VERSION - 대상 GLSL 또는 GLSL ES 버전 번호(예: 100, 300, 330).
• QSHADER_GLSL_ES - GLSL ES를 대상으로 할 때만 정의됩니다.
• QSHADER_HLSL - HLSL을 대상으로 할 때 정의됩니다(일반적으로 Direct 3D에서 사용됨).
• QSHADER_HLSL_VERSION - 대상 HLSL 셰이더 모델 버전(예: 50
• QSHADER_MSL - Metal 셰이딩 언어(Metal)를 대상으로 할 때 정의됩니다(일반적으로 Metal에서 사용됨)
• QSHADER_MSL_VERSION - 대상 MSL 버전(예: 12 또는 20).

이를 통해 다음과 같은 셰이더 코드를 작성할 수 있습니다.

#if QSHADER_HLSL || QSHADER_MSL
vec2 uv = vec2(uv_coord.x, 1.0 - uv_coord.y);
#else
vec2 uv = uv_coord;
#endif

void QShaderBaker::setPreamble(const QByteArray &preamble)

일반 셰이더 코드보다 먼저 처리되는 사용자 정의 버전 지시문( preamble )을 지정합니다.

이는 단순히 소스 문자열의 맨 앞에 내용을 추가하는 것 이상입니다. 즉, 모든 코드보다 앞에 배치되어야 하는 GLSL 버전 지시문의 유효성에는 영향을 미치지 않습니다. 또한, 보고된 오류 메시지의 줄 번호는 preamble 에 지정된 내용을 무시하고 그대로 유지됩니다.

서두(preamble)의 사용 사례 중 하나는 동적으로 생성된 ` #define ` 문을 투명하게 삽입하는 것입니다.

void QShaderBaker::setSourceDevice(QIODevice *device, QShader::Stage stage, const QString &fileName = QString())

소스 device 를 설정합니다. 이를 통해 단순한 파일뿐만 아니라 모든 QIODevice 을 사용할 수 있습니다. stage 는 셰이더 단계를 지정하며, 선택 사항인 fileName 에는 오류 메시지에 사용되는 파일 이름이 포함됩니다.

void QShaderBaker::setSourceFileName(const QString &fileName)

셰이더 소스 파일의 이름을 ` fileName`로 설정합니다. 이 파일은 ` bake()`를 호출할 때 읽어들여집니다. 셰이더 스테이지는 파일 확장자를 통해 자동으로 추론됩니다. 이를 원하지 않거나 불가능한 경우에는 대신 `stage` 인자를 사용하는 오버로드를 사용하십시오.

지원되는 파일 확장자는 다음과 같습니다:

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

void QShaderBaker::setSourceFileName(const QString &fileName, QShader::Stage stage)

셰이더 소스 파일의 이름을 fileName 로 설정합니다. 이 파일은 bake()를 호출할 때 읽히게 됩니다. 셰이더 스테이지는 stage 로 지정됩니다.

void QShaderBaker::setSourceString(const QByteArray &sourceString, QShader::Stage stage, const QString &fileName = QString())

입력 셰이더 sourceString 를 설정합니다. stage 는 셰이더 단계를 지정하며, 선택 사항인 fileName 에는 오류 메시지에 사용되는 파일 이름이 포함됩니다.

void QShaderBaker::setSpirvOptions(QShaderBaker::SpirvOptions options)

생성된 SPIR-V 바이너리에 대한 추가 options 를 설정합니다. 기본적으로 플래그는 설정되지 않습니다.

void QShaderBaker::setTessellationMode(QShaderDescription::TessellationMode mode)

테셀레이션 제어 셰이더용 MSL 셰이더 코드를 생성할 때는 테셀레이션 mode (삼각형 또는 사각형)을 사전에 파악해야 합니다. GLSL에서는 일반적으로 테셀레이션 평가 셰이더에서 이를 선언하지만, Metal의 경우 테셀레이션 제어 셰이더에서 컴퓨트 셰이더를 생성할 때도 이를 파악해야 합니다.

설정되지 않은 경우 기본값은 삼각형입니다.

void QShaderBaker::setTessellationOutputVertexCount(int count)

테셀레이션 평가 셰이더용 MSL 셰이더 코드를 생성할 때는, 테셀레이션 제어 셰이더의 출력 버텍스 count 를 사전에 파악하고 있어야 합니다. GLSL에서는 일반적으로 테셀레이션 제어 셰이더 내에서 이를 선언하지만, Metal의 경우 테셀레이션 평가 셰이더에서 버텍스 셰이더를 생성할 때도 이를 파악하고 있어야 합니다.

설정되지 않은 경우 기본값은 3입니다.