QC++ / Qt 学习之路

绘图系统 QPainter

QPainter 绘制、坐标变换与 GraphicsView

进阶第 29 / 48 章第四篇 · Qt 进阶

#三层架构:QPaintDevice / QPainter / QPaintEngine

Qt 的绘图系统是一个经典的三层设计,理解它你就明白了为什么"同一段绘制代码"能输出到窗口、图片、打印机、PDF:

层类职责
绘制设备QPaintDevice能被画的东西:QWidget、QPixmap、QImage、QPrinter…
画笔QPainter你唯一需要打交道的 API:drawLine()、drawText()…
绘制引擎QPaintEngine把 QPainter 的指令翻译成具体设备的原生命令

QPaintEngine 对应用开发者几乎不可见,但它是"一次编写、到处绘制"的关键。你调用 painter.drawRect(),在屏幕上它变成系统的 GDI/Direct2D 调用,在 PDF 上变成一段矢量指令,在 QImage 上变成像素运算——你的代码一行都不用改。

这意味着一个重要的实践:把绘制逻辑写成"与设备无关"的代码,只依赖传入的 QPainter 和 rect(),这样同一份代码可以直接用于屏幕渲染和导出高清图片。

#坐标系统与变换

Qt 的坐标原点在左上角,x 向右为正,y 向下为正(与数学坐标相反,和绝大多数 GUI 框架一致)。

QPainter 坐标系与变换默认原点在左上角:x 向右为正,y 向下为正;变换改变的是坐标系本身默认坐标系原点 (0,0) 在左上角,x →,y ↓xyQt(18,18)painter.drawRect(18, 18, 80, 48);未做任何变换,坐标即窗口像素坐标translate(100,80) + rotate(30) 之后先平移再旋转,图形随之移动并倾斜xyQt(18,18)painter.translate(100, 80);painter.rotate(30); // 顺时针 30 度painter.save()translate / rotate修改变换矩阵painter.restore()save() 与 restore() 必须成对出现:restore() 后坐标系回到 save() 那一刻的状态
QPainter 默认坐标系与变换后的坐标系

QPainter 内置一个变换矩阵,提供了四个常用操作。理解它们的关键在于:变换是累积的,且作用顺序与调用顺序相反(矩阵右乘)。

方法作用常见用途
translate(dx, dy)平移原点把原点移到控件中心,方便画极坐标图形
scale(sx, sy)缩放绘制缩略图、翻转(负值)
rotate(deg)顺时针旋转仪表指针、刻度
shear(sh, sv)错切斜体效果,少用

黄金搭档是 save() / restore():绘制前 save() 保存矩阵与画笔画刷状态,绘制后 restore() 恢复。它们必须成对出现,否则绘制状态会"泄漏"到后续代码,产生极难排查的错位 bug。

C++
// 自定义控件:绘制时钟表盘
#include <QWidget>
#include <QPainter>
#include <QPaintEvent>
#include <QTime>
#include <cmath>

// 该类在 paintEvent 中绘制一个圆形表盘
class ClockWidget : public QWidget
{
    Q_OBJECT
public:
    explicit ClockWidget(QWidget *parent = nullptr) : QWidget(parent)
    {
        setMinimumSize(200, 200);
    }

protected:
    void paintEvent(QPaintEvent *) override
    {
        QPainter p(this);
        p.setRenderHint(QPainter::Antialiasing, true);   // 抗锯齿

        const qreal side = qMin(width(), height());
        const QPointF center(width() / 2.0, height() / 2.0);

        p.save();
        p.translate(center);                             // 原点移到中心
        p.scale(side / 200.0, side / 200.0);             // 归一化到 200×200 逻辑坐标

        // 表盘背景
        p.setPen(Qt::NoPen);
        p.setBrush(QColor("#ffffff"));
        p.drawEllipse(QPointF(0, 0), 100, 100);

        // 12 个刻度
        for (int i = 0; i < 12; ++i) {
            p.save();
            p.rotate(i * 30.0);                          // 每次绕新原点旋转
            p.setPen(QPen(QColor("#333333"), (i % 3 == 0) ? 3 : 1));
            p.drawLine(QPointF(0, -88), QPointF(0, -96));
            p.restore();                                 // 恢复,避免累积旋转
        }

        const QTime now = QTime::currentTime();

        // 时针
        p.save();
        p.rotate(30.0 * (now.hour() % 12) + 0.5 * now.minute());
        p.setPen(QPen(QColor("#1a1a1a"), 6, Qt::SolidLine, Qt::RoundCap));
        p.drawLine(QPointF(0, 0), QPointF(0, -45));
        p.restore();

        // 分针
        p.save();
        p.rotate(6.0 * now.minute() + 0.1 * now.second());
        p.setPen(QPen(QColor("#444444"), 3, Qt::SolidLine, Qt::RoundCap));
        p.drawLine(QPointF(0, 0), QPointF(0, -72));
        p.restore();

        p.restore();                                     // 与外层 save 配对
    }
};

这个例子展示了变换的精髓:先 translate 到中心,再用逻辑坐标(半径 100)绘图,最后用 scale 适配实际控件尺寸。这样无论控件多大,绘制代码都不用改——这是自绘控件适应 DPI 缩放和窗口拉伸的标准做法。

注意循环里的 save()/restore() 包住了 rotate()。如果省掉,12 次旋转会累积(0°、30°、60°…360°),刻度会 spiral 出去。

#抗锯齿的代价

QPainter::Antialiasing 让边缘平滑,但代价是性能下降,尤其在低端设备或大面积绘制时。建议:

  • 静态内容、图表、文字:开启;
  • 高速刷新的波形、实时曲线:关闭或用 QPainter::Antialiasing 配合脏矩形优化;
  • 文字另有 QPainter::TextAntialiasing。

#画笔、画刷与渐变

QPen 管线条,QBrush 管填充。渐变是让界面"有质感"的性价比最高的手段。

C++
#include <QPainter>
#include <QLinearGradient>
#include <QRadialGradient>
#include <QConicalGradient>

void drawGradients(QPainter &p, const QRect &rect)
{
    // 线性渐变:沿对角线从蓝到紫
    QLinearGradient lg(rect.topLeft(), rect.bottomRight());
    lg.setColorAt(0.0, QColor("#4facfe"));
    lg.setColorAt(1.0, QColor("#7c3aed"));
    p.setPen(Qt::NoPen);
    p.setBrush(lg);
    p.drawRoundedRect(rect.adjusted(10, 10, -10, -10), 12, 12);

    // 径向渐变:模拟高光球体
    QRadialGradient rg(rect.center(), rect.width() / 4.0);
    rg.setColorAt(0.0, QColor(255, 255, 255, 200));
    rg.setColorAt(1.0, QColor(255, 255, 255, 0));
    p.setBrush(rg);
    p.drawEllipse(rect.center(), rect.width() / 4, rect.height() / 4);

    // 锥形渐变:适合做色环、仪表盘
    QConicalGradient cg(rect.center(), 90);
    cg.setColorAt(0.0, QColor("#ff6b6b"));
    cg.setColorAt(0.5, QColor("#feca57"));
    cg.setColorAt(1.0, QColor("#ff6b6b"));
    p.setBrush(cg);
    p.drawEllipse(rect.center(), 60, 60);

    // 画笔:虚线、端点、连接样式
    p.setBrush(Qt::NoBrush);
    p.setPen(QPen(QColor("#2d7ff9"), 2, Qt::DashLine, Qt::RoundCap, Qt::RoundJoin));
    p.drawRect(rect.adjusted(4, 4, -4, -4));
}

三种渐变各有主场:QLinearGradient 用于按钮、面板背景;QRadialGradient 用于高光、聚光效果;QConicalGradient 用于色环、旋钮。渐变坐标默认使用逻辑坐标,会跟随 QPainter 的变换,这点与 CSS 渐变(相对元素盒子)不同,要留意。

#绘制文本与图片

C++
#include <QPainter>
#include <QFontMetrics>
#include <QPixmap>

void drawTextAndImage(QPainter &p, const QRect &rect, const QPixmap &logo)
{
    QFont f = p.font();
    f.setPixelSize(16);
    f.setBold(true);
    p.setFont(f);
    p.setPen(QColor("#1a1a1a"));

    // 单行文本:指定对齐与区域
    p.drawText(rect, Qt::AlignLeft | Qt::AlignVCenter, "Qt 绘图系统");

    // 文本省略:用 QFontMetrics 手动裁剪
    QFontMetrics fm(f);
    QString elided = fm.elidedText("这是一段很长的标题文字需要省略",
                                   Qt::ElideRight, 200);
    p.drawText(rect.adjusted(0, 24, 0, 0), Qt::AlignLeft, elided);

    // 图片:保持宽高比缩放绘制
    QPixmap scaled = logo.scaled(64, 64, Qt::KeepAspectRatio,
                                 Qt::SmoothTransformation);
    p.drawPixmap(rect.topRight() - QPoint(scaled.width() + 8, -8), scaled);
}

Qt::SmoothTransformation 会做双线性插值,缩略图质量明显好于默认的 FastTransformation,代价是慢;只在最终显示时用,拖动过程中可用快速模式。

#QPixmap / QImage / QPicture 怎么选

这三个类都能"装图",但定位完全不同,选错会严重影响性能:

类存储位置优化方向用途
QPixmap显存(平台相关)绘制快界面上显示的一切:图标、背景、截图
QImage内存(与平台无关)像素访问快读写像素、图像处理、算法、跨平台 IO
QPicture指令序列回放绘制记录 QPainter 指令并重复播放
QSvgRenderer矢量指令无损缩放图标、可缩放图形

判断口诀:要"画"用 QPixmap,要"算"用 QImage。一个典型错误是在循环里对 QPixmap 逐个像素操作——每次 toImage() 和 fromImage() 都是一次昂贵的格式转换。

#双缓冲:为什么 Qt 里很少手动写

双缓冲的思路是"先在离屏画布上画完,再一次性贴到屏幕",目的是消除闪烁。在 Qt 中:

  • Qt 4 之后,QWidget 默认就是双缓冲的(Qt::WA_PaintOnScreen 关闭时),你直接在 paintEvent 里画,Qt 自动缓冲。
  • 需要手动双缓冲的场景是:绘制极耗时且频繁刷新(如示波器)。做法是维护一个 QPixmap m_buffer,在 paintEvent 中只 drawPixmap(),真正的绘制在别处更新 buffer。
C++
#include <QWidget>
#include <QPixmap>
#include <QPainter>

class WaveWidget : public QWidget
{
    Q_OBJECT
public:
    explicit WaveWidget(QWidget *parent = nullptr) : QWidget(parent) {}

    void appendSample(double v)
    {
        m_samples.append(v);
        if (m_samples.size() > width()) {
            m_samples.removeFirst();
        }
        renderBuffer();      // 只在数据变化时重绘缓冲区
        update();            // 然后请求一次轻量贴图
    }

protected:
    void paintEvent(QPaintEvent *) override
    {
        QPainter p(this);
        p.drawPixmap(0, 0, m_buffer);       // 极快:一次位块传输
    }

    void resizeEvent(QResizeEvent *e) override
    {
        QWidget::resizeEvent(e);
        m_buffer = QPixmap(size());
        m_buffer.fill(Qt::black);
        renderBuffer();
    }

private:
    void renderBuffer()
    {
        if (m_buffer.isNull()) {
            return;
        }
        m_buffer.fill(Qt::black);
        QPainter bp(&m_buffer);
        bp.setPen(QPen(QColor("#3ecf8e"), 1.5));
        for (int i = 1; i < m_samples.size(); ++i) {
            const double y1 = height() / 2.0 - m_samples.at(i - 1) * height() / 2.0;
            const double y2 = height() / 2.0 - m_samples.at(i)     * height() / 2.0;
            bp.drawLine(QPointF(i - 1, y1), QPointF(i, y2));
        }
    }

    QList<double> m_samples;
    QPixmap       m_buffer;
};

这个模式把"昂贵绘制"和"廉价刷新"解耦:数据每秒来 60 次就画 60 次 buffer,但界面重绘(比如被其他窗口遮挡后恢复)只是贴图,几乎零成本。

#Graphics View 框架入门

QPainter 直接绘制有个致命问题:没有对象概念。你画了 100 个圆,想让用户拖动第 37 个,就得自己写命中检测、自己管 Z 序、自己处理局部刷新。Graphics View 就是为解决这个而生的,它采用 Scene-View-Item 三层:

QGraphicsView 三件套:View / Scene / Item场景管数据,视图管显示,图元是可绘制对象QGraphicsView视口 viewportA只显示场景的一部分可滚动 / 缩放 / 旋转QGraphicsScene无限大场景坐标,无像素边界视口可见区域场景管理所有 Item 的层级、选中与碰撞QGraphicsItem 派生类QGraphicsRectItemQGraphicsEllipseItemQGraphicsTextItem自定义 Item需重写 paint() 与 boundingRect()三种坐标系:图元坐标 / 场景坐标 / 视图坐标view->mapToScene(viewPos); // 视图坐标 → 场景坐标view->mapFromScene(scenePos); // 场景坐标 → 视图坐标item->mapToScene(itemPos); // 图元坐标 → 场景坐标场景负责存放与管理 Item,视图只负责显示与交互;一个场景可被多个视图同时显示
QGraphicsView 场景—视图—图元三层结构
层类职责
场景QGraphicsScene容纳图元的容器,管理 Z 序、碰撞、选中、索引
视图QGraphicsView显示窗口,负责滚动、缩放、坐标变换、事件分发
图元QGraphicsItem场景中的一个对象,自己知道怎么画、怎么碰撞

坐标系统也分三层:图元坐标 → 场景坐标 → 视图坐标,各有 mapToScene() / mapFromScene() 等转换函数。

C++
#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsItem>
#include <QGraphicsSceneMouseEvent>
#include <QPainter>
#include <QRandomGenerator>
#include <QDebug>

class NodeItem : public QGraphicsItem
{
public:
    explicit NodeItem(const QString &label) : m_label(label)
    {
        setFlag(ItemIsMovable, true);            // 允许拖动
        setFlag(ItemIsSelectable, true);         // 允许选中
        setFlag(ItemSendsGeometryChanges, true); // 位置变化时通知
        setZValue(1);
    }

    QRectF boundingRect() const override
    {
        return {-40, -20, 80, 40};               // 必须覆盖所有绘制内容
    }

    void paint(QPainter *p, const QStyleOptionGraphicsItem *, QWidget *) override
    {
        p->setRenderHint(QPainter::Antialiasing);
        p->setPen(QPen(isSelected() ? QColor("#2d7ff9") : QColor("#8892a0"), 2));
        p->setBrush(QColor("#ffffff"));
        p->drawRoundedRect(boundingRect(), 6, 6);
        p->setPen(QColor("#1a1a1a"));
        p->drawText(boundingRect(), Qt::AlignCenter, m_label);
    }

protected:
    // 碰撞:用椭圆区域而非矩形,更贴合视觉
    QPainterPath shape() const override
    {
        QPainterPath path;
        path.addRoundedRect(boundingRect(), 6, 6);
        return path;
    }

    QVariant itemChange(GraphicsItemChange change, const QVariant &value) override
    {
        if (change == ItemPositionChange && scene()) {
            qDebug() << "移动到" << value.toPointF();  // 可在此做吸附/边界限制
        }
        return QGraphicsItem::itemChange(change, value);
    }

private:
    QString m_label;
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    auto *scene = new QGraphicsScene(-200, -150, 400, 300);

    for (int i = 0; i < 6; ++i) {
        auto *node = new NodeItem(QString("节点 %1").arg(i + 1));
        node->setPos(QRandomGenerator::global()->bounded(-150, 150),
                     QRandomGenerator::global()->bounded(-100, 100));
        scene->addItem(node);
    }

    auto *view = new QGraphicsView(scene);
    view->setRenderHint(QPainter::Antialiasing);
    view->setDragMode(QGraphicsView::RubberBandDrag);  // 框选
    view->setViewportUpdateMode(QGraphicsView::SmartViewportUpdate);
    view->resize(640, 480);
    view->show();

    // 碰撞检测示例:找出与第一个图元相交的所有图元
    auto *first = scene->items().constFirst();
    const QList<QGraphicsItem *> hits = scene->collidingItems(first);
    qDebug() << "与首个节点碰撞的图元数:" << hits.size();

    return app.exec();
}

几个关键点:

  • boundingRect() 必须完整包含所有绘制内容,返回小了会导致残影(重绘区域不够);返回过大会降低性能。
  • shape() 可选,不实现就用 boundingRect()。实现它可以让碰撞和点击更精确。
  • setFlag(ItemIsMovable) 一行就让图元可拖动,这是 Graphics View 相对裸 QPainter 最大的价值。
  • 图元的 paint() 使用图元局部坐标,原点通常设为图元中心,这样旋转时自然绕中心转。

#该用 QPainter 还是 Graphics View

需求选择
固定图表、仪表盘、自定义控件外观QPainter + paintEvent
大量可交互、可移动、可缩放的图元Graphics View
需要打印/导出同样内容两者都行,Graphics View 有 scene->render(&painter)
对性能要求极端(百万点)手写 QPainter + 脏矩形

Qt 5 提示:Qt 6 中 QGraphicsView 的绘制后端改为默认使用 OpenGL/软件光栅的自适应选择,API 基本不变。差异点:Qt 6 移除了 QPainter::HighQualityAntialiasing(已废弃),统一使用 QPainter::Antialiasing;boundingRect() 的返回类型在两代中均为 QRectF。

#小结

  1. 绘图三层架构是 QPaintDevice(设备)/ QPainter(API)/ QPaintEngine(翻译),带来"一次编写、到处绘制"的能力。
  2. 坐标变换是累积的,translate + 逻辑坐标 + scale 是自绘控件适配尺寸与 DPI 的标准范式;save()/restore() 必须成对。
  3. QPixmap 为显示优化(显存),QImage 为像素访问优化(内存)——要"画"用 QPixmap,要"算"用 QImage。
  4. QWidget 默认已双缓冲,仅在高频重绘时才需要手动维护 QPixmap 缓冲区。
  5. Graphics View 用 Scene/View/Item 三层提供对象化图元、自动命中检测、Z 序与缩放,适合交互式图形编辑器。

#练习

  1. 完善 ClockWidget:让秒针每秒走动(QTimer 1000ms),并添加刻度数字 1~12。
  2. 用 QImage 实现一个简单的灰度化函数,比较在 QImage 和 QPixmap 上逐像素操作的性能差异(QElapsedTimer)。
  3. 用 QGraphicsView 实现一个可拖拽连线的简易流程图:继承 QGraphicsItem 画节点,用 QGraphicsLineItem 连接两个节点,拖动节点时更新连线端点。
  4. 给第 3 题的图元实现 mousePressEvent 选中、hoverEnterEvent 高亮,并用 QGraphicsScene::collidingItems() 检测节点重叠并标红。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。