Класс QImage

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

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

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

Типы

Открытые функции

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

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

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

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

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

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

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

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

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

Класс 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-битных индексов в таблицу цветов с не более чем двумя цветами. Существуют два разных типа монохромных изображений: с порядком битов большого эндиана (MSB первым) или малого эндиана (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, Image Composition Example, Image Viewer Example, Scribble Example, и Pixelator Example.

Member Type Documentation

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

Member Function Documentation

QImage::QImage()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QImage::QImage(const QImage &image)

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

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

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

QImage::QImage(QImage &&other)

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

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

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(), byteCount(), и constBits().

const uchar *QImage::bits() const

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

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

int QImage::byteCount() const

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

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

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

int QImage::bytesPerLine() const

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

Это эквивалентно byteCount() / 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().

QImage QImage::convertToFormat(Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создает и возвращает 1-битный эвристический маску для этого изображения.

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

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

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

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

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

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

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

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

int QImage::depth() const

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

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

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

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

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

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

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

Format QImage::format() const

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

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

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

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

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

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

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

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

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

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

bool QImage::hasAlphaChannel() const

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

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

int QImage::height() const

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

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

void QImage::invertPixels(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 = Q_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 = Q_NULLPTR)

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

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

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

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

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

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

QImage QImage::mirrored(bool horizontal = false, bool vertical = true) const

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

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

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

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

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

Возвращает true при успехе.

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

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

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

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

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

QImage QImage::rgbSwapped() const

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

Исходное изображение QImage не изменяется.

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

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

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

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

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

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

bool QImage::save(QIODevice *device, const char *format = Q_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-bpp, приведите возвращённый указатель к QRgb* (QRgb имеет 32-битовый размер) и используйте его для чтения/записи значения пикселя. Вы не можете использовать указатель uchar* напрямую, так как формат пикселя зависит от порядка байтов на платформе. Используйте qRed(), qGreen(), qBlue() и qAlpha() для доступа к пикселям.

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

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

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

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

Устанавливает цвет в заданном index таблицы цветов в указанное значение colorValue. Значение цвета является ARGB-четверкой.

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

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

void QImage::setColorCount(int colorCount)

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

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

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

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

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

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

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

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

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

void QImage::setDevicePixelRatio(qreal scaleFactor)

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

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

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

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

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

void QImage::setDotsPerMeterX(int x)

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

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

[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 отсоединит его как обычно.

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

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

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

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

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

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

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