内容

• 公共类型
• 公共函数
• 静态公共成员
• 相关非成员
• 详细描述
• 读写图像文件
• 图像信息
• 像素操纵
• 图像格式
• 图像变换
• Legal Information

QImage 类

The QImage 类提供独立于硬件的图像表示 (允许直接访问像素数据，且可以用作描绘设备)。 更多...

头：	#include <QImage>
继承：	QPaintDevice

注意： 此类的所有函数 可重入 .

• 所有成员列表，包括继承成员
• 过时成员
• 兼容成员

公共类型

enum	Format { Format_Invalid, Format_Mono, Format_MonoLSB, Format_Indexed8, ..., Format_ARGB4444_Premultiplied }
enum	InvertMode { InvertRgb, InvertRgba }

公共函数

	QImage ()
	QImage (const QSize & size , Format format )
	QImage (int width , int height , Format format )
	QImage (uchar * data , int width , int height , Format format )
	QImage (const uchar * data , int width , int height , Format format )
	QImage (uchar * data , int width , int height , int bytesPerLine , Format format )
	QImage (const uchar * data , int width , int height , int bytesPerLine , Format format )
	QImage (const char * const[] xpm )
	QImage (const QString & fileName , const char * format = 0)
	QImage (const char * fileName , const char * format = 0)
	QImage (const QImage & image )
	~QImage ()
bool	allGray () const
int	bitPlaneCount () const
uchar *	bits ()
const uchar *	bits () const
int	byteCount () const
int	bytesPerLine () const
qint64	cacheKey () const
QRgb	color (int i ) const
int	colorCount () const
QVector<QRgb>	colorTable () const
const uchar *	constBits () const
const uchar *	constScanLine (int i ) const
QImage	convertToFormat (Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) const
QImage	convertToFormat (Format format , const QVector<QRgb> & colorTable , Qt::ImageConversionFlags flags = Qt::AutoColor) const
QImage	copy (const QRect & rectangle = QRect()) const
QImage	copy (int x , int y , int width , int height ) const
QImage	createAlphaMask (Qt::ImageConversionFlags flags = Qt::AutoColor) const
QImage	createHeuristicMask (bool clipTight = true) const
QImage	createMaskFromColor (QRgb color , Qt::MaskMode mode = Qt::MaskInColor) const
int	depth () const
int	dotsPerMeterX () const
int	dotsPerMeterY () const
void	fill (uint pixelValue )
void	fill (Qt::GlobalColor color )
void	fill (const QColor & color )
格式	format () const
bool	hasAlphaChannel () const
int	height () const
void	invertPixels (InvertMode mode = InvertRgb)
bool	isGrayscale () const
bool	isNull () const
bool	load (const QString & fileName , const char * format = 0)
bool	load (QIODevice * device , const char * format )
bool	loadFromData (const uchar * data , int len , const char * format = 0)
bool	loadFromData (const QByteArray & data , const char * format = 0)
QImage	mirrored (bool horizontal = false, bool vertical = true) const
QPoint	offset () const
QRgb	pixel (const QPoint & position ) const
QRgb	pixel (int x , int y ) const
int	pixelIndex (const QPoint & position ) const
int	pixelIndex (int x , int y ) const
QRect	rect () const
QImage	rgbSwapped () const
bool	save (const QString & fileName , const char * format = 0, int quality = -1) const
bool	save (QIODevice * device , const char * format = 0, int quality = -1) const
QImage	scaled (const QSize & size , Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const
QImage	scaled (int width , int height , Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const
QImage	scaledToHeight (int height , Qt::TransformationMode mode = Qt::FastTransformation) const
QImage	scaledToWidth (int width , Qt::TransformationMode mode = Qt::FastTransformation) const
uchar *	scanLine (int i )
const uchar *	scanLine (int i ) const
void	setColor (int index , QRgb colorValue )
void	setColorCount (int colorCount )
void	setColorTable (const QVector<QRgb> colors )
void	setDotsPerMeterX (int x )
void	setDotsPerMeterY (int y )
void	setOffset (const QPoint & offset )
void	setPixel (const QPoint & position , uint index_or_rgb )
void	setPixel (int x , int y , uint index_or_rgb )
void	setText (const QString & key , const QString & text )
QSize	size () const
void	swap (QImage & other )
QString	text (const QString & key = QString()) const
QStringList	textKeys () const
QImage	transformed (const QMatrix & matrix , Qt::TransformationMode mode = Qt::FastTransformation) const
QImage	transformed (const QTransform & matrix , Qt::TransformationMode mode = Qt::FastTransformation) const
bool	valid (const QPoint & pos ) const
bool	valid (int x , int y ) const
int	width () const
	operator QVariant () const
bool	operator!= (const QImage & image ) const
QImage &	operator= (const QImage & image )
QImage &	operator= (QImage && other )
bool	operator== (const QImage & image ) const

• 12 公共函数继承自 QPaintDevice

静态公共成员

QImage	fromData (const uchar * data , int size , const char * format = 0)
QImage	fromData (const QByteArray & data , const char * format = 0)
QMatrix	trueMatrix (const QMatrix & matrix , int width , int height )
QTransform	trueMatrix (const QTransform & matrix , int width , int height )

相关非成员

QDataStream &	operator<< (QDataStream & stream , const QImage & image )
QDataStream &	operator>> (QDataStream & stream , QImage & image )

额外继承成员

• 1 保护函数继承自 QPaintDevice

详细描述

The QImage 类提供独立于硬件的图像表示 (允许直接访问像素数据，且可以用作描绘设备)。

Qt 为处理图像数据提供了 4 个类： QImage , QPixmap , QBitmap and QPicture . QImage 是为 I/O 和直接访问/操纵像素而设计并优化的，而 QPixmap 是为在屏幕上展示图像而设计并优化的。 QBitmap 只是方便类，继承 QPixmap ，确保 1 深度。最后， QPicture 类是描绘设备，它记录并重演 QPainter 命令。

因为 QImage 是 QPaintDevice 子类， QPainter 可以用于在图像上直接绘制。当使用 QPainter 在 QImage ，描绘可以在当前 GUI 线程外的其它线程中履行。

The QImage 类支持几种图像格式，描述通过 Format 枚举。这些包括单色、8 位、32 位且 Alpha 融合图像 (可用于所有 Qt 4.x 版本)。

QImage 提供了可以用于获取有关图像各种信息的一批函数。还有几个函数使图像能够变换。

QImage 对象可以按值围绕传递由于 QImage 类使用 隐式数据共享 . QImage 对象还可以被流化和比较。

注意： 若愿意加载 QImage 对象以静态 Qt 构建，参考 插件怎么样 .

警告： 描绘 QImage 采用格式 QImage::Format_Indexed8 不支持。

读写图像文件

QImage 提供了几种方式加载图像文件：可以加载文件当构造 QImage 对象，或通过使用 load () 或 loadFromData () 函数稍后。 QImage 还提供静态 fromData () 函数，构造 QImage 从给定数据。当加载图像时，文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 Qt 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

只需调用 save () 函数以保存 QImage 对象。

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

格式	描述	Qt 支持
BMP	Windows 位图	读/写
GIF	GIF (图形互换格式) 可选	读取
JPG	JPEG (联合摄影专家组)	读/写
JPEG	JPEG (联合摄影专家组)	读/写
PNG	PNG (便携式网络图形)	读/写
PBM	PBM (便携式位图)	读取
PGM	PGM (便携式灰度图)	读取
PPM	Portable Pixmap (便携式像素图)	读/写
TIFF	TIFF (标签化图像文件格式)	读/写
XBM	X11 Bitmap (X11 位图)	读/写
XPM	X11 Pixmap (X11 像素图)	读/写

图像信息

QImage 提供了可以用于获取有关图像各种信息的一批函数：

	可用函数
几何体	The size (), width (), height (), dotsPerMeterX ()，和 dotsPerMeterY () 函数提供图像大小和宽高比的有关信息。 The rect () 函数返回图像的封闭矩形。 valid () 函数告诉给定坐标对是否在此矩形内。 offset () 函数返回图像意欲偏移的像素数，当相对于其它图像定位时，还可以操纵这使用 setOffset () 函数。
颜色	可以检索像素的颜色，通过将其坐标传递给 pixel () 函数。 pixel () 函数返回颜色如 QRgb 值独立于图像格式。 若是单色和 8 位图像， colorCount () 和 colorTable () 函数提供用于存储图像数据的颜色分量的有关信息： colorTable () 函数返回图像的整个颜色表。要获得单个条目，使用 pixelIndex () 函数检索给定坐标对的像素索引，然后使用 color () 函数检索颜色。注意，若手动创建 8 位图像，还必须设置图像的有效颜色表。 The hasAlphaChannel () 函数告诉是否有 Alpha 通道，若图像格式遵守的话。 allGray () 和 isGrayscale () 函数告诉图像的颜色是否都为灰度着色。 另请参阅 像素操纵 and 图像变换 章节。
文本	The text () 函数返回关联给定文本键的图像文本。图像的＝文本键的检索可以使用 textKeys () 函数。使用 setText () 函数能更改图像的文本。
低级信息	The depth () 函数返回图像的深度。支持的深度包括 1 位 (单色)、8 位、16 位、24 位及 32 位。 bitPlaneCount () 函数告诉使用的那些位是多少。更多信息见 图像格式 章节。 The format (), bytesPerLine ()，和 byteCount () 函数提供存储在图像中的数据的有关低级信息。 The cacheKey () 函数返回唯一内容标识数为此 QImage 对象。

像素操纵

用于操纵图像像素的函数从属图像格式。原因是单色和 8 位图像基于索引并使用颜色查找表，而 32 位图像直接存储 ARGB 值。对于有关图像格式的更多信息，见 图像格式 章节。

若是 32 位图像， setPixel () 函数可以用于将给定坐标处的像素颜色，更改为按 ARGB 四元组指定的任何其它颜色。要制作合适 QRgb 值，使用 qRgb () (将默认 Alpha 分量添加到给定 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);

QImage 还提供 scanLine () 函数返回指向具有给定索引的扫描线处的像素数据的指针，和 bits () 函数返回指向第一像素数据的指针 (这相当于 scanLine(0) ).

图像格式

存储的每个像素在 QImage 由整数表示。整数的大小因格式而异。 QImage 支持几种图像格式，描述通过 Format 枚举。

单色图像的存储是使用 1 位索引到最多 2 颜色的颜色表。有 2 种不同类型的单色图像：大端在前 (MSB 优先) 或小端在前 (LSB 优先) 位次序。

8 位图像的存储是使用 8 位索引到颜色表，即，每像素拥有一字节。颜色表为 QVector < QRgb >，和 QRgb typedef 相当于包含 0xAARRGGBB 格式 ARGB 四元组的无符号 int。

32 位图像没有颜色表；取而代之，每个像素包含 QRgb 值。有 3 种不同类型的 32 位图像分别存储 RGB (即 0xffRRGGBB)、ARGB 和预乘 ARGB 值。在预乘格式中，红色、绿色和蓝色通道乘以 Alpha 分量除以 255。

图像的格式可以被检索使用 format () 函数。使用 convertToFormat () 函数能将图像转换为另一种格式。 allGray () 和 isGrayscale () 函数分辨彩色图像是否可以安全地转换为灰度图像。

图像变换

QImage 支持许多函数为创建原始变换版本的新图像： createAlphaMask () 函数构建并返回 1 BPP (位每像素) 遮罩从此图像的 Alpha 缓冲，和 createHeuristicMask () 函数创建并返回 1 BPP (位每像素) 试探遮罩为此图像。后一函数的工作是通过从一角选择颜色，然后从所有边缘开始去除相应颜色的像素。

The mirrored () 函数返回期望方向的图像镜像， scaled () 返回比例缩放到期望尺度矩形的图像副本，和 rgbSwapped () 函数从 RGB 图像构造 BGR 图像。

The scaledToWidth () 和 scaledToHeight () 函数返回图像的比例缩放副本。

The transformed () 函数返回按给定变换矩阵和变换模式变换的图像副本：在内部，调节变换矩阵以补偿不想要的平移，即， transformed () 返回包含原始图像的所有变换点的最小图像。静态 trueMatrix () 函数返回用于变换图像的实际矩阵。

还有原位改变图像属性的函数：

函数	描述
setDotsPerMeterX ()	通过设置以物理米为单位的水平拟合像素数定义宽高比。
setDotsPerMeterY ()	通过设置以物理米为单位的垂直拟合像素数定义宽高比。
fill ()	采用给定像素值填充整个图像。
invertPixels ()	反转图像中的所有像素值使用给定 InvertMode 值。
setColorTable ()	设置用于变换颜色索引的颜色表。仅单色和 8 位格式。
setColorCount ()	重置颜色表大小。仅单色和 8 位格式。

Legal Information

For smooth scaling, the transformed () functions use code based on smooth scaling algorithm by Daniel M. Duley.

Copyright (C) 2004, 2005 Daniel M. Duley

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

另请参阅 QImageReader , QImageWriter , QPixmap , QSvgRenderer , 图像合成范例 , 图像查看器范例 , 涂鸦范例 ，和 像素器范例 .

成员类型文档编制

enum QImage:: Format

The following image formats are available in Qt. Values greater than QImage::Format_RGB16 were added in Qt 4.4. See the notes after the table.

常量	值	描述
QImage::Format_Invalid	0	图像无效。
QImage::Format_Mono	1	图像的存储是使用 1 位每像素。字节首先与 MSB (最显著位) 一起打包。
QImage::Format_MonoLSB	2	图像的存储是使用 1 位每像素。字节首先与 LSB (低显著位) 一起打包。
QImage::Format_Indexed8	3	图像的存储是使用 8 位索引到颜色映射。
QImage::Format_RGB32	4	图像的存储是使用 32 位 RGB 格式 (0xffRRGGBB)。
QImage::Format_ARGB32	5	图像的存储是使用 32 位 ARGB 格式 (0xAARRGGBB)。
QImage::Format_ARGB32_Premultiplied	6	图像的存储是使用预乘 32 位 ARGB 格式 (0xAARRGGBB)，即红色、绿色和蓝色通道乘以 Alpha 分量除以 255 (若 RR、GG 或 BB 的值高于 Alpha 通道，结果未定义)。某些操作 (譬如：使用 Alpha 融合的图像合成) 使用预乘 ARGB32 比采用纯 ARGB32 更快。
QImage::Format_RGB16	7	图像的存储是使用 16 位 RGB 格式 (5-6-5)。
QImage::Format_ARGB8565_Premultiplied	8	图像的存储是使用预乘 24 位 ARGB 格式 (8-5-6-5)。
QImage::Format_RGB666	9	图像的存储是使用 24 位 RGB 格式 (6-6-6)。未使用的最显著位始终为 0。
QImage::Format_ARGB6666_Premultiplied	10	图像的存储是使用预乘 24 位 ARGB 格式 (6-6-6-6)。
QImage::Format_RGB555	11	图像的存储是使用 16 位 RGB 格式 (5-5-5)。未使用的最显著位始终为 0。
QImage::Format_ARGB8555_Premultiplied	12	图像的存储是使用预乘 24 位 ARGB 格式 (8-5-5-5)。
QImage::Format_RGB888	13	图像的存储是使用 24 位 RGB 格式 (8-8-8)。
QImage::Format_RGB444	14	图像的存储是使用 16 位 RGB 格式 (4-4-4)。未使用位始终为 0。
QImage::Format_ARGB4444_Premultiplied	15	图像的存储是使用预乘 16 位 ARGB 格式 (4-4-4-4)。

注意： 绘制进 QImage 采用 QImage::Format_Indexed8 不支持。

注意： 不要渲染成 ARGB32 图像使用 QPainter 。使用 QImage::Format_ARGB32_Premultiplied 明显更快。

另请参阅 format () 和 convertToFormat ().

enum QImage:: InvertMode

此枚举类型用于描述应如何反转像素值在 invertPixels () 函数。

常量	值	描述
QImage::InvertRgb	0	仅反转 RGB 值并使 Alpha 通道保持不变。
QImage::InvertRgba	1	反转所有通道，包括 Alpha 通道。

另请参阅 invertPixels ().

成员函数文档编制

QImage:: QImage ()

构造空图像。

另请参阅 isNull ().

QImage:: QImage (const QSize & size , Format format )

构造图像采用给定 size and format .

A null 图像被返回，若无法分配内存。

警告： 这将创建 QImage 采用未初始化数据。调用 fill () 采用适当像素值填充图像，先于绘制它采用 QPainter .

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

构造图像采用给定 width , height and format .

A null 图像将被返回，若无法分配内存。

警告： 这将创建 QImage 采用未初始化数据。调用 fill () 采用适当像素值填充图像，先于绘制它采用 QPainter .

QImage:: QImage ( uchar * data , int width , int height , Format format )

构造图像采用给定 width , height and format ，使用现有内存缓冲 data 。 width and height 必须指定以像素为单位， data 必须 32 位对齐，且图像中的每一数据扫描线也必须 32 位对齐。

缓冲必须仍然有效在整个寿命期内对于 QImage . The image does not delete the buffer at destruction.

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

QImage:: QImage (const uchar * data , int width , int height , Format format )

构造图像采用给定 width , height and format ，使用现有只读内存缓冲， data 。 width and height 必须指定以像素为单位， data 必须 32 位对齐，且图像中的每一数据扫描线也必须 32 位对齐。

缓冲必须仍然有效在整个寿命期内对于 QImage and all copies that have not been modified or otherwise detached from the original buffer. The image does not delete the buffer at destruction.

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

不像类似 QImage 构造函数接受非 const 数据缓，此版本从不更改缓冲内容。例如，调用这允许从原生数据高效构造 QImage，不可能改变原生数据。 QImage::bits () 将返回图像的深拷贝，而不是传递给构造函数的缓冲。这允许高效构造 QImage 从原生数据，不可能改变原生数据。

QImage:: QImage ( uchar * data , int width , int height , int bytesPerLine , Format format )

构造图像采用给定 width , height and format ，使用现有内存缓冲 data 。 width and height 必须指定以像素为单位。 bytesPerLine 指定每行的字节数 (步幅)。

缓冲必须仍然有效在整个寿命期内对于 QImage . The image does not delete the buffer at destruction.

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

QImage:: QImage (const uchar * data , int width , int height , int bytesPerLine , Format format )

构造图像采用给定 width , height and format ，使用现有内存缓冲 data 。 width and height 必须指定以像素为单位。 bytesPerLine 指定每行的字节数 (步幅)。

缓冲必须仍然有效在整个寿命期内对于 QImage . The image does not delete the buffer at destruction.

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

不像类似 QImage 构造函数接受非 const 数据缓，此版本从不更改缓冲内容。例如，调用这允许从原生数据高效构造 QImage，不可能改变原生数据。 QImage::bits () 将返回图像的深拷贝，而不是传递给构造函数的缓冲。这允许高效构造 QImage 从原生数据，不可能改变原生数据。

QImage:: QImage (const char * const[] xpm )

构造图像从给定 xpm 图像。

确保图像是有效 XPM 图像。错误被默默忽略。

注意，通过使用不寻常声明稍微挤压 XPM 变量是可能的：

static const char * const start_xpm[] = {
    "16 15 8 1",
    "a c #cec6bd",
....
					

额外 const 使整个定义只读，这稍微更高效 (如：当代码在共享库中时) 且能与应用程序一起存储在 ROM 中。

QImage:: QImage (const QString & fileName , const char * format = 0)

构造图像并试着从文件加载图像，采用给定 fileName .

加载器试图读取图像使用指定 format 。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。

若图像加载失败，此对象为 null 图像。

文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

另请参阅 isNull () 和 读写图像文件 .

QImage:: QImage (const char * fileName , const char * format = 0)

构造图像并试着从文件加载图像，采用给定 fileName .

加载器试图读取图像使用指定 format 。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。

若图像加载失败，此对象为 null 图像。

文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

You can disable this constructor by defining QT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful, for example, if you want to ensure that all user-visible strings go through QObject::tr ().

另请参阅 QString::fromAscii (), isNull ()，和 读写图像文件 .

QImage:: QImage (const QImage & image )

构造浅拷贝为给定 image .

有关浅拷贝的更多信息，见 隐式数据共享 文档编制。

另请参阅 copy ().

QImage:: ~QImage ()

销毁图像并清理。

bool QImage:: allGray () const

Returns true if all the colors in the image are shades of gray (i.e. their red, green and blue components are equal); otherwise false.

注意：此函数很慢对于没有颜色表的图像。

另请参阅 isGrayscale ().

int QImage:: bitPlaneCount () const

返回图像位平面数。

位平面数是每像素的颜色和透明度信息位数。这异于 (即：小于) 深度当图像格式包含未使用位时。

该函数在 Qt 4.7 引入。

另请参阅 depth (), format ()，和 图像格式 .

uchar * QImage:: bits ()

返回第一像素数据指针。这相当于 scanLine (0).

注意， QImage 使用 隐式数据共享 。此函数对共享像素数据履行深拷贝，从而确保此 QImage 是唯一使用当前返回值的。

另请参阅 scanLine (), byteCount ()，和 constBits ().

const uchar * QImage:: bits () const

这是重载函数。

注意， QImage 使用 隐式数据共享 ，但此函数执行 not 对共享像素数据履行深拷贝，因为返回数据是 const。

int QImage:: byteCount () const

返回由图像数据占据的字节数。

该函数在 Qt 4.6 引入。

另请参阅 bytesPerLine (), bits ()，和 图像信息 .

int QImage:: bytesPerLine () const

返回每图像扫描线的字节数。

这相当于 byteCount () / height ().

另请参阅 scanLine ().

qint64 QImage:: cacheKey () const

返回的数字标识内容对于此 QImage 对象。截然不同的 QImage 对象才可以拥有相同键，若它们引用相同内容。

键将改变当变更图像时。

QRgb QImage:: color ( int i ) const

返回颜色表中的颜色在索引 i 。第一颜色在索引 0。

图像颜色表中的颜色的指定是按 ARGB 四元组 ( QRgb )。使用 qAlpha (), qRed (), qGreen ()，和 qBlue () 函数能获取颜色值分量。

另请参阅 setColor (), pixelIndex ()，和 像素操纵 .

int QImage:: colorCount () const

返回图像的颜色表大小。

注意，colorCount() 返回 0 对于 32 BPP (位每像素) 图像，因为这些图像不使用颜色表，取而代之是将像素值编码成 ARGB 四元组。

该函数在 Qt 4.6 引入。

另请参阅 setColorCount () 和 图像信息 .

QVector < QRgb > QImage:: colorTable () const

返回在图像颜色表中包含的颜色列表，或空列表若图像没有颜色表

另请参阅 setColorTable (), colorCount ()，和 color ().

const uchar * QImage:: constBits () const

返回第一像素数据指针。

注意， QImage 使用 隐式数据共享 ，但此函数执行 not 对共享像素数据履行深拷贝，因为返回数据是 const。

该函数在 Qt 4.7 引入。

另请参阅 bits () 和 constScanLine ().

const uchar * QImage:: constScanLine ( int i ) const

返回像素数据的指针在扫描线索引 i 。第一扫描线在索引 0。

扫描线数据对齐 32 位边界。

注意， QImage 使用 隐式数据共享 ，但此函数执行 not 对共享像素数据履行深拷贝，因为返回数据是 const。

该函数在 Qt 4.7 引入。

另请参阅 scanLine () 和 constBits ().

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

返回图像副本按给定 format .

指定图像转换 flags 控制转换过程中如何处理图像数据。

另请参阅 Image Format.

QImage QImage:: convertToFormat ( Format format , const QVector < QRgb > & colorTable , Qt::ImageConversionFlags flags = Qt::AutoColor) const

这是重载函数。

返回图像的副本将转换到给定 format ，使用指定 colorTable .

Conversion from 32 bit to 8 bit indexed is a slow operation and will use a straightforward nearest color approach, with no dithering.

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

将图像的子区域作为新图像返回。

返回的图像拷贝自位置 ( rectangle .x(), rectangle .y()) 在此图像中，且将始终拥有的大小如给定 rectangle .

在此图像外的区域，像素被设为 0。对于 32 位 RGB 图像，这意味着黑色；对于 32 位 ARGB 图像，这意味着透明黑色；对于 8 位图像，这意味着颜色表中的 0 索引颜色可以是任何颜色；对于 1 位图像，这意味着 Qt::color0 .

若给定 rectangle 是 null 矩形，整个图像被拷贝。

另请参阅 QImage ().

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

这是重载函数。

返回的图像拷贝自位置 ( x , y ) 在此图像中，且将始终拥有给定 width and height 。在此图像外的区域，像素被设为 0。

QImage QImage:: createAlphaMask ( Qt::ImageConversionFlags flags = Qt::AutoColor) const

从此图像的 Alpha 缓冲构建并返回 1 BPP (位每像素) 遮罩。返回 null 图像，若图像格式为 QImage::Format_RGB32 .

The flags 自变量是按位 OR 的 Qt::ImageConversionFlags ，和控制转换过程。为标志传递 0 将设置所有默认选项。

返回图像拥有小端在前位次序 (即：图像的格式为 QImage::Format_MonoLSB )，可以转换到大端在前 ( QImage::Format_Mono ) 使用 convertToFormat () 函数。

另请参阅 createHeuristicMask () 和 图像变换 .

QImage QImage:: createHeuristicMask ( bool clipTight = true) const

为此图像创建并返回 1 BPP (位每像素) 试探遮罩。

函数的工作是通过从一角选择颜色，然后从所有边缘开始去除相应颜色的像素。4 角投票要遮住哪种颜色。若绘制 (这通常意味着此函数不适用于图像)，结果是任意的。

返回图像拥有小端在前位次序 (即：图像的格式为 QImage::Format_MonoLSB )，可以转换到大端在前 ( QImage::Format_Mono ) 使用 convertToFormat () 函数。

若 clipTight 为 true (默认)，遮罩刚好足够大以覆盖像素；否则，遮罩 > 数据像素。

注意：此函数忽视 Alpha 缓冲。

另请参阅 createAlphaMask () 和 图像变换 .

QImage QImage:: createMaskFromColor ( QRgb color , Qt::MaskMode mode = Qt::MaskInColor) const

创建并返回此图像的遮罩基于给定 color 值。若 mode 为 MaskInColor (默认值)，所有像素匹配 color 将是不透明像素在遮罩中。若 mode 为 MaskOutColor，匹配给定颜色的所有像素都是透明的。

另请参阅 createAlphaMask () 和 createHeuristicMask ().

int QImage:: depth () const

返回图像的深度。

图像深度是用于存储单个像素的位数，也称 BPP (位每像素)。

支持深度 1、8、16、24 及 32。

另请参阅 bitPlaneCount (), convertToFormat (), 图像格式 ，和 图像信息 .

int QImage:: dotsPerMeterX () const

返回每物理米水平拟合的像素数。连同 dotsPerMeterY ()，此数字定义图像的预期比例缩放和宽高比。

另请参阅 setDotsPerMeterX () 和 图像信息 .

int QImage:: dotsPerMeterY () const

返回每物理米垂直拟合的像素数。连同 dotsPerMeterX ()，此数字定义图像的预期比例缩放和宽高比。

另请参阅 setDotsPerMeterY () 和 图像信息 .

void QImage:: fill ( uint pixelValue )

填充整个图像采用给定 pixelValue .

若图像深度为 1，仅使用最低位。若为 fill(0)、fill(2) 等，采用 0 填充图像。若为 fill(1)、fill(3) 等，采用 1 图像填充。若深度为 8，使用最低 8 位，和若深度为 16，使用最低 16 位。

注意： QImage::pixel () returns the color of the pixel at the given coordinates while QColor::pixel () returns the pixel value of the underlying window system (essentially an index value), so normally you will want to use QImage::pixel () 以使用来自现有图像的颜色或 QColor::rgb () 以使用特定颜色。

另请参阅 depth () 和 图像变换 .

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

这是重载函数。

填充图像采用给定 color ，描述为标准全局颜色。

该函数在 Qt 4.8 引入。

void QImage:: fill (const QColor & color )

这是重载函数。

填充整个图像采用给定 color .

若图像深度为 1，图像将被填充采用 1 若 color 等于 Qt::color1 ；否则，将采用 0 填充它。

若图像深度为 8，填充图像采用的索引对应 color 在颜色表中 (若存在)；否则，将采用 0 填充它。

该函数在 Qt 4.8 引入。

Format QImage:: format () const

返回图像格式。

另请参阅 图像格式 .

[static] QImage QImage:: fromData (const uchar * data , int size , const char * format = 0)

构造 QImage 从第一 size 字节的给定二进制 data 。加载器试图读取图像使用指定 format 。若 format is not specified (which is the default), the loader probes the file for a header to guess the file format. binary data . The loader attempts to read the image, either using the optional image format specified or by determining the image format from the data.

若 format is not specified (which is the default), the loader probes the file for a header to determine the file format. If format 有指定，它必须是某一值返回通过 QImageReader::supportedImageFormats ().

若图像加载失败，返回图像将为 null 图像。

另请参阅 load (), save ()，和 读写图像文件 .

[static] QImage QImage:: fromData (const QByteArray & data , const char * format = 0)

这是重载函数。

加载图像从给定 QByteArray data .

bool QImage:: hasAlphaChannel () const

Returns true if the image has a format that respects the alpha channel, otherwise returns false.

另请参阅 图像信息 .

int QImage:: height () const

返回图像的高度。

另请参阅 图像信息 .

void QImage:: invertPixels ( InvertMode mode = InvertRgb)

反转图像所有像素值。

给定反转 mode 才有意义当图像深度为 32 时。默认 mode is InvertRgb ，使 Alpha 通道保持不变。若 mode is InvertRgba ，Alpha 位也反转。

反转 8 位图像意味着替换所有像素，使用颜色索引 i 采用像素使用颜色索引 255 减 i 。1 位图像的情况也如此。注意，颜色表 not 改变。

另请参阅 图像变换 .

bool QImage:: isGrayscale () const

对于 32 位图像，此函数相当于 allGray ().

For 8-bpp images, this function returns true if color(i) is QRgb (i, i, i) for all indexes of the color table; otherwise returns false.

另请参阅 allGray () 和 图像格式 .

bool QImage:: isNull () const

Returns true if it is a null image, otherwise returns false.

null 图像的所有参数都设置为零，并且没有分配的数据。

bool QImage:: load (const QString & fileName , const char * format = 0)

从文件加载图像采用给定 fileName . Returns true if the image was successfully loaded; otherwise returns false.

加载器试图读取图像使用指定 format ，如 PNG 或 JPG。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。

文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

另请参阅 读写图像文件 .

bool QImage:: load ( QIODevice * device , const char * format )

这是重载函数。

此函数读取 QImage 从给定 device 。例如，这可以用于将图像直接加载到 QByteArray .

bool QImage:: loadFromData (const uchar * data , int len , const char * format = 0)

加载图像从第一 len 字节的给定二进制 data . Returns true if the image was successfully loaded; otherwise returns false.

加载器试图读取图像使用指定 format ，如 PNG 或 JPG。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。

另请参阅 读写图像文件 .

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

这是重载函数。

加载图像从给定 QByteArray data .

QImage QImage:: mirrored ( bool horizontal = false, bool vertical = true) const

返回图像的镜像，在水平和/或垂直方向上镜像取决于是否 horizontal and vertical 被设为 true 或 false。

注意：原始图像不改变。

另请参阅 图像变换 .

QPoint QImage:: offset () const

返回图像相对于其它图像定位时，打算偏移的像素数。

另请参阅 setOffset () 和 图像信息 .

QRgb QImage:: pixel (const QPoint & position ) const

返回像素的颜色在给定 position .

若 position 无效，结果未定义。

警告： This function is expensive when used for massive pixel manipulations.

另请参阅 setPixel (), valid ()，和 像素操纵 .

QRgb QImage:: pixel ( int x , int y ) const

这是重载函数。

返回像素的颜色按坐标 ( x , y ).

int QImage:: pixelIndex (const QPoint & position ) const

返回像素索引在给定 position .

若 position 无效，或图像不是调色板图像 ( depth () > 8)，结果未定义。

另请参阅 valid (), depth ()，和 像素操纵 .

int QImage:: pixelIndex ( int x , int y ) const

这是重载函数。

返回像素索引在 ( x , y ).

QRect QImage:: rect () const

返回封闭矩形 (0, 0, width (), height ()) 为图像。

另请参阅 图像信息 .

QImage QImage:: rgbSwapped () const

返回 QImage ，所有像素的红色和蓝色分量值被交换，将 RGB 图像高效转换成 BGR 图像。

原始 QImage 不改变。

另请参阅 图像变换 .

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

保存图像到文件采用给定 fileName ，使用给定图像文件 format and quality 因子。若 format 为 0， QImage 将试图猜测格式通过查看 fileName 的后缀。

The quality 因子必须在 0 到 100 范围内或为 -1。指定 0 以获得小压缩文件，100 为大的未压缩文件，和 -1 (默认) 使用默认设置。

Returns true if the image was successfully saved; otherwise returns false.

另请参阅 读写图像文件 .

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

这是重载函数。

此函数写入 QImage 到给定 device .

例如，这可以用于将图像直接保存到 QByteArray :

        QImage image;
        QByteArray ba;
        QBuffer buffer(&ba);
        buffer.open(QIODevice::WriteOnly);
        image.save(&buffer, "PNG"); // writes image into ba in PNG format
					

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

返回图像副本被比例缩放到的矩形定义通过给定 size 根据给定 aspectRatioMode and transformMode .

• 若 aspectRatioMode is Qt::IgnoreAspectRatio ，图像被比例缩放到 size .
• 若 aspectRatioMode is Qt::KeepAspectRatio ，图像被比例缩放到尽可能大的矩形，不超出 size , 保留宽高比。
• 若 aspectRatioMode is Qt::KeepAspectRatioByExpanding ，图像被比例缩放到矩形尽可能小地大于 size , 保留宽高比。

若给定 size 为空，此函数返回 null 图像。

另请参阅 isNull () 和 图像变换 .

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

这是重载函数。

返回的图像副本被比例缩放到矩形采用给定 width and height 根据给定 aspectRatioMode and transformMode .

若 width 或 height 为 0 或负数，此函数返回 null 图像。

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

返回图像的比例缩放副本。返回图像被比例缩放到给定 height 使用指定变换 mode .

此函数自动计算图像宽度，以便保留图像比率。

若给定 height 为 0 或负数，返回 null 图像。

另请参阅 图像变换 .

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

返回图像的比例缩放副本。返回图像被比例缩放到给定 width 使用指定变换 mode .

此函数自动计算图像高度，以便保留其宽高比。

若给定 width 为 0 或负数，返回 null 图像。

另请参阅 图像变换 .

uchar * QImage:: scanLine ( int i )

返回像素数据的指针在扫描线索引 i 。第一扫描线在索引 0。

扫描线数据对齐 32 位边界。

警告： 若正访问 32 BPP (位每像素) 图像数据，则返回指针会被铸造成 QRgb* ( QRgb 拥有 32 位大小) 并使用它来读/写像素值。无法使用 uchar* 指针直接，因为像素格式从属底层平台字节序。使用 qRed (), qGreen (), qBlue ()，和 qAlpha () 来访问像素。

另请参阅 bytesPerLine (), bits (), 像素操纵 ，和 constScanLine ().

const uchar * QImage:: scanLine ( int i ) const

这是重载函数。

void QImage:: setColor ( int index , QRgb colorValue )

设置颜色在给定 index 在颜色表中，到给定 colorValue 。颜色值是 ARGB 四元组。

若 index 超出颜色表当前大小，展开它采用 setColorCount ().

另请参阅 color (), colorCount (), setColorTable ()，和 像素操纵 .

void QImage:: setColorCount ( int colorCount )

重置颜色表大小以包含 colorCount 条目。

若颜色表被展开，所有额外颜色将被设为透明 (即 qRgba (0, 0, 0, 0)).

当使用图像时，颜色表必须足够大以拥有呈现在图像中的所有像素/索引值条目，否则结果未定义。

该函数在 Qt 4.6 引入。

另请参阅 colorCount (), colorTable (), setColor ()，和 图像变换 .

void QImage:: setColorTable (const QVector < QRgb > colors )

将用于翻译颜色索引的颜色表设为 QRgb 值，到指定 colors .

当使用图像时，颜色表必须足够大以拥有呈现在图像中的所有像素/索引值条目，否则结果未定义。

另请参阅 colorTable (), setColor ()，和 图像变换 .

void QImage:: setDotsPerMeterX ( int x )

将每物理米水平拟合像素数设为 x .

连同 dotsPerMeterY ()， 此数字定义图像的预期比例缩放和宽高比，并确定比例缩放当 QPainter 在图像中绘制图形。它不改变图像的比例缩放或宽高比，当在其它描绘设备中渲染时。

另请参阅 dotsPerMeterX () 和 图像信息 .

void QImage:: setDotsPerMeterY ( int y )

将每物理米垂直拟合像素数设为 y .

连同 dotsPerMeterX ()， 此数字定义图像的预期比例缩放和宽高比，并确定比例缩放当 QPainter 在图像中绘制图形。它不改变图像的比例缩放或宽高比，当在其它描绘设备中渲染时。

另请参阅 dotsPerMeterY () 和 图像信息 .

void QImage:: setOffset (const QPoint & offset )

将图像相对于其它图像定位时，打算偏移的像素数设为 offset .

另请参阅 offset () 和 图像信息 .

void QImage:: setPixel (const QPoint & position , uint index_or_rgb )

设置像素索引或颜色在给定 position to index_or_rgb .

If the image's format is either monochrome or 8-bit, the given index_or_rgb 值必须是图像颜色表中的索引，否则参数必须是 QRgb 值。

若 position 不是有效图像坐标对，或者若 index_or_rgb >= colorCount () in the case of monochrome and 8-bit images, the result is undefined.

警告： 此函数很昂贵由于调用了内部 detach() 函数在调用内；若涉及性能，推荐使用 scanLine() to access pixel data directly.

另请参阅 pixel () 和 像素操纵 .

void QImage:: setPixel ( int x , int y , uint index_or_rgb )

这是重载函数。

设置像素索引或颜色在 ( x , y ) 到 index_or_rgb .

void QImage:: setText (const QString & key , const QString & text )

将图像文本设为给定 text 并将其关联到给定 key .

若仅仅想要存储单文本块 (即：comment 或仅仅描述)，可以传递空键，或使用像 Description 的一般键。

图像文本被嵌入图像数据当调用 save () 或 QImageWriter::write ().

并非所有图像格式都支持嵌入文本。可以找出哪些特定图像或格式支持嵌入文本通过使用 QImageWriter::supportsOption ()。给出范例：

        QImageWriter writer;
        writer.setFormat("png");
        if (writer.supportsOption(QImageIOHandler::Description))
            qDebug() << "Png supports embedded text";
					

可以使用 QImageWriter::supportedImageFormats () 以找出哪些图像格式是可用的。

另请参阅 text () 和 textKeys ().

QSize QImage:: size () const

返回图片大小，即其 width () 和 height ().

另请参阅 图像信息 .

void QImage:: swap ( QImage & other )

交换图像 other 与此图像。此操作非常快且从不失败。

该函数在 Qt 4.8 引入。

QString QImage:: text (const QString & key = QString()) const

返回的图像文本关联给定 key 。若指定 key 是空字符串，返回整个图像文本，每个键文本对由换行符分隔。

另请参阅 setText () 和 textKeys ().

QStringList QImage:: textKeys () const

返回此图像的文本键。

可以使用这些键与 text () 列表某个键的图像文本。

另请参阅 text ().

QImage QImage:: transformed (const QMatrix & matrix , Qt::TransformationMode mode = Qt::FastTransformation) const

返回图像副本的变换是使用给定变换 matrix 和变换 mode .

变换 matrix 在内部调节以补偿不想要的平移；即，产生图像是包含原始图像所有变换点的最小图像。使用 trueMatrix () 函数检索用于变换图像的实际矩阵。

另请参阅 trueMatrix () 和 图像变换 .

QImage QImage:: transformed (const QTransform & matrix , Qt::TransformationMode mode = Qt::FastTransformation) const

返回图像副本的变换是使用给定变换 matrix 和变换 mode .

变换 matrix 在内部调节以补偿不想要的平移；即，产生图像是包含原始图像所有变换点的最小图像。使用 trueMatrix () 函数检索用于变换图像的实际矩阵。

不像其它重载，此函数可以用于对图像履行透视变换。

另请参阅 trueMatrix () 和 图像变换 .

[static] QMatrix QImage:: trueMatrix (const QMatrix & matrix , int width , int height )

返回用于变换图像的实际矩阵采用给定 width , height and matrix .

当变换图像使用 transformed () 函数，变换矩阵在内部调节以补偿不想要的平移，即 transformed () 返回包含原始图像中所有变换点的最小图像。此函数返回修改矩阵，将来自原始图像中的点正确地映射到新图像。

另请参阅 transformed () 和 图像变换 .

[static] QTransform QImage:: trueMatrix (const QTransform & matrix , int width , int height )

返回用于变换图像的实际矩阵采用给定 width , height and matrix .

当变换图像使用 transformed () 函数，变换矩阵在内部调节以补偿不想要的平移，即 transformed () 返回包含原始图像中所有变换点的最小图像。此函数返回修改矩阵，将来自原始图像中的点正确地映射到新图像。

不像其它重载，此函数创建可以用于对图像履行透视变换的变换矩阵。

另请参阅 transformed () 和 图像变换 .

bool QImage:: valid (const QPoint & pos ) const

返回 true 若 pos is a valid coordinate pair within the image; otherwise returns false.

另请参阅 rect () 和 QRect::contains ().

bool QImage:: valid ( int x , int y ) const

这是重载函数。

返回 true 若 QPoint ( x , y ) is a valid coordinate pair within the image; otherwise returns false.

int QImage:: width () const

返回图像宽度。

另请参阅 图像信息 .

QImage:: operator QVariant () const

将图像返回作为 QVariant .

bool QImage:: operator!= (const QImage & image ) const

Returns true if this image and the given image have different contents; otherwise returns false.

比较可能很慢，除非有一些明显差异 (譬如：不同宽度)，在这种情况下函数会快速返回。

另请参阅 operator= ().

QImage & QImage:: operator= (const QImage & image )

赋值浅拷贝为给定 image 到此图像并返回此图像的引用。

有关浅拷贝的更多信息，见 隐式数据共享 文档编制。

另请参阅 copy () 和 QImage ().

QImage & QImage:: operator= ( QImage && other )

bool QImage:: operator== (const QImage & image ) const

Returns true if this image and the given image have the same contents; otherwise returns false.

比较可能很慢，除非有一些明显差异 (如：不同大小或格式)，在这种情况下函数会快速返回。

另请参阅 operator= ().

相关非成员

QDataStream & operator<< ( QDataStream & stream , const QImage & image )

写入给定 image 到给定 stream 作为 PNG 图像，或作为 BMP 图像若流的版本为 1。注意：将流写入文件不会产生有效图像文件。

另请参阅 QImage::save () 和 序列化 Qt 数据类型 .

QDataStream & operator>> ( QDataStream & stream , QImage & image )

读取图像从给定 stream 并把它存储在给定 image .

另请参阅 QImage::load () 和 序列化 Qt 数据类型 .