QPixmap类

注意：该函数是Qt 4.6及以前Qt 3的兼容部分。从4.7版开始提升为官方API状态，以支持更新位图图像，而不创建新的QPixmap（如fromImage()所做）。

另请参阅 fromImage。

QPixmap QPixmap::copy(const QRect &rectangle = QRect()) const

返回由给定 矩形 指定的位图子集的深拷贝。有关深拷贝的更多信息，请参阅隐式数据共享文档。

如果给定的 矩形 为空，则复制整个图像。

另请参阅 operator=，QPixmap 以及 Pixmap Transformations。

QPixmap QPixmap::copy(int x, int y, int width, int height) const

这是一个重载的函数。

返回由矩形 QRect ( x， y， 宽， 高) 指定的像素子集的深拷贝。

QBitmap QPixmap::createHeuristicMask(bool clipTight = true) const

为此位图创建并返回一个启发式遮罩。

该函数通过对一个角落选择一个颜色，然后从所有边缘开始移除该颜色的像素来实现。如果 clipTight 为真（默认值），则遮罩仅覆盖像素；否则，遮罩大于数据像素。

遮罩可能不是完美的，但应该是合理的，因此您可以执行以下操作

QPixmap myPixmap;
myPixmap.setMask(myPixmap.createHeuristicMask());

此函数较慢，因为它涉及到将 QImage 转换为/从，以及非平凡的运算。

另请参阅 QImage::createHeuristicMask() 和 createMaskFromColor。

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

基于给定的 maskColor 创建并返回一个遮罩。如果 mode 是 Qt::MaskInColor，则所有匹配 maskColor 的像素将是透明的。如果 mode 为 Qt::MaskOutColor，则所有匹配 maskColor 的像素将是完全不透明的。

此函数较慢，因为它涉及到将 QImage 转换为/从。

另请参阅 createHeuristicMask() 和 QImage::createMaskFromColor。

[静态] int QPixmap::defaultDepth()

返回应用程序使用的默认图深度。

在所有平台上，将返回主屏幕的深度。

另请参阅 depth()，QColormap::depth()，以及Pixmap Information。

int QPixmap::depth() const

返回图深的值。

图深度也称为每像素比特数（bpp）或图的位平面。空像素具有深度0。

另请参阅 defaultDepth()和Pixmap Information。

void QPixmap::detach()

将图从共享图数据中分离。

当图的内容将要更改时，Qt会自动分离图。这几乎在所有修改图的成员函数中都会进行（如fill()，fromImage()，load()等），以及在图上的QPainter::begin()中。

有两次异常情况必须显式调用detach()，即在调用handle()或x11PictureHandle()函数时（仅在X11上可用）。否则，使用系统调用进行的任何修改将作用于共享数据。

如果只有一个引用或图尚未初始化，则detach()函数将立即返回。

[自 6.2] QSizeF QPixmap::deviceIndependentSize() const

以设备无关像素为单位返回图的大小。

使用用户界面大小计算时，应使用此值。

返回值等同于 pixmap.size() / pixmap.devicePixelRatio。

此函数是在Qt 6.2中引入的。

qreal QPixmap::devicePixelRatio() const

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

当根据图大小计算布局几何形状时，请使用此函数：QSize layoutSize = image.size() / image.devicePixelRatio()

默认值为1.0。

另请参阅 setDevicePixelRatio()和QImageReader。

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

使用指定的颜色填充图。

当图正在绘画时，此函数的效果是未定义的。

另请参阅 Pixmap Transformations。

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

使用指定的 标志 控制转换，将给定的 图像 转换为位图。标志参数是 Qt::ImageConversionFlags 的按位或。如果 标志 为 0，则设置所有默认选项。

对于单色和 8 位图像，图像首先转换为 32 位位图，然后使用调色板中的颜色填充。如果此操作过于昂贵，您可以改用 QBitmap::fromImage。

另请参阅 fromImageReader，toImage 和 位图转换。

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

这是一个重载的函数。

如果可能，将给定的 图像 转换为位图而不进行复制。

[静态] QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags = Qt::AutoColor)

从图像读取器直接读取图像以创建 QPixmap。标志参数是 Qt::ImageConversionFlags 的按位或。如果标志参数为 0，则设置所有默认选项。

在某些系统上，直接读取图像到 QPixmap 可能比读取 QImage 转换为 QPixmap 使用更少的内存。

另请参阅 fromImage，toImage 和 位图转换。

bool QPixmap::hasAlpha() const

如果此位图具有通道alpha，或具有掩码，则返回 true，否则返回 false。

另请参阅 hasAlphaChannel() 和 mask。

bool QPixmap::hasAlphaChannel() const

如果位图具有支持alpha通道的格式，则返回 true，否则返回 false。

另请参阅 hasAlpha。

int QPixmap::height() const

返回位图的高度。

另请参阅 size() 和 位图信息。

bool QPixmap::isNull() const

如果这是空位图，则返回 true；否则返回 false。

空位图的宽度为零，高度为零，内容为零。您不能在空位图中绘图。

bool QPixmap::isQBitmap() const

如果这是 QBitmap，则返回 true；否则返回 false。

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

从指定的文件名 fileName 加载位图。如果位图加载成功，则返回 true；否则，使位图无效并返回 false。

加载器尝试使用指定的 format 读取 pixmap。如果未指定 format（这是默认情况），加载器将检查文件头以猜测文件格式。

文件名可以指向磁盘上的实际文件，也可以指向应用程序的嵌入资源之一。有关如何在应用程序的可执行文件中嵌入位图和其他资源文件的详细信息，请参阅 资源系统 概述。

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

注意，当从主线程文件加载位图时，QPixmap 会自动添加到 QPixmapCache；用于的键是内部的，无法获得。

另请参阅loadFromData() 和 读写图像文件。

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

从给定的二进制 data 的前 len 个字节加载位图。如果位图加载成功，则返回 true；否则，使位图无效并返回 false。

加载器尝试使用指定的 format 读取 pixmap。如果未指定 format（这是默认情况），加载器将检查文件头以猜测文件格式。

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

另请参阅load() 和 读写图像文件。

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

这是一个重载的函数。

使用指定的 format 和转换 flags 从二进制 data 加载位图。

QBitmap QPixmap::mask() const

从位图的颜色通道中提取位图掩码。

另请参阅setMask() 和 位图信息。

QRect QPixmap::rect() const

返回位图的外接矩形。

另请参阅位图信息。

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

使用指定的图像文件 format 和 quality 因子将位图保存到具有给定 fileName 的文件中。如果成功，则返回 true；否则返回 false。

quality 因子必须在 [0,100] 范围内或 -1。指定 0 以获得小型压缩文件，100 对于大型未压缩文件，-1 使用默认设置。

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

另请参阅读取和写入图像文件。

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

这是一个重载的函数。

此函数使用指定的图像文件格式和质量因素，将QPixmap写入给定的设备。这可以用于，例如，直接将 pixmap 保存到QByteArray。

QPixmap pixmap;
QByteArray bytes;
QBuffer buffer(&bytes);
buffer.open(QIODevice::WriteOnly);
pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format

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

根据由aspectRatioMode和transformMode指定的纵横比和变换模式，将 pixmap 缩放到给定的大小。

• 如果aspectRatioMode是Qt::IgnoreAspectRatio，则 pixmap 会被缩放到大小。
• 如果aspectRatioMode是Qt::KeepAspectRatio，则 pixmap 会被缩放到尽可能大的矩形中，但保留大小内的纵横比。
• 如果aspectRatioMode是Qt::KeepAspectRatioByExpanding，则 pixmap 会被缩放到尽可能小的矩形中，但保持纵横比，超出大小。

如果给定的大小是空的，这个函数将返回一个空 pixmap。

在某些情况下，将 pixmap 绘制到设置缩放的画家而不是缩放 pixmap 可能更有益。当画家是基于 OpenGL 或缩放因子快速变化时，这种情况会出现。

另请参阅isNull() 和 Pixmap 变换。

QPixmap QPixmap::scaled(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

这是一个重载的函数。

返回一个缩放后的 pixmap 的副本，其大小是根据给定的宽度和高度按照给定的纵横比模式和变换模式计算的。

如果宽度和高度中的任何一个为零或负数，这个函数将返回一个空 pixmap。

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

返回一个缩放后的图像副本。返回的图像是使用指定的变换模式缩放到给定的高度的。pixmap 的宽度会自动计算，以保证 pixmap 的纵横比。

如果高度为 0 或负数，将返回一个空 pixmap。

另请参阅isNull() 和 Pixmap 变换。

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

返回一个缩放后的图像副本。返回的图像是按照指定的变换模式缩放到给定的宽度的。pixmap 的高度会自动计算，以保证 pixmap 的纵横比。

如果宽度为 0 或负数，将返回一个空 pixmap。

另请参阅isNull() 和 Pixmap 变换。

void QPixmap::scroll(int dx, int dy, int x, int y, int 宽度, int 高度, QRegion *暴露 = nullptr)

此便利函数等同于调用 QPixmap::scroll(dx, dy, QRect(x, y, 宽度, 高度), 暴露).

另请参阅QWidget::scroll() 和 QGraphicsItem::scroll().

void QPixmap::scroll(int dx, int dy, const QRect &矩形, QRegion *暴露 = nullptr)

通过 (dx, dy) 滚动此位图的 矩形 区域。暴露区域保持不变。您可以可选地传递一个空的 QRegion 指针以获取滚动操作暴露的 暴露 区域。

QPixmap pixmap("background.png");
QRegion exposed;
pixmap.scroll(10, 10, pixmap.rect(), &exposed);

在位图上有活动的画家时不能滚动。

另请参阅QWidget::scroll() 和 QGraphicsItem::scroll().

void QPixmap::setDevicePixelRatio(qreal scaleFactor)

设置位图的设备像素缩放比。这是图像像素和设备无关像素之间的比例。

默认的 scaleFactor 是 1.0。将其设置为其它的两个效果是

在位图上打开的 QPainters 将被缩放。例如，如果在 200x200 的图像上以 2.0 的比例绘制，则结果将是 100x100 的有效（设备无关）绘制边界。

Qt 中根据位图大小计算布局几何形状的代码路径将考虑该比例：QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio()。这种效果的净结果是位图以高DPI位图的形式显示，而不是大型位图（请参阅 绘制高分辨率位图和图像版本）。

另请参阅devicePixelRatio() 和 deviceIndependentSize().

void QPixmap::setMask(const QBitmap &mask)

设置掩码位图。

此函数将 mask 与位图的alpha通道合并。掩码中的像素值 1 表示位图的像素保持不变；值为 0 表示像素是透明的。掩码的大小必须与此位图相同。

设置空掩码将重置掩码，使先前透明的像素变为黑色。当在位图上绘画时，此函数的效果是未定义的。

另请参阅mask()、Pixmap 变换 和 QBitmap。

QSize QPixmap::size() const

返回位图的大小。

另请参阅width()、height() 和 Pixmap 信息。

[noexcept] void QPixmap::swap(QPixmap &other)

与当前位图交换 other 位图。此操作非常快且永远不会失败。

QImage QPixmap::toImage() const

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

如果像素绘图有1位深度，则返回的图像也将是1位深度。更多位的图像将以最接近底层系统的格式返回。通常对于带有alpha通道的像素绘图是QImage::Format_ARGB32_Premultiplied，对于没有alpha通道的像素绘图是QImage::Format_RGB32或QImage::Format_RGB16。

注意，目前对于单色图像，忽略alpha蒙版。

另请参阅fromImage()和图像格式。

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

返回一个副本的像素绘图，它使用给定的变换transform和变换mode来变换。原始像素绘图不改变。

变换transform在内部调整以补偿不希望的平移；即生成的像素绘图是最小的像素绘图，包含原始像素绘图的所有变换点。使用trueMatrix()函数检索用于变换像素的实际矩阵。

此函数速度较慢，因为它涉及到将像素绘图转换成QImage，进行非平凡的计算，并将像素绘图转换回QPixmap。

另请参阅trueMatrix()和像素变换。

[静态] QTransform QPixmap::trueMatrix(const QTransform &matrix, int width, int height)

返回用于以给定width、height和matrix变换像素的实际矩阵。

使用transformed()函数变换像素时，变换矩阵在内部调整以补偿不希望的平移，即transformed()返回包含原始像素绘图所有变换点的最小像素绘图。此函数返回修改后的矩阵，它将原始像素绘图中的点正确映射到新像素绘图。

另请参阅transformed()和像素变换。

int QPixmap::width() const

返回像素绘图宽度。

另请参阅 size() 和 位图信息。

QVariant QPixmap::operator QVariant() const

将像素绘图作为QVariant返回。

bool QPixmap::operator!() const

如果这是空位图，则返回 true；否则返回 false。

另请参阅isNull。

QPixmap &QPixmap::operator=(const QPixmap &pixmap)

将给定的 pixmap 分配给此 pixmap 并返回对此 pixmap 的引用。

另请参阅复制() 和 QPixmap。

[noexcept] QPixmap &QPixmap::operator=(QPixmap &&other)

将 other 移赋给此 QPixmap 实例。