1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qimage.h"

    43 #include "qdatastream.h"

    44 #include "qbuffer.h"

    45 #include "qmap.h"

    46 #include "qmatrix.h"

    47 #include "qtransform.h"

    48 #include "qimagereader.h"

    49 #include "qimagewriter.h"

    50 #include "qstringlist.h"

    51 #include "qvariant.h"

    52 #include "qimagepixmapcleanuphooks_p.h"

    53 #include <ctype.h>

    54 #include <stdlib.h>

    55 #include <limits.h>

    56 #include <math.h>

    57 #include <private/qdrawhelper_p.h>

    58 #include <private/qmemrotate_p.h>

    59 #include <private/qpixmapdata_p.h>

    60 #include <private/qimagescale_p.h>

    61 

    62 #include <qhash.h>

    63 

    64 #include <private/qpaintengine_raster_p.h>

    65 

    66 #include <private/qimage_p.h>

    67 

    68 QT_BEGIN_NAMESPACE

    69 

    70 static inline bool checkPixelSize(const QImage::Format format)

    71 {

    72     switch (format) {

    73     case QImage::Format_ARGB8565_Premultiplied:

    74         return (sizeof(qargb8565) == 3);

    75     case QImage::Format_RGB666:

    76         return (sizeof(qrgb666) == 3);

    77     case QImage::Format_ARGB6666_Premultiplied:

    78         return (sizeof(qargb6666) == 3);

    79     case QImage::Format_RGB555:

    80         return (sizeof(qrgb555) == 2);

    81     case QImage::Format_ARGB8555_Premultiplied:

    82         return (sizeof(qargb8555) == 3);

    83     case QImage::Format_RGB888:

    84         return (sizeof(qrgb888) == 3);

    85     case QImage::Format_RGB444:

    86         return (sizeof(qrgb444) == 2);

    87     case QImage::Format_ARGB4444_Premultiplied:

    88         return (sizeof(qargb4444) == 2);

    89     default:

    90         return true;

    91     }

    92 }

    93 

    94 #if defined(Q_CC_DEC) && defined(__alpha) && (__DECCXX_VER-0 >= 50190001)

    95 #pragma message disable narrowptr

    96 #endif

    97 

    98 

    99 #define QIMAGE_SANITYCHECK_MEMORY(image) \

   100     if ((image).isNull()) { \

   101         qWarning("QImage: out of memory, returning null image"); \

   102         return QImage(); \

   103     }

   104 

   105 

   106 static QImage rotated90(const QImage &src);

   107 static QImage rotated180(const QImage &src);

   108 static QImage rotated270(const QImage &src);

   109 

   110 // ### Qt 5: remove

   111 Q_GUI_EXPORT qint64 qt_image_id(const QImage &image)

   112 {

   113     return image.cacheKey();

   114 }

   115 

   116 const QVector<QRgb> *qt_image_colortable(const QImage &image)

   117 {

   118     return &image.d->colortable;

   119 }

   120 

   121 extern int qt_defaultDpiX();

   122 extern int qt_defaultDpiY();

   123 

   124 QBasicAtomicInt qimage_serial_number = Q_BASIC_ATOMIC_INITIALIZER(1);

   125 

   126 QImageData::QImageData()

   127     : ref(0), width(0), height(0), depth(0), nbytes(0), data(0),

   128 #ifdef QT3_SUPPORT

   129       jumptable(0),

   130 #endif

   131       format(QImage::Format_ARGB32), bytes_per_line(0),

   132       ser_no(qimage_serial_number.fetchAndAddRelaxed(1)),

   133       detach_no(0),

   134       dpmx(qt_defaultDpiX() * 100 / qreal(2.54)),

   135       dpmy(qt_defaultDpiY() * 100 / qreal(2.54)),

   136       offset(0, 0), own_data(true), ro_data(false), has_alpha_clut(false),

   137       is_cached(false), paintEngine(0)

   138 {

   139 }

   140 

   141 static int depthForFormat(QImage::Format format)

   142 {

   143     int depth = 0;

   144     switch(format) {

   145     case QImage::Format_Invalid:

   146     case QImage::NImageFormats:

   147         Q_ASSERT(false);

   148     case QImage::Format_Mono:

   149     case QImage::Format_MonoLSB:

   150         depth = 1;

   151         break;

   152     case QImage::Format_Indexed8:

   153         depth = 8;

   154         break;

   155     case QImage::Format_RGB32:

   156     case QImage::Format_ARGB32:

   157     case QImage::Format_ARGB32_Premultiplied:

   158         depth = 32;

   159         break;

   160     case QImage::Format_RGB555:

   161     case QImage::Format_RGB16:

   162     case QImage::Format_RGB444:

   163     case QImage::Format_ARGB4444_Premultiplied:

   164         depth = 16;

   165         break;

   166     case QImage::Format_RGB666:

   167     case QImage::Format_ARGB6666_Premultiplied:

   168     case QImage::Format_ARGB8565_Premultiplied:

   169     case QImage::Format_ARGB8555_Premultiplied:

   170     case QImage::Format_RGB888:

   171         depth = 24;

   172         break;

   173     }

   174     return depth;

   175 }

   176 

   177 /*! \fn QImageData * QImageData::create(const QSize &size, QImage::Format format, int numColors)

   178 

   179     \internal

   180 

   181     Creates a new image data.

   182     Returns 0 if invalid parameters are give or anything else failed.

   183 */

   184 QImageData * QImageData::create(const QSize &size, QImage::Format format, int numColors)

   185 {

   186     if (!size.isValid() || numColors < 0 || format == QImage::Format_Invalid)

   187         return 0;                                // invalid parameter(s)

   188 

   189     if (!checkPixelSize(format)) {

   190         qWarning("QImageData::create(): Invalid pixel size for format %i",

   191                  format);

   192         return 0;

   193     }

   194 

   195     uint width = size.width();

   196     uint height = size.height();

   197     uint depth = depthForFormat(format);

   198 

   199     switch (format) {

   200     case QImage::Format_Mono:

   201     case QImage::Format_MonoLSB:

   202         numColors = 2;

   203         break;

   204     case QImage::Format_Indexed8:

   205         numColors = qBound(0, numColors, 256);

   206         break;

   207     default:

   208         numColors = 0;

   209         break;

   210     }

   211 

   212     const int bytes_per_line = ((width * depth + 31) >> 5) << 2; // bytes per scanline (must be multiple of 8)

   213 

   214     // sanity check for potential overflows

   215     if (INT_MAX/depth < width

   216         || bytes_per_line <= 0

   217         || height <= 0

   218         || INT_MAX/uint(bytes_per_line) < height

   219         || INT_MAX/sizeof(uchar *) < uint(height))

   220         return 0;

   221 

   222     QScopedPointer<QImageData> d(new QImageData);

   223     d->colortable.resize(numColors);

   224     if (depth == 1) {

   225         d->colortable[0] = QColor(Qt::black).rgba();

   226         d->colortable[1] = QColor(Qt::white).rgba();

   227     } else {

   228         for (int i = 0; i < numColors; ++i)

   229             d->colortable[i] = 0;

   230     }

   231 

   232     d->width = width;

   233     d->height = height;

   234     d->depth = depth;

   235     d->format = format;

   236     d->has_alpha_clut = false;

   237     d->is_cached = false;

   238 

   239     d->bytes_per_line = bytes_per_line;

   240 

   241     d->nbytes = d->bytes_per_line*height;

   242     d->data  = (uchar *)malloc(d->nbytes);

   243 

   244     if (!d->data) {

   245         return 0;

   246     }

   247 

   248     d->ref.ref();

   249     return d.take();

   250 

   251 }

   252 

   253 QImageData::~QImageData()

   254 {

   255     if (is_cached)

   256         QImagePixmapCleanupHooks::executeImageHooks((((qint64) ser_no) << 32) | ((qint64) detach_no));

   257     delete paintEngine;

   258     if (data && own_data)

   259         free(data);

   260 #ifdef QT3_SUPPORT

   261     if (jumptable)

   262         free(jumptable);

   263     jumptable = 0;

   264 #endif

   265     data = 0;

   266 }

   267 

   268 

   269 bool QImageData::checkForAlphaPixels() const

   270 {

   271     bool has_alpha_pixels = false;

   272 

   273     switch (format) {

   274 

   275     case QImage::Format_Indexed8:

   276         has_alpha_pixels = has_alpha_clut;

   277         break;

   278 

   279     case QImage::Format_ARGB32:

   280     case QImage::Format_ARGB32_Premultiplied: {

   281         uchar *bits = data;

   282         for (int y=0; y<height && !has_alpha_pixels; ++y) {

   283             for (int x=0; x<width; ++x)

   284                 has_alpha_pixels |= (((uint *)bits)[x] & 0xff000000) != 0xff000000;

   285             bits += bytes_per_line;

   286         }

   287     } break;

   288 

   289     case QImage::Format_ARGB8555_Premultiplied:

   290     case QImage::Format_ARGB8565_Premultiplied: {

   291         uchar *bits = data;

   292         uchar *end_bits = data + bytes_per_line;

   293 

   294         for (int y=0; y<height && !has_alpha_pixels; ++y) {

   295             while (bits < end_bits) {

   296                 has_alpha_pixels |= bits[0] != 0;

   297                 bits += 3;

   298             }

   299             bits = end_bits;

   300             end_bits += bytes_per_line;

   301         }

   302     } break;

   303 

   304     case QImage::Format_ARGB6666_Premultiplied: {

   305         uchar *bits = data;

   306         uchar *end_bits = data + bytes_per_line;

   307 

   308         for (int y=0; y<height && !has_alpha_pixels; ++y) {

   309             while (bits < end_bits) {

   310                 has_alpha_pixels |= (bits[0] & 0xfc) != 0;

   311                 bits += 3;

   312             }

   313             bits = end_bits;

   314             end_bits += bytes_per_line;

   315         }

   316     } break;

   317 

   318     case QImage::Format_ARGB4444_Premultiplied: {

   319         uchar *bits = data;

   320         uchar *end_bits = data + bytes_per_line;

   321 

   322         for (int y=0; y<height && !has_alpha_pixels; ++y) {

   323             while (bits < end_bits) {

   324                 has_alpha_pixels |= (bits[0] & 0xf0) != 0;

   325                 bits += 2;

   326             }

   327             bits = end_bits;

   328             end_bits += bytes_per_line;

   329         }

   330     } break;

   331 

   332     default:

   333         break;

   334     }

   335 

   336     return has_alpha_pixels;

   337 }

   338 

   339 /*!

   340     \class QImage

   341 

   342     \ingroup painting

   343     \ingroup shared

   344 

   345     \reentrant

   346 

   347     \brief The QImage class provides a hardware-independent image

   348     representation that allows direct access to the pixel data, and

   349     can be used as a paint device.

   350 

   351     Qt provides four classes for handling image data: QImage, QPixmap,

   352     QBitmap and QPicture.  QImage is designed and optimized for I/O,

   353     and for direct pixel access and manipulation, while QPixmap is

   354     designed and optimized for showing images on screen. QBitmap is

   355     only a convenience class that inherits QPixmap, ensuring a

   356     depth of 1. Finally, the QPicture class is a paint device that

   357     records and replays QPainter commands.

   358 

   359     Because QImage is a QPaintDevice subclass, QPainter can be used to

   360     draw directly onto images.  When using QPainter on a QImage, the

   361     painting can be performed in another thread than the current GUI

   362     thread.

   363 

   364     The QImage class supports several image formats described by the

   365     \l Format enum. These include monochrome, 8-bit, 32-bit and

   366     alpha-blended images which are available in all versions of Qt

   367     4.x.

   368 

   369     QImage provides a collection of functions that can be used to

   370     obtain a variety of information about the image. There are also

   371     several functions that enables transformation of the image.

   372 

   373     QImage objects can be passed around by value since the QImage

   374     class uses \l{Implicit Data Sharing}{implicit data

   375     sharing}. QImage objects can also be streamed and compared.

   376 

   377     \note If you would like to load QImage objects in a static build of Qt,

   378     refer to the \l{How To Create Qt Plugins#Static Plugins}{Plugin HowTo}.

   379 

   380     \warning Painting on a QImage with the format

   381     QImage::Format_Indexed8 is not supported.

   382 

   383     \tableofcontents

   384 

   385     \section1 Reading and Writing Image Files

   386 

   387     QImage provides several ways of loading an image file: The file

   388     can be loaded when constructing the QImage object, or by using the

   389     load() or loadFromData() functions later on. QImage also provides

   390     the static fromData() function, constructing a QImage from the

   391     given data.  When loading an image, the file name can either refer

   392     to an actual file on disk or to one of the application's embedded

   393     resources. See \l{The Qt Resource System} overview for details

   394     on how to embed images and other resource files in the

   395     application's executable.

   396 

   397     Simply call the save() function to save a QImage object.

   398 

   399     The complete list of supported file formats are available through

   400     the QImageReader::supportedImageFormats() and

   401     QImageWriter::supportedImageFormats() functions. New file formats

   402     can be added as plugins. By default, Qt supports the following

   403     formats:

   404 

   405     \table

   406     \header \o Format \o Description                      \o Qt's support

   407     \row    \o BMP    \o Windows Bitmap                   \o Read/write

   408     \row    \o GIF    \o Graphic Interchange Format (optional) \o Read

   409     \row    \o JPG    \o Joint Photographic Experts Group \o Read/write

   410     \row    \o JPEG   \o Joint Photographic Experts Group \o Read/write

   411     \row    \o PNG    \o Portable Network Graphics        \o Read/write

   412     \row    \o PBM    \o Portable Bitmap                  \o Read

   413     \row    \o PGM    \o Portable Graymap                 \o Read

   414     \row    \o PPM    \o Portable Pixmap                  \o Read/write

   415     \row    \o TIFF   \o Tagged Image File Format         \o Read/write

   416     \row    \o XBM    \o X11 Bitmap                       \o Read/write

   417     \row    \o XPM    \o X11 Pixmap                       \o Read/write

   418     \endtable

   419 

   420     \section1 Image Information

   421 

   422     QImage provides a collection of functions that can be used to

   423     obtain a variety of information about the image:

   424 

   425     \table

   426     \header

   427     \o \o Available Functions

   428 

   429     \row

   430     \o Geometry

   431     \o

   432 

   433     The size(), width(), height(), dotsPerMeterX(), and

   434     dotsPerMeterY() functions provide information about the image size

   435     and aspect ratio.

   436 

   437     The rect() function returns the image's enclosing rectangle. The

   438     valid() function tells if a given pair of coordinates is within

   439     this rectangle. The offset() function returns the number of pixels

   440     by which the image is intended to be offset by when positioned

   441     relative to other images, which also can be manipulated using the

   442     setOffset() function.

   443 

   444     \row

   445     \o Colors

   446     \o

   447 

   448     The color of a pixel can be retrieved by passing its coordinates

   449     to the pixel() function.  The pixel() function returns the color

   450     as a QRgb value indepedent of the image's format.

   451 

   452     In case of monochrome and 8-bit images, the colorCount() and

   453     colorTable() functions provide information about the color

   454     components used to store the image data: The colorTable() function

   455     returns the image's entire color table. To obtain a single entry,

   456     use the pixelIndex() function to retrieve the pixel index for a

   457     given pair of coordinates, then use the color() function to

   458     retrieve the color. Note that if you create an 8-bit image

   459     manually, you have to set a valid color table on the image as

   460     well.

   461 

   462     The hasAlphaChannel() function tells if the image's format

   463     respects the alpha channel, or not. The allGray() and

   464     isGrayscale() functions tell whether an image's colors are all

   465     shades of gray.

   466 

   467     See also the \l {QImage#Pixel Manipulation}{Pixel Manipulation}

   468     and \l {QImage#Image Transformations}{Image Transformations}

   469     sections.

   470 

   471     \row

   472     \o Text

   473     \o

   474 

   475     The text() function returns the image text associated with the

   476     given text key. An image's text keys can be retrieved using the

   477     textKeys() function. Use the setText() function to alter an

   478     image's text.

   479 

   480     \row

   481     \o Low-level information

   482     \o

   483     The depth() function returns the depth of the image. The supported

   484     depths are 1 (monochrome), 8 and 32 (for more information see the

   485     \l {QImage#Image Formats}{Image Formats} section).

   486 

   487     The format(), bytesPerLine(), and byteCount() functions provide

   488     low-level information about the data stored in the image.

   489 

   490     The cacheKey() function returns a number that uniquely

   491     identifies the contents of this QImage object.

   492     \endtable

   493 

   494     \section1 Pixel Manipulation

   495 

   496     The functions used to manipulate an image's pixels depend on the

   497     image format. The reason is that monochrome and 8-bit images are

   498     index-based and use a color lookup table, while 32-bit images

   499     store ARGB values directly. For more information on image formats,

   500     see the \l {Image Formats} section.

   501 

   502     In case of a 32-bit image, the setPixel() function can be used to

   503     alter the color of the pixel at the given coordinates to any other

   504     color specified as an ARGB quadruplet. To make a suitable QRgb

   505     value, use the qRgb() (adding a default alpha component to the

   506     given RGB values, i.e. creating an opaque color) or qRgba()

   507     function. For example:

   508 

   509     \table

   510     \row

   511     \o \inlineimage qimage-32bit_scaled.png

   512     \o

   513     \snippet doc/src/snippets/code/src_gui_image_qimage.cpp 0

   514     \header

   515     \o {2,1}32-bit

   516     \endtable

   517 

   518     In case of a 8-bit and monchrome images, the pixel value is only

   519     an index from the image's color table. So the setPixel() function

   520     can only be used to alter the color of the pixel at the given

   521     coordinates to a predefined color from the image's color table,

   522     i.e. it can only change the pixel's index value. To alter or add a

   523     color to an image's color table, use the setColor() function.

   524 

   525     An entry in the color table is an ARGB quadruplet encoded as an

   526     QRgb value. Use the qRgb() and qRgba() functions to make a

   527     suitable QRgb value for use with the setColor() function. For

   528     example:

   529 

   530     \table

   531     \row

   532     \o \inlineimage qimage-8bit_scaled.png

   533     \o

   534     \snippet doc/src/snippets/code/src_gui_image_qimage.cpp 1

   535     \header

   536     \o {2,1} 8-bit

   537     \endtable

   538 

   539     QImage also provide the scanLine() function which returns a

   540     pointer to the pixel data at the scanline with the given index,

   541     and the bits() function which returns a pointer to the first pixel

   542     data (this is equivalent to \c scanLine(0)).

   543 

   544     \section1 Image Formats

   545 

   546     Each pixel stored in a QImage is represented by an integer. The

   547     size of the integer varies depending on the format. QImage

   548     supports several image formats described by the \l Format

   549     enum.

   550 

   551     Monochrome images are stored using 1-bit indexes into a color table

   552     with at most two colors. There are two different types of

   553     monochrome images: big endian (MSB first) or little endian (LSB

   554     first) bit order.

   555 

   556     8-bit images are stored using 8-bit indexes into a color table,

   557     i.e.  they have a single byte per pixel. The color table is a

   558     QVector<QRgb>, and the QRgb typedef is equivalent to an unsigned

   559     int containing an ARGB quadruplet on the format 0xAARRGGBB.

   560 

   561     32-bit images have no color table; instead, each pixel contains an

   562     QRgb value. There are three different types of 32-bit images

   563     storing RGB (i.e. 0xffRRGGBB), ARGB and premultiplied ARGB

   564     values respectively. In the premultiplied format the red, green,

   565     and blue channels are multiplied by the alpha component divided by

   566     255.

   567 

   568     An image's format can be retrieved using the format()

   569     function. Use the convertToFormat() functions to convert an image

   570     into another format. The allGray() and isGrayscale() functions

   571     tell whether a color image can safely be converted to a grayscale

   572     image.

   573 

   574     \section1 Image Transformations

   575 

   576     QImage supports a number of functions for creating a new image

   577     that is a transformed version of the original: The

   578     createAlphaMask() function builds and returns a 1-bpp mask from

   579     the alpha buffer in this image, and the createHeuristicMask()

   580     function creates and returns a 1-bpp heuristic mask for this

   581     image. The latter function works by selecting a color from one of

   582     the corners, then chipping away pixels of that color starting at

   583     all the edges.

   584 

   585     The mirrored() function returns a mirror of the image in the

   586     desired direction, the scaled() returns a copy of the image scaled

   587     to a rectangle of the desired measures, and the rgbSwapped() function

   588     constructs a BGR image from a RGB image.

   589 

   590     The scaledToWidth() and scaledToHeight() functions return scaled

   591     copies of the image.

   592 

   593     The transformed() function returns a copy of the image that is

   594     transformed with the given transformation matrix and

   595     transformation mode: Internally, the transformation matrix is

   596     adjusted to compensate for unwanted translation,

   597     i.e. transformed() returns the smallest image containing all

   598     transformed points of the original image. The static trueMatrix()

   599     function returns the actual matrix used for transforming the

   600     image.

   601 

   602     There are also functions for changing attributes of an image

   603     in-place:

   604 

   605     \table

   606     \header \o Function \o Description

   607     \row

   608     \o setDotsPerMeterX()

   609     \o Defines the aspect ratio by setting the number of pixels that fit

   610     horizontally in a physical meter.

   611     \row

   612     \o setDotsPerMeterY()

   613     \o Defines the aspect ratio by setting the number of pixels that fit

   614     vertically in a physical meter.

   615     \row

   616     \o fill()

   617     \o Fills the entire image with the given pixel value.

   618     \row

   619     \o invertPixels()

   620     \o Inverts all pixel values in the image using the given InvertMode value.

   621     \row

   622     \o setColorTable()

   623     \o Sets the color table used to translate color indexes. Only

   624     monochrome and 8-bit formats.

   625     \row

   626     \o setColorCount()

   627     \o Resizes the color table. Only monochrome and 8-bit formats.

   628 

   629     \endtable

   630 

   631     \section1 Legal Information

   632 

   633     For smooth scaling, the transformed() functions use code based on

   634     smooth scaling algorithm by Daniel M. Duley.

   635 

   636     \legalese

   637      Copyright (C) 2004, 2005 Daniel M. Duley

   638 

   639      Redistribution and use in source and binary forms, with or without

   640         modification, are permitted provided that the following conditions

   641         are met:

   642 

   643      1. Redistributions of source code must retain the above copyright

   644         notice, this list of conditions and the following disclaimer.

   645      2. Redistributions in binary form must reproduce the above copyright

   646         notice, this list of conditions and the following disclaimer in the

   647         documentation and/or other materials provided with the distribution.

   648 

   649      THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR

   650      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

   651      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

   652      IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,

   653      INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT

   654      NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

   655      DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

   656      THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

   657      (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

   658      THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   659     \endlegalese

   660 

   661     \sa QImageReader, QImageWriter, QPixmap, QSvgRenderer, {Image Composition Example},

   662         {Image Viewer Example}, {Scribble Example}, {Pixelator Example}

   663 */

   664 

   665 /*!

   666     \enum QImage::Endian

   667     \compat

   668 

   669     This enum type is used to describe the endianness of the CPU and

   670     graphics hardware. It is provided here for compatibility with earlier versions of Qt.

   671 

   672     Use the \l Format enum instead. The \l Format enum specify the

   673     endianess for monchrome formats, but for other formats the

   674     endianess is not relevant.

   675 

   676     \value IgnoreEndian  Endianness does not matter. Useful for some

   677                          operations that are independent of endianness.

   678     \value BigEndian     Most significant bit first or network byte order, as on SPARC, PowerPC, and Motorola CPUs.

   679     \value LittleEndian  Least significant bit first or little endian byte order, as on Intel x86.

   680 */

   681 

   682 /*!

   683     \enum QImage::InvertMode

   684 

   685     This enum type is used to describe how pixel values should be

   686     inverted in the invertPixels() function.

   687 

   688     \value InvertRgb    Invert only the RGB values and leave the alpha

   689                         channel unchanged.

   690 

   691     \value InvertRgba   Invert all channels, including the alpha channel.

   692 

   693     \sa invertPixels()

   694 */

   695 

   696 /*!

   697     \enum QImage::Format

   698 

   699     The following image formats are available in Qt. Values greater

   700     than QImage::Format_RGB16 were added in Qt 4.4. See the notes

   701     after the table.

   702 

   703     \value Format_Invalid   The image is invalid.

   704     \value Format_Mono      The image is stored using 1-bit per pixel. Bytes are

   705                             packed with the most significant bit (MSB) first.

   706     \value Format_MonoLSB   The image is stored using 1-bit per pixel. Bytes are

   707                             packed with the less significant bit (LSB) first.

   708 

   709     \value Format_Indexed8  The image is stored using 8-bit indexes

   710                             into a colormap. 

   711 

   712     \value Format_RGB32     The image is stored using a 32-bit RGB format (0xffRRGGBB).

   713 

   714     \value Format_ARGB32    The image is stored using a 32-bit ARGB

   715                             format (0xAARRGGBB).

   716 

   717     \value Format_ARGB32_Premultiplied  The image is stored using a premultiplied 32-bit

   718                             ARGB format (0xAARRGGBB), i.e. the red,

   719                             green, and blue channels are multiplied

   720                             by the alpha component divided by 255. (If RR, GG, or BB

   721                             has a higher value than the alpha channel, the results are

   722                             undefined.) Certain operations (such as image composition

   723                             using alpha blending) are faster using premultiplied ARGB32

   724                             than with plain ARGB32.

   725 

   726     \value Format_RGB16     The image is stored using a 16-bit RGB format (5-6-5).

   727 

   728     \value Format_ARGB8565_Premultiplied  The image is stored using a

   729                             premultiplied 24-bit ARGB format (8-5-6-5).

   730     \value Format_RGB666    The image is stored using a 24-bit RGB format (6-6-6).

   731                             The unused most significant bits is always zero.

   732     \value Format_ARGB6666_Premultiplied  The image is stored using a

   733                             premultiplied 24-bit ARGB format (6-6-6-6).

   734     \value Format_RGB555    The image is stored using a 16-bit RGB format (5-5-5).

   735                             The unused most significant bit is always zero.

   736     \value Format_ARGB8555_Premultiplied  The image is stored using a

   737                             premultiplied 24-bit ARGB format (8-5-5-5).

   738     \value Format_RGB888    The image is stored using a 24-bit RGB format (8-8-8).

   739     \value Format_RGB444    The image is stored using a 16-bit RGB format (4-4-4).

   740                             The unused bits are always zero.

   741     \value Format_ARGB4444_Premultiplied  The image is stored using a

   742                             premultiplied 16-bit ARGB format (4-4-4-4).

   743 

   744     \note Drawing into a QImage with QImage::Format_Indexed8 is not

   745     supported.

   746 

   747     \note Do not render into ARGB32 images using QPainter.  Using

   748     QImage::Format_ARGB32_Premultiplied is significantly faster.

   749 

   750     \sa format(), convertToFormat()

   751 */

   752 

   753 /*****************************************************************************

   754   QImage member functions

   755  *****************************************************************************/

   756 

   757 // table to flip bits

   758 static const uchar bitflip[256] = {

   759     /*

   760         open OUT, "| fmt";

   761         for $i (0..255) {

   762             print OUT (($i >> 7) & 0x01) | (($i >> 5) & 0x02) |

   763                       (($i >> 3) & 0x04) | (($i >> 1) & 0x08) |

   764                       (($i << 7) & 0x80) | (($i << 5) & 0x40) |

   765                       (($i << 3) & 0x20) | (($i << 1) & 0x10), ", ";

   766         }

   767         close OUT;

   768     */

   769     0, 128, 64, 192, 32, 160, 96, 224, 16, 144, 80, 208, 48, 176, 112, 240,

   770     8, 136, 72, 200, 40, 168, 104, 232, 24, 152, 88, 216, 56, 184, 120, 248,

   771     4, 132, 68, 196, 36, 164, 100, 228, 20, 148, 84, 212, 52, 180, 116, 244,

   772     12, 140, 76, 204, 44, 172, 108, 236, 28, 156, 92, 220, 60, 188, 124, 252,

   773     2, 130, 66, 194, 34, 162, 98, 226, 18, 146, 82, 210, 50, 178, 114, 242,

   774     10, 138, 74, 202, 42, 170, 106, 234, 26, 154, 90, 218, 58, 186, 122, 250,

   775     6, 134, 70, 198, 38, 166, 102, 230, 22, 150, 86, 214, 54, 182, 118, 246,

   776     14, 142, 78, 206, 46, 174, 110, 238, 30, 158, 94, 222, 62, 190, 126, 254,

   777     1, 129, 65, 193, 33, 161, 97, 225, 17, 145, 81, 209, 49, 177, 113, 241,

   778     9, 137, 73, 201, 41, 169, 105, 233, 25, 153, 89, 217, 57, 185, 121, 249,

   779     5, 133, 69, 197, 37, 165, 101, 229, 21, 149, 85, 213, 53, 181, 117, 245,

   780     13, 141, 77, 205, 45, 173, 109, 237, 29, 157, 93, 221, 61, 189, 125, 253,

   781     3, 131, 67, 195, 35, 163, 99, 227, 19, 147, 83, 211, 51, 179, 115, 243,

   782     11, 139, 75, 203, 43, 171, 107, 235, 27, 155, 91, 219, 59, 187, 123, 251,

   783     7, 135, 71, 199, 39, 167, 103, 231, 23, 151, 87, 215, 55, 183, 119, 247,

   784     15, 143, 79, 207, 47, 175, 111, 239, 31, 159, 95, 223, 63, 191, 127, 255

   785 };

   786 

   787 const uchar *qt_get_bitflip_array()                        // called from QPixmap code

   788 {

   789     return bitflip;

   790 }

   791 

   792 #if defined(QT3_SUPPORT)

   793 static QImage::Format formatFor(int depth, QImage::Endian bitOrder)

   794 {

   795     QImage::Format format;

   796     if (depth == 1) {

   797         format = bitOrder == QImage::BigEndian ? QImage::Format_Mono : QImage::Format_MonoLSB;

   798     } else if (depth == 8) {

   799         format = QImage::Format_Indexed8;

   800     } else if (depth == 32) {

   801         format = QImage::Format_RGB32;

   802     } else if (depth == 24) {

   803         format = QImage::Format_RGB888;

   804     } else if (depth == 16) {

   805         format = QImage::Format_RGB16;

   806     } else {

   807         qWarning("QImage: Depth %d not supported", depth);

   808         format = QImage::Format_Invalid;

   809     }

   810     return format;

   811 }

   812 #endif

   813 

   814 /*!

   815     Constructs a null image.

   816 

   817     \sa isNull()

   818 */

   819 

   820 QImage::QImage()

   821     : QPaintDevice()

   822 {

   823     d = 0;

   824 }

   825 

   826 /*!

   827     Constructs an image with the given \a width, \a height and \a

   828     format.

   829 

   830     \warning This will create a QImage with uninitialized data. Call

   831     fill() to fill the image with an appropriate pixel value before

   832     drawing onto it with QPainter.

   833 */

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

   835     : QPaintDevice()

   836 {

   837     d = QImageData::create(QSize(width, height), format, 0);

   838 }

   839 

   840 /*!

   841     Constructs an image with the given \a size and \a format.

   842 

   843     \warning This will create a QImage with uninitialized data. Call

   844     fill() to fill the image with an appropriate pixel value before

   845     drawing onto it with QPainter.

   846 */

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

   848     : QPaintDevice()

   849 {

   850     d = QImageData::create(size, format, 0);

   851 }

   852 

   853 

   854 

   855 QImageData *QImageData::create(uchar *data, int width, int height,  int bpl, QImage::Format format, bool readOnly)

   856 {

   857     QImageData *d = 0;

   858 

   859     if (format == QImage::Format_Invalid)

   860         return d;

   861 

   862     if (!checkPixelSize(format)) {

   863         qWarning("QImageData::create(): Invalid pixel size for format %i",

   864                  format);

   865         return 0;

   866     }

   867 

   868     const int depth = depthForFormat(format);

   869     const int calc_bytes_per_line = ((width * depth + 31)/32) * 4;

   870     const int min_bytes_per_line = (width * depth + 7)/8;

   871 

   872     if (bpl <= 0)

   873         bpl = calc_bytes_per_line;

   874 

   875     if (width <= 0 || height <= 0 || !data

   876         || INT_MAX/sizeof(uchar *) < uint(height)

   877         || INT_MAX/uint(depth) < uint(width)

   878         || bpl <= 0

   879         || height <= 0

   880         || bpl < min_bytes_per_line

   881         || INT_MAX/uint(bpl) < uint(height))

   882         return d;                                        // invalid parameter(s)

   883 

   884     d = new QImageData;

   885     d->ref.ref();

   886 

   887     d->own_data = false;

   888     d->ro_data = readOnly;

   889     d->data = data;

   890     d->width = width;

   891     d->height = height;

   892     d->depth = depth;

   893     d->format = format;

   894 

   895     d->bytes_per_line = bpl;

   896     d->nbytes = d->bytes_per_line * height;

   897 

   898     return d;

   899 }

   900 

   901 /*!

   902     Constructs an image with the given \a width, \a height and \a

   903     format, that uses an existing memory buffer, \a data. The \a width

   904     and \a height must be specified in pixels, \a data must be 32-bit aligned,

   905     and each scanline of data in the image must also be 32-bit aligned.

   906 

   907     The buffer must remain valid throughout the life of the

   908     QImage. The image does not delete the buffer at destruction.

   909 

   910     If \a format is an indexed color format, the image color table is

   911     initially empty and must be sufficiently expanded with

   912     setColorCount() or setColorTable() before the image is used.

   913 */

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

   915     : QPaintDevice()

   916 {

   917     d = QImageData::create(data, width, height, 0, format, false);

   918 }

   919 

   920 /*!

   921     Constructs an image with the given \a width, \a height and \a

   922     format, that uses an existing read-only memory buffer, \a

   923     data. The \a width and \a height must be specified in pixels, \a

   924     data must be 32-bit aligned, and each scanline of data in the

   925     image must also be 32-bit aligned.

   926 

   927     The buffer must remain valid throughout the life of the QImage and

   928     all copies that have not been modified or otherwise detached from

   929     the original buffer. The image does not delete the buffer at

   930     destruction.

   931 

   932     If \a format is an indexed color format, the image color table is

   933     initially empty and must be sufficiently expanded with

   934     setColorCount() or setColorTable() before the image is used.

   935 

   936     Unlike the similar QImage constructor that takes a non-const data buffer,

   937     this version will never alter the contents of the buffer.  For example,

   938     calling QImage::bits() will return a deep copy of the image, rather than

   939     the buffer passed to the constructor.  This allows for the efficiency of

   940     constructing a QImage from raw data, without the possibility of the raw

   941     data being changed.

   942 */

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

   944     : QPaintDevice()

   945 {

   946     d = QImageData::create(const_cast<uchar*>(data), width, height, 0, format, true);

   947 }

   948 

   949 /*!

   950     Constructs an image with the given \a width, \a height and \a

   951     format, that uses an existing memory buffer, \a data. The \a width

   952     and \a height must be specified in pixels. \a bytesPerLine

   953     specifies the number of bytes per line (stride).

   954 

   955     The buffer must remain valid throughout the life of the

   956     QImage. The image does not delete the buffer at destruction.

   957 

   958     If \a format is an indexed color format, the image color table is

   959     initially empty and must be sufficiently expanded with

   960     setColorCount() or setColorTable() before the image is used.

   961 */

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

   963     :QPaintDevice()

   964 {

   965     d = QImageData::create(data, width, height, bytesPerLine, format, false);

   966 }

   967 

   968 

   969 /*!

   970     Constructs an image with the given \a width, \a height and \a

   971     format, that uses an existing memory buffer, \a data. The \a width

   972     and \a height must be specified in pixels. \a bytesPerLine

   973     specifies the number of bytes per line (stride).

   974 

   975     The buffer must remain valid throughout the life of the

   976     QImage. The image does not delete the buffer at destruction.

   977 

   978     If \a format is an indexed color format, the image color table is

   979     initially empty and must be sufficiently expanded with

   980     setColorCount() or setColorTable() before the image is used.

   981 

   982     Unlike the similar QImage constructor that takes a non-const data buffer,

   983     this version will never alter the contents of the buffer.  For example,

   984     calling QImage::bits() will return a deep copy of the image, rather than

   985     the buffer passed to the constructor.  This allows for the efficiency of

   986     constructing a QImage from raw data, without the possibility of the raw

   987     data being changed.

   988 */

   989 

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

   991     :QPaintDevice()

   992 {

   993     d = QImageData::create(const_cast<uchar*>(data), width, height, bytesPerLine, format, true);

   994 }

   995 

   996 /*!

   997     Constructs an image and tries to load the image from the file with

   998     the given \a fileName.

   999 

  1000     The loader attempts to read the image using the specified \a

  1001     format. If the \a format is not specified (which is the default),

  1002     the loader probes the file for a header to guess the file format.

  1003 

  1004     If the loading of the image failed, this object is a null image.

  1005 

  1006     The file name can either refer to an actual file on disk or to one

  1007     of the application's embedded resources. See the

  1008     \l{resources.html}{Resource System} overview for details on how to

  1009     embed images and other resource files in the application's

  1010     executable.

  1011 

  1012     \sa isNull(), {QImage#Reading and Writing Image Files}{Reading and Writing Image Files}

  1013 */

  1014 

  1015 QImage::QImage(const QString &fileName, const char *format)

  1016     : QPaintDevice()

  1017 {

  1018     d = 0;

  1019     load(fileName, format);

  1020 }

  1021 

  1022 /*!

  1023     Constructs an image and tries to load the image from the file with

  1024     the given \a fileName.

  1025 

  1026     The loader attempts to read the image using the specified \a

  1027     format. If the \a format is not specified (which is the default),

  1028     the loader probes the file for a header to guess the file format.

  1029 

  1030     If the loading of the image failed, this object is a null image.

  1031 

  1032     The file name can either refer to an actual file on disk or to one

  1033     of the application's embedded resources. See the

  1034     \l{resources.html}{Resource System} overview for details on how to

  1035     embed images and other resource files in the application's

  1036     executable.

  1037 

  1038     You can disable this constructor by defining \c

  1039     QT_NO_CAST_FROM_ASCII when you compile your applications. This can

  1040     be useful, for example, if you want to ensure that all

  1041     user-visible strings go through QObject::tr().

  1042 

  1043     \sa QString::fromAscii(), isNull(), {QImage#Reading and Writing

  1044     Image Files}{Reading and Writing Image Files}

  1045 */

  1046 #ifndef QT_NO_CAST_FROM_ASCII

  1047 QImage::QImage(const char *fileName, const char *format)

  1048     : QPaintDevice()

  1049 {

  1050     // ### Qt 5: if you remove the QImage(const QByteArray &) QT3_SUPPORT

  1051     // constructor, remove this constructor as well. The constructor here

  1052     // exists so that QImage("foo.png") compiles without ambiguity.

  1053     d = 0;

  1054     load(QString::fromAscii(fileName), format);

  1055 }

  1056 #endif

  1057 

  1058 #ifndef QT_NO_IMAGEFORMAT_XPM

  1059 extern bool qt_read_xpm_image_or_array(QIODevice *device, const char * const *source, QImage &image);

  1060 

  1061 /*!

  1062     Constructs an image from the given \a xpm image.

  1063 

  1064     Make sure that the image is a valid XPM image. Errors are silently

  1065     ignored.

  1066 

  1067     Note that it's possible to squeeze the XPM variable a little bit

  1068     by using an unusual declaration:

  1069 

  1070     \snippet doc/src/snippets/code/src_gui_image_qimage.cpp 2

  1071 

  1072     The extra \c const makes the entire definition read-only, which is

  1073     slightly more efficient (e.g., when the code is in a shared

  1074     library) and able to be stored in ROM with the application.

  1075 */

  1076 

  1077 QImage::QImage(const char * const xpm[])

  1078     : QPaintDevice()

  1079 {

  1080     d = 0;

  1081     if (!xpm)

  1082         return;

  1083     if (!qt_read_xpm_image_or_array(0, xpm, *this))

  1084         // Issue: Warning because the constructor may be ambigious

  1085         qWarning("QImage::QImage(), XPM is not supported");

  1086 }

  1087 #endif // QT_NO_IMAGEFORMAT_XPM

  1088 

  1089 /*!

  1090     \fn QImage::QImage(const QByteArray &data)

  1091 

  1092     Use the static fromData() function instead.

  1093 

  1094     \oldcode

  1095         QByteArray data;

  1096         ...

  1097         QImage image(data);

  1098     \newcode

  1099         QByteArray data;

  1100         ...

  1101         QImage image = QImage::fromData(data);

  1102     \endcode

  1103 */

  1104 

  1105 

  1106 /*!

  1107     Constructs a shallow copy of the given \a image.

  1108 

  1109     For more information about shallow copies, see the \l {Implicit

  1110     Data Sharing} documentation.

  1111 

  1112     \sa copy()

  1113 */

  1114 

  1115 QImage::QImage(const QImage &image)

  1116     : QPaintDevice()

  1117 {

  1118     d = image.d;

  1119     if (d)

  1120         d->ref.ref();

  1121 }

  1122 

  1123 #ifdef QT3_SUPPORT

  1124 /*!

  1125     \fn QImage::QImage(int width, int height, int depth, int numColors, Endian bitOrder)

  1126 

  1127     Constructs an image with the given \a width, \a height, \a depth,

  1128     \a numColors colors and \a bitOrder.

  1129 

  1130     Use the constructor that accepts a width, a height and a format

  1131     (i.e. specifying the depth and bit order), in combination with the

  1132     setColorCount() function, instead.

  1133 

  1134     \oldcode

  1135         QImage image(width, height, depth, numColors);