PySide6.QtQuick.QSGMaterialShader

class QSGMaterialShader

QSGMaterialShader 类表示一个与图形API无关的着色器程序。More_…

概要

方法

虚拟方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

QSGMaterialShader 表示顶点和片段着色器的组合，定义图形管道状态更改的数据，以及更新图形资源（如统一缓冲区和纹理）的逻辑。

注意

所有带有QSG前缀的类应仅在场景图的渲染线程上使用。有关更多信息，请参见场景图和渲染。

QSGMaterial 和 QSGMaterialShader 形成了紧密的关系。对于一个场景图（包括嵌套图），有一个唯一的 QSGMaterialShader 实例，它封装了场景图用于渲染具有该材质的对象的着色器和其他数据。每个 QSGGeometryNode 可以有一个唯一的 QSGMaterial，它定义了在绘制节点时必须如何配置图形管道。QSGMaterialShader 的实例永远不会由用户显式创建，它将在需要时由场景图通过 createShader() 创建。场景图通过调用 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是QSGMaterial，它在createShader()中创建了一个Shader的实例，并且它持有一个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 场景图 - 自定义材质 场景图 - 两个纹理提供者 场景图 - 图

class Flag

(继承自 enum.Flag) 标志值，用于指示特殊材料属性。

常量

描述

QSGMaterialShader.UpdatesGraphicsPipelineState

设置此标志将启用调用 updateGraphicsPipelineState() 。
class Stage
__init__()

构造一个新的 QSGMaterialShader 。

combinedImageSamplerCount(binding)
Parameters:

binding – int

Return type:

整数

返回在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];

此计数是updateSampledImage的纹理参数中QSGTexture指针的数量。

另请参阅

updateSampledImage

flags()
Return type:

Flag的组合

返回当前为此材质着色器设置的标志。

另请参阅

setFlags()

setFlag(flags[, on=true])
Parameters:

  • flags – Flag 的组合

  • on – 布尔值

如果on为真，则在此材质着色器上设置flags；否则清除指定的标志。

setFlags(flags)
Parameters:

flags – Flag 的组合

设置此材质着色器的flags。

另请参阅

flags()

setShaderFileName(stage, filename)
Parameters:

  • stage – Stage

  • filename – str

为指定的stage设置着色器的filename。

该文件预计包含一个序列化的QShader。

setShaderFileName(stage, filename, viewCount)
Parameters:

  • stage – Stage

  • filename – str

  • viewCount – int

为指定的stage设置着色器的filename。

该文件预计包含一个序列化的QShader。

当启用multiview渲染时，特别是在使用构建系统的MULTIVIEW便捷选项时，会使用此重载。

viewCount 应为 2、3 或 4。filename 会根据此值自动调整。

updateGraphicsPipelineState(state, ps, newMaterial, oldMaterial)
Parameters:
Return type:

布尔

此函数由场景图调用，以使材质能够提供一组自定义的图形状态。材质可自定义的状态集仅限于混合及相关设置。

注意

此函数仅在通过setFlags()启用UpdatesGraphicsPipelineState标志时调用。默认情况下未设置，因此此函数永远不会被调用。

每当对ps中的任何成员进行更改时，返回值必须为true。

注意

ps 的内容在此函数的多次调用之间不会持久保存。

当前的渲染state是从场景图中传递的。

可以从newMaterial中提取子类特定的状态。当oldMaterial为空时，此着色器刚刚被激活。

updateUniformData(state, newMaterial, oldMaterial)
Parameters:
Return type:

布尔

此函数由场景图调用，以更新着色器程序的统一缓冲区内容。实现不需要执行任何实际的图形操作，它仅负责将数据复制到从uniformData()返回的QByteArray中。场景图负责使该缓冲区在着色器中可见。

当前的渲染state是从场景图中传递的。如果状态指示任何相关状态是脏的，实现必须更新可通过uniformData()访问的缓冲区数据中的适当区域。当状态（如矩阵或不透明度）不是脏的时，不需要触及相应的区域，因为数据是持久的。

返回值必须为true，只要对统一数据进行了任何更改。

子类特定的状态，例如纯色材料的颜色，应从newMaterial中提取，以相应地更新缓冲区中的相关区域。

oldMaterial 可用于在更新材质状态时最小化缓冲区更改（通常是 memcpy 调用）。当 oldMaterial 为 null 时，此着色器刚刚被激活。

class RenderState

封装了在调用updateUniformData()和其他update类型函数期间的当前渲染状态。More_…

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

渲染状态包含了许多访问器，着色器需要遵循这些访问器以符合场景图的当前状态。

class DirtyState

常量

描述

QSGMaterialShader.RenderState.DirtyMatrix

(继承自 enum.Flag) 用于指示矩阵已更改并且必须更新。

QSGMaterialShader.RenderState.DirtyOpacity

用于指示不透明度已更改，必须更新。

QSGMaterialShader.RenderState.DirtyCachedMaterialData

用于指示缓存的材质状态已更改，必须更新。

QSGMaterialShader.RenderState.DirtyAll

用于指示所有内容都需要更新。
combinedMatrix()
Return type:

QMatrix4x4

返回由模型视图矩阵和投影矩阵组合而成的矩阵。

combinedMatrix(index)
Parameters:

索引 – int

Return type:

QMatrix4x4

determinant()
Return type:

浮点数

返回用于渲染的模型视图行列式。

devicePixelRatio()
Return type:

浮点数

返回用于渲染的物理像素与设备独立像素之间的比率。

deviceRect()
Return type:

QRect

返回正在渲染的表面的设备矩形

dirtyStates()
Return type:

DirtyState的组合

返回哪些渲染状态已更改，并且需要更新使用此材质渲染的几何体以符合当前渲染状态。

isMatrixDirty()
Return type:

布尔

如果dirtyStates()包含脏矩阵状态，则返回true，否则返回false。

isOpacityDirty()
Return type:

布尔

如果dirtyStates()包含脏的不透明度状态，则返回true，否则返回false。

modelViewMatrix()
Return type:

QMatrix4x4

返回模型视图矩阵。

如果材料设置了RequiresFullMatrix标志，这保证是从场景图计算的完整变换矩阵。

然而，如果未设置此标志，渲染器可能会选择更改此矩阵。例如，它可能会在CPU上预变换顶点并将此矩阵设置为单位矩阵。

在上述情况下，仍然可以通过在材料中设置RequiresDeterminant标志并调用determinant()访问器来检索实际的矩阵行列式。

opacity()
Return type:

浮点数

返回用于渲染的累积不透明度。

projectionMatrix()
Return type:

QMatrix4x4

返回投影矩阵。

projectionMatrix(index)
Parameters:

索引 – int

Return type:

QMatrix4x4

projectionMatrixCount()
Return type:

整数

resourceUpdateBatch()
Return type:

QRhiResourceUpdateBatch

返回一个资源更新批次，可以将上传和复制操作排队到该批次中。这通常由updateSampledImage()用于将纹理图像内容更新排队。

rhi()
Return type:

QRhi

返回当前的QRhi。

uniformData()
Return type:

QByteArray

返回指向着色器中统一（常量）缓冲区数据的指针。统一数据只能从updateUniformData()更新。在其他可重新实现的函数中，例如updateSampledImage()，返回值为null。

注意

强烈建议在着色器中使用std140声明统一块，并仔细研究OpenGL规范第7.6.2.2节中描述的标准统一块布局。确保数据在QByteArray中的正确位置放置，并考虑对齐要求，这是QSGMaterialShader实现的责任。即使目标语言默认使用不同的打包规则，转换为其他着色语言的着色器代码也应使用相同的块成员偏移量。

注意

避免从C++ POD类型（如结构体）复制以一次性更新多个成员，除非已验证C++结构体和GLSL统一块的布局匹配。

viewportRect()
Return type:

QRect

返回正在渲染到的表面的视口矩形。

class GraphicsPipelineState

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

class BlendFactor

常量

描述

QSGMaterialShader.GraphicsPipelineState.Zero

QSGMaterialShader.GraphicsPipelineState.One

QSGMaterialShader.GraphicsPipelineState.SrcColor

QSGMaterialShader.GraphicsPipelineState.OneMinusSrcColor

QSGMaterialShader.GraphicsPipelineState.DstColor

QSGMaterialShader.GraphicsPipelineState.OneMinusDstColor

QSGMaterialShader.GraphicsPipelineState.SrcAlpha

QSGMaterialShader.GraphicsPipelineState.OneMinusSrcAlpha

QSGMaterialShader.GraphicsPipelineState.DstAlpha

QSGMaterialShader.GraphicsPipelineState.OneMinusDstAlpha

QSGMaterialShader.GraphicsPipelineState.ConstantColor

QSGMaterialShader.GraphicsPipelineState.OneMinusConstantColor

QSGMaterialShader.GraphicsPipelineState.ConstantAlpha

QSGMaterialShader.GraphicsPipelineState.OneMinusConstantAlpha

QSGMaterialShader.GraphicsPipelineState.SrcAlphaSaturate

QSGMaterialShader.GraphicsPipelineState.Src1Color

QSGMaterialShader.GraphicsPipelineState.OneMinusSrc1Color

QSGMaterialShader.GraphicsPipelineState.Src1Alpha

QSGMaterialShader.GraphicsPipelineState.OneMinusSrc1Alpha
class BlendOp

常量

描述

QSGMaterialShader.GraphicsPipelineState.BlendOp.Add

QSGMaterialShader.GraphicsPipelineState.BlendOp.Subtract

QSGMaterialShader.GraphicsPipelineState.BlendOp.ReverseSubtract

QSGMaterialShader.GraphicsPipelineState.BlendOp.Min

QSGMaterialShader.GraphicsPipelineState.BlendOp.Max

在版本6.8中添加。

class ColorMaskComponent

常量

描述

QSGMaterialShader.GraphicsPipelineState.R

QSGMaterialShader.GraphicsPipelineState.G

QSGMaterialShader.GraphicsPipelineState.B

QSGMaterialShader.GraphicsPipelineState.A
class CullMode

常量

描述

QSGMaterialShader.GraphicsPipelineState.CullNone

QSGMaterialShader.GraphicsPipelineState.CullFront

QSGMaterialShader.GraphicsPipelineState.CullBack
class PolygonMode

指定多边形光栅化模式

多边形模式（在Metal中称为三角形填充模式，在D3D中称为填充模式）指定了在光栅化多边形时使用的填充模式。多边形可以绘制为实心（填充），或者作为线框（线）。

警告

OpenGL ES 不支持 Line 多边形模式。无论设置何种多边形模式，OpenGL ES 都会将所有多边形光栅化为填充状态。使用 Line 会使您的应用程序不可移植。

常量

描述

QSGMaterialShader.GraphicsPipelineState.Fill

多边形的内部被填充（默认）

QSGMaterialShader.GraphicsPipelineState.Line

多边形的边界边缘被绘制为线段。
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.blendEnable
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.srcColor
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.dstColor
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.colorWrite
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.blendConstant
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.cullMode
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.polygonMode
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.separateBlendFactors
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.srcAlpha
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.dstAlpha
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.opColor
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.opAlpha