QImageReader类

成员函数文档

QImageReader::QImageReader()

构建一个空的QImageReader对象。在读取图像之前，调用setDevice()或setFileName()。

[明确] QImageReader::QImageReader(QIODevice *device, const QByteArray &format = QByteArray())

使用设备device和图像格式format构建QImageReader对象。

[明确定义] QImageReader::QImageReader(const QString &fileName, const QByteArray &format = QByteArray())

使用文件名fileName和图像格式format构造一个QImageReader对象。

另请参阅setFileName().

[异常安全] QImageReader::~QImageReader()

销毁QImageReader对象。

[静态, 自6.0版以来] int QImageReader::allocationLimit()

返回当前的分配限制（以兆字节为单位）。

此函数自Qt 6.0版本引入。

另请参阅setAllocationLimit().

bool QImageReader::autoDetectImageFormat() const

如果此图像读取器启用了图像格式自动检测，则返回true；否则返回false。默认情况下，自动检测是启用的。

另请参阅setAutoDetectImageFormat().

bool QImageReader::autoTransform() const

如果图像处理程序将在read()时应用转换元数据，则返回true。

另请参阅setAutoTransform()，transformation()和read().

QColor QImageReader::backgroundColor() const

返回读取图像时使用的背景颜色。如果图像格式不支持设置背景颜色，则返回一个无效颜色。

另请参阅setBackgroundColor()和read().

bool QImageReader::canRead() const

如果可以为设备读取图像（即图像格式受支持，并且设备似乎包含有效数据），则返回true；否则返回false。

canRead()是一个轻量级函数，它只进行快速测试以查看图像数据是否有效。即使在canRead()返回true之后，如果图像数据损坏，read()可能还会返回false。

对于支持动画的图像，当所有帧都已读取时，canRead()返回false。

另请参阅read()，supportedImageFormats()和QMimeDatabase。

QRect QImageReader::clipRect() const

返回图像的剪辑矩形（也称为ROI或感兴趣区域）。如果没有设置剪辑矩形，则返回一个无效的QRect。

另请参阅setClipRect().

int QImageReader::currentImageNumber() const

对于支持动画的图像格式，此函数返回当前帧的序列号。如果图像格式不支持动画，则返回0。

如果发生错误，此函数返回-1。

参见：supportsAnimation()，QImageIOHandler::currentImageNumber() 和 canRead()。

QRect QImageReader::currentImageRect() const

对于支持动画的图像格式，此函数返回当前帧的矩形。否则，返回空矩形。

参见：supportsAnimation() 和 QImageIOHandler::currentImageRect()。

bool QImageReader::decideFormatFromContent() const

返回图像读取器是否应根据数据流的 contents 决定使用哪个插件，而不是根据文件扩展名。

参见：setDecideFormatFromContent()。

QIODevice *QImageReader::device() const

返回当前分配给 QImageReader 的设备，如果没有分配设备，则返回 nullptr。

参见：setDevice()。

QImageReader::ImageReaderError QImageReader::error() const

返回上次发生的错误类型。

参见：ImageReaderError 和 errorString()。

QString QImageReader::errorString() const

返回上次发生的错误的可读描述。

参见：error()。

QString QImageReader::fileName() const

如果当前分配的设备是 QFile，或者如果调用了 setFileName()，则此函数返回 QImageReader 从中读取的文件名。否则（即，如果没有分配设备或设备不是 QFile），返回空的 QString。

参见：setFileName() 和 setDevice()。

QByteArray QImageReader::format() const

返回 QImageReader 用于读取图像的格式。

您可以在将设备分配给读取器之后调用此函数，以确定设备的格式。例如

QImageReader reader("image.png");
// reader.format() == "png"

如果读取器无法从设备中读取任何图像（例如，设备中没有图像，或者图像已被读取），或者格式不受支持，则此函数返回空的 QByteArray()。

参见：setFormat() 和 supportedImageFormats()。

int QImageReader::imageCount() const

对于支持动画的图像格式，此函数返回动画中的图像总数。如果格式不支持动画，则返回 0。

如果发生错误，此函数返回-1。

参见：supportsAnimation()，QImageIOHandler::imageCount() 和 canRead()。

QImage::Format QImageReader::imageFormat() const

返回图像的格式，而不实际上读取图像内容。该格式描述了QImageReader::read()函数返回的图像格式，而不是实际图像的格式。

如果图像格式不支持此功能，则此函数返回一个无效格式。

另请参阅QImageIOHandler::ImageOption，QImageIOHandler::option() 和 QImageIOHandler::supportsOption。

[静态] QByteArray QImageReader::imageFormat(const QString &fileName)

如果支持，此函数返回文件fileName的图像格式。否则，返回空字符串。

[静态] QByteArray QImageReader::imageFormat(QIODevice *device)

如果支持，此函数返回设备device的图像格式。否则，返回空字符串。

另请参阅QImageReader::autoDetectImageFormat。

[静态] QList<QByteArray> QImageReader::imageFormatsForMimeType(const QByteArray &mimeType)

返回与mimeType对应的图像格式列表。

请注意，在调用此函数之前必须创建QGuiApplication实例。

另请参阅supportedImageFormats() 和 supportedMimeTypes。

bool QImageReader::jumpToImage(int imageNumber)

对于支持动画的图像格式，此函数跳转到序列号为imageNumber的图像，如果成功则返回true，如果找不到对应的图像则返回false。

下一次调用read()将尝试读取此图像。

另请参阅jumpToNextImage() 和 QImageIOHandler::jumpToImage。

bool QImageReader::jumpToNextImage()

对于支持动画的图像格式，此函数将越过当前图像，如果成功则返回true，如果在动画中没有后续图像则返回false。

默认实现调用read()，然后丢弃生成的图像，但图像处理器可能有更有效的实现此操作的方法。

另请参阅jumpToImage() 和 QImageIOHandler::jumpToNextImage。

int QImageReader::loopCount() const

对于支持动画的图像格式，此函数返回动画应循环的次数。如果此函数返回-1，这可能意味着动画应无限循环或发生错误。如果发生错误，canRead()将返回false。

参见supportsAnimation()、QImageIOHandler::loopCount()和canRead。

int QImageReader::nextImageDelay() const

对于支持动画的图像格式，此函数返回等待显示动画下一帧的毫秒数。如果图像格式不支持动画，则返回0。

如果发生错误，此函数返回-1。

参见supportsAnimation、QImageIOHandler::nextImageDelay和canRead。

int QImageReader::quality() const

返回图像格式的质量设置。

参见setQuality。

QImage QImageReader::read()

从设备读取图像。成功时返回读入的图像；否则返回一个空的QImage。您可以使用error()找到错误的类型，或使用errorString()获取错误的描述。

对于支持动画的图像格式，重复调用read()将返回下一帧。当所有帧已读取完毕时，将返回一个空图像。

参见canRead、supportedImageFormats、supportsAnimation和QMovie。

bool QImageReader::read(QImage *image)

这是一个重载函数。

从设备读取图像到image，其中image必须指向一个QImage。成功时返回true；否则返回false。

如果image与即将读取的图像数据具有相同的格式和大小，则此函数在读取之前可能不需要分配新图像。因此，它可能比其他read()重载函数更快；尤其是当读取具有相同格式和大小的多个图像时。

QImage icon(64, 64, QImage::Format_RGB32);
QImageReader reader("icon_64x64.bmp");
if (reader.read(&icon)) {
    // Display icon
}

对于支持动画的图像格式，重复调用read()将返回下一帧。当所有帧已读取完毕时，将返回一个空图像。

参见canRead、supportedImageFormats、supportsAnimation和QMovie。

QRect QImageReader::scaledClipRect() const

返回图像的缩放裁剪矩形。

参见setScaledClipRect。

QSize QImageReader::scaledSize() const

返回图像的缩放大小。

参见setScaledSize。

[静态，自6.0以来] void QImageReader::setAllocationLimit(int mbLimit)

将分配限制设置为mbLimit兆字节。需要超过此限制QImage内存分配的图像将被拒绝。如果mbLimit为0，则将禁用分配大小检查。

此限制有助于应用程序避免加载损坏的图像文件时内存使用量意外增大。通常不需要更改它。默认限制足够大，适用于所有常用图像大小。

在运行时，此值可能被环境变量QT_IMAGEIO_MAXALLOC覆盖。

此函数自Qt 6.0版本引入。

另请参阅 allocationLimit().

void QImageReader::setAutoDetectImageFormat(bool enabled)

如果enabled为真，则启用图像格式自动检测；否则，将其禁用。默认情况下，自动检测已启用。

QImageReader使用广泛的方法来检测图像格式；首先，如果您向QImageReader传递一个文件名，并且给定的文件名不指向现有文件，它会尝试检测文件扩展名，通过给定的文件名添加支持默认扩展名，每次一个。然后它使用以下方法来检测图像格式

• 首先查询图像插件，基于可选的格式字符串或文件名后缀（如果源设备是文件）。在此阶段不会进行内容检测。QImageReader将选择支持读取此格式的第一个插件。
• 如果没有插件支持图像格式，Qt的内置处理器将基于可选的格式字符串或文件名后缀进行检测。
• 如果没有找到具有能力的插件或内置处理器，将通过检查数据流的内容测试每个插件。
• 如果没有任何插件能够根据数据内容检测图像格式，将测试每个内置图像处理器的内容。
• 最后，如果在所有上述方法失败后，当尝试读取图像时QImageReader将报告失败。

通过禁用图像格式自动检测，QImageReader将只根据格式字符串（即不测试文件名扩展名）查询插件和内置处理器。

另请参阅 autoDetectImageFormat、QImageIOHandler::canRead和QImageIOPlugin::capabilities。

void QImageReader::setAutoTransform(bool enabled)

当enabled为true时，确定返回由read()返回的图像应自动应用转换元数据。

另请参阅 autoTransform、transformation和read。

void QImageReader::setBackgroundColor(const QColor &color)

将背景颜色设置为color。预期支持此操作的图像格式在读取图像之前将背景初始化为color。

另请参阅 backgroundColor和read。

void QImageReader::setClipRect(const QRect &rect)

将图像剪辑矩形（也称为ROI，即感兴趣区域）设置为rect。rect的坐标相对于未转换的图像大小，该大小由size()返回。

另请参阅 clipRect()，setScaledSize() 和 setScaledClipRect()。

void QImageReader::setDecideFormatFromContent(bool ignored)

如果将 ignored 设置为 true，则图像读取器将忽略指定的格式或文件扩展名，仅根据数据流中的内容决定使用哪个插件。

设置此标志意味着将加载所有图像插件。每个插件将读取图像数据中的第一个字节并决定该插件是否兼容。

这还将禁用自动检测图像格式。

另请参阅 decideFormatFromContent()。

void QImageReader::setDevice(QIODevice *device)

设置 QImageReader 的设备为 device。如果设备已经设置，旧设备将被从 QImageReader 中删除，否则保持不变。

如果设备尚未打开，QImageReader 将尝试通过调用 open() 以只读模式打开设备。请注意，这不适用于某些设备，例如 QProcess，QTcpSocket 和 QUdpSocket，在这些设备上需要更多的逻辑来打开设备。

另请参阅 device() 和 setFileName()。

void QImageReader::setFileName(const QString &fileName)

将 QImageReader 的文件名设置为 fileName。内部，QImageReader 将创建一个 QFile 对象并以只读模式打开它，并在读取图像时使用它。

如果 fileName 不包含文件扩展名（例如，.png 或 .bmp），QImageReader 将遍历所有支持的扩展名，直到找到一个匹配的文件。

另请参阅 fileName()，setDevice() 和 supportedImageFormats()。

void QImageReader::setFormat(const QByteArray &format)

将 QImageReader 读取图像时使用的格式设置为 format。 format 是一个不区分大小写的文本字符串。例如

QImageReader reader;
reader.setFormat("png"); // same as reader.setFormat("PNG");

您可以通过调用 supportedImageFormats() 获取 QImageReader 支持的所有格式列表。

另请参阅 format()。

void QImageReader::setQuality(int quality)

将图像格式的质量设置为 quality。

某些图像格式，尤其是有损格式，会在以下方面权衡：a) 结果图像的可视质量，和 b) 解码执行时间。该函数为此设置了支持此功能的图像格式的权衡级别。

在缩放图像读取的情况下，质量设置还可能影响缩放算法在视觉质量和执行速度之间的权衡级别。

“质量”的范围取决于图像格式。例如，“jpeg”格式支持从0（低视觉质量）到100（高视觉质量）的质量范围。

另请参阅quality()和setScaledSize()。

void QImageReader::setScaledClipRect(const QRect &rect)

将缩放后的剪辑矩形设置为rect。缩放后的剪辑矩形是在图像缩放后应用剪辑矩形的（也称为ROI，或感兴趣区域）。

另请参阅scaledClipRect()和setScaledSize()。

void QImageReader::setScaledSize(const QSize &size)

将图像的缩放大小设置为size。缩放是在初始剪辑矩形之后，但在缩放剪辑矩形应用之前进行的。使用的缩放算法取决于图像格式。默认情况下（即如果图像格式不支持缩放），QImageReader将使用Qt::SmoothScaling的QImage::scale()。

另请参阅scaledSize()，setClipRect()和setScaledClipRect()。

QSize QImageReader::size() const

返回图像的大小，而不实际读取图像内容。

如果图像格式不支持此功能，此函数返回无效的大小。Qt的内置图像处理程序都支持此功能，但自定义图像格式插件并不需要进行此类操作。

另请参阅QImageIOHandler::ImageOption，QImageIOHandler::option() 和 QImageIOHandler::supportsOption。

QByteArray QImageReader::subType() const

返回图像的子类型。

[静态]QList<QByteArray> QImageReader::supportedImageFormats()

返回QImageReader支持的图像格式列表。

默认情况下，Qt可以读取以下格式

通过Qt SVG模块支持读取和写入SVG文件。通过Qt Image Formats模块提供对其他图像格式的支持。

注意，在调用此函数之前必须创建QApplication实例。

另请参阅setFormat()，QImageWriter::supportedImageFormats()和QImageIOPlugin。

[静态]QList<QByteArray> QImageReader::supportedMimeTypes()

返回支持由 QImageReader 的 MIME 类型列表。

注意，在调用此函数之前必须创建QApplication实例。

另请参阅supportedImageFormats() 和 QImageWriter::supportedMimeTypes。

QList<QByteArray> QImageReader::supportedSubTypes() const

返回图像支持的子类型列表。

bool QImageReader::supportsAnimation() const

如果图像格式支持动画，则返回 true，否则返回 false。

另请参阅QMovie::supportedFormats。

bool QImageReader::supportsOption(QImageIOHandler::ImageOption option) const

如果读取器支持 option，则返回 true；否则返回 false。

不同的图像格式支持不同的选项。调用此函数可确定当前格式是否支持某个选项。例如，PNG 格式允许将文本嵌入到图像的元数据中（参见 text()），BMP 格式允许在将整个图像加载到内存中之前确定图像的大小（参见 size()）。

QImageReader reader(":/image.png");
if (reader.supportsOption(QImageIOHandler::Size))
    qDebug() << "Size:" << reader.size();

另请参阅QImageWriter::supportsOption。

QString QImageReader::text(const QString &key) const

返回与 key 关联的图像文本。

此选项的支持是通过 QImageIOHandler::Description 实现的。

另请参阅textKeys() 和 QImageWriter::setText。

QStringList QImageReader::textKeys() const

返回与此图像相关的文本键。您可以使用这些键与 text() 一起列出特定键的图像文本。

此选项的支持是通过 QImageIOHandler::Description 实现的。

另请参阅text，QImageWriter::setText 和 QImage::textKeys。

QImageIOHandler::Transformations QImageReader::transformation() const

返回图像的转换元数据，包括图像方向。如果格式不支持转换元数据，则返回 QImageIOHandler::TransformationNone。

另请参阅setAutoTransform() 和 autoTransform。