QPixmap

一、描述

Qt 提供了四个用于处理图像数据的类：

• QImage 是为 I/O 以及直接像素访问和操作而设计和优化的。
• QPixmap 是为在屏幕上显示图像而设计和优化的。
• QBitmap是一个继承QPixmap的便利类，保证深度为1。如果QPixmap对象确实是位图，isQBitmap()函数返回true，否则返回false。
• QPicture 类是一个绘制设备，用于记录和重放 QPainter 命令。

QPixmap 对象可以通过值传递，因为 QPixmap 类使用隐式数据共享。QPixmap 对象也可以流式传输。

像素图中的像素数据是内部的，由底层窗口系统管理。像素只能通过 QPainter 函数或通过将 QPixmap 转换为 QImage 来访问。

通常，QImage 类用于加载图像文件，并操作图像数据。然后将 QImage 对象转成 QPixmap 对象在屏幕上显示。

1.1、图像文件格式

支持的文件格式的完整列表可通过 QImageReader::supportedImageFormats() 和 QImageWriter::supportedImageFormats() 函数获得。新的文件格式可以作为插件添加。默认情况下，Qt 支持以下格式：

• BMP：（读写）
• GIF：（只读）
• JPG：（读写）
• JPEG：（读写）
• PNG：（读写）
• PBM：（只读）
• PGM：（只读）
• PPM：（读写）
• XBM：（读写）
• XPM：（读写）

二、成员函数

1、QPixmap(const QString &fileName, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

从 fileName 的文件构造像素图。如果文件不存在或格式未知，则像素图变为空像素图。

如果需要修改图像以适应较低分辨率的结果（例如从 32 位转换为 8 位），使用 flags 来控制转换。

enum Qt::ImageConversionFlag：图像转换标志

• Qt::AutoColor：如果图像的深度为 1 并且仅包含黑白像素，则像素图变为单色。
• Qt::ColorOnly：像素图抖动/转换为原生显示深度。
• Qt::MonoOnly：像素图变为单色。如有必要，可使用所选抖动算法对其进行抖动处理。
• Qt::DiffuseDither：使用误差扩散的高质量抖动。
• Qt::OrderedDither： 更快的有序抖动。
• Qt::ThresholdDither：无抖动，使用最接近的颜色。
• Qt::ThresholdAlphaDither：无抖动。
• Qt::OrderedAlphaDither：更快的有序抖动。
• Qt::DiffuseAlphaDither：使用误差扩散的高质量抖动。颜色匹配与抖动偏好：
• Qt::PreferDither：转换为较小的色彩空间时始终抖动图像。
• Qt::AvoidDither：如果源图像使用比目标格式的颜色表的大小更多的不同颜色，则仅对索引格式进行抖动。
• Qt::AutoDither：仅在向下转换为 1 位或 8 位索引格式时进行抖动。
• Qt::NoOpaqueDetection：不检查图像是否包含非不透明像素。如果知道图像是半透明的，并且希望避免在找到非不透明像素之前检查图像中的像素的开销，或者如果希望像素图因某些其他原因保留 alpha 通道，请使用此选项。如果图像没有 Alpha 通道，则此标志无效。
• Qt::NoFormatConversion：不要对图像进行任何格式转换。例如，在将 QImage 转换为 QPixmap 以进行一次性渲染操作时可能很有用。请注意，不是首选格式的 QPixmap 作为绘图设备会慢得多。 

QPixmap(const QSize &size)

构造给定大小的像素图。

这将创建一个带有未初始化数据的 QPixmap。 在使用 QPainter 绘制之前，调用 fill() 用适当的颜色填充像素图。

2、qint64 cacheKey() 

返回标识此 QPixmap 的数字。如果不同的 QPixmap 对象引用相同的内容，则它们具有相同的缓存键。当像素图改变时，cacheKey() 将改变。

3、bool convertFromImage(const QImage &image, Qt::ImageConversionFlags flags = Qt::AutoColor)

使用指定的标志用给定的图像替换此像素图的数据以控制转换。 flags 参数是 Qt::ImageConversionFlags 按位或的结果。如果结果是此像素图不为空，则返回 true。

4、QPixmap copy(const QRect &rectangle = QRect()) 

返回给定矩形指定的像素图子集的深拷贝副本。如果 rectangle 为空，则复制整个图像。

5、QBitmap createHeuristicMask(bool clipTight = true) 

为这个像素图创建并返回一个启发式掩码。

该功能的工作原理是从一个角中选择一种颜色，然后从所有边缘开始切掉该颜色的像素。 如果 clipTight 为 true（默认值），则掩码刚好足以覆盖像素； 否则，掩码大于数据像素。

6、QBitmap createMaskFromColor(const QColor &maskColor, Qt::MaskMode mode = Qt::MaskInColor) 

根据给定的 maskColor 创建并返回此像素图的遮罩。

如果模式为 Qt::MaskInColor，则匹配 maskColor 的所有像素都将是透明的。

如果 mode 是 Qt::MaskOutColor，则匹配 maskColor 的所有像素都将是不透明的。

    QPixmap img("c:\\5.jpg");
    QBitmap map = img.createMaskFromColor(QColor("#050706"),Qt::MaskOutColor);

    QLabel label;
    label.setPixmap(map);
    label.show();

    QBitmap map = img.createMaskFromColor(QColor("#050706"),Qt::MaskInColor);

7、[static] int defaultDepth()

返回应用程序使用的默认像素图深度。实际将返回主屏幕的深度。

 8、int depth() 

返回像素图的深度。

像素图深度也称为每像素位数 (bpp) 或像素图的位平面。空像素图的深度为 0。

9、void detach()

从共享像素图数据中分离像素图。一般不用自己调用。

10、QSizeF deviceIndependentSize() 

返回设备无关的以像素为单位的大小。在用户界面计算图像大小时应使用此值。

返回值等价于 pixmap.size() / pixmap.devicePixelRatio()，

11、qreal devicePixelRatio() 

返回像素图的设备像素比率。这是设备像素和设备独立像素之间的比率。

默认值为 1.0。 

12、void fill(const QColor &color = Qt::white)

用给定的颜色填充像素图。

13、[static] QPixmap fromImage(const QImage &image, Qt::ImageConversionFlags flags = Qt::AutoColor)

       [static] QPixmap fromImage(QImage &&image, Qt::ImageConversionFlags flags = Qt::AutoColor)

QImage 转换为像素图。

对于单色和 8 位图像，图像首先转换为 32 位像素图，然后填充颜色表中的颜色。如果这太昂贵了，可以使用 QBitmap::fromImage() 代替。

14、[static] fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags = Qt::AutoColor)

从直接从 imageReader 读取的图像创建 QPixmap。在某些系统上，将图像直接读取到 QPixmap 可以比读取 QImage 将其转换为 QPixmap 使用更少的内存。

15、bool hasAlpha() 

像素图是否有 alpha 通道或有遮罩。

16、bool hasAlphaChannel() 

像素图的格式是否符合 alpha 通道。

17、bool isNull() 

是否空像素图。空像素图具有零宽度、零高度且没有内容。不能绘制空像素图。

18、bool isQBitmap() 

是否是 QBitmap。

19、bool load(const QString &fileName, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

加载像素图。如果成功加载像素图，则返回 true；否则会使像素图无效并返回 false。

20、bool loadFromData(const uchar *data, uint len, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

       bool loadFromData(const QByteArray &data, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

从二进制数据的前 len 个字节加载像素图。 如果像素图加载成功，则返回 true； 否则会使像素图无效并返回 false。

21、void setMask(const QBitmap &mask)

设置遮罩位图。

此函数将遮罩与像素图的 alpha 通道合并。遮罩上的像素值为 1 表示像素图的像素不变； 值为 0 表示像素是透明的。遮罩必须与此像素图具有相同的大小。

设置空掩码会重置掩码，将之前透明的像素保留为黑色。

在绘制像素图时，此函数的效果未定义。

警告：这可能是一项昂贵的操作。

22、bool save(const QString &fileName, const char *format = nullptr, int quality = -1) 

保存像素图为文件。成功则返回true，否则返回false。

品质因数必须在 [0,100] 或 -1 范围内。 指定 0 获取小型压缩文件，100 获取大型未压缩文件，-1 使用默认设置。

如果 format 为 nullptr，将从 fileName 的后缀中选择一种图像格式。

bool save(QIODevice *device, const char *format = nullptr, int quality = -1)

重载函数。例如，可用于将像素图直接保存到 QByteArray 中：

 QPixmap pixmap;
 QByteArray bytes;
 QBuffer buffer(&bytes);
 buffer.open(QIODevice::WriteOnly);
 pixmap.save(&buffer, "PNG"); // 将像素图以 PNG 格式写入字节数组

23、QPixmap scaled(const QSize &size, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation)

将像素图缩放到给定大小。

如果size为空，则此函数返回一个空像素图。

在某些情况下，使用 QPainter 绘制而不是进行缩放将会有更好的效果。（例如，当 QPainter 基于 OpenGL 或比例因子快速变化时）

enum Qt::AspectRatioMode：此枚举类型定义缩放矩形时纵横比发生的变化。

• Qt::IgnoreAspectRatio：大小自由缩放。不保留纵横比。
• Qt::KeepAspectRatio：在给定的矩形内缩放到尽可能大的矩形，保持纵横比。
• Qt::KeepAspectRatioByExpanding：尺寸被缩放到给定矩形之外的一个尽可能小的矩形，保持纵横比。

enum Qt::TransformationMode：此枚举类型定义图像转换（例如，缩放）是否应该平滑。

• Qt::FastTransformation：变换执行得很快，没有平滑。
• Qt::SmoothTransformation：使用双线性过滤对结果图像进行变换。

24、QPixmap scaledToWidth(int width, Qt::TransformationMode mode = Qt::FastTransformation)

        QPixmap scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation)

返回图像的缩放副本。像素图的高度 / 宽度是自动计算的，以便保留像素图的纵横比。

如果参数1为 0 或负数，则返回空像素图。

25、void scroll(int dx, int dy, const QRect &rect, QRegion *exposed = nullptr)

按 (dx, dy) 滚动此像素图的区域 rect。

exposed 区域保持不变。可以选择将指针传递给空的 QRegion 以获取滚动操作公开的区域。

当像素图上有活动画家时无法滚动。

    QPixmap pixmap("D://eee.jpg");

    QLabel label;
    label.setPixmap(pixmap);
    label.show();

    QRegion exposed;
    pixmap.scroll(100, 100, pixmap.rect(), &exposed);
    QLabel label2;
    label2.setPixmap(pixmap);
    label2.show();

26、void setDevicePixelRatio(qreal scaleFactor)

设置像素图的设备像素比率。这是图像像素与设备无关像素之间的比率。

默认比例因子为 1.0。 将其设置为其他内容有两个效果：

• 在像素图上打开的 QPainter 将被缩放。例如，如果比例为 2.0，则在 200x200 图像上绘制将导致实际上有效绘制边界为 100x100。
• Qt 中根据像素图大小计算布局几何的代码路径将考虑比例：QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio() 这样做的净效果是像素图显示为高 DPI 像素图 而不是一个大的像素图

    QPixmap pixmap("D://eee.jpg");

    QLabel label;
    label.setPixmap(pixmap);
    label.setWindowTitle("label01");
    label.show();

    QPixmap pixmap2 = pixmap;
    pixmap2.setDevicePixelRatio(2);
    QLabel label2;
    label2.setPixmap(pixmap2);
    label2.setWindowTitle("label02");
    label2.show();

    QPixmap pixmap("D://eee.jpg");
    QPixmap pixmap2 = pixmap;

    QPainter p1(&pixmap);
    p1.setPen(Qt::red);
    p1.drawText(100,100,"黄河之水天上来");

    QLabel label;
    label.setPixmap(pixmap);
    label.setWindowTitle("label01");
    label.show();

    pixmap2.setDevicePixelRatio(2);
    QPainter p2(&pixmap2);
    p2.setPen(Qt::red);
    p2.drawText(100,100,"黄河之水天上来");
    QLabel label2;
    label2.setPixmap(pixmap2);
    label2.setWindowTitle("label02");
    label2.show();

 27、QImage toImage() 

将像素图转换为 QImage。 如果转换失败，则返回空图像。

28、QPixmap transformed(const QTransform  &transform, Qt::TransformationMode mode = Qt::FastTransformation) 

变换图像。这个函数很慢，因为它涉及到 QImage 的转换。

29、QVariant operator QVariant() 

以 QVariant 形式返回像素图。

 30、bool operator!()

    QPixmap pixmap("D://eee.jpg");
    if(!pixmap)
    {
    }

三、相关非成员

1、QDataStream & operator<<(QDataStream &stream, const QPixmap &pixmap)

将给定的像素图作为 PNG 图像写入给定的流。

请注意，将流写入文件不会产生有效的图像文件。

    QFile file("file.dat");
    QDataStream stream(&file);
    file.open(QIODevice::WriteOnly);

    QPixmap pixmap("D://eee.jpg");
    stream << pixmap;
    file.close();

2、QDataStream & operator>>(QDataStream &stream, QPixmap &pixmap)

从给定的流中读取图像到给定的像素图。

    QFile file("file.dat");
    file.open(QIODevice::ReadOnly);
    QDataStream stream(&file);
    QPixmap pixmap;
    stream >> pixmap;
    file.close();

    QLabel label;
    label.setPixmap(pixmap);
    label.show();