Класс 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-битовых индексов в таблицу цветов с максимум двумя цветами. Существуют два типа монохромных изображений: с порядком битов «big endian» (MSB вначале) или «little endian» (LSB вначале).

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

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

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

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

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

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

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

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

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

Правовая информация

Для плавного масштабирования функции transformed() используют код, основанный на алгоритме плавного масштабирования Даниэля М. Дули.

Copyright (C) 2004, 2005 Daniel M. Duley

Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

См. также QImageReader, QImageWriter, QPixmap, QSvgRenderer, Image Composition Example, Image Viewer Example, Scribble Example, и Pixelator Example.

Описание типа элемента

enum QImage::Format

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

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

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

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

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

enum QImage::InvertMode

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

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

Описание функций-членов

QImage::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.

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

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

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

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

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

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

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

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

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

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

Преобразование из 32-битного в 8-битный индексированный формат — медленная операция и будет использовать простой подход «ближайший цвет» без д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.

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

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

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

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

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

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 байтов заданных двоичных данных. Возвращает true если изображение успешно загружено; в противном случае делает изображение недействительным и возвращает false.

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

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

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

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

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.

Коэффициент quality должен быть в диапазоне от 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 бита на пиксель, преобразуйте возвращённый указатель в 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().

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