ImageData

#include <bb/ImageData>

To link against this class, add the following line to your .pro file: LIBS += -lbb

A class that encapsulates pixels and width, height, format information for images.

The ImageData class implements value semantics using copy-on-write, which is also known as "lazy copy" or "lazy evaluation" and by Qt as "implicit data sharing".

This means that copies can conceptually be treated as distinct objects, although for performance reasons, they share memory until one of the copies is actually written to, thus becoming distinct from the original. For example:

bb::ImageData image1(bb::PixelFormat::RGBA_Premultiplied, 400, 300);
bb::ImageData image2 = image1;

// image2 is a copy of image1, so holds the same pixel values. In fact, it points to the same memory location:
qDebug() << (image1.constPixels() == image2.constPixels()); // true

// but now let's change image2
unsigned char * pixels = image2.pixels();

// now image2 is different than image1, so they point to different memory locations
qDebug() << (image1.constPixels() == image2.constPixels()); // false
ImageData can easily be used with Qt's QImage (if you are linking in the QtGui library): 
bb::ImageData fromQImage(const QImage &qImage)
{
    bb::ImageData imageData(bb::PixelFormat::RGBA_Premultiplied, qImage.width(), qImage.height());

    unsigned char *dstLine = imageData.pixels();
    for (int y = 0; y < imageData.height(); y++) {
        unsigned char * dst = dstLine;
        for (int x = 0; x < imageData.width(); x++) {
            QRgb srcPixel = qImage.pixel(x, y);
            *dst++ = qRed(srcPixel);
            *dst++ = qGreen(srcPixel);
            *dst++ = qBlue(srcPixel);
            *dst++ = qAlpha(srcPixel);
        }
        dstLine += imageData.bytesPerLine();
    }

    return imageData;
}
Note that the above example is written for clarity, at the possible expense of performance.
Note:

An invalid ImageData contains undefined data. This means that pixels() and constPixels() will return invalid pointers in this case. Use the isValid() method to check for valid ImageData objects.

Since:

BlackBerry 10.0.0

Public Functions Index

ImageData ()
ImageData (PixelFormat::Type format, int width, int height)
~ImageData ()
ImageData (const ImageData &other)
ImageData &operator= (const ImageData &other)
boolisValid () const
PixelFormat::Typeformat () const
intwidth () const
intheight () const
intbytesPerLine () const
unsigned char *pixels ()
const unsigned char *pixels () const
const unsigned char *constPixels () const

Static Public Functions Index

ImageDatafromPixels (const unsigned char *sourceBuffer, PixelFormat::Type format, int width, int height, int sourceBytesPerLine)

Public Functions

ImageData ()

Creates an invalid ImageData.

Since:

BlackBerry 10.0.0

ImageData (

Creates an ImageData, allocating the necessary memory (for abs(width * height) pixels).

Parameters
format

The format of the created pixels. See PixelFormat for the list of supported formats.

width

The width of the created image buffer.

height

The height of the created image buffer.
Since:

BlackBerry 10.0.0

~ImageData ()

Destructor.

Since:

BlackBerry 10.0.0

ImageData (

Constructs an ImageData as a copy of the given image buffer.

The two ImageData objects share a single internal buffer until either attempts to write to the buffer, at which time a full copy is made.

Parameters
other

The ImageData to copy from.
Since:

BlackBerry 10.0.0

ImageData & operator= (

Assigns the value of other to this ImageData.

Like the copy constructor, this does a shallow-copy until a point at which a full copy is necessary.

Parameters
other

The ImageData to assign.
Return:

The ImageData instance.

Since:

BlackBerry 10.0.0

bool isValid ()

Whether this ImageData object contains valid image data.

Return:

true if this ImageData object contains valid image data, false otherwise.

Since:

BlackBerry 10.0.0

PixelFormat::Type format ()

The format of the pixels.

Return:

The format of the pixels.

See:

PixelFormat.

Since:

BlackBerry 10.0.0

int width ()

The width of the image.

Return:

The width of the image.

Since:

BlackBerry 10.0.0

int height ()

The height of the image.

Return:

The height of the image.

Since:

BlackBerry 10.0.0

int bytesPerLine ()

The bytes per line of the image buffer.

The bytes per line is equivalent to "byte address of first pixel on second line - byte address of first pixel on first line".

Return:

The bytes per line of the image buffer.

Since:

BlackBerry 10.0.0

unsigned char * pixels ()

Get a read/write pointer to the start of pixel memory.

If the internal buffer is currently shared by other instances of ImageData, then a copy of the buffer is made at this point.

Return:

A read/write pointer to the start of pixel memory.

Since:

BlackBerry 10.0.0

const unsigned char * pixels ()

Get a read-only pointer to the start of pixel memory.

Return:

A read-only pointer to the start of pixel memory.

Since:

BlackBerry 10.0.0

const unsigned char * constPixels ()

Get a read-only pointer to the start of pixel memory.

Return:

A read-only pointer to the start of pixel memory.

Since:

BlackBerry 10.0.0

Static Public Functions

ImageData fromPixels (
  • const unsigned char *sourceBuffer,
  • PixelFormat::Typeformat,
  • intwidth,
  • intheight,
  • intsourceBytesPerLine )

Creates an ImageData from existing memory.

The memory is copied into a newly allocated buffer that the ImageData owns.

Parameters
sourceBuffer

The address of the first pixel to copy from.

format

The format of the created pixels. See PixelFormat for the list of supported formats.

width

The width of the created image data.

height

The height of the created image data.

sourceBytesPerLine

The number of bytes per line (stride) in the sourceBuffer.
Return:

The newly created ImageData.

Since:

BlackBerry 10.0.0