Into

Modules

Documentation

classPiiQImage

#include <PiiQImage.h>

A matrix that shares data with a QImage, and an image that shares data with a PiiMatrix.

Inherits QImage, PiiMatrix< T >

Description

The matrix is constructed with either a QImage or a PiiMatrix, and modifying either will also modify the other. The data will always be owned by the PiiMatrix part of the class; if you construct a PiiQImage with a QImage, the QImage will be hacked to believe it doesn't own its data any more.

PiiQImage breaks many usual programming paradigms, and can be considered an ugly, dangerous hack. But it saves a lot of memory and processing time by making conversions between PiiMatrix and QImage unnecessary.

Since QImage supports 1, 8 and 32 bit images, and PiiMatrix cannot go below 8 bits, the template type must be either 8 or 32 bits in size. Use unsigned char for gray scale and indexed images, and PiiColor4<unsigned char> for color images.

WARNING! If you make a copy of PiiQImage either as a QImage or as a PiiMatrix, and subsequently call any non-const function on the original object, the internal data will be automatically duplicated by either QImage or PiiMatrix. As a result, the inherited PiiQImage ends up having two data buffers, and either one may change depending on which function you call. (Now, stop here and re-read. Seriously.) There is no way PiiQImage could prevent this. To ease things a bit make sure that PiiQImages are always passed as pointers. 

 QImage img;
 PiiColorQImage* pMatrix = PiiColorQImage::create(img); // takes img's data
 // pMatrix->row(0) and pMatrix->scanLine(0) point to the same memory location
 QImage img2(*pMatrix); // Creates a shallow copy of matrix
 pMatrix->scanLine(0); // Detaches the QImage part of matrix
 // Now, the row pointers are different

If you construct a PiiQImage with a PiiMatrix, make sure that the original goes out of scope or gets modified before you modify the result. 

 PiiMatrix<unsigned char> mat;
 PiiGrayQImage* pImg = PiiGrayQImage::create(mat);
 pImg->row(0); // WRONG, non-const function detaches matrix data

 // Modify the original before the copy ...
 PiiGrayQImage* pImg = PiiGrayQImage::create(mat);
 mat = PiiMatrix<unsigned char>();
 pImg->row(0); // fine, pImg is the sole owner of its data

 // ... or make sure the original goes out of scope.
 PiiGrayQImage* pImg;
 {
   PiiMatrix<unsigned char> mat;
   pImg = PiiGrayQImage::create(mat);
 }
 pImg->row(0); // fine, pImg is the sole owner of its data

Constructors and destructor

~PiiQImage
( )

Public member functions

PiiMatrix< T >
toMatrix
( )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns a new matrix in the stack.

PiiMatrix< T > *
toMatrixPointer
( )

Transfers the ownership of the internal data pointer to a new matrix, deletes this and returns the new matrix.

PII_CORE_EXPORT bool
hasOwnData
( )

Returns true if image owns its data.

PII_CORE_EXPORT uchar *
releaseQImageBits
( )

Makes image believe it no longer owns its internal buffer.

PII_CORE_EXPORT void
setQImageData
( )

Set the internal data pointer of image to data.

PII_CORE_EXPORT void
setQImageFormat
(
  • QImage * image
  • QImage::Format format
)

Set the format of image to format.

PII_CORE_EXPORT void
setQImageRowLength
(
  • QImage * image
  • int bytesPerLine
)

Set the row length of image to bytesPerLine.

PII_CORE_EXPORT void
setQImageWidth
( )

Set the width of image to width.

Static public member functions

static PiiQImage *
create
( )

Returns a new PiiQImage that steals the data buffer from image.

static PiiQImage *
create
( )

Returns a new PiiQImage is a shallow copy of matrix and shares the same data with QImage.

template<class U>
static PiiQImage *
create
( )

Returns a new PiiQImage that is a deep copy of matrix and shared the same data with QImage.

static QImage
matrixToQImage
( )

Convert a PiiMatrix to a QImage.

Function details

  • ~PiiQImage

    ()
    [inline]

  • static PiiQImage * create

    ( )
    [static]

    Returns a new PiiQImage that steals the data buffer from image.

    One must ensure that the depth of the given image (image.depth()) equals to the size of the template type (sizeof(T)*8). Otherwise, the behavior is undefined (read: your program will crash). The QImage will still be valid after constructing a PiiQImage, but it has lost the ownership of its internal buffer. PiiQImage will free() the buffer when deleted. If image doesn't own its data buffer (it is constructed with external data), the external data must remain valid throughout the lifetime of this object and will not be released upon destruction.

  • static PiiQImage * create

    ( )
    [static]

    Returns a new PiiQImage is a shallow copy of matrix and shares the same data with QImage.

    If matrix is already shared, it will be detached (see PiiTypelessMatrix::detach()). The color depth of the resulting image will correspond to the size of the template type T: unsigned char and char will become an 8-bit indexed image, PiiColor4<unsigned char> and PiiColor4<char> will become 32-bit RGB. Make sure to call a non-const member function (or detach()) of matrix before modifying the PiiQImage.

  • template<class U>

    static PiiQImage * create

    ( )
    [static]

    Returns a new PiiQImage that is a deep copy of matrix and shared the same data with QImage.

    This function automatically converts the data type of matrix to a QImage-compatible type. 

     // QImage doesn't support 24-bit RGB
 PiiMatrix<PiiColor<unsigned char> > mat;
 // The result is 32-bit RGB
 PiiColorQImage* pImg = PiiColorQImage::create(mat);

  • static QImage matrixToQImage

    ( )
    [static]

    Convert a PiiMatrix to a QImage.

    This function creates a deep copy of matrix' data.

  • PiiMatrix< T > toMatrix

    ()
    [inline]

    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns a new matrix in the stack.

    This function can be used to move the data from a QImage to a PiiMatrix in the stack: 

     PiiMatrix<PiiColor4<> > func()
 {
   QImage img(10, 10, QImage::Format_RGB32);
   return PiiColorQImage::create(img)->toMatrix();
 }

  • PiiMatrix< T > * toMatrixPointer

    ()
    [inline]

    Transfers the ownership of the internal data pointer to a new matrix, deletes this and returns the new matrix.

    This function is useful if you need to get rid of the QImage part of a PiiQImage. If you pass a pointer to a PiiQImage as a PiiMatrix, you risk leaking memory because PiiMatrix doesn't have a virtual destructor. 

     template <class T> void destroy(PiiMatrix<T>* mat)
 {
   delete mat;
 }

 QImage qimg;
 PiiColorQImage* pImg = PiiColorQImage::create(qimg);
 destroy(pImg); // WRONG! QImage's destructor won't be called
 destroy(pImg->toMatrixPointer()); // correct
 // pImg is now deleted, don't touch!

  • PII_CORE_EXPORT bool hasOwnData

    ( )

    Returns true if image owns its data.

  • PII_CORE_EXPORT uchar * releaseQImageBits

    ( )

    Makes image believe it no longer owns its internal buffer.

    The image works as usual but the buffer must be freed (with free()) by the caller.

  • PII_CORE_EXPORT void setQImageData

    ( )

    Set the internal data pointer of image to data.

  • PII_CORE_EXPORT void setQImageFormat

    (
    • QImage * image
    • QImage::Format format
    )

    Set the format of image to format.

  • PII_CORE_EXPORT void setQImageRowLength

    (
    • QImage * image
    • int bytesPerLine
    )

    Set the row length of image to bytesPerLine.

  • PII_CORE_EXPORT void setQImageWidth

    ( )

    Set the width of image to width.

Notes (0)

Add a note

Not a single note added yet. Be the first, add yours.