// Allocate new image data on the heap
Qul::Image image1(drawImgSize, drawImgSize, Qul::PixelFormat_ARGB32_Premultiplied);

// Uses the data at myimagedata without a copy.
// (no cleanup function passed in, so lifetime of myimagedata must exceed any use)
// Application should take care about memory and texture width alignment
Qul::Image image2(getLogoData(),
                  logoImgWidth,
                  logoImgHeight,
                  Qul::PixelFormat_ARGB32_Premultiplied);

bytesPerLine % (bytesPerPixel * requiredPixelWidthAlignment) == 0

Member Function Documentation

Image::Image(int width, int height, Qul::PixelFormat pixelFormat)

Construct by allocating new image data on the heap.

Not all pixelFormat are supported on all platforms. Images with unsupported formats are not drawn, but do not cause an error.

Image::Image(uint8_t *bits, int width, int height, Qul::PixelFormat pixelFormat, int bytesPerLine = -1, Qul::Image::CleanupFunction cleanupFunction = nullptr)

Construct from externally owned memory.

Image takes ownership of bits. The cleanupFunction will be run when the last reference to the data (including SharedImage references) is destroyed.

Some platforms have specific requirements for image data. If these are not met, the application prints an error and halts. See Image::requiredAlignment and Image::requiredPixelWidthAlignment.

Not all pixelFormat are supported on all platforms. Images with unsupported formats are not drawn, but do not cause an error.

The image data behind bits may only be changed between calls to beginWrite() and endWrite(). See also ImageWriteGuard.

If bytesPerLine is -1, it is calculated based on the width and pixelFormat.

Image::Image()

Construct an empty image.

void Image::beginWrite()

Prepare the referenced memory for write operations.

Call this function before writing to the assigned memory area to avoid potential artifacts. Call endWrite() when done.

Many platforms support hardware-accelerated drawing operations that run asynchronously. This function waits for all such operations that read from the assigned memory area to finish. On other platforms, the image may need to be uploaded to the GPU memory once the write operation has finished.

See also endWrite().

const uint8_t *Image::bits() const

Returns the image pixel data for reading.

uint8_t *Image::bits()

Returns the image pixel data for reading or writing.

int Image::bitsPerPixel() const

Returns the image bits per pixel.

int Image::bytesPerLine() const

Returns the image bytes per line.

void Image::endWrite()

End a write operation to the referenced memory.

This may trigger a dcache flush in preparation for asynchronous read operations, or may upload the image data to the GPU memory.

If the image data is currently visible on the screen, it is redrawn for the next frame.

See also beginWrite().

int Image::height() const

Returns the image height in pixels.

Qul::PixelFormat Image::pixelFormat() const

Returns the image PixelFormat.

void Image::reallocate(int width, int height, Qul::PixelFormat pixelFormat)

Change the size and format of the image, affecting all existing references.

This executes the cleanup function on the existing image data, and allocates new image data for the given width, height and pixelFormat on the heap to replace it.

All references to this Image will update to the new image data.

int Image::width() const

Returns the image width in pixels.

Qul::SharedImage Image::operator Qul::SharedImage() const

Implicitly convert to SharedImage.

Image and SharedImage use the same reference count to the underlying data.