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

     2 **

     3 ** Copyright (C) 2009 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 numColors() 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 numBytes() 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 setNumColors()

   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 all versions of Qt:

   700 

   701     \value Format_Invalid   The image is invalid.

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

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

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

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

   706 

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

   708                             into a colormap. \warning Drawing into a

   709                             QImage with Indexed8 format is not

   710                             supported.

   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). \warning Do not

   716                             render into ARGB32 images using

   717                             QPainter. Format_ARGB32_Premultiplied is

   718                             significantly faster.

   719 

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

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

   722                             green, and blue channels are multiplied

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

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

   725                             undefined.) Certain operations (such as image composition

   726                             using alpha blending) are faster using premultiplied ARGB32

   727                             than with plain ARGB32.

   728 

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

   730 

   731     \value Format_ARGB8565_Premultiplied  The image is stored using a

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

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

   734                             The unused most significant bits is always zero.

   735     \value Format_ARGB6666_Premultiplied  The image is stored using a

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

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

   738                             The unused most significant bit is always zero.

   739     \value Format_ARGB8555_Premultiplied  The image is stored using a

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

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

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

   743                             The unused bits are always zero.

   744     \value Format_ARGB4444_Premultiplied  The image is stored using a

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

   746 

   747     \sa format(), convertToFormat()

   748 */

   749 

   750 /*****************************************************************************

   751   QImage member functions

   752  *****************************************************************************/

   753 

   754 // table to flip bits

   755 static const uchar bitflip[256] = {

   756     /*

   757         open OUT, "| fmt";

   758         for $i (0..255) {

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

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

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

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

   763         }

   764         close OUT;

   765     */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   782 };

   783 

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

   785 {

   786     return bitflip;

   787 }

   788 

   789 #if defined(QT3_SUPPORT)

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

   791 {

   792     QImage::Format format;

   793     if (depth == 1) {

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

   795     } else if (depth == 8) {

   796         format = QImage::Format_Indexed8;

   797     } else if (depth == 32) {

   798         format = QImage::Format_RGB32;

   799     } else if (depth == 24) {

   800         format = QImage::Format_RGB888;

   801     } else if (depth == 16) {

   802         format = QImage::Format_RGB16;

   803     } else {

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

   805         format = QImage::Format_Invalid;

   806     }

   807     return format;

   808 }

   809 #endif

   810 

   811 /*!

   812     Constructs a null image.

   813 

   814     \sa isNull()

   815 */

   816 

   817 QImage::QImage()

   818     : QPaintDevice()

   819 {

   820     d = 0;

   821 }

   822 

   823 /*!

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

   825     format.

   826 

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

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

   829     drawing onto it with QPainter.

   830 */

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

   832     : QPaintDevice()

   833 {

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

   835 }

   836 

   837 /*!

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

   839 

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

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

   842     drawing onto it with QPainter.

   843 */

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

   845     : QPaintDevice()

   846 {

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

   848 }

   849 

   850 

   851 

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

   853 {

   854     QImageData *d = 0;

   855 

   856     if (format == QImage::Format_Invalid)

   857         return d;

   858 

   859     if (!checkPixelSize(format)) {

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

   861                  format);

   862         return 0;

   863     }

   864 

   865     const int depth = depthForFormat(format);

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

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

   868 

   869     if (bpl <= 0)

   870         bpl = calc_bytes_per_line;

   871 

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

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

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

   875         || bpl <= 0

   876         || height <= 0

   877         || bpl < min_bytes_per_line

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

   879         return d;                                        // invalid parameter(s)

   880 

   881     d = new QImageData;

   882     d->ref.ref();

   883 

   884     d->own_data = false;

   885     d->ro_data = readOnly;

   886     d->data = data;

   887     d->width = width;

   888     d->height = height;

   889     d->depth = depth;

   890     d->format = format;

   891 

   892     d->bytes_per_line = bpl;

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

   894 

   895     return d;

   896 }

   897 

   898 /*!

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

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

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

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

   903 

   904     The buffer must remain valid throughout the life of the

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

   906 

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

   908     initially empty and must be sufficiently expanded with

   909     setNumColors() or setColorTable() before the image is used.

   910 */

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

   912     : QPaintDevice()

   913 {

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

   915 }

   916 

   917 /*!

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

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

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

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

   922     image must also be 32-bit aligned.

   923 

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

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

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

   927     destruction.

   928 

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

   930     initially empty and must be sufficiently expanded with

   931     setNumColors() or setColorTable() before the image is used.

   932 

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

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

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

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

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

   938     data being changed.

   939 */

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

   941     : QPaintDevice()

   942 {

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

   944 }

   945 

   946 /*!

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

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

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

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

   951 

   952     The buffer must remain valid throughout the life of the

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

   954 

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

   956     initially empty and must be sufficiently expanded with

   957     setNumColors() or setColorTable() before the image is used.

   958 */

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

   960     :QPaintDevice()

   961 {

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

   963 }

   964 

   965 

   966 /*!

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

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

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

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

   971 

   972     The buffer must remain valid throughout the life of the

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

   974 

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

   976     initially empty and must be sufficiently expanded with

   977     setNumColors() or setColorTable() before the image is used.

   978 

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

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

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

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

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

   984     data being changed.

   985 */

   986 

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

   988     :QPaintDevice()

   989 {

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

   991 }

   992 

   993 /*!

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

   995     the given \a fileName.

   996 

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

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

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

  1000 

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

  1002 

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

  1004     of the application's embedded resources. See the

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

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

  1007     executable.

  1008 

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

  1010 */

  1011 

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

  1013     : QPaintDevice()

  1014 {

  1015     d = 0;

  1016     load(fileName, format);

  1017 }

  1018 

  1019 /*!

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

  1021     the given \a fileName.

  1022 

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

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

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

  1026 

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

  1028 

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

  1030     of the application's embedded resources. See the

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

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

  1033     executable.

  1034 

  1035     You can disable this constructor by defining \c

  1036     QT_NO_CAST_FROM_ASCII when you compile your applications. This can

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

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

  1039 

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

  1041     Image Files}{Reading and Writing Image Files}

  1042 */

  1043 #ifndef QT_NO_CAST_FROM_ASCII

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

  1045     : QPaintDevice()

  1046 {

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

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

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

  1050     d = 0;

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

  1052 }

  1053 #endif

  1054 

  1055 #ifndef QT_NO_IMAGEFORMAT_XPM

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

  1057 

  1058 /*!

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

  1060 

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

  1062     ignored.

  1063 

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

  1065     by using an unusual declaration:

  1066 

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

  1068 

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

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

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

  1072 */

  1073 

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

  1075     : QPaintDevice()

  1076 {

  1077     d = 0;

  1078     if (!xpm)

  1079         return;

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

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

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

  1083 }

  1084 #endif // QT_NO_IMAGEFORMAT_XPM

  1085 

  1086 /*!

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

  1088 

  1089     Use the static fromData() function instead.

  1090 

  1091     \oldcode

  1092         QByteArray data;

  1093         ...

  1094         QImage image(data);

  1095     \newcode

  1096         QByteArray data;

  1097         ...

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

  1099     \endcode

  1100 */

  1101 

  1102 

  1103 /*!

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

  1105 

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

  1107     Data Sharing} documentation.

  1108 

  1109     \sa copy()

  1110 */

  1111 

  1112 QImage::QImage(const QImage &image)

  1113     : QPaintDevice()

  1114 {

  1115     d = image.d;

  1116     if (d)

  1117         d->ref.ref();

  1118 }

  1119 

  1120 #ifdef QT3_SUPPORT

  1121 /*!

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

  1123 

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

  1125     \a numColors colors and \a bitOrder.

  1126 

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

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

  1129     setNumColors() function, instead.

  1130 

  1131     \oldcode

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

  1133     \newcode

  1134         QImage image(width, height, format);