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

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

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

Читает изображение из устройства. При успехе возвращается прочитанное изображение; в противном случае возвращается 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().

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

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

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

Эта функция была добавлена в 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().