手搓一个带顶点色的QSG自定义Material：从GLSL到Qt Quick渲染管线的完整指南

手搓一个带顶点色的QSG自定义Material：从GLSL到Qt Quick渲染管线的完整指南

在Qt Quick的世界里，Scene Graph（场景图）是渲染引擎的核心架构。对于需要高性能图形渲染的场景，直接操作QSG节点和材质往往能带来更精细的控制和更好的性能表现。本文将带你从零开始，实现一个支持顶点颜色（Vertex Color）的自定义Material，深入剖析QSG渲染管线的每个环节。

1. QSG渲染管线基础

Qt Quick Scene Graph采用基于节点的树状结构来描述UI元素，每个可视元素对应一个QSGNode。当我们需要自定义渲染时，通常需要关注以下几个核心类：

• QSGGeometryNode：包含几何数据（顶点、索引）和材质信息
• QSGGeometry：定义顶点数据的结构和内容
• QSGMaterial：描述物体表面的外观特性
• QSGMaterialShader：实现实际的GLSL着色器代码

与传统的QPainter方式不同，QSG直接工作在OpenGL层面，这要求我们对图形管线有基本了解。一个典型的渲染流程包括：

1. 顶点着色器处理几何数据
2. 图元装配和光栅化
3. 片段着色器计算最终像素颜色
4. 混合输出到帧缓冲区

提示：在QSG中，所有渲染操作都在专门的渲染线程执行，这意味着我们必须在主线程准备好所有渲染数据。

2. 自定义Geometry实现

要实现顶点颜色功能，首先需要定义能够携带颜色信息的顶点结构。Qt提供了QSGGeometry::defaultAttributes_ColoredPoint2D()，但为了更深入理解原理，我们选择自己实现：

class ColoredGeometry : public QSGGeometry { public: struct Vertex { float x, y; uchar r, g, b, a; void set(float nx, float ny, QColor color) { x = nx; y = ny; r = color.red(); g = color.green(); b = color.blue(); a = color.alpha(); } }; static const QSGGeometry::AttributeSet &attributes() { static QSGGeometry::Attribute attr[] = { QSGGeometry::Attribute::create(0, 2, GL_FLOAT, true), // 位置 QSGGeometry::Attribute::create(1, 4, GL_UNSIGNED_BYTE, false) // 颜色 }; static QSGGeometry::AttributeSet set = { 2, sizeof(Vertex), attr }; return set; } ColoredGeometry(int vertexCount) : QSGGeometry(attributes(), vertexCount) {} Vertex *vertexData() { return static_cast<Vertex*>(vertexData()); } };

这个自定义Geometry类具有以下特点：

• 每个顶点包含位置(x,y)和颜色(r,g,b,a)信息
• 使用GL_FLOAT存储位置，GL_UNSIGNED_BYTE存储颜色分量
• 提供了便捷的set方法用于设置顶点属性

3. 实现自定义Material

QSGMaterial负责定义物体表面的外观特性。对于支持顶点颜色的材质，我们需要：

1. 继承QSGMaterial并实现必要接口
2. 提供对应的着色器程序
3. 处理材质状态更新

class VertexColorMaterial : public QSGMaterial { public: QSGMaterialType *type() const override { static QSGMaterialType type; return &type; } QSGMaterialShader *createShader() const override { return new VertexColorShader; } int compare(const QSGMaterial *other) const override { return 0; // 简单实现，所有实例视为相同 } }; class VertexColorShader : public QSGMaterialShader { public: const char *vertexShader() const override { return R"( attribute highp vec4 vertexCoord; attribute highp vec4 vertexColor; uniform highp mat4 matrix; uniform highp float opacity; varying lowp vec4 color; void main() { gl_Position = matrix * vertexCoord; color = vertexColor * opacity; } )"; } const char *fragmentShader() const override { return R"( varying lowp vec4 color; void main() { gl_FragColor = color; } )"; } char const *const *attributeNames() const override { static const char *names[] = { "vertexCoord", "vertexColor", 0 }; return names; } void initialize() override { QSGMaterialShader::initialize(); m_matrix_id = program()->uniformLocation("matrix"); m_opacity_id = program()->uniformLocation("opacity"); } void updateState(const RenderState &state, QSGMaterial *, QSGMaterial *) override { if (state.isMatrixDirty()) program()->setUniformValue(m_matrix_id, state.combinedMatrix()); if (state.isOpacityDirty()) program()->setUniformValue(m_opacity_id, state.opacity()); } private: int m_matrix_id; int m_opacity_id; };

着色器代码中的关键点：

• vertexCoord和vertexColor对应Geometry中的顶点属性
• matrix是QSG自动提供的模型视图投影矩阵
• opacity处理节点的透明度
• 颜色值在顶点着色器中计算后通过varying传递给片段着色器

4. 整合到QQuickItem

最后，我们需要将这些组件整合到一个自定义QQuickItem中：

class ColoredShape : public QQuickItem { Q_OBJECT public: ColoredShape(QQuickItem *parent = nullptr) : QQuickItem(parent) { setFlag(ItemHasContents); } protected: QSGNode *updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *) override { QSGGeometryNode *node = static_cast<QSGGeometryNode*>(oldNode); if (!node) { node = new QSGGeometryNode; auto *geometry = new ColoredGeometry(4); auto *material = new VertexColorMaterial; node->setGeometry(geometry); node->setMaterial(material); node->setFlag(QSGNode::OwnsGeometry); node->setFlag(QSGNode::OwnsMaterial); // 设置顶点数据 auto *v = geometry->vertexData(); v[0].set(0, 0, Qt::red); v[1].set(width(), 0, Qt::green); v[2].set(width(), height(), Qt::blue); v[3].set(0, height(), Qt::yellow); geometry->setDrawingMode(GL_TRIANGLE_FAN); } else { // 更新已有节点的几何数据 auto *geometry = node->geometry(); auto *v = static_cast<ColoredGeometry*>(geometry)->vertexData(); v[1].x = width(); v[2].x = width(); v[2].y = height(); v[3].y = height(); node->markDirty(QSGNode::DirtyGeometry); } return node; } };

关键实现细节：

1. ItemHasContents标志：必须设置这个标志才能启用自定义渲染
2. 节点所有权：通过OwnsGeometry和OwnsMaterial标志管理资源生命周期
3. 脏标记：数据变更后必须调用markDirty()通知渲染线程
4. 绘制模式：支持GL_TRIANGLES、GL_LINES等多种图元类型

5. 性能优化与高级技巧

在实际项目中，我们还需要考虑以下优化点：

5.1 批处理渲染

QSG会自动合并使用相同材质的几何节点，为了最大化批处理效果：

• 尽量复用材质实例
• 避免频繁修改材质状态
• 对静态内容使用QSGGeometry::StaticDrawing

geometry->setDrawingMode(GL_TRIANGLES); geometry->setVertexDataPattern(QSGGeometry::StaticPattern);

5.2 着色器优化

现代GLSL支持更多优化特性：

// 使用精度限定符减少功耗 attribute highp vec4 position; varying mediump vec4 color; // 使用内置函数优化计算 gl_Position = matrix * (position * vec4(1.0, 1.0, 1.0, 1.0));

5.3 动态几何更新

对于频繁变动的几何数据，考虑以下策略：

6. 调试与问题排查

QSG渲染问题通常表现为黑屏或图形异常，常用调试手段包括：

1. 检查OpenGL错误：

GLenum err; while ((err = glGetError()) != GL_NO_ERROR) { qDebug() << "OpenGL error:" << err; }

2. 验证着色器编译：

if (!program()->link()) { qWarning() << "Shader link error:" << program()->log(); }

3. 使用调试工具：

• Qt Creator的Scene Graph调试视图
• OpenGL调试器（如RenderDoc）
• 打印顶点数据验证内容

在实现自定义Material的过程中，最常见的陷阱包括：

• 顶点属性定义与着色器不匹配
• 忘记设置Dirty标记导致更新不生效
• 资源管理不当造成内存泄漏
• 跨线程访问OpenGL资源

7. 实际应用案例

让我们看一个更复杂的例子：实现一个渐变颜色的圆环。这个例子展示了如何：

1. 动态生成几何数据
2. 使用顶点颜色实现平滑渐变
3. 处理抗锯齿边缘

QSGNode *GradientRing::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *) { const int segments = 64; QSGGeometryNode *node = static_cast<QSGGeometryNode*>(oldNode); if (!node) { node = new QSGGeometryNode; auto *geometry = new ColoredGeometry(segments * 2); auto *material = new VertexColorMaterial; node->setGeometry(geometry); node->setMaterial(material); node->setFlag(QSGNode::OwnsGeometry); node->setFlag(QSGNode::OwnsMaterial); } auto *geometry = static_cast<ColoredGeometry*>(node->geometry()); geometry->allocate(segments * 2); const float outer = width() / 2; const float inner = outer * 0.7f; auto *v = geometry->vertexData(); for (int i = 0; i < segments; ++i) { float angle = 2 * M_PI * i / segments; float x = cosf(angle); float y = sinf(angle); QColor outerColor = QColor::fromHsvF(i / float(segments), 1, 1); QColor innerColor = outerColor.darker(150); v[i*2].set(outer + outer*x, outer + outer*y, outerColor); v[i*2+1].set(outer + inner*x, outer + inner*y, innerColor); } geometry->setDrawingMode(GL_TRIANGLE_STRIP); node->markDirty(QSGNode::DirtyGeometry); return node; }

这个实现展示了QSG的强大之处：通过精细控制每个顶点的位置和颜色，我们可以创建出高度定制化的视觉效果，同时保持高效的渲染性能。