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

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

对于每种材质类型与renderMode 的组合，该函数仅会被调用一次，并在内部进行缓存。

对于大多数材质而言，renderMode 可以忽略。少数材质可能需要针对特定的渲染模式进行自定义处理。例如，如果材质实现抗锯齿的方式在使用 RenderMode3D 时需要考虑透视变换。

QSGMaterial::Flags QSGMaterial::flags() const

返回材质的标志。

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

如果on 为真，则在此材质上设置标志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 个视图。它与其他视图数量不兼容。在设置着色器条件时，必须通过--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。随后，Material 可以在运行时根据 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() 或 3D API 特定函数（例如将arraySize 参数设为大于 1 的fromVulkanImage()）进行指定时。 随后，渲染器将把视图计数传播到图形管道和材质中。

该函数在 Qt 6.8 中引入。