Класс QImageReader

Класс QImageReader предоставляет формат-независимый интерфейс для чтения изображений из файлов или других устройств. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Типы

Общедоступные функции

Статические общедоступные члены

Подробное описание

Наиболее распространённый способ чтения изображений — через конструкторы QImage и QPixmap, или вызов QImage::load() и QPixmap::load(). QImageReader — специализированный класс, который даёт вам больший контроль при чтении изображений. Например, вы можете прочитать изображение в определённый размер, вызвав setScaledSize(), и выбрать область обрезки, эффективно загрузив только части изображения, вызвав setClipRect(). В зависимости от поддержки в формате изображения, это может сэкономить память и ускорить загрузку изображений.

Чтобы прочитать изображение, вы начинаете с создания объекта QImageReader. Передайте имя файла или указатель на устройство, а также формат изображения в конструктор QImageReader. Затем вы можете установить несколько параметров, таких как область обрезки (вызвав setClipRect()) и размер масштабирования (вызвав setScaledSize()). canRead() возвращает изображение, если QImageReader может прочитать изображение (т.е. формат изображения поддерживается и устройство открыто для чтения). Вызовите read() для чтения изображения.

Если при чтении изображения возникнет ошибка, read() вернёт нулевое QImage. Затем вы можете вызвать error(), чтобы определить тип ошибки, или errorString(), чтобы получить удобочитаемое описание того, что пошло не так.

Форматы

Вызовите supportedImageFormats() для получения списка форматов, которые может читать QImageReader. QImageReader поддерживает все встроенные форматы изображений, а также любые плагины форматов изображений, которые поддерживают чтение. Вызовите supportedMimeTypes(), чтобы получить список поддерживаемых MIME-типов, которые, например, можно передать в QFileDialog::setMimeTypeFilters().

QImageReader по умолчанию автоматически определяет формат изображения, просматривая предоставленную (необязательную) строку формата, суффикс имени файла и содержимое потока данных. Вы можете включить или отключить эту функцию, вызвав setAutoDetectImageFormat().

Высокоразрешающие версии изображений

Возможно предоставить высокоразрешающие версии изображений, если используется масштабирование между пикселями устройства и независимыми от устройства пикселями.

Высокоразрешающая версия отмечается суффиксом @2x к базовому имени. Прочитанное изображение будет иметь отношение пикселей устройства, установленное в значение 2.

Это можно отключить, установив переменную среды QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING.

См. также QImageWriter, QImageIOHandler, QImageIOPlugin, QMimeDatabase, QColorSpace, QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), и QPainter::drawImage().

Документация типов членов

перечисление QImageReader::ImageReaderError

Это перечисление описывает различные типы ошибок, которые могут возникнуть при чтении изображений с помощью QImageReader.

Документация функций-членов

QImageReader::QImageReader(const QString &fileName, const QByteArray &format = QByteArray())

Создаёт объект QImageReader с именем файла fileName и форматом изображения format.

См. также setFileName().

QImageReader::QImageReader(QIODevice *device, const QByteArray &format = QByteArray())

Создаёт объект QImageReader с устройством device и форматом изображения format.

QImageReader::QImageReader()

Создаёт пустой объект QImageReader. Перед чтением изображения вызовите setDevice() или setFileName().

QImageReader::~QImageReader()

Удаляет объект QImageReader.

[static, since 6.0] int QImageReader::allocationLimit()

Возвращает текущее ограничение выделения памяти в мегабайтах.

Эта функция была добавлена в Qt 6.0.

См. также setAllocationLimit().

bool QImageReader::autoDetectImageFormat() const

Возвращает true, если автоматическое определение формата изображения включено в этом читателе изображений; в противном случае возвращает false. По умолчанию автоматическое определение включено.

См. также setAutoDetectImageFormat().

[since 5.5] bool QImageReader::autoTransform() const

Возвращает true, если обработчик изображения применит метаданные преобразования при вызове read().

Эта функция была добавлена в Qt 5.5.

См. также setAutoTransform(), transformation() и read().

QColor QImageReader::backgroundColor() const

Возвращает цвет фона, используемый при чтении изображения. Если формат изображения не поддерживает установку цвета фона, возвращается недействительный цвет.

См. также setBackgroundColor() и read().

bool QImageReader::canRead() const

Возвращает true, если изображение может быть прочитано из устройства (т.е. формат изображения поддерживается и устройство, похоже, содержит допустимые данные); в противном случае возвращает false.

canRead() — это лёгкая функция, которая выполняет только быструю проверку, чтобы увидеть, являются ли данные изображения допустимыми. read() всё ещё может вернуть false после того, как canRead() вернёт true, если данные изображения повреждены.

Для изображений, которые поддерживают анимацию, 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

Возвращает значение, определяющее, должен ли читатель изображений определить, какой плагин использовать, только на основе содержимого потока данных, а не на основе расширения файла.

См. также 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().

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

Если поддерживается, эта функция возвращает формат изображения файла fileName. В противном случае возвращается пустая строка.

[static] QByteArray QImageReader::imageFormat(QIODevice *device)

Если поддерживается, эта функция возвращает формат изображения устройства device. В противном случае возвращается пустая строка.

См. также QImageReader::autoDetectImageFormat().

[static, since 5.12] QList<QByteArray> QImageReader::imageFormatsForMimeType(const QByteArray &mimeType)

Возвращает список форматов изображений, соответствующих mimeType.

Обратите внимание, что экземпляр QGuiApplication должен быть создан перед вызовом этой функции.

Эта функция была добавлена в Qt 5.12.

См. также 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, которое должно указывать на 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().

[static, since 6.0] void QImageReader::setAllocationLimit(int mbLimit)

Устанавливает предел выделения памяти на mbLimit мегабайт. Изображения, требующие выделения памяти QImage больше этого предела, будут отклонены. Если mbLimit равно 0, проверка размера выделения будет отключена.

Этот предел помогает приложениям избежать неожиданно большого использования памяти при загрузке повреждённых файлов изображений. Обычно его изменять не нужно. Предустановленный предел достаточно велик для всех обычно используемых размеров изображений.

Эта функция была добавлена в Qt 6.0.

См. также allocationLimit().

void QImageReader::setAutoDetectImageFormat(bool enabled)

Если enabled равно true, то автоматическое определение формата изображения включено; в противном случае — выключено. По умолчанию автоматическое определение включено.

QImageReader использует расширенный подход к определению формата изображения; во-первых, если вы передаёте имя файла в QImageReader, он попытается определить расширение файла, если заданный файл не существует, добавляя поддерживаемые расширения по умолчанию к имени файла по одному.

Затем он использует следующий подход для определения формата изображения:

• Сначала запрашиваются плагины изображений, на основе либо строкового формата (необязательно), либо суффикса имени файла (если устройство — файл). В этот момент детектирование содержимого не выполняется. QImageReader выберет первый плагин, поддерживающий чтение этого формата.
• Если ни один плагин не поддерживает формат изображения, проверяются встроенные обработчики Qt, на основе либо строкового формата (необязательно), либо суффикса имени файла.
• Если не найдены ни подходящие плагины, ни встроенные обработчики, каждый плагин проверяется путём проверки содержимого потока данных.
• Если ни один плагин не смог определить формат изображения на основе содержимого данных, проверяется каждый встроенный обработчик изображений путём проверки содержимого.
• Наконец, если все вышеперечисленные подходы не увенчались успехом, QImageReader сообщит об ошибке при попытке чтения изображения.

Отключив автоматическое определение формата изображения, QImageReader будет запрашивать плагины и встроенные обработчики только на основе строкового формата (т.е. расширения имен файлов не будут проверяться).

См. также autoDetectImageFormat(), QImageIOHandler::canRead(), и QImageIOPlugin::capabilities().

[since 5.5] void QImageReader::setAutoTransform(bool enabled)

Определяет, что изображения, возвращаемые функцией read(), должны иметь автоматически применённые метаданные преобразования, если enabled равно true.

Эта функция была добавлена в Qt 5.5.

См. также 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 попытается открыть его в режиме ReadOnly, вызвав open(). Обратите внимание, что это не работает для некоторых устройств, таких как QProcess, QTcpSocket и QUdpSocket, где требуется дополнительная логика для открытия устройства.

См. также device() и setFileName().

void QImageReader::setFileName(const QString &fileName)

Устанавливает имя файла QImageReader на fileName. Внутренне QImageReader создаст объект QFile и откроет его в режиме ReadOnly, чтобы использовать его при чтении изображений.

Если 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.

Некоторые форматы изображений, в частности сжатые, предполагают компромисс между а) визуальным качеством результирующего изображения и б) временем выполнения декодирования. Эта функция устанавливает уровень этого компромисса для форматов изображений, которые его поддерживают.

В случае масштабирования чтения изображения, значение качества может также повлиять на уровень компромисса между визуальным качеством и скоростью выполнения алгоритма масштабирования.

Диапазон значений quality зависит от формата изображения. Например, формат "jpeg" поддерживает диапазон качества от 0 (низкое визуальное качество) до 100 (высокое визуальное качество).

См. также quality() и setScaledSize().

void QImageReader::setScaledClipRect(const QRect &rect)

Устанавливает масштабируемый прямоугольник обрезки на rect. Масштабируемый прямоугольник обрезки — это прямоугольник обрезки (также известный как ROI, или область интереса), который применяется после масштабирования изображения.

См. также scaledClipRect() и setScaledSize().

void QImageReader::setScaledSize(const QSize &size)

Устанавливает масштабированный размер изображения на size. Масштабирование выполняется после первоначального прямоугольника обрезки, но до применения масштабируемого прямоугольника обрезки. Алгоритм, используемый для масштабирования, зависит от формата изображения. По умолчанию (то есть если формат изображения не поддерживает масштабирование), QImageReader будет использовать QImage::scale() с Qt::SmoothScaling.

См. также scaledSize(), setClipRect() и setScaledClipRect().

QSize QImageReader::size() const

Возвращает размер изображения, без фактического чтения содержимого изображения.

Если формат изображения не поддерживает эту функцию, эта функция возвращает недопустимый размер. Встроенные обработчики изображений Qt поддерживают эту функцию, но пользовательские плагины форматов изображений не обязаны.

См. также QImageIOHandler::ImageOption, QImageIOHandler::option() и QImageIOHandler::supportsOption().

[since 5.4] QByteArray QImageReader::subType() const

Возвращает подтип изображения.

Эта функция была добавлена в Qt 5.4.

[static] QList<QByteArray> QImageReader::supportedImageFormats()

Возвращает список форматов изображений, поддерживаемых QImageReader.

По умолчанию Qt может читать следующие форматы:

Чтение и запись SVG файлов поддерживаются модулем Qt SVG. Модуль Qt Image Formats предоставляет поддержку дополнительных форматов изображений.

Обратите внимание, что экземпляр QApplication должен быть создан перед вызовом этой функции.

См. также setFormat(), QImageWriter::supportedImageFormats() и QImageIOPlugin.

[static] QList<QByteArray> QImageReader::supportedMimeTypes()

Возвращает список MIME-типов, поддерживаемых QImageReader.

Обратите внимание, что экземпляр QApplication должен быть создан перед вызовом этой функции.

См. также supportedImageFormats() и QImageWriter::supportedMimeTypes().

[since 5.4] QList<QByteArray> QImageReader::supportedSubTypes() const

Возвращает список подтипов, поддерживаемых изображением.

Эта функция была добавлена в Qt 5.4.

bool QImageReader::supportsAnimation() const

Возвращает true , если формат изображения поддерживает анимацию; в противном случае возвращается false.

См. также QMovie::supportedFormats().

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

Возвращает true , если читатель поддерживает option; в противном случае возвращает 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().

[since 5.5] QImageIOHandler::Transformations QImageReader::transformation() const

Возвращает метаданные преобразования изображения, включая ориентацию изображения. Если формат не поддерживает метаданные преобразования, возвращается QImageIOHandler::TransformationNone.

Эта функция была добавлена в Qt 5.5.

См. также setAutoTransform() и autoTransform().