QSGMaterial Class

멤버 함수 문서

[virtual] int QSGMaterial::compare(const QSGMaterial *other) const

이 머티리얼을 other 와 비교하여, 둘이 같으면 0을 반환하고, 이 머티리얼이 other 보다 먼저 정렬되어야 하면 -1을, other 가 먼저 정렬되어야 하면 1을 반환합니다.

씬 그래프는 상태 변화를 최소화하기 위해 지오메트리 노드의 순서를 재조정할 수 있습니다. 비교 함수는 정렬 과정에서 호출되어, QSGMaterialShader::updateState()가 호출될 때마다 발생하는 상태 변화를 최소화하도록 머티리얼을 정렬할 수 있게 합니다.

this 포인터와 other 는 type()과 동일한 값을 가짐이 보장됩니다.

[pure virtual] QSGMaterialShader *QSGMaterial::createShader(QSGRendererInterface::RenderMode renderMode) const

이 함수는 ` QSGMaterial`의 특정 구현체에서 지오메트리를 렌더링하는 데 사용되는 ` QSGMaterialShader ` 구현체의 새로운 인스턴스를 반환합니다.

이 함수는 머티리얼 유형과 renderMode 의 각 조합에 대해 한 번만 호출되며, 내부적으로 캐시됩니다.

대부분의 머티리얼의 경우, ` renderMode `는 무시해도 됩니다. 일부 머티리얼은 특정 렌더 모드에 대해 별도의 처리가 필요할 수 있습니다. 예를 들어, `RenderMode3D`가 사용 중일 때 원근 변환을 고려해야 하는 방식으로 앤티앨리어싱을 구현하는 머티리얼이 있습니다.

QSGMaterial::Flags QSGMaterial::flags() const

머티리얼의 플래그를 반환합니다.

void QSGMaterial::setFlag(QSGMaterial::Flags flags, bool on = true)

on 가 true인 경우, 이 머티리얼에 flags 플래그를 설정하고, 그렇지 않은 경우 해당 속성을 지웁니다.

[pure virtual] QSGMaterialType *QSGMaterial::type() const

이 함수는 씬 그래프에 의해 호출되어, createShader()에 의해 인스턴스화된 QSGMaterialShader 에 고유한 식별자를 조회합니다.

대부분의 머티리얼의 경우, 일반적인 접근 방식은 정적이며 전역적으로 사용 가능한 QSGMaterialType 인스턴스에 대한 포인터를 반환하는 것입니다. QSGMaterialType 는 불투명한 객체입니다. 이 객체의 목적은 고유한 머티리얼 식별자를 생성하는 유형 안전하고 간단한 방법을 제공하는 데에만 있습니다.

QSGMaterialType *type() const override
{
    static QSGMaterialType type;
    return &type;
}

[since 6.8] int QSGMaterial::viewCount() const

멀티뷰 렌더링에서 해당 머티리얼이 사용된 경우의 뷰 수를 반환합니다.

일반적으로 반환 값은 1 입니다. 뷰 수가 2보다 크면 멀티뷰 렌더링 패스를 의미합니다. 멀티뷰를 지원하는 머티리얼은 createShader() 내에서, 또는 해당 QSGMaterialShader 생성자에서 viewCount()를 쿼리하여 적절한 셰이더가 선택되도록 해야 합니다. 그런 다음, 멀티뷰 모드에서는 여러 개의 행렬이 존재하므로(뷰마다 하나씩), 버텍스 셰이더는 gl_ViewIndex 을 사용하여 모델-뷰-투영 행렬 배열을 인덱싱해야 합니다.

예를 들어, 다음과 같은 간단한 버텍스 셰이더를 살펴보겠습니다:

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
    mat4 matrix[2];
    float opacity;
};

void main()
{
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
    color = vertexColor * opacity;
}

이 셰이더는 2개의 뷰만 처리하도록 준비되어 있으며, 다른 뷰 수와는 호환되지 않습니다. 셰이더를 조건부로 설정할 때는 qsb 도구를 --view-count 2 옵션과 함께 호출해야 하며, CMake 통합을 사용하는 경우 qt_add_shaders() 명령어에서 VIEW_COUNT 2 를 지정해야 합니다.

개발자는 서로 다른 뷰 수를 처리하는 과정을 간소화하기 위해 자동으로 삽입된 전처리기 변수 QSHADER_VIEW_COUNT 를 사용하는 것이 좋습니다. 예를 들어, 동일한 소스 파일에서 비멀티뷰와 뷰 수가 2인 멀티뷰를 모두 지원해야 하는 경우 다음과 같이 처리할 수 있습니다:

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
#if QSHADER_VIEW_COUNT >= 2
    mat4 matrix[QSHADER_VIEW_COUNT];
#else
    mat4 matrix;
#endif
    float opacity;
};

void main()
{
#if QSHADER_VIEW_COUNT >= 2
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
#else
    gl_Position = matrix * vertexCoord;
#endif
    color = vertexColor * opacity;
}

이제 동일한 소스 파일을 qsb 또는 qt_add_shaders() 를 통해 두 번 실행할 수 있습니다. 한 번은 뷰 수를 지정하지 않고, 다른 한 번은 뷰 수를 2로 설정하여 실행합니다. 그러면 머티리얼은 런타임에 viewCount()를 기반으로 적절한 .qsb 파일을 선택할 수 있습니다.

CMake를 사용하면 다음과 같이 구현할 수 있습니다. 이 예제에서 해당 QSGMaterialShader 는 viewCount()의 값에 따라 :/shaders/example.vert.qsb 와 :/shaders/multiview/example.vert.qsb 중에서 하나를 선택하게 됩니다. (프래그먼트 셰이더도 마찬가지입니다)

qt_add_shaders(application "application_shaders"
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

qt_add_shaders(application "application_multiview_shaders"
    GLSL
        330,300es
    HLSL
        61
    MSL
        12
    VIEW_COUNT
        2
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
    OUTPUTS
        shaders/multiview/example.vert
        shaders/multiview/example.frag
)

편의를 위해 qt_add_shaders()에도 MULTIVIEW 옵션이 있습니다. 이 옵션은 먼저 qsb 도구를 정상적으로 실행한 다음, VIEW_COUNT 를 2 로 재정의하고, GLSL, HLSL, MSL 를 적절한 기본값으로 설정한 후, qsb 를 다시 실행하여 이번에는 접미사가 추가된 .qsb 파일을 출력합니다. 그러면 머티리얼 구현체는 viewCount 인자를 받는 QSGMaterialShader::setShaderFileName() 오버로드를 사용할 수 있으며, 이 오버로드는 올바른 .qsb 파일을 자동으로 선택합니다.

따라서 다음 코드는 수동으로 관리하는 출력 파일을 지정할 필요가 없다는 점을 제외하면, 위에서 보여준 호출 예제와 대체로 동일합니다. 자동으로 선택된 셰이딩 언어 버전이 충분하지 않은 경우가 있을 수 있으므로, 이 경우 애플리케이션은 모든 항목을 명시적으로 계속 지정해야 합니다.

qt_add_shaders(application "application_multiview_shaders"
    MULTIVIEW
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

Qt의 멀티뷰 지원에 대한 더 자세한 저수준 정보는 QRhi::MultiView, QRhiColorAttachment::setMultiViewCount() 및 QRhiGraphicsPipeline::setMultiViewCount()을 참조하십시오. Qt Quick 장면 그래프 렌더러는 QQuickRenderTarget::fromRhiRenderTarget()을 통해 지정되거나, arraySize 인자가 1보다 큰 fromVulkanImage()과 같은 3D API 특정 함수를 통해 지정될 때 멀티뷰 렌더 타깃을 인식할 수 있도록 준비되어 있습니다. 그러면 렌더러는 뷰 수를 그래픽 파이프라인과 머티리얼로 전달합니다.

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