QImageReader

一、描述

QImageReader 类提供了一个独立于格式的接口，用于从文件或其他设备中读取图像。

读取图像最常见的方法是通过 QImage 和 QPixmap 。与它们相比，QImageReader 可以在读取图像时提供更多控制。例如，可以通过调用 setScaledSize() 将图像读取为特定大小，并且可以通过调用 setClipRect() 选择一个剪辑矩形，有效地仅加载图像的一部分。根据图像格式的底层支持，这可以节省内存并加快图像的加载速度。

QImageReader 假定对分配的文件或设备具有独占控制权。在 QImageReader 对象的生命周期内修改分配的文件或设备的任何尝试都将产生未定义的结果。

二、类型成员

1、enum QImageReader::ImageReaderError：此枚举描述了使用 QImageReader 读取图像时可能发生的不同类型的错误。

• FileNotFoundError：没有找到具有该名称的文件。如果文件名不包含扩展名，并且 Qt 不支持具有正确扩展名的文件，也会发生这种情况。
• DeviceError：读取图像时遇到设备错误。
• UnsupportedFormatError：Qt 不支持请求的图像格式。
• InvalidDataError：图像数据无效，无法从中读取图像。例如图像文件损坏。
• UnknownError：发生未知错误。

三、成员函数

1、【static】void setAllocationLimit(int mbLimit)

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

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

2、void setAutoDetectImageFormat(bool enabled)

设置启用 / 禁用图像格式自动检测。默认启用自动检测。

3、void setAutoTransform(bool enabled)

设置 read() 返回的图像是否自动应用转换元数据。

      QImageIOHandler::Transformations transformation()

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

enum QImageIOHandler::Transformation：此枚举描述了某些图像格式支持的不同转换或方向。

• TransformationNone：不应应用任何转换。
• TransformationMirror：水平镜像图像。
• TransformationFlip：垂直镜像图像。
• TransformationRotate：将图像旋转 180 度。
• TransformationRotate90：将图像旋转 90 度。
• TransformationMirrorAndRotate90：水平镜像图像，然后将其旋转 90 度。
• TransformationFlipAndRotate90：垂直镜像图像，然后将其旋转 90 度。
• TransformationRotate270：将图像旋转 270 度。 这与水平、垂直镜像然后旋转 90 度相同。

 4、void setBackgroundColor(const QColor &color)

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

5、bool canRead()

是否可以为设备读取图像（即支持图像格式，并且设备似乎包含有效数据）

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

对于支持动画的图像，canRead() 在读取所有帧后返回 false。

6、void setClipRect(const QRect &rect)

设置图像剪辑矩形（也称为 ROI，或感兴趣区域）。rect 的坐标相对于未转换的图像大小。

7、int currentImageNumber()

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

8、QRect currentImageRect()

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

9、void setDecideFormatFromContent(bool ignored)

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

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

这也会禁用自动检测图像格式。

10、QImageReader::ImageReaderError error()

返回最后发生的错误类型。

11、QString errorString()

返回最后发生的错误的描述。

12、void setFileName(const QString &fileName)

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

如果 fileName 不包含文件扩展名，将遍历所有支持的扩展名，直到找到匹配的文件。

13、void setFormat(const QByteArray &format)

设置在读取图像时将使用的格式。format 是不区分大小写的文本字符串。

QImageReader reader;
reader.setFormat("png");

14、int imageCount()

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

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

15、QImage::Format imageFormat()

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

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

16、【static】QByteArray imageFormat(const QString &fileName)

        【static】QByteArray imageFormat(QIODevice *device)

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

    qDebug()<

 17、【static】QList imageFormatsForMimeType(const QByteArray &mimeType)

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

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

18、bool jumpToImage(int imageNumber)

对于支持动画的图片格式，该函数跳转到序号为 imageNumber 的图片，成功返回true，找不到对应的图片返回 false。

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

19、bool jumpToNextImage()

对于支持动画的图片格式，该函数会跳转到下一帧图片，成功则返回 true，动画中没有后续图片则返回 false。

20、int loopCount()

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

21、int nextImageDelay()

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

22、QImage read()

从设备读取图像。成功时，返回读取的图像，否则返回一个空 QImage。可以调用 error() 来查找发生的错误类型，或者调用 errorString() 来获取错误描述。

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

      bool read(QImage *image)

将设备中的图像读入 image。返回是否成功读入。

如果图像与即将读取的图像数据具有相同的格式和尺寸，则该函数可能不需要在读取前分配新的图像。正因为如此，它可以比另一个 read() 重载更快。

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

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

23、void setDevice(QIODevice *device)

设置设备。如果设备尚未打开，将尝试通过调用 open() 以 ReadOnly 模式打开设备。

 24、void setQuality(int quality)

设置图像格式的质量。

一些图像格式，尤其是有损图像格式，需要在“结果图像的视觉质量”和“解码执行时间”之间进行权衡。此函数设置支持它的图像格式的权衡级别。

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

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

25、void setScaledClipRect(const QRect &rect)

设置缩放的剪辑矩形。

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

26、void setScaledSize(const QSize &size)

设置图像的缩放大小。

27、QSize size()        实用

返回图像的大小，而不实际读取图像内容。如果图像格式不支持此功能，则此函数返回无效大小。

28、【static】QList supportedImageFormats()

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

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

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

29、【static】QList supportedMimeTypes()

返回支持的 MIME 类型列表。

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

 30、bool supportsAnimation()

图像格式是否支持动画。

31、bool supportsOption(QImageIOHandler::ImageOption option) const

是否支持选项。

不同的图像格式支持不同的选项。调用该函数来判断当前格式是否支持某个选项。

例如，PNG 格式允许将文本嵌入到图像的元数据中（text()），而 BMP 格式允许确定图像的大小，而无需将整个图像加载到内存中（size()）。

enum QImageIOHandler::ImageOption：此枚举描述了 QImageIOHandler 支持的不同选项。一些选项用于查询图像的属性，而其他选项用于切换应写入图像的方式。

• Size：图像的原始大小。
• ClipRect：剪辑矩形，或 ROI（感兴趣区域）。
• ScaledSize：图像的缩放大小。
• ScaledClipRect：图像的缩放剪辑矩形（或 ROI，感兴趣区域）。支持此选项的处理程序应在应用任何缩放 (ScaleSize) 或常规剪辑 (ClipRect) 后应用提供的剪辑矩形 (QRect)。
• Description：图像描述。某些图像格式，例如 GIF 和 PNG，允许将文本嵌入到图像数据中（例如，用于存储版权信息）。
• CompressionRatio：图像数据的压缩率。支
• Gamma：图像的伽玛级别。
• Quality：图像的质量等级。
• Name：图像的名称。
• SubType：图像的子类型。
• IncrementalReading：支持此选项的处理程序预计会分几次读取图像。QImageReader 会将图像视为动画。
• Endianness：图像的字节序。
• Animation：动画类型的图像格式。
• BackgroundColor：背景颜色，某些图像格式允许指定背景颜色。
• ImageFormat：处理程序返回的图像数据格式。这可以是 QImage::Format 中列出的任何格式。
• SupportedSubTypes：支持的子类型名称列表（QList）。
• OptimizedWrite：写入时打开优化标志。
• ProgressiveScanWrite：将图像写入为逐行扫描图像。
• ImageTransformation：可以读取图像的转换元数据。

32、QString text(const QString &key)

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

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

33、QStringList textKeys()

返回此图像的文本键。可以将这些键与 text() 一起使用来列出某个键的图像文本。

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

34、QImageIOHandler::Transformations transformation()

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