QImage Class

The QImage class provides a hardware-independent image of 32-bit pixels. More…

List of all members, including inherited members

Public Types

Public Functions

Reimplemented Public Functions

Static Public Members

Reimplemented Protected Functions

Detailed Description

QImage stores an image as an array of pixels and doubles as a paint device: draw on it with QPainter. Windows that paint with a QRasterWindow draw into a QImage as well.

QImage image(200, 100, QImage::Format_ARGB32_Premultiplied);
image.fill(Qt::white);
QPainter painter(&image);
painter.fillRect(10, 10, 50, 30, Qt::red);
painter.end();
QRgb pixel = image.pixel(20, 20);

Copies of an image share their pixels until one of them is written to (implicit sharing). Constructing an image on external memory with the pointer constructors does not copy the data; the data must outlive the image and all of its copies, and changing the image changes the memory.

The width(), height() and depth() of an image come from QPaintDevice. The depth is 32, or 0 for a null image.

See also QPainter, QColor and QPaintDevice.

Differences from Qt

Member Type Documentation

enum QImage::Format

This enum describes how the pixels of an image are stored. Every format has 32 bits per pixel, written in the byte order of the machine as 0xAARRGGBB.

Member Function Documentation

QImage::QImage()

Constructs a null image.

See also isNull().

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

Constructs an image of the given size and format. The pixels are not initialized; call fill(). If format is invalid or the size is not positive, the image is null.

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

This is an overloaded function.

Constructs an image that is width pixels wide and height pixels high.

QImage::QImage(uchar *data, int width, int height, Format format)

This is an overloaded function.

Constructs an image of width by height pixels in format that uses the memory at data, which must be 32-bit aligned, hold height lines of width * 4 bytes, and outlive the image.

QImage::QImage(uchar *data, int width, int height, qsizetype bytesPerLine, Format format)

This is an overloaded function.

Constructs an image on the memory at data, which holds height lines that start bytesPerLine bytes apart. bytesPerLine must be at least width * 4 and a multiple of 4.

QImage::QImage(const uchar *data, int width, int height, Format format)

This is an overloaded function.

Constructs a read-only image on the constant memory at data. The first write detaches the image, which copies the pixels.

QImage::QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, Format format)

This is an overloaded function.

Constructs a read-only image on the constant memory at data, with lines bytesPerLine bytes apart.

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

Constructs an image from the file fileName. If the file cannot be read or is not an image that Nt knows, the image is null.

The format is accepted for compatibility with Qt and is ignored: the format is found from the contents of the file.

See also load() and isNull().

QImage::QImage(const QImage &other)

Constructs a copy of other. The pixels are shared until one image is changed.

QImage::QImage(QImage &&other)

Moves other into the new image, which leaves other null.

[override] QImage::~QImage()

Destroys the image.

uchar * QImage::bits()

Returns a pointer to the first pixel, detaching the image from any copies first. Returns nullptr for a null image.

See also constBits() and scanLine().

const uchar * QImage::bits() const

This is an overloaded function.

Returns a pointer to the first pixel without detaching.

qsizetype QImage::bytesPerLine() const

Returns the number of bytes in one scan line, which can be larger than four times the width.

const uchar * QImage::constBits() const

Returns a pointer to the first pixel. It does not detach; use it only to read.

See also bits().

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

Returns a pointer to the pixels of line y, or nullptr if y is out of range. It does not detach; use it only to read.

See also scanLine().

QImage QImage::convertToFormat(Format format) const

Returns a copy of the image in the given format, or a null image if format is invalid. Converting to Format_RGB32 drops the alpha channel.

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

Returns a deep copy of the part of the image inside rect. A null rect copies the whole image. Areas of rect outside the image are transparent black (or opaque black in Format_RGB32).

QImage QImage::copy(int x, int y, int w, int h) const

This is an overloaded function.

Returns a copy of the part of the image at (x, y) that is w by h pixels.

void QImage::detach()

Makes the image own its pixels, copying them if they are shared with another image or live in external memory that the image does not own.

See also isDetached().

void QImage::fill(uint pixel)

Fills the whole image with the pixel value pixel, which is stored as it is (so premultiplied in Format_ARGB32_Premultiplied).

See also setPixel().

void QImage::fill(const QColor &color)

This is an overloaded function.

Fills the image with color, converted to the format of the image.

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

This is an overloaded function.

Fills the image with color.

Format QImage::format() const

Returns the format of the image.

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

Returns an image loaded from the size bytes at data, or a null image if they are not a supported image. The format is ignored.

See also loadFromData().

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

This is an overloaded function.

Returns an image loaded from data.

bool QImage::hasAlphaChannel() const

Returns true if the format has an alpha channel, that is, unless it is Format_RGB32.

bool QImage::isDetached() const

Returns true if no other image shares the pixels and the image does not wrap read-only memory.

See also detach().

bool QImage::isNull() const

Returns true if the image has no pixels.

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

Loads the image in the file fileName and returns true if it succeeded; otherwise returns false and leaves the image null. The formats are PNG, BMP and JPEG. The format is found from the contents of the file, so the format is ignored.

PNG files of every color type, bit depth and interlacing load, with transparency. BMP files of 1, 4, 8, 16, 24 and 32 bits without compression load. JPEG files, including progressive and CMYK ones, load as opaque images. Images without transparency load as Format_RGB32 and the others as Format_ARGB32.

See also save() and loadFromData().

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

This is an overloaded function.

Loads the image from device, which must be open for reading, and reads it to its end.

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

Loads the image from the len bytes at data and returns true if it succeeded. The format is ignored, as in load().

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

This is an overloaded function.

Loads the image from data.

[override, protected] int QImage::metric(PaintDeviceMetric metric) const

Reimplements QPaintDevice::metric().

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

Returns true if the image differs from other.

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

Assigns other to this image; the pixels are shared.

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

Moves other into this image, which leaves other null.

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

Returns true if other has the same size and format and every pixel is equal.

[override] QPaintEngine * QImage::paintEngine() const

Reimplements QPaintDevice::paintEngine().

Returns the paint engine of the image: a raster engine. Returns nullptr for a null image.

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

Returns the color of the pixel at (x, y) as a straight (not premultiplied) QRgb. Returns 0 if the position is outside the image.

See also setPixel() and pixelColor().

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

This is an overloaded function.

Returns the color of the pixel at pt.

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

Returns the pixel at (x, y) as a QColor, which is invalid when the position is outside the image.

See also setPixelColor() and pixel().

QRect QImage::rect() const

Returns the rectangle that covers the image, with its top left at the origin.

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

Saves the image to the file fileName and returns true if it succeeded. The format is "PNG", "BMP", "JPG" or "JPEG", in any case; if it is nullptr, the suffix of the file name decides.

The quality is between 0 and 100, or -1 for the default. For JPEG, 100 is the best quality and the largest file. For PNG, 0 is the strongest compression and 100 stores the pixels without it. BMP ignores it.

PNG and BMP files keep the alpha channel. JPEG files cannot, and the transparency is dropped.

See also load().

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

This is an overloaded function.

Writes the image to device, which must be open for writing. The format must be given.

uchar * QImage::scanLine(int y)

Returns a pointer to the pixels of line y, detaching the image first. y must be in range.

See also constScanLine() and bits().

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

This is an overloaded function.

Returns a pointer to the pixels of line y without detaching.

void QImage::setDevicePixelRatio(qreal ratio)

Sets the device pixel ratio of the image to ratio: the number of pixels of the image that stand for one unit of the coordinates of a QPainter that paints on it. A ratio of 2 makes a painter draw everything twice as large, and drawImage() show the image at half its size. Values below 1 are ignored. The backing store of a window on a high-resolution screen is an image with this set.

See also QPaintDevice::devicePixelRatio().

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

Sets the pixel at (x, y) to index_or_rgb, a straight QRgb that is converted to the format of the image. Does nothing outside the image.

See also pixel().

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

This is an overloaded function.

Sets the pixel at pt to index_or_rgb.

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

Sets the pixel at (x, y) to color.

See also pixelColor() and setPixel().

QSize QImage::size() const

Returns the size of the image in pixels.

qsizetype QImage::sizeInBytes() const

Returns the number of bytes the pixels occupy.

void QImage::swap(QImage &other)

Swaps this image with other.

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

Returns true if the pixel at (x, y) lies inside the image.

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

This is an overloaded function.

Returns true if pt lies inside the image.