QSGMaterial Class

成员函数文档

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

将此材质与other 进行比较，如果两者相等，则返回 0；如果此材质应排序在other 之前，则返回 -1 ；如果other 应排序在 之前，则返回 1。

场景图可以对几何节点重新排序，以尽量减少状态变化。在排序过程中会调用比较函数，以便在每次调用 QSGMaterialShader::updateState() 时对材质进行排序，尽量减少状态变化。

此指针和other 保证具有相同的type() 。

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

此函数返回QSGMaterialShader 实现的一个新实例，该实现用于为QSGMaterial 的特定实现渲染几何图形。

该函数只对材料类型和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 个视图，且仅限 2 个视图。它与其他视图数不兼容。在调节 Shader 时，必须用--view-count 2 调用qsb 工具，如果使用 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 文件。然后，材料实现就可以使用QSGMaterialShader::setShaderFileName() 重载，其中包含一个viewCount 参数，它会自动选择正确的 .qsb 文件。

因此，除了不需要指定手动管理的输出文件外，下面的调用与上面的示例调用基本等价。请注意，在某些情况下，自动选择的着色语言版本可能不够充分，在这种情况下，应用程序应继续明确指定所有内容。

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

有关 Qt XML 多视图支持的更多低级细节，请参见QRhi::MultiView 、QRhiColorAttachment::setMultiViewCount() 和QRhiGraphicsPipeline::setMultiViewCount()。当通过QQuickRenderTarget::fromRhiRenderTarget() 或 3D API 特定函数（如fromVulkanImage() 且arraySize 参数大于 1）指定多视图渲染目标时，Qt Quick 场景图渲染器就能识别多视图渲染目标。然后，渲染器会将视图数传播给图形管道和材质。

此函数在 Qt 6.8 中引入。