Класс QImage

Класс QImage предоставляет аппаратно-независимое представление изображения, позволяющее получить прямой доступ к данным пикселей, и может использоваться как устройство рисования. Подробнее...

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

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

Типы Public

Public Функции

• 14 общедоступные функции, унаследованные от QPaintDevice

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

Защищенные функции

• 1 защищенная функция, унаследованная от QPaintDevice

Связанные нечлены

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

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

Qt предоставляет четыре класса для обработки данных изображений: QImage, QPixmap, QBitmap и QPicture. QImage разработан и оптимизирован для ввода-вывода и прямого доступа к пикселям и их манипулирования, в то время как QPixmap разработан и оптимизирован для отображения изображений на экране. QBitmap — это просто класс-обёртка, который наследуется от QPixmap, обеспечивая глубину 1. Наконец, класс QPicture — это устройство рисования, которое записывает и воспроизводит команды QPainter.

Поскольку QImage является подклассом QPaintDevice, QPainter может использоваться для прямого рисования на изображениях. При использовании QPainter на QImage рисование может выполняться в другом потоке, отличном от текущего потока GUI.

Класс QImage поддерживает несколько форматов изображений, описанных перечислением Format. К ним относятся монохромные, 8-битные, 32-битные и альфа-смешанные изображения, доступные во всех версиях Qt 4.x.

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

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

Примечание: Если вы хотите загружать объекты QImage в статической сборке Qt, обратитесь к Руководству по плагинам.

Предупреждение: Рисование на QImage с форматом QImage::Format_Indexed8 не поддерживается.

Чтение и запись файлов изображений

QImage предоставляет несколько способов загрузки файла изображения: файл можно загрузить при создании объекта QImage или с помощью функций load() или loadFromData() позже. QImage также предоставляет статическую функцию fromData(), создающую QImage из заданных данных. При загрузке изображения имя файла может ссылаться на фактический файл на диске или на один из встроенных ресурсов приложения. См. обзор Системы ресурсов Qt для получения подробной информации о том, как встроить изображения и другие файлы ресурсов в исполняемый файл приложения.

Для сохранения объекта QImage просто вызовите функцию save().

Полный список поддерживаемых форматов файлов доступен через функции QImageReader::supportedImageFormats() и QImageWriter::supportedImageFormats(). Новые форматы файлов могут быть добавлены как плагины. По умолчанию Qt поддерживает следующие форматы:

Информация об изображении

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

Манипулирование пикселями

Функции, используемые для манипулирования пикселями изображения, зависят от формата изображения. Причина в том, что монохромные и 8-битные изображения основаны на индексах и используют таблицу соответствия цветов, а 32-битные изображения хранят значения ARGB напрямую. Дополнительную информацию о форматах изображений см. в разделе Форматы изображений.

В случае 32-битного изображения функцию setPixel() можно использовать для изменения цвета пикселя в заданных координатах на любой другой цвет, указанный в виде четвёрки ARGB. Для создания соответствующего значения QRgb используйте функции qRgb() (добавляя по умолчанию альфа-компонент к заданным значениям RGB, т.е. создавая непрозрачный цвет) или qRgba(). Например:

32-битное
	QImage image(3, 3, QImage::Format_RGB32); QRgb value; value = qRgb(189, 149, 39); // 0xffbd9527 image.setPixel(1, 1, value); value = qRgb(122, 163, 39); // 0xff7aa327 image.setPixel(0, 1, value); image.setPixel(1, 0, value); value = qRgb(237, 187, 51); // 0xffedba31 image.setPixel(2, 1, value);

В случае 8-битных и монохромных изображений значение пикселя является только индексом в таблице цветов изображения. Таким образом, функцию setPixel() можно использовать только для изменения цвета пикселя в заданных координатах на предварительно определённый цвет из таблицы цветов изображения, то есть она может изменить только индексное значение пикселя. Для изменения или добавления цвета в таблицу цветов изображения используйте функцию setColor().

Элемент таблицы цветов является четвёркой ARGB, закодированной как значение QRgb. Используйте функции qRgb() и qRgba() для создания подходящего значения QRgb для использования с функцией setColor(). Например:

8-битное
	QImage image(3, 3, QImage::Format_Indexed8); QRgb value; value = qRgb(122, 163, 39); // 0xff7aa327 image.setColor(0, value); value = qRgb(237, 187, 51); // 0xffedba31 image.setColor(1, value); value = qRgb(189, 149, 39); // 0xffbd9527 image.setColor(2, value); image.setPixel(0, 1, 0); image.setPixel(1, 0, 0); image.setPixel(1, 1, 2); image.setPixel(2, 1, 1);

Для изображений с более чем 8 битами на цветовой канал можно использовать методы setPixelColor() и pixelColor() для установки и получения значений QColor.

QImage также предоставляет функцию scanLine(), которая возвращает указатель на данные пикселей в строке сканирования с заданным индексом, и функцию bits(), которая возвращает указатель на первые данные пикселей (это эквивалентно scanLine(0)).

Форматы изображений

Каждый пиксель, хранящийся в QImage, представляется целым числом. Размер целого числа зависит от формата. QImage поддерживает несколько форматов изображений, описанных перечислением Format.

Монохромные изображения хранятся с использованием 1-битовых индексов в таблицу цветов с максимум двумя цветами. Существует два типа монохромных изображений: с порядком битов big endian (MSB вначале) или little endian (LSB вначале).

8-битные изображения хранятся с использованием 8-битовых индексов в таблице цветов, т.е. они имеют по одному байту на пиксель. Таблица цветов — это QVector<QRgb>, а тип QRgb эквивалентен целому без знака, содержащему четвёрку ARGB в формате 0xAARRGGBB.

32-битные изображения не имеют таблицы цветов; вместо этого каждый пиксель содержит значение QRgb. Существует три разных типа 32-битных изображений, хранящих RGB (т.е. 0xffRRGGBB), ARGB и умноженные на альфа значения ARGB соответственно. В формате, умноженном на альфа, красный, зелёный и синий каналы умножаются на альфа-компонент, делённый на 255.

Формат изображения можно получить, используя функцию format(). Используйте функции convertToFormat(), чтобы преобразовать изображение в другой формат. Функции allGray() и isGrayscale() определяют, можно ли безопасно преобразовать цветное изображение в градацию серого.

Преобразования изображений

QImage поддерживает ряд функций для создания нового изображения, являющегося преобразованной версией исходного: функция createAlphaMask() создаёт и возвращает маску 1 бит на пиксель из буфера альфа-канала этого изображения, а функция createHeuristicMask() создаёт и возвращает 1-битовую эвристическую маску для данного изображения. Последняя функция работает, выбирая цвет из одного из углов, а затем удаляя пиксели этого цвета, начиная с всех краёв.

Функция mirrored() возвращает отражение изображения в нужном направлении, функция scaled() возвращает копию изображения, масштабированную до прямоугольника заданных размеров, а функция rgbSwapped() создаёт изображение BGR из RGB-изображения.

Функции scaledToWidth() и scaledToHeight() возвращают масштабированные копии изображения.

Функция transformed() возвращает копию изображения, преобразованную с заданной матрицей преобразования и режимом преобразования: внутренне матрица преобразования корректируется, чтобы компенсировать нежелательное смещение, т.е. transformed() возвращает наименьшее изображение, содержащее все преобразованные точки исходного изображения. Статическая функция trueMatrix() возвращает фактическую матрицу, используемую для преобразования изображения.

Также существуют функции для изменения атрибутов изображения на месте:

См. также QImageReader, QImageWriter, QPixmap, QSvgRenderer, Пример композиции изображений, Пример просмотрщика изображений, Пример рисования и Пример Пикселизатора.

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

enum QImage::Format

В Qt доступны следующие форматы изображений. См. примечания после таблицы.

Примечание: Рисование в QImage с QImage::Format_Indexed8 не поддерживается.

Примечание: Избегайте большинства операций рендеринга напрямую в большинство этих форматов с помощью QPainter. Оптимизированный рендеринг лучше всего подходит для форматов Format_RGB32 и Format_ARGB32_Premultiplied, а вторично для рендеринга в форматы Format_RGB16, Format_RGBX8888, Format_RGBA8888_Premultiplied, Format_RGBX64 и Format_RGBA64_Premultiplied

См. также format() и convertToFormat().

enum QImage::InvertMode

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

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

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

Возвращает QImage, в которой значения красного и синего компонентов всех пикселей были поменены местами, что эффективно преобразует изображение RGB в изображение BGR.

Исходный QImage не изменяется.

См. также Преобразования изображений.

Возвращает зеркальное отражение изображения, отражённое по горизонтали и/или вертикали в зависимости от того, установлены ли horizontal и vertical в значение true или false.

Обратите внимание, что исходное изображение не изменяется.

См. также Преобразования изображений.

Возвращает копию изображения в заданном формате format.

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

См. также Форматы изображений.

QImage::QImage()

Создаёт изображение null.

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

QImage::QImage(const QSize &size, QImage::Format format)

Создаёт изображение с заданным размером size и форматом format.

Возвращается изображение null, если память не может быть выделена.

Предупреждение: Это создаст QImage с неинициализированными данными. Вызовите fill(), чтобы заполнить изображение подходящим значением пикселя перед отрисовкой на нём с помощью QPainter.

QImage::QImage(int width, int height, QImage::Format format)

Создаёт изображение с заданной шириной width, высотой height и форматом format.

Будет возвращено изображение null, если память не может быть выделена.

Предупреждение: Это создаст QImage с неинициализированными данными. Вызовите fill(), чтобы заполнить изображение подходящим значением пикселя перед отрисовкой на нём с помощью QPainter.

QImage::QImage(uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

Создаёт изображение с заданной шириной, высотой и форматом, использующее существующий буфер памяти data. Ширина и высота должны быть указаны в пикселях, data должен быть выровнен по 32 битам, а каждая строка данных в изображении также должна быть выровнена по 32 битам.

Буфер должен оставаться действительным на протяжении всего жизненного цикла QImage и всех его копий, которые не были изменены или иным образом отсоединены от исходного буфера. Изображение не удаляет буфер при уничтожении. Вы можете предоставить указатель на функцию cleanupFunction вместе с дополнительным указателем cleanupInfo, которые будут вызваны, когда будет уничтожена последняя копия.

Если format — формат индексированных цветов, таблица цветов изображения изначально пуста и должна быть достаточно расширена с помощью setColorCount() или setColorTable() перед использованием изображения.

QImage::QImage(const uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

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

Буфер должен оставаться действительным на протяжении всего жизненного цикла QImage и всех его копий, которые не были изменены или иным образом отсоединены от исходного буфера. Изображение не удаляет буфер при уничтожении. Вы можете предоставить указатель на функцию cleanupFunction вместе с дополнительным указателем cleanupInfo, которые будут вызваны, когда будет уничтожена последняя копия.

Если format — формат индексированных цветов, таблица цветов изображения изначально пуста и должна быть достаточно расширена с помощью setColorCount() или setColorTable() перед использованием изображения.

В отличие от аналогичного конструктора QImage, принимающего буфер данных без const, эта версия никогда не изменит содержимое буфера. Например, вызов QImage::bits() вернёт глубокую копию изображения, а не буфер, переданный в конструктор. Это позволяет эффективно создавать QImage из сырых данных, не давая возможности изменить сырые данные.

QImage::QImage(uchar *data, int width, int height, int bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

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

Буфер должен оставаться действительным на протяжении всего жизненного цикла QImage и всех его копий, которые не были изменены или иным образом отсоединены от исходного буфера. Изображение не удаляет буфер при уничтожении. Вы можете предоставить указатель на функцию cleanupFunction вместе с дополнительным указателем cleanupInfo, которые будут вызваны, когда будет уничтожена последняя копия.

Если format — формат индексированных цветов, таблица цветов изображения изначально пуста и должна быть достаточно расширена с помощью setColorCount() или setColorTable() перед использованием изображения.

QImage::QImage(const uchar *data, int width, int height, int bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

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

Буфер должен оставаться действительным на протяжении всего жизненного цикла QImage и всех его копий, которые не были изменены или иным образом отсоединены от исходного буфера. Изображение не удаляет буфер при уничтожении. Вы можете предоставить указатель на функцию cleanupFunction вместе с дополнительным указателем cleanupInfo, которые будут вызваны, когда будет уничтожена последняя копия.

Если format — формат индексированных цветов, таблица цветов изображения изначально пуста и должна быть достаточно расширена с помощью setColorCount() или setColorTable() перед использованием изображения.

В отличие от конструктора QImage, принимающего буфер данных без модификатора const, эта версия никогда не изменит содержимое буфера. Например, вызов QImage::bits() вернёт глубокую копию изображения, а не буфер, переданный в конструктор. Это позволяет эффективно создавать QImage из исходных данных, не рискуя их изменением.

QImage::QImage(const char *const [] xpm)

Создаёт изображение из заданного изображения xpm.

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

Обратите внимание, что можно немного сжать переменную XPM, используя необычное объявление:

static const char * const start_xpm[] = {
    "16 15 8 1",
    "a c #cec6bd",
....

Дополнительный const делает всё определение только для чтения, что немного эффективнее (например, при использовании в общей библиотеке) и позволяет хранить его в ПЗУ вместе с приложением.

QImage::QImage(const QString &fileName, const char *format = nullptr)

Создаёт изображение и пытается загрузить изображение из файла с заданным именем fileName.

Загрузчик пытается прочитать изображение с использованием указанного формата format. Если format не указан (что является значением по умолчанию), он определяется автоматически на основе расширения и заголовка файла. Подробнее см. {QImageReader::setAutoDetectImageFormat()}{QImageReader}.

Если загрузка изображения не удалась, этот объект является пустым изображением.

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

См. также isNull() и Чтение и запись файлов изображений.

QImage::QImage(const QImage &image)

Создаёт неглубокую копию данного изображения image.

Дополнительную информацию о неглубоких копиях см. в документации по неявной совместной обработке данных.

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

QImage::QImage(QImage &&other)

Создаёт QImage с использованием перемещения, указывая на тот же объект, на который указывало other.

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

[virtual] QImage::~QImage()

Уничтожает изображение и очищает ресурсы.

bool QImage::allGray() const

Возвращает true, если все цвета в изображении являются оттенками серого (т. е. их красные, зелёные и синие компоненты равны); в противном случае false.

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

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

int QImage::bitPlaneCount() const

Возвращает количество плоскостей битов в изображении.

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

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

См. также depth(), format() и Форматы изображений.

uchar *QImage::bits()

Возвращает указатель на первые данные пикселей. Это эквивалентно scanLine(0).

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

См. также scanLine(), sizeInBytes() и constBits().

const uchar *QImage::bits() const

Это перегруженная функция.

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

int QImage::bytesPerLine() const

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

Это эквивалентно sizeInBytes() / height() при ненулевом значении height().

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

qint64 QImage::cacheKey() const

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

Ключ изменится при изменении изображения.

QRgb QImage::color(int i) const

Возвращает цвет в цветовой таблице по индексу i. Первый цвет находится по индексу 0.

Цвета в цветовой таблице изображения задаются как четвёрки ARGB (QRgb). Используйте функции qAlpha(), qRed(), qGreen() и qBlue(), чтобы получить компоненты значений цвета.

См. также setColor(), pixelIndex() и Обработка пикселей.

int QImage::colorCount() const

Возвращает размер цветовой таблицы изображения.

Обратите внимание, что colorCount() возвращает 0 для изображений 32-bpp, поскольку эти изображения не используют цветовые таблицы, а вместо этого кодируют значения пикселей как четвёрки ARGB.

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

См. также setColorCount() и Информация об изображении.

QVector<QRgb> QImage::colorTable() const

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

См. также setColorTable(), colorCount() и color().

const uchar *QImage::constBits() const

Возвращает указатель на первые данные пикселей.

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

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

См. также bits() и constScanLine().

const uchar *QImage::constScanLine(int i) const

Возвращает указатель на данные пикселей на строке сканирования с индексом i. Первая строка сканирования имеет индекс 0.

Данные строки сканирования выровнены по границе 32 бит.

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

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

См. также scanLine() и constBits().

QImage QImage::convertToFormat(QImage::Format format, const QVector<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const

Это перегруженная функция.

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

Преобразование из форматов RGB в индексированные форматы — медленная операция и будет использовать прямой подход ближайшего цвета без использования дithering.

QImage QImage::copy(const QRect &rectangle = QRect()) const

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

Возвращаемое изображение копируется из позиции (rectangle.x(), rectangle.y()) в этом изображении и всегда будет иметь размер заданного rectangle.

В областях за пределами этого изображения пиксели устанавливаются в 0. Для 32-битных RGB-изображений это означает чёрный; для 32-битных ARGB-изображений это означает прозрачный чёрный; для 8-битных изображений это означает цвет с индексом 0 в цветовой таблице, который может быть любым; для 1-битных изображений это означает Qt::color0.

Если заданный rectangle является нулевым прямоугольником, копируется всё изображение.

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

QImage QImage::copy(int x, int y, int width, int height) const

Это перегруженная функция.

Возвращаемое изображение копируется из позиции (x, y) в этом изображении и всегда будет иметь заданную width и height. В областях за пределами этого изображения пиксели устанавливаются в 0.

QImage QImage::createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const

Создаёт и возвращает 1-битный маску из буфера альфа-канала в этом изображении. Возвращает пустое изображение, если формат изображения — QImage::Format_RGB32.

Аргумент flags представляет собой битовое ИЛИ значений из перечисления Qt::ImageConversionFlags и управляет процессом преобразования. Передача 0 для параметра flags устанавливает все значения по умолчанию.

Возвращаемый образ имеет порядок битов little-endian (т.е. формат изображения — QImage::Format_MonoLSB), который можно преобразовать в big-endian (QImage::Format_Mono) с помощью функции convertToFormat().

См. также createHeuristicMask() и Преобразования изображений.

QImage QImage::createHeuristicMask(bool clipTight = true) const

Создаёт и возвращает эвристическую маску для этого изображения с 1 бит на пиксель.

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

Возвращаемое изображение имеет порядок битов little-endian (т.е. формат изображения — QImage::Format_MonoLSB), который можно преобразовать в big-endian (QImage::Format_Mono) с помощью функции convertToFormat().

Если clipTight имеет значение true (по умолчанию), маска имеет минимальный размер, достаточный для покрытия пикселей; в противном случае, маска больше, чем пиксели данных.

Обратите внимание, что эта функция игнорирует альфа-канал.

См. также createAlphaMask() и Преобразования изображений.

QImage QImage::createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const

Создаёт и возвращает маску для этого изображения, основанную на заданном значении цвета color. Если mode равен MaskInColor (значение по умолчанию), все пиксели, совпадающие с color, будут непрозрачными пикселями в маске. Если mode равен MaskOutColor, все пиксели, совпадающие с заданным цветом, будут прозрачными.

См. также createAlphaMask() и createHeuristicMask().

int QImage::depth() const

Возвращает глубину изображения.

Глубина изображения — это количество битов, используемых для хранения одного пикселя, также называемое количеством битов на пиксель (bpp).

Поддерживаемые глубины: 1, 8, 16, 24, 32 и 64.

См. также bitPlaneCount(), convertToFormat(), Форматы изображений и Информация об изображении.

qreal QImage::devicePixelRatio() const

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

Используйте эту функцию при расчёте геометрии макета на основе размера изображения: QSize layoutSize = image.size() / image.devicePixelRatio()

Значение по умолчанию — 1.0.

См. также setDevicePixelRatio() и QImageReader.

int QImage::dotsPerMeterX() const

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

См. также setDotsPerMeterX() и Информация об изображении.

int QImage::dotsPerMeterY() const

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

См. также setDotsPerMeterY() и Информация об изображении.

void QImage::fill(uint pixelValue)

Заполняет всё изображение заданным значением pixelValue.

Если глубина этого изображения равна 1, используется только младший бит. Если вы вызываете fill(0), fill(2) и т.д., изображение заполняется нулями. Если вы вызываете fill(1), fill(3) и т.д., изображение заполняется единицами. Если глубина равна 8, используются 8 младших битов, а если глубина равна 16, используются 16 младших битов.

Примечание: QImage::pixel() возвращает цвет пикселя в заданных координатах, в то время как QColor::pixel() возвращает значение пикселя для базовой системы окон (по существу, индексное значение), поэтому обычно вы хотите использовать QImage::pixel() для использования цвета из существующего изображения или QColor::rgb() для использования определённого цвета.

См. также depth() и Преобразования изображений.

void QImage::fill(const QColor &color)

Это перегруженная функция.

Заполняет всё изображение заданным цветом color.

Если глубина изображения равна 1, изображение будет заполнено 1, если color равен Qt::color1; в противном случае оно будет заполнено 0.

Если глубина изображения равна 8, изображение будет заполнено индексом, соответствующим color в таблице цветов, если она присутствует; в противном случае оно будет заполнено 0.

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

void QImage::fill(Qt::GlobalColor color)

Это перегруженная функция.

Заполняет изображение заданным цветом color, описанным как стандартный глобальный цвет.

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

QImage::Format QImage::format() const

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

См. также Форматы изображений.

[static] QImage QImage::fromData(const uchar *data, int size, const char *format = nullptr)

Создаёт QImage из первых size байтов заданных двоичных данных data. Загрузчик пытается прочитать изображение, используя указанный format. Если format не указан (что является значением по умолчанию), загрузчик анализирует данные, чтобы угадать формат файла.

Если format указан, он должен быть одним из значений, возвращаемых функцией QImageReader::supportedImageFormats().

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

См. также load(), save() и Чтение и запись файлов изображений.

[static] QImage QImage::fromData(const QByteArray &data, const char *format = nullptr)

Это перегруженная функция.

Загружает изображение из заданного QByteArray data.

bool QImage::hasAlphaChannel() const

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

См. также Информация об изображении.

int QImage::height() const

Возвращает высоту изображения.

См. также Информация об изображении.

void QImage::invertPixels(QImage::InvertMode mode = InvertRgb)

Инвертирует все значения пикселей в изображении.

Указанный режим инверсии mode имеет значение только при глубине изображения 32. Значение по умолчанию mode — InvertRgb, при котором альфа-канал не изменяется. Если mode — InvertRgba, инвертируются и биты альфа-канала.

Инвертирование 8-битного изображения означает замену всех пикселей с индексом цвета i на пиксель с индексом цвета 255 минус i. То же самое относится к 1-битному изображению. Обратите внимание, что таблица цветов не изменяется.

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

См. также Преобразования изображений.

bool QImage::isGrayscale() const

Для 32-битных изображений эта функция эквивалентна allGray().

Для изображений с цветовыми индексами эта функция возвращает true если цвет(i) равен QRgb(i, i, i) для всех индексов таблицы цветов; в противном случае возвращает false.

См. также allGray() и Форматы изображений.

bool QImage::isNull() const

Возвращает true если это пустое изображение, в противном случае возвращает false.

Пустое изображение имеет все параметры, установленные в ноль, и не содержит выделенных данных.

bool QImage::load(const QString &fileName, const char *format = nullptr)

Загружает изображение из файла с заданным именем fileName. Возвращает true если изображение было успешно загружено; в противном случае делает изображение недоступным и возвращает false.

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

Имя файла может ссылаться на фактический файл на диске или на один из встроенных ресурсов приложения. Смотрите обзор Системы ресурсов для получения подробной информации о том, как встраивать изображения и другие файлы ресурсов в исполняемый файл приложения.

См. также Чтение и запись файлов изображений.

bool QImage::load(QIODevice *device, const char *format)

Это перегруженная функция.

Эта функция считывает QImage из заданного device. Это можно, например, использовать для загрузки изображения непосредственно в QByteArray.

bool QImage::loadFromData(const uchar *data, int len, const char *format = nullptr)

Загружает изображение из первых len байтов заданных двоичных данных. Возвращает true, если изображение было успешно загружено; в противном случае делает изображение недействительным и возвращает false.

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

См. также Чтение и запись файлов изображений.

bool QImage::loadFromData(const QByteArray &data, const char *format = nullptr)

Это перегруженная функция.

Загружает изображение из заданного QByteArray data.

QPoint QImage::offset() const

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

См. также setOffset() и Информация об изображении.

QRgb QImage::pixel(const QPoint &position) const

Возвращает цвет пикселя в заданной позиции.

Если позиция недействительна, результаты не определены.

Предупреждение: Эта функция является ресурсоёмкой при использовании для массовой обработки пикселей. Используйте constBits() или constScanLine() при необходимости чтения многих пикселей.

См. также setPixel(), valid(), constBits(), constScanLine(), и Обработка пикселей.

QRgb QImage::pixel(int x, int y) const

Это перегруженная функция.

Возвращает цвет пикселя в координатах (x, y).

QColor QImage::pixelColor(const QPoint &position) const

Возвращает цвет пикселя в заданной позиции в виде QColor.

Если позиция недействительна, возвращается недействительный QColor.

Предупреждение: Эта функция является ресурсоёмкой при использовании для массовой обработки пикселей. Используйте constBits() или constScanLine() при необходимости чтения многих пикселей.

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

См. также setPixelColor(), setPixel(), valid(), constBits(), constScanLine(), и Обработка пикселей.

QColor QImage::pixelColor(int x, int y) const

Это перегруженная функция.

Возвращает цвет пикселя в координатах (x, y) в виде QColor.

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

QPixelFormat QImage::pixelFormat() const

Возвращает QImage::Format как QPixelFormat

int QImage::pixelIndex(const QPoint &position) const

Возвращает индекс пикселя в заданной позиции.

Если позиция недействительна или изображение не является палитровым изображением (depth() > 8), результаты не определены.

См. также valid(), depth() и Обработка пикселей.

int QImage::pixelIndex(int x, int y) const

Это перегруженная функция.

Возвращает индекс пикселя в координатах (x, y).

QRect QImage::rect() const

Возвращает охватывающую прямоугольник (0, 0, width(), height()) изображения.

См. также Информация об изображении.

bool QImage::reinterpretAsFormat(QImage::Format format)

Изменяет формат изображения на format без изменения данных. Работает только между форматами одинаковой глубины.

Возвращает true, если успешно.

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

Предупреждение: Функция не проверяет, являются ли данные изображения допустимыми в новом формате, и все равно вернет true, если глубины совместимы. Операции с изображением с недопустимыми данными не определены.

Предупреждение: Если изображение не отсоединено, это приведет к копированию данных.

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

См. также hasAlphaChannel() и convertToFormat().

bool QImage::save(const QString &fileName, const char *format = nullptr, int quality = -1) const

Сохраняет изображение в файл с заданным именем fileName, используя заданный формат изображения format и коэффициент качества quality. Если format равен 0, QImage попытается угадать формат, посмотрев на расширение fileName.

Коэффициент quality должен быть в диапазоне от 0 до 100 или -1. Укажите 0 для получения небольших сжатых файлов, 100 для больших несжатых файлов и -1 (значение по умолчанию) для использования стандартных настроек.

Возвращает true если изображение было успешно сохранено; в противном случае возвращает false.

См. также Чтение и запись файлов изображений.

bool QImage::save(QIODevice *device, const char *format = nullptr, int quality = -1) const

Это перегруженная функция.

Эта функция записывает QImage в заданный device.

Это можно, например, использовать для сохранения изображения непосредственно в QByteArray:

        QImage image;
        QByteArray ba;
        QBuffer buffer(&ba);
        buffer.open(QIODevice::WriteOnly);
        image.save(&buffer, "PNG"); // writes image into ba in PNG format

QImage QImage::scaled(const QSize &size, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

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

• Если aspectRatioMode равен Qt::IgnoreAspectRatio, изображение масштабируется до size.
• Если aspectRatioMode равен Qt::KeepAspectRatio, изображение масштабируется до максимально возможного прямоугольника внутри size, сохраняя соотношение сторон.
• Если aspectRatioMode равен Qt::KeepAspectRatioByExpanding, изображение масштабируется до наименьшего возможного прямоугольника вне size, сохраняя соотношение сторон.

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

См. также isNull() и Преобразования изображений.

QImage QImage::scaled(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

Это перегруженная функция.

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

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

QImage QImage::scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation) const

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

Эта функция автоматически вычисляет ширину изображения так, чтобы сохранялось соотношение сторон изображения.

Если заданное height равно 0 или отрицательно, возвращается пустое изображение.

См. также Преобразования изображений.

QImage QImage::scaledToWidth(int width, Qt::TransformationMode mode = Qt::FastTransformation) const

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

Эта функция автоматически вычисляет высоту изображения, сохраняя его соотношение сторон.

Если заданная width равна 0 или отрицательна, возвращается пустое изображение.

См. также Преобразования изображений.

uchar *QImage::scanLine(int i)

Возвращает указатель на данные пикселей в строке сканирования с индексом i. Первая строка сканирования имеет индекс 0.

Данные строки сканирования выравниваются как минимум по 32 бита. Для 64-битных форматов используется родное выравнивание 64-битных целых чисел (64 бита для большинства платформ, но заметно 32 бита на i386).

Предупреждение: Если вы обращаетесь к данным изображения 32 бита на пиксель, приведите возвращаемый указатель к типу QRgb* (QRgb имеет размер 32 бита) и используйте его для чтения/записи значения пикселя. Вы не можете использовать указатель uchar* напрямую, так как формат пикселя зависит от порядка байтов на платформе. Используйте qRed(), qGreen(), qBlue() и qAlpha() для доступа к пикселям.

См. также bytesPerLine(), bits(), Обработка пикселей и constScanLine().

const uchar *QImage::scanLine(int i) const

Это перегруженный метод.

void QImage::setColor(int index, QRgb colorValue)

Устанавливает цвет по указанному index в таблице цветов на заданное значение colorValue. Значение цвета — четвёрка ARGB.

Если index выходит за пределы текущего размера таблицы цветов, она расширяется с помощью setColorCount().

См. также color(), colorCount(), setColorTable() и Обработка пикселей.

void QImage::setColorCount(int colorCount)

Изменяет размер таблицы цветов, чтобы она содержала colorCount элементов.

Если таблица цветов расширяется, все дополнительные цвета устанавливаются как прозрачные (т. е. qRgba(0, 0, 0, 0)).

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

Этот метод был добавлен в Qt 4.6.

См. также colorCount(), colorTable(), setColor() и Преобразования изображений.

void QImage::setColorTable(const QVector<QRgb> colors)

Устанавливает таблицу цветов, используемую для преобразования индексов цветов в значения QRgb, на указанные colors.

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

См. также colorTable(), setColor() и Преобразования изображений.

void QImage::setDevicePixelRatio(qreal scaleFactor)

Устанавливает коэффициент пикселей устройства для изображения. Это отношение между пикселями изображения и независимыми от устройства пикселями.

Значение по умолчанию для scaleFactor — 1.0. Установка его на другое значение имеет два эффекта:

QPainters, открытые на изображении, будут масштабированы. Например, рисование на изображении 200x200 с коэффициентом 2.0 приведет к эффективным (независимым от устройства) границам рисования 100x100.

Пути кода в Qt, вычисляющие геометрию макета на основе размера изображения, учтут этот коэффициент: QSize layoutSize = image.size() / image.devicePixelRatio() Конечный эффект заключается в том, что изображение отображается как изображение высокой четкости, а не как большое изображение (см. Рисование высококачественных версий растровых и изображений).

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

void QImage::setDotsPerMeterX(int x)

Устанавливает количество пикселей, помещающихся горизонтально в 1 метр, на x.

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

См. также dotsPerMeterX() и Сведения об изображении.

void QImage::setDotsPerMeterY(int y)

Устанавливает количество пикселей, помещающихся вертикально в 1 метр, на y.

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

См. также dotsPerMeterY() и Сведения об изображении.

void QImage::setOffset(const QPoint &offset)

Устанавливает количество пикселей, на которое изображение должно быть смещено при позиционировании относительно других изображений, на offset.

См. также offset() и Сведения об изображении.

void QImage::setPixel(const QPoint &position, uint index_or_rgb)

Устанавливает индекс пикселя или цвет в заданной position на index_or_rgb.

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

Если position — некорректная пара координат в изображении, или index_or_rgb >= colorCount() в случае монохромных и палитровых изображений, результат будет неопределенным.

Предупреждение: Этот метод затратен из-за вызова внутренней функции detach() внутри; если важна производительность, рекомендуем использовать scanLine() или bits() для прямого доступа к данным пикселей.

См. также pixel() и Обработка пикселей.

void QImage::setPixel(int x, int y, uint index_or_rgb)

Это перегруженный метод.

Устанавливает индекс пикселя или цвет в точке (x, y) на index_or_rgb.

void QImage::setPixelColor(const QPoint &position, const QColor &color)

Устанавливает цвет в заданной position на color.

Если position — некорректная пара координат в изображении, или формат изображения — монохромный или палитровый, результат будет неопределенным.

Предупреждение: Этот метод затратен из-за вызова внутренней функции detach() внутри; если важна производительность, рекомендуем использовать scanLine() или bits() для прямого доступа к данным пикселей.

Этот метод был добавлен в Qt 5.6.

См. также pixelColor(), pixel(), bits(), scanLine() и Обработка пикселей.

void QImage::setPixelColor(int x, int y, const QColor &color)

Это перегруженный метод.

Устанавливает цвет пикселя в точке (x, y) на color.

Этот метод был добавлен в Qt 5.6.

void QImage::setText(const QString &key, const QString &text)

Устанавливает текст изображения на заданный text и связывает его с заданным key.

Если вы хотите просто сохранить один текстовый блок (например, «комментарий» или просто описание), вы можете либо передать пустой ключ, либо использовать универсальный ключ, например, «Описание».

Текст изображения встраивается в данные изображения, когда вы вызываете save() или QImageWriter::write().

Не все форматы изображений поддерживают встроенный текст. Вы можете узнать, поддерживает ли конкретное изображение или формат встраивание текста, используя QImageWriter::supportsOption(). Пример:

    QImageWriter writer;
    writer.setFormat("png");
    if (writer.supportsOption(QImageIOHandler::Description))
        qDebug() << "Png supports embedded text";

Вы можете использовать QImageWriter::supportedImageFormats(), чтобы узнать, какие форматы изображений доступны.

См. также text() и textKeys().

QSize QImage::size() const

Возвращает размер изображения, т.е. его width() и height().

См. также Информация об изображении.

qsizetype QImage::sizeInBytes() const

Возвращает размер данных изображения в байтах.

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

См. также byteCount(), bytesPerLine(), bits(), и Информация об изображении.

[protected] QImage QImage::smoothScaled(int w, int h) const

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

void QImage::swap(QImage &other)

Меняет местами изображение other с этим изображением. Эта операция очень быстрая и никогда не терпит неудачу.

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

QString QImage::text(const QString &key = QString()) const

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

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

QStringList QImage::textKeys() const

Возвращает ключи текста для этого изображения.

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

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

CGImageRef QImage::toCGImage() const

Создает CGImage эквивалент этого QImage. Возвращает CGImageRef дескриптор.

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

Эта функция быстрая и не копирует и не преобразует данные изображения.

Следующие форматы изображений поддерживаются и будут сопоставлены с соответствующим родным типом изображения:

Другие форматы не поддерживаются; эта функция возвращает нулевой CGImageRef для этих случаев. Пользователи этой функции могут предварительно преобразовать QImage в поддерживаемый формат, например, Format_ARGB32_Premultiplied.

Цветовое пространство CGImageRef установлено в цветовое пространство sRGB.

См. также QtMac::toNSImage().

[static] QImage::Format QImage::toImageFormat(QPixelFormat format)

Преобразует format в QImage::Format

[static] QPixelFormat QImage::toPixelFormat(QImage::Format format)

Преобразует format в QPixelFormat

QImage QImage::transformed(const QMatrix &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const

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

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

Матрица преобразования matrix внутренне корректируется для компенсации нежелательного смещения; т.е. полученное изображение — это наименьшее изображение, содержащее все преобразованные точки исходного изображения. Используйте функцию trueMatrix(), чтобы получить фактическую матрицу, используемую для преобразования изображения.

См. также trueMatrix() и Преобразования изображений.

QImage QImage::transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const

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

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

Матрица преобразования matrix внутренне корректируется для компенсации нежелательного смещения; т.е. полученное изображение — это наименьшее изображение, содержащее все преобразованные точки исходного изображения. Используйте функцию trueMatrix(), чтобы получить фактическую матрицу, используемую для преобразования изображения.

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

См. также trueMatrix() и Преобразования изображений.

[static] QMatrix QImage::trueMatrix(const QMatrix &matrix, int width, int height)

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

При преобразовании изображения с помощью функции transformed() матрица преобразования внутренне корректируется для компенсации нежелательного смещения, т.е. transformed() возвращает наименьшее изображение, содержащее все преобразованные точки исходного изображения. Эта функция возвращает измененную матрицу, которая правильно отображает точки из исходного изображения в новое изображение.

См. также transformed() и Преобразования изображений.

[static] QTransform QImage::trueMatrix(const QTransform &matrix, int width, int height)

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

При преобразовании изображения с помощью функции transformed() матрица преобразования внутренне корректируется для компенсации нежелательного смещения, т.е. transformed() возвращает наименьшее изображение, содержащее все преобразованные точки исходного изображения. Эта функция возвращает измененную матрицу, которая правильно отображает точки из исходного изображения в новое изображение.

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

См. также transformed() и Преобразования изображений.

bool QImage::valid(const QPoint &pos) const

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

См. также rect() и QRect::contains().

bool QImage::valid(int x, int y) const

Это перегруженная функция.

Возвращает true, если QPoint(x, y) — это корректная пара координат внутри изображения; в противном случае возвращает false.

int QImage::width() const

Возвращает ширину изображения.

См. также Информация об изображении.

QVariant QImage::operator QVariant() const

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

bool QImage::operator!=(const QImage &image) const

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

Сравнение может быть медленным, если нет явного различия, такого как разная ширина, в этом случае функция вернётся быстро.

См. также operator=().

QImage &QImage::operator=(const QImage &image)

Присваивает поверхностную копию заданного изображения image этому изображению и возвращает ссылку на это изображение.

Дополнительную информацию о поверхностных копиях см. в документации Неявное совместное использование данных.

См. также copy() и QImage().

QImage &QImage::operator=(QImage &&other)

Перемещает присваивание other этому экземпляру QImage.

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

bool QImage::operator==(const QImage &image) const

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

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

См. также operator=().

void myImageCleanupHandler(void *info);