Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

QSGMaterialShader Class

QSGMaterialShader 클래스는 그래픽 API와 무관한 셰이더 프로그램을 나타냅니다. 더 보기...

헤더: #include <QSGMaterialShader>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick

공개 유형

struct GraphicsPipelineState
class RenderState
enum Flag { UpdatesGraphicsPipelineState }
flags Flags

공개 함수

QSGMaterialShader()
(since 6.4) int combinedImageSamplerCount(int binding) const
QSGMaterialShader::Flags flags() const
void setFlag(QSGMaterialShader::Flags flags, bool on = true)
void setFlags(QSGMaterialShader::Flags flags)
virtual bool updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual void updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual bool updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

보호된 함수

void setShader(QSGMaterialShader::Stage stage, const QShader &shader)
void setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)
(since 6.8) void setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

상세 설명

QSGMaterialShader는 버텍스 셰이더와 프래그먼트 셰이더의 조합, 그래픽 파이프라인 상태 변화를 정의하는 데이터, 그리고 유니폼 버퍼 및 텍스처와 같은 그래픽 리소스를 업데이트하는 로직을 나타냅니다.

참고: QSG 접두사가 붙은모든 클래스는 장면 그래프의 렌더링 스레드에서만 사용해야 합니다. 자세한 내용은 장면 그래프 및 렌더링을 참조하십시오.

QSGMaterial 와 QSGMaterialShader는 긴밀한 관계를 형성합니다. 하나의 씬 그래프(중첩된 그래프 포함)에는 해당 머티리얼을 사용하여 오브젝트를 렌더링하는 데 씬 그래프가 사용하는 셰이더 및 기타 데이터를 캡슐화하는 고유한 QSGMaterialShader 인스턴스가 하나 존재합니다. 각 QSGGeometryNode 에는 노드를 그리는 동안 그래픽 파이프라인을 어떻게 구성해야 하는지를 정의하는 고유한 QSGMaterial 가 있을 수 있습니다. 사용자가 QSGMaterialShader 인스턴스를 명시적으로 생성하는 일은 없으며, 이는 QSGMaterial::createShader()를 통해 씬 그래프에 의해 필요에 따라 생성됩니다. 씬 그래프는 QSGMaterial::createShader() 메서드를 호출하여 QSGMaterialShader 인스턴스를 생성하며, 이를 통해 각 셰이더 구현체에 대해 단 하나의 인스턴스만 존재하도록 보장합니다.

Qt 5에서는 QSGMaterialShader가 OpenGL에 묶여 있었습니다. 이 클래스는 QOpenGLShaderProgram 를 기반으로 직접 구축되었으며, updateState() 와 같이 임의의 OpenGL 명령을 실행할 수 있는 함수들을 가지고 있었습니다. Qt 6에서는 더 이상 그렇지 않습니다. QSGMaterialShader는 엄밀히 말해 데이터 지향적이지 않으며, 이는 데이터(셰이더 및 원하는 파이프라인 상태 변경 사항)와 함께 유니폼 버퍼의 데이터를 업데이트하는 로직을 함께 제공함을 의미합니다. 그래픽 API에 대한 직접적인 접근은 제공되지 않습니다. 즉, QSGMaterialShader는 자체적으로 OpenGL, Vulkan, Metal 또는 Direct 3D 호출을 수행할 수 없습니다. 통합된 셰이더 관리 기능과 결합되어, QSGMaterialShader는 한 번만 작성하면 실행 시점에 지원되는 모든 그래픽 API에서 작동할 수 있습니다.

보호된 ` setShaderFileName()` 함수를 호출하여 설정된 셰이더는 머티리얼이 지오메트리에서 가져온 버텍스 데이터를 어떻게 처리할지, 그리고 프래그먼트에 어떻게 셰이딩을 적용할지 제어합니다. QSGMaterialShader는 일반적으로 생성 시 버텍스 셰이더와 프래그먼트 셰이더를 설정합니다. 이후 셰이더를 변경하면 의도한 효과가 나타나지 않을 수 있으므로 피해야 합니다.

Qt 6에서는 기본적으로 .qsb 파일을 애플리케이션과 함께 배포하며, 일반적으로 리소스 시스템을 통해 임베드되고 setShaderFileName()를 호출할 때 참조됩니다. .qsb 파일은 Qt Shader Tools 모듈의 qsb 도구를 사용하여 Vulkan 스타일의 GLSL 소스 코드에서 오프라인으로, 또는 늦어도 애플리케이션 빌드 시점에 생성됩니다.

오버라이드할 수 있는 가상 메서드는 세 가지가 있습니다. 이 메서드들은 유니폼 버퍼, 텍스처 및 파이프라인 상태 변경을 위한 데이터나 데이터를 생성하는 로직을 제공합니다.

updateUniformData()는 하위 클래스에서 가장 흔히 재구현되는 함수입니다. 이 함수는 QByteArray 의 내용을 업데이트해야 하며, 이 내용은 이후 셰이더에 유니폼 버퍼로 노출됩니다. 버텍스 또는 프래그먼트 셰이더에 유니폼 블록이 포함된 모든 QSGMaterialShader는 updateUniformData()를 재구현해야 합니다.

updateSampledImage()는 셰이더 코드가 텍스처를 샘플링할 때 관련이 있습니다. 이 함수는 각 샘플러(또는 해당되는 API의 경우 결합된 이미지 샘플러)에 대해 호출되며, 셰이더에 노출될 QSGTexture 를 지정할 수 있는 옵션을 제공합니다.

셰이더 파이프라인 상태 변경은 그다지 자주 사용되지 않습니다. 한 가지 사용 사례는 특정 블렌드 모드를 사용하려는 머티리얼입니다. 관련 함수는 updateGraphicsPipelineState()입니다. 이 함수는 QSGMaterialShader가 UpdatesGraphicsPipelineState 플래그를 설정하여 활성화하지 않는 한 호출되지 않습니다. 이 함수의 역할은 전달받은 GraphicsPipelineState 구조체 인스턴스를 원하는 변경 사항으로 업데이트하는 것입니다. 현재는 블렌딩 및 컬링 관련 기능만 사용할 수 있으며, 그 외의 상태는 머티리얼로 제어할 수 없습니다.

텍스처 지원도 포함된 간단한 예제는 다음과 같을 수 있습니다. 여기서는 Material이 createShader() 내에서 Shader 인스턴스를 생성하는 QSGMaterial 이며, 프래그먼트 셰이더에서 샘플링하고자 하는 QSGTexture 를 보유하고 있다고 가정합니다. 버텍스 셰이더는 모델-뷰-투영 행렬에만 의존합니다.

class Shader : public QSGMaterialShader
{
public:
    Shader()
    {
        setShaderFileName(VertexStage, QLatin1String(":/materialshader.vert.qsb"));
        setShaderFileName(FragmentStage, QLatin1String(":/materialshader.frag.qsb"));
    }

    bool updateUniformData(RenderState &state, QSGMaterial *, QSGMaterial *)
    {
        bool changed = false;
        QByteArray *buf = state.uniformData();
        if (state.isMatrixDirty()) {
            const QMatrix4x4 m = state.combinedMatrix();
            memcpy(buf->data(), m.constData(), 64);
            changed = true;
        }
        return changed;
    }

    void updateSampledImage(RenderState &, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *)
    {
        Material *mat = static_cast<Material *>(newMaterial);
        if (binding == 1)
            *texture = mat->texture();
    }
};

셰이더에 대한 Vulkan 스타일의 GLSL 소스 코드는 다음과 같을 수 있습니다. 이 코드들은 qsb 도구를 사용하여 오프라인에서 사전 처리되어야 하며, 이 도구는 Shader() 생성자에서 참조되는 .qsb 파일을 생성합니다.

#version 440
layout(location = 0) in vec4 aVertex;
layout(location = 1) in vec2 aTexCoord;
layout(location = 0) out vec2 vTexCoord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
} ubuf;
out gl_PerVertex { vec4 gl_Position; };
void main() {
    gl_Position = ubuf.qt_Matrix * aVertex;
    vTexCoord = aTexCoord;
}
#version 440
layout(location = 0) in vec2 vTexCoord;
layout(location = 0) out vec4 fragColor;
layout(binding = 1) uniform sampler2D srcTex;
void main() {
    vec4 c = texture(srcTex, vTexCoord);
    fragColor = vec4(c.rgb * 0.5, 1.0);
}

참고: QSG 접두사가 붙은모든 클래스는 장면 그래프의 렌더링 스레드에서만 사용해야 합니다. 자세한 내용은 ‘장면 그래프 및 렌더링’을 참조하십시오.

QSGMaterial, Scene Graph - Custom Material, Scene Graph - Two Texture Providers 및 Scene Graph - Graph항목도 참조하십시오 .

멤버 유형 문서

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

특수한 재료 특성을 나타내는 플래그 값.

상수값설명
QSGMaterialShader::UpdatesGraphicsPipelineState0x0001이 플래그를 설정하면 ` updateGraphicsPipelineState()`을 호출할 수 있습니다.

Flags 유형은 QFlags<Flag>에 대한 typedef입니다. 이 유형은 플래그 값들의 OR 조합을 저장합니다.

멤버 함수 설명

QSGMaterialShader::QSGMaterialShader()

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

[since 6.4] int QSGMaterialShader::combinedImageSamplerCount(int binding) const

binding 에 있는 결합된 이미지 샘플러 변수의 요소 수를 반환합니다. 이 값은 셰이더 코드에서 내부적으로 분석하여 얻습니다. 이 변수는 배열일 수 있으며, 한 차원 이상일 수도 있습니다.

이 카운트는 변수 내의 결합된 이미지 샘플러 항목의 총 개수를 나타냅니다. 다음 예제에서, srcA 의 카운트는 1, srcB 의 카운트는 4, srcC 의 카운트는 6입니다.

layout (binding = 0) uniform sampler2D srcA;
layout (binding = 1) uniform sampler2D srcB[4];
layout (binding = 2) uniform sampler2D srcC[2][3];

이 카운트는 QSGMaterialShader::updateSampledImage 의 텍스처 매개변수에 포함된 QSGTexture 포인터의 수입니다.

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

QSGMaterialShader::updateSampledImage도 참조하십시오 .

QSGMaterialShader::Flags QSGMaterialShader::flags() const

이 머티리얼 셰이더에 현재 설정된 플래그를 반환합니다.

setFlags()도 참조하십시오 .

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

on 가 true인 경우, 이 머티리얼 셰이더의 ‘ flags ’를 설정하고, 그렇지 않은 경우 지정된 플래그를 지웁니다.

void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)

이 머티리얼 셰이더에 대한 flags 를 설정합니다.

flags()도 참조하십시오 .

[protected] void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)

지정된 stage 에 대한 shader 를 설정합니다.

[protected] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)

지정된 stage 에 대한 셰이더의 filename 를 설정합니다.

이 파일에는 직렬화된 QShader 가 포함되어 있어야 합니다.

경고: .qsb 파일을 포함한셰이더는 신뢰할 수 있는 콘텐츠로 간주됩니다. 애플리케이션 개발자는 애플리케이션의 일부가 아닌 사용자가 제공한 콘텐츠의 로딩을 허용하기 전에 잠재적인 영향을 신중하게 고려해야 합니다.

[protected, since 6.8] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

지정된 stage 에 대한 셰이더의 filename 를 설정합니다.

이 파일에는 직렬화된 QShader 가 포함되어 있어야 합니다.

이 오버로드는 multiview 렌더링을 활성화할 때, 특히 빌드 시스템의 MULTIVIEW 편의 옵션이 사용될 때 사용됩니다.

viewCount 값은 2, 3 또는 4여야 합니다. filename 는 이 값에 따라 자동으로 조정됩니다.

경고: .qsb 파일을 포함한셰이더는 신뢰할 수 있는 콘텐츠로 간주됩니다. 애플리케이션 개발자는 애플리케이션의 일부가 아닌 사용자가 제공한 콘텐츠의 로딩을 허용하기 전에 잠재적인 영향을 신중하게 고려해야 합니다.

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

[virtual] bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

이 함수는 씬 그래프에 의해 호출되어, 머티리얼이 사용자 정의 그래픽 상태 세트를 제공할 수 있도록 합니다. 머티리얼별로 사용자 정의할 수 있는 상태 세트는 블렌딩 및 관련 설정으로 제한됩니다.

참고: 이 함수는 setFlags()을 통해 UpdatesGraphicsPipelineState 플래그가 활성화된 경우에만 호출됩니다. 기본적으로 이 플래그는 설정되어 있지 않으므로, 이 함수는 호출되지 않습니다.

ps 의 멤버 중 어느 하나라도 변경된 경우, 반환 값은 반드시 true 여야 합니다.

참고: ps 의내용은 이 함수가 호출될 때마다 유지되지 않습니다.

현재 렌더링용 ` state `는 씬 그래프에서 전달됩니다.

newMaterial 에서 서브클래스별 상태를 추출할 수 있습니다. oldMaterial 가 null인 경우, 이 셰이더가 방금 활성화된 상태입니다.

[virtual] void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

이 함수는 씬 그래프에 의해 호출되며, 셰이더 내에서 샘플링된 이미지를 사용할 수 있도록 준비합니다. 일반적으로 이는 결합된 이미지 샘플러의 형태로 이루어집니다.

binding 는 샘플러의 바인딩 번호입니다. 이 함수는 ` QSGMaterialShader`과 연관된 셰이더 코드 내의 각 결합된 이미지 샘플러 변수에 대해 호출됩니다.

texture 는 ` QSGTexture ` 포인터의 배열입니다. 이 배열의 요소 수는 셰이더 코드에서 지정된 이미지 샘플러 변수의 요소 수와 일치합니다. 이 변수는 배열일 수 있으며, 한 차원 이상일 수도 있습니다. 배열의 요소 수는 다음을 통해 확인할 수 있습니다. QSGMaterialShader::combinedImageSamplerCount

texture 의 요소가 null인 경우, 반환하기 전에 유효한 QSGTexture 포인터로 설정해야 합니다. null이 아닐 경우, 새로운 QSGTexture * 를 저장할지, 아니면 이미 알려진 QSGTexture 의 일부 매개변수를 업데이트할지는 머티리얼이 결정합니다. QSGTexture 의 소유권은 이전되지 않습니다.

현재 렌더링 중인 state 는 씬 그래프에서 전달됩니다. 필요한 경우, QSGTexture::commitTextureOperations()을 통해 텍스처 데이터 업로드를 큐에 추가하는 것은 머티리얼의 책임입니다.

newMaterial 에서 서브클래스별 상태를 추출할 수 있습니다.

oldMaterial 변경을 최소화하기 위해 사용할 수 있습니다. oldMaterial 가 null인 경우, 이 셰이더가 방금 활성화된 상태입니다.

QSGMaterialShader::combinedImageSamplerCount도 참조하십시오 .

[virtual] bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

이 함수는 셰이더 프로그램의 유니폼 버퍼 내용이 업데이트되도록 하기 위해 씬 그래프에 의해 호출됩니다. 이 함수의 구현체는 실제 그래픽 연산을 수행할 필요가 없으며, 단지 ` RenderState::uniformData()`에서 반환된 ` QByteArray `로 데이터를 복사하는 역할만 담당합니다. 씬 그래프는 해당 버퍼가 셰이더에서 가시적으로 처리되도록 관리합니다.

현재 렌더링 중인 state 는 씬 그래프에서 전달됩니다. 상태(state)가 관련 상태가 '더티(dirty)' 상태임을 나타내는 경우, 구현체는 RenderState::uniformData()을 통해 접근 가능한 버퍼 데이터의 해당 영역을 업데이트해야 합니다. 행렬(matrix)이나 불투명도(opacity)와 같은 상태가 '더티' 상태가 아닌 경우, 데이터는 영구적이므로 해당 영역을 수정할 필요가 없습니다.

유니폼 데이터에 어떤 변경이 이루어진 경우, 반환 값은 반드시 true 여야 합니다.

플랫 컬러 머티리얼의 색상과 같은 서브클래스별 상태는 newMaterial 에서 추출하여 버퍼의 관련 영역을 그에 맞게 업데이트해야 합니다.

oldMaterial 을 사용하면 머티리얼 상태를 업데이트할 때 버퍼 변경(일반적으로 memcpy 호출)을 최소화할 수 있습니다. oldMaterial 가 null인 경우, 이 셰이더가 방금 활성화된 것입니다.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.