Класс QImage

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

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

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

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

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

• 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 для получения подробностей о том, как встраивать изображения и другие файлы ресурсов в исполняемый файл приложения.

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

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

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

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

Обработка пикселей

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

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

32-bit
	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-bit
	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 доступны следующие форматы изображений. Значения от Format_ARGB8565_Premultiplied до Format_ARGB4444_Premultiplied были добавлены в Qt 4.4. Значения Format_RGBX8888, Format_RGBA8888 и Format_RGBA8888_Premultiplied были добавлены в Qt 5.2. Значения Format_BGR30, Format_A2BGR30_Premultiplied, Format_RGB30, Format_A2RGB30_Premultiplied были добавлены в Qt 5.4. Format_Alpha8 и Format_Grayscale8 были добавлены в Qt 5.5. См. примечания после таблицы.

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

Примечание: Не рендерить в изображения ARGB32 с использованием QPainter. Использование QImage::Format_ARGB32_Premultiplied значительно быстрее.

Примечание: Форматы с более чем 8 битами на цветовой канал будут обрабатываться растровым процессором только с использованием 8 бит на цвет.

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

enum QImage::InvertMode

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

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

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

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

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

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

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

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

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

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

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

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

QImage::QImage()

Конструирует пустое изображение.

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

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

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

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

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

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

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

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

Предупреждение: Это создаст 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, принимающего неконстантный буфер данных, этот вариант никогда не изменит содержимое буфера. Например, вызов 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, принимающего неконстантный буфер данных, этот вариант никогда не изменит содержимое буфера. Например, вызов 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.

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

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

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

См. также 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-битных изображений, поскольку эти изображения не используют таблицы цветов, а вместо этого кодируют значения пикселей как четвёрки 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

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

Возвращает копию изображения, преобразованного в указанный формат, используя указанную 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-битный маску из буфера альфа-канала в этом изображении. Возвращает изображение null, если формат изображения QImage::Format_RGB32.

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

Возвращаемое изображение имеет порядок бит 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.

См. также 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-битному изображению. Обратите внимание, что таблица цветов не изменяется.

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

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

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. Если format не указан (что является значением по умолчанию), он определяется автоматически на основе расширения файла и заголовка. Подробнее см. {QImageReader::setAutoDetectImageFormat()}{QImageReader}.

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

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

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

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

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

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

Загружает изображение из первых len байтов заданных двоичных данных data. Возвращает 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

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

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

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

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

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

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

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

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

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

Если position недействительна, возвращается недействительный 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

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

Если position недействительна или изображение не является палитровым изображением (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-бита.

Предупреждение: Если вы обращаетесь к данным изображения с 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. Если установить значение отличное от 1.0, произойдут два эффекта:

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

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

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

void QImage::setDotsPerMeterX(int x)

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

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

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

void QImage::setDotsPerMeterY(int y)

Устанавливает количество пикселей, приходящихся на один метр по вертикали, в значение 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);