Класс QImageReader

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

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

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

Типы публичного доступа

Функции публичного доступа

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

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

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

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

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

Примечание: QImageReader предполагает исключительный контроль над файлом или устройством, которое присвоено. Любые попытки изменить назначенный файл или устройство в течение срока существования объекта QImageReader приведут к неопределённым результатам.

Форматы

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

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

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

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

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

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

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

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

перечисление 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.

bool QImageReader::autoDetectImageFormat() const

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

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

bool QImageReader::autoTransform() const

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

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

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

QColor QImageReader::backgroundColor() const

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

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

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

bool QImageReader::canRead() const

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

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

Примечание: Обращение к QMimeDatabase обычно является лучшим подходом, чем эта функция, для идентификации потенциально не являющихся изображениями файлов или данных.

Для изображений, поддерживающих анимацию, 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().

float QImageReader::gamma() const

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

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

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

int QImageReader::imageCount() const

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

Функция возвращает -1, если произошла ошибка.

См. также supportsAnimation(), QImageIOHandler::imageCount() и canRead().

QImage::Format QImageReader::imageFormat() const

Возвращает формат изображения, не читая фактическое содержимое изображения. Формат описывает формат изображения, возвращаемый QImageReader::read(), а не формат фактического изображения.

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

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

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

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

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

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

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

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

[static] 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

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

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

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

void QImageReader::setAutoDetectImageFormat(bool enabled)

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

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

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

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

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

void QImageReader::setAutoTransform(bool enabled)

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

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

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

void QImageReader::setBackgroundColor(const QColor &color)

Устанавливает цвет фона на color. Ожидается, что форматы изображений, поддерживающие эту операцию, инициализируют фон цветом color перед чтением изображения.

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

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

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

void QImageReader::setFileName(const QString &fileName)

Устанавливает имя файла QImageReader на fileName. Внутренне QImageReader создаст объект QFile и откроет его в режиме QIODevice::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::setGamma(float gamma)

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

Для коррекции гаммы до стандартного цветового пространства ПК установите гамму на 1/2.2.

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

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

void QImageReader::setQuality(int quality)

Устанавливает значение качества формата изображения на quality.

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

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

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

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

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

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().

QList<QByteArray> QImageReader::supportedSubTypes() const

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

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

bool QImageReader::supportsAnimation() const

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

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

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

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

См. также QImageWriter::supportsOption().

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

Возвращает текст изображения, связанный с key.

Поддержка этого параметра реализована через QImageIOHandler::Description.

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

См. также textKeys() и QImageWriter::setText().

QStringList QImageReader::textKeys() const

Возвращает ключи текста для этого изображения. Вы можете использовать эти ключи с text() для вывода текста изображения для определенного ключа.

Поддержка этого параметра реализована через QImageIOHandler::Description.

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

См. также text(), QImageWriter::setText(), и QImage::textKeys().

QImageIOHandler::Transformations QImageReader::transformation() const

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

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

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