Класс QImage

Класс 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-битное
	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» (старший бит впереди) или «little endian» (младший бит впереди).

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.

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

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

QImage::QImage(QImage &&other)

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

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

QImage::QImage(const QImage &image)

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

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

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

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

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

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

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

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

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

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 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(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, 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, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

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

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

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

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

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

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

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

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

Создаёт изображение заданного размера и формата.

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

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

QImage::QImage()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QImage::convertTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)

Отвязать и преобразовать изображение в заданный формат на месте.

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

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

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

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-битный маску из буфера альфа-канала в этом изображении. Возвращает пустое изображение, если формат изображения — 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 и 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 если color(i) равно QRgb(i, i, i) для всех индексов таблицы цветов; в противном случае возвращает false.

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

bool QImage::isNull() const

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

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

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

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

Загрузчик пытается прочитать изображение с использованием указанного формата, например, PNG или JPG. Если format не указан (по умолчанию), он определяется автоматически на основе суффикса и заголовка файла. Подробности см. в 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. Если format не указан (по умолчанию), загрузчик исследует файл, чтобы определить формат файла.

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

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 пустой, этот метод возвращает изображение null.

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

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

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

Возвращает копию изображения, масштабированного до прямоугольника заданной ширины и высоты в соответствии с заданным 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() . Конечный эффект заключается в том, что изображение отображается как изображение с высокой точкой 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

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

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

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

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

Другие форматы не поддерживаются; эта функция возвращает null 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)

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

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

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

[static] QTransform QImage::trueMatrix(const QTransform &matrix, int width, int 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=().

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

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

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

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

void myImageCleanupHandler(void *info);