C

Image Struct

struct Qul::Image

An image representation that allows direct access to the pixel data. More...

Header: #include <qul/image.h>
Since: Qt Quick Ultralite 1.5

This struct was introduced in Qt Quick Ultralite 1.5.

Public Functions

Image(int width, int height, Qul::PixelFormat pixelFormat)
Image(uint8_t *bits, int width, int height, Qul::PixelFormat pixelFormat, int bytesPerLine = -1, Qul::Image::CleanupFunction cleanupFunction = nullptr)
Image()
void beginWrite()
const uint8_t *bits() const
uint8_t *bits()
int bytesPerLine() const
int bytesPerPixel() const
void endWrite()
int height() const
Qul::PixelFormat pixelFormat() const
void reallocate(int width, int height, Qul::PixelFormat pixelFormat)
int width() const
Qul::SharedImage operator Qul::SharedImage() const

Static Public Members

const uintptr_t requiredAlignment
const uintptr_t requiredPixelWidthAlignment

Detailed Description

You can use Image to pass image data to the Qt Quick Ultralite renderer. Image can either allocate new image data on the heap, or accept memory that you have prepared separately.

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

Image takes ownership of data that is passed in. If any cleanup is needed when the last Image or SharedImage reference is destroyed, pass a cleanupFunction to the constructor.

Once an Image instance is constructed, the image data may only be modified between calls to beginWrite() and endWrite() (see ImageWriteGuard).

Note: Some platforms require address alignment or that the bytes-per-line of the image data has to be aligned to a certain multiple of pixels:

bytesPerLine % (bytesPerPixel * requiredPixelWidthAlignment) == 0

Platforms generally don't support all PixelFormats. See Image::requiredAlignment and Image::requiredPixelWidthAlignment.

See also SharedImage and ImageWriteGuard.

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.

Note: If the image is needed for rendering before endWrite() is called, nothing will be drawn to the screen.

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.

Note: Modifications of the pixel data must be placed between calls to beginWrite() and endWrite().

int Image::bytesPerLine() const

Returns the image bytes per line.

int Image::bytesPerPixel() const

Returns the image bytes per pixel.

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.

Member Variable Documentation

const uintptr_t Image::requiredAlignment

The minimum alignment required by the platform for image data.

See also Image::requiredPixelWidthAlignment.

const uintptr_t Image::requiredPixelWidthAlignment

The platform requires that width of image is a multiple of this value.

See also Image::requiredAlignment.

Available under certain Qt licenses.
Find out more.