Класс QImageReader

Класс 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, QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), QPainter::drawImage(), и Qt::AA_UseHighDpiPixmaps.

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

enum QImageReader::ImageReaderError

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

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

QImageReader::QImageReader()

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

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

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

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

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

См. также 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, если данные изображения повреждены.

Для изображений, поддерживающих анимацию, canRead() возвращает false после чтения всех кадров.

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

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, или 0, если устройство не было назначено.

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

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

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

Читает изображение из устройства. При успехе возвращает прочитанное изображение, в противном случае — null QImage. Затем вы можете вызвать error(), чтобы узнать тип произошедшей ошибки, или errorString(), чтобы получить удобочитаемое описание ошибки.

Для форматов изображений, поддерживающих анимацию, многократный вызов read() вернёт последующие кадры. После чтения всех кадров возвращается null-изображение.

См. также 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() вернёт последующие кадры. После чтения всех кадров возвращается null-изображение.

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

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

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

Диапазон значений 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::Transformation_None.

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

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