Qt5.7文档翻译：QImage类,QImage Class

QImage 类提供了一种与硬件无关的图像表示手段，可以直接访问到具体的像素数据，也可以用作一个绘制设备。 详细说明……

注意 ： 这个类中的所有函数都是 可重入的 。

详细说明

QImage 类提供了一种与硬件无关的图像表示手段，可以直接访问到具体的像素数据，也可以用作一个绘制设备。

Qt提供 了四种用来处理图像数据的类： QImage 、 QPixmap 、 QBitmap 和 QPicture 。 QImage 是专为输入/输出而设计并且优化的， 可用于直接访问及操作单个像素， 而 QPixmap 是专为在屏幕上显示图像而设计并优化的。 QBitmap 只是 一个继承了 QPixmap 的便利类， 它能确保位深是1 。 最后 一个， QPicture 类是一个绘图设备，它会记录并回放 QPainter 命令。

因为QImage 是一个 QPaintDevice 子类，所以 可使用 QPainter 来直接向图片中画图。 当妳在 QImage 上使用 QPainter 时，可以在图形界面线程以外的线程来进行绘图操作。

QImage 类支持多种图片格式，它们 由 Format 枚举量来列举。其中包括单色 位图、8位、32位和带透明通道的图片格式，这些格式在 Qt 4.x 的所有版本中都被支持。

QImage提供 了一组函数，可用来获取该图片的一系列信息。另外有一些函数可用于将图片进行变换。

QImage对象 可以以传值的方式来到处传递，因为QImage 类使用了 隐 式数据共享 技术。 QImage对象 还可以被进行流式处理，可以进行比较。

注意 ： 如果 妳想要在静态编译的Qt 版本里载入QImage 对象的话，参考 如何处理插件 。

警告： 现在 不支持以 QImage::Format_Indexed8 格式在 QImage 上绘图。

读取及写入图片文件

QImage提供 了多种手段来载入一个图片文件：文件 可在构造QImage 对象 时就载入， 也可以稍后使用 load ()或 loadFromData ()函数来载入。 QImage 还提供了静态的 fromData ()函数， 可从给定的数据中构造出一个QImage。 在载入一个图片时，文件 名可以指向硬盘 上的一个真正文件，也可以指向程序 的嵌入资源中的某个文件。参考 Qt资源系统 概述， 以了解如何 向程序的可执行程序中嵌入图片及其它资源文件。

直接调用 save ()函数 就可以保存此QImage 对象。

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

图片信息

QImage提供 了大量函数，可用于获取该图片的各种信息：

像素操作

用来操作 一 张 图片中的像素的那些函数，取决于该图片的格式。原因 是，单色位图和8位的图片都使用 了颜色查找表，而32位的图片是直接储存颜色（ARGB）值的。参考 图片格式 小节 ，以了解更多关于图片格式的信息。

对于 32位的图片， 可用 setPixel ()函数 来将指定坐标的像素的颜色改变成任意 一个以ARGB 四元组表示的颜色。 要想创建一个适当的 QRgb 值的话， 就使用 qRgb ()（ 向指定的红绿蓝（ RGB ）值中添加一个默认的透明度分量，也就是说，创建一个完全不透明的颜色 ）或 qRgba ()函数。 例如：

32位
	QImage image(3, 3, QImage ::Format_RGB32); QRgb value; value = qRgb (189, 149, 39); // 0xffbd9527 image.setPixel(1, 1, value); value = qRgb (122, 163, 39); // 0xff7aa327 image.setPixel(0, 1, value); image.setPixel(1, 0, value); value = qRgb (237, 187, 51); // 0xffedba31 image.setPixel(2, 1, value);

对于 8位的和单色位图，像素 的值只是图片的颜色表中的一个索引。所以 ， setPixel ()函数只能用来 将指定坐标处的像素的颜色设置成图片的颜色表中的某个预设颜色， 也就是说，它只能改变该像素的索引值。 要想改变某个颜色或者向图片的颜色表中加入新的颜色，就使用 setColor ()函数。

颜色 表中的条目都是一个透红绿蓝（ARGB）四元组，编码为一个 QRgb 值的形式。使用 qRgb () 和 qRgba ()函数来产生适当的 QRgb 值，再用于 setColor ()函数中。例如：

8位
	QImage image(3, 3, QImage ::Format_Indexed8); QRgb value; value = qRgb (122, 163, 39); // 0xff7aa327 image.setColor(0, value); value = qRgb (237, 187, 51); // 0xffedba31 image.setColor(1, value); value = qRgb (189, 149, 39); // 0xffbd9527 image.setColor(2, value); image.setPixel(0, 1, 0); image.setPixel(1, 0, 0); image.setPixel(1, 1, 2); image.setPixel(2, 1, 1);

对于那些单个颜色通道 的数值超过 8 位的图片。 可使用 setPixelColor ()和 pixelColor ()方法来设置及获取对应位置的 QColor 值。

QImage 还提供了 scanLine ()函数， 它返回的是，指定 的 索引 值对应的扫描线的像素数据的指针 。 以及 bits ()函数， 它返回的是第一个像素数据的指针（等价 于 scanLine(0) ）。

图片格式

QImage 中储存的每个像素都是用一个整数表示的。取决 于图片格式的不同，整数的占用空间大小也不同。 QImage支持多种图片格式 ，由 Format 枚举值来枚举。

单色图片 是使用1位的索引值来表示每个像素的，它的颜色表最多允许有2种颜色。有两种不同类型的单色图片：大端在前（big endian） ( 最重要的字节（ MSB ）在最前面 ) 或小端在前（little endian） ( 最不重要的字节（ LSB ）在最前面 ) ，它们的位顺序不同。

8 位图片使用的是带有8位索引的颜色表，也就是说，每个像素 的值都是一个字节。颜色表 是一个 QVector < QRgb >， 而 QRgb 这个类型定义（ typedef ）等价 于一个无符号整数，其中包含 的是一个透红绿蓝四元组，具体格式 是0xAARRGGBB。

32 位图片没有颜色表；每个像素直接包含 一个 QRgb 值。 有三种不同类型的32位图片，分别储存： 红绿蓝 ( 也就是说， 0xffRRGGBB) 、透红绿蓝和预乘 （premultiplied） 的透红绿蓝值。 在预乘的格式中 ，红、绿、蓝通道的数值都已经乘以透明通道值再除以255。

图片 的格式可使用 format ()函数来获取。使用 convertToFormat ()函数 可将一个图片转换成另一种格式。 allGray () 和 isGrayscale ()函数 可告之，是否一张彩色图片可被安全地转换为灰度图片。

图片变换

QImage支持多个函数 ，可用来对原图片进行变换而得到一张新图片： createAlphaMask ()函数根据 此图片的透明通道缓存值 构造 并返回一个1位的掩码（mask）， createHeuristicMask ()函数构建 并返回此图片的一个1位的启发式（heuristic）掩码。 后一个函数 的工作过程是：首先在某个角落里选择一个颜色，然后 从所有的边开始，削去所有具有那个颜色 的像素。

mirrored ()函数按照给定 的方向将图片做镜像变换，然后返回新图片。 scaled () 将图片缩放到设定好的尺寸，再返回新图片。 rgbSwapped ()函数 从一张红绿蓝（RGB）图片中构造出一张蓝绿红（BGR）图片。

scaledToWidth () 和 scaledToHeight ()函数 ，将图片缩放到指定尺寸，然后返回新图片。

transformed ()函数 ，将图片按照指定的变换矩阵和变换模式来变换，然后返回新图片： 在内部实现中，变换矩阵 会被调整， 以避免发生不需要的转换（translation）， 也就是说， transformed () 会返回一个包含了原图片中所有被变换的点的最小图片。静态函数 trueMatrix ()返回 的是 在变换图片的过程中使用的实际矩阵。

还有一些函数，可用来就地改变一张图片的属性：

参考 QImageReader 、 QImageWriter 、 QPixmap 、 QSvgRenderer 、 图片合成示例 、 图片查看 器示例 、 涂鸦示例 和 像素 化示例 。

成员类型文档

enum QImage::Format

注意 ： 不支持对一个具有QImage::Format_Indexed8 格式的 QImage 进行绘图操作。

注意 ：不要使用 QPainter 向ARGB32 图片中渲染。使用QImage::Format_ARGB32_Premultiplied 会快得多。

注意 ：对于那些单个颜色通道中有多于8 位数值的格式，在光栅引擎（raster engine）中处理时，只会使用8 位颜色数值。

参考 format () 和 convertToFormat () 。

成员函数文档

QImage:: QImage ( int width ,  int height ,  Format format )

使用指定的宽度 width 、高度 height 和格式 format 来构造一个图片。

如果内存分配失败， 则会返回一个无效（ null ）图片。

警告： 这个函数所创建的 QImage ，其数据并未初始化。 在使用 QPainter 向它进行绘图操作之前，要调用 fill ()来以某种适当的像素值填充该图片。

QImage:: QImage ( uchar  * data ,  int width ,  int height ,  Format format ,  QImageCleanupFunction cleanupFunction  = Q_NULLPTR,  void  * cleanupInfo  = Q_NULLPTR)

使用指定的宽度 width 、高度 height 、格式 format 和已有的内存缓冲区数据 data 来构造一个图片。宽度 width 和高度 height 的单位是像素，数据 data必须是按照32位对齐的，图片数据中的每个扫描线也必须是按照32位对齐的。

在这个 QImage 实例及所有未被修改或未从原始缓冲区中脱离的副本的生命周期中，此缓冲区都必须一直保持处于有效状态。 该图片对象实例，并不会在析构时释放这个缓冲区。 妳可以提供一个函数指针 cleanupFunction ，它能够带一个额外的指针参数 cleanupInfo ， 当最后一个副本被销毁时，该函数会被调用。

如果 format 是某种索引颜色格式，那么 ，图片的颜色表在初始状态下是空白的，在使用该图片之前，必须使用 setColorCount ()或 setColorTable ()来有效地 扩 充颜色 表。

QImage:: QImage (const  uchar  * data ,  int width ,  int height ,  Format format ,  QImageCleanupFunction cleanupFunction  = Q_NULLPTR,  void  * cleanupInfo  = Q_NULLPTR)

使用指定的宽度 width 、高度 height 、格式 format 和已有的只读内存缓冲区数据 data 来构造一个图片。宽度 width 和高度 height 的单位是像素，数据 data 必须是按照32位对齐的，图片数据中的每个扫描线也必须是按照32位对齐的。

在这个 QImage 实例及所有未被修改或未从原始缓冲区中脱离的副本的生命周期中，此缓冲区都必须一直保持处于有效状态。 该图片对象实例，并不会在析构时释放这个缓冲区。 妳可以提供一个函数指针 cleanupFunction ，它能够带一个额外的指针参数 cleanupInfo ， 当最后一个副本被销毁时，该函数会被调用。

如果 format 是某种索引颜色格式，那么 ，图片的颜色表在初始状态下是空白的，在使用该图片之前，必须使用 setColorCount ()或 setColorTable ()来有效地 扩 充颜色 表。

这个版本的构造函数，与另外类似的那 个 使用非 常量 数据缓冲区的 QImage 构造函数不同， 它永远不会改变缓冲 区中的内容。例如， 当妳调用 QImage::bits ()时， 会返回该图片的一份深度复制副本， 而不会直接返回 之前传递给构造函数的那块缓冲区。 这样，就可以高效地从原生数据中构造 QImage 实例，又不会改变原生数据中的内容。

QImage:: QImage ( uchar  * data ,  int width ,  int height ,  int bytesPerLine ,  Format format ,  QImageCleanupFunction cleanupFunction  = Q_NULLPTR,  void  * cleanupInfo  = Q_NULLPTR)

使用指定的宽度 width 、高度 height 、格式 format 和已有的内存缓冲区数据 data 来构造一个图片。 宽度 width 和高度 height 的单位是像素。 bytesPerLine指定的是，每一行像素中的数据字节个数(扫描线间距（stride）)。

在这个 QImage 实例及所有未被修改或未从原始缓冲区中脱离的副本的生命周期中，此缓冲区都必须一直保持处于有效状态。 该图片对象实例，并不会在析构时释放这个缓冲区。 妳可以提供一个函数指针 cleanupFunction ，它能够带一个额外的指针参数 cleanupInfo ， 当最后一个副本被销毁时，该函数会被调用。

如果 format 是某种索引颜色格式，那么 ，图片的颜色表在初始状态下是空白的，在使用该图片之前，必须使用 setColorCount ()或 setColorTable ()来有效地 扩 充颜色 表。

QImage:: QImage (const  uchar  * data ,  int width ,  int height ,  int bytesPerLine ,  Format format ,  QImageCleanupFunction cleanupFunction  = Q_NULLPTR,  void  * cleanupInfo  = Q_NULLPTR)

使用指定的宽度 width 、高度 height 、格式 format 和已有的只读内存缓冲区数据 data 来构造一个图片。宽度 width 和高度 height 的单位是像素。 bytesPerLine 指定的是，每一行像素中的数据字节个数(扫描线间距（stride）)。

在这个 QImage 实例及所有未被修改或未从原始缓冲区中脱离的副本的生命周期中，此缓冲区都必须一直保持处于有效状态。 该图片对象实例，并不会在析构时释放这个缓冲区。 妳可以提供一个函数指针 cleanupFunction ，它能够带一个额外的指针参数 cleanupInfo ， 当最后一个副本被销毁时，该函数会被调用。

如果 format 是某种索引颜色格式，那么 ，图片的颜色表在初始状态下是空白的，在使用该图片之前，必须使用 setColorCount ()或 setColorTable ()来有效地 扩 充颜色 表。

这个版本的构造函数，与另外类似的那 个 使用非 常量 数据缓冲区的 QImage 构造函数不同， 它永远不会改变缓冲 区中的内容。例如， 当妳调用 QImage::bits ()时， 会返回该图片的一份深度复制副本， 而不会直接返回 之前传递给构造函数的那块缓冲区。 这样，就可以高效地从原生数据中构造 QImage 实例，又不会改变原生数据中的内容。

QImage  QImage:: convertToFormat ( Format format ,  Qt::ImageConversionFlags flags  = Qt::AutoColor) const

返回 此图片的具有指定格式 format 的一个副本。

所指定的图片转换标志位 flags ，控制着在转换过程中如何处理那些图片数据。

参考 图片格式 。

void  QImage:: fill ( uint pixelValue )

使用指定的像素值 pixelValue 来填充整个图片。

如果这张图片的色深为 1，那么只有最低位会被用上。举个例子，如果妳调用 fill(0)、fill(2)等等，则图片会被 0填充；如果妳调用 fill(1)、fill(3)等等，则图片会被 1填充。如果色深为8，则只有最低8位被使用。如果位深为16，则只有最低16位被使用。

注意： QImage::pixel ()返回指定坐标处的像素点的颜色，而 QColor::pixel ()返回的是底层窗口系统中指定位置的像素值（本质上是一个索引值），所以，一般情况下，妳应当使用 QImage::pixel ()来获取已有图片中的某个颜色，或使用 QColor::rgb ()来生成一个指定的颜色。

参考 depth ()和 图片变换 。

void  QImage:: fill (const  QColor  & color )

这是一个重载函数。

使用指定的颜色 color 来填充整张图片。

如果色深为 1，则：当 color 等于 Qt::color1 时，图片会被1填充；否则，会被 0填充。

如果图片的色深为 8,则：当颜色表中存在着对应于 color 的索引时，会使用该索引填充；否则，会使用0填充。

这个函数是从Qt 4.8 开始引入的。（ ☯：所以在QT4.7里是无效的 ）

void  QImage:: fill ( Qt::GlobalColor color )

这是一个重载函数。

使用指定的颜色 color 来填充这张图片，这个颜色值是一个标准的全局颜色值。

这个函数是从Qt 4.8 开始引入的。（ ☯：所以在QT4.7里是无效的 ）

Format  QImage:: format () const

返回 此图片的格式。

参考 图片格式 。

void  QImage:: invertPixels ( InvertMode mode  = InvertRgb)

将这个图片里的所有像素的值反转。

指定 的反转模式 （ mode ） 只在图片 的颜色深度为 32 时才有意义。默认 的模式（ mode ）是 InvertRgb ，它不会改变透明（alpha）通道的值。如果模式（ mode ）是 InvertRgba 的话，那麽透明通道也会被反转。

将8 位的图片进行反转的话，就意味着将所有使用颜色索引 i 的像素替换成使用颜色索引255 - i 的像素。 对于单色的图片也是同理。注意，颜色表并 不会 改变。

如果图片中带有预乘的（premultiplied）透明通道，那么，首先会将图片转换成ARGB32格式，进行反转之后，再转换回原来的格式。

参 考 图片变换 。

bool  QImage:: loadFromData (const  QByteArray  & data , const  char  * format  = Q_NULLPTR)

这是一个重载函数。

直接 从给定的数据 QByteArray data 中载入一张图片。

未知美人