1QImage(3qt)                                                        QImage(3qt)
2
3
4

NAME

6       QImage - Hardware-independent pixmap representation with direct access
7       to the pixel data
8

SYNOPSIS

10       #include <qimage.h>
11
12   Public Members
13       enum Endian { IgnoreEndian, BigEndian, LittleEndian }
14       QImage ()
15       QImage ( int w, int h, int depth, int numColors = 0, Endian bitOrder =
16           IgnoreEndian )
17       QImage ( const QSize & size, int depth, int numColors = 0, Endian
18           bitOrder = IgnoreEndian )
19       QImage ( const QString & fileName, const char * format = 0 )
20       QImage ( const char * const xpm[] )
21       QImage ( const QByteArray & array )
22       QImage ( uchar * yourdata, int w, int h, int depth, QRgb * colortable,
23           int numColors, Endian bitOrder )
24       QImage ( uchar * yourdata, int w, int h, int depth, int bpl, QRgb *
25           colortable, int numColors, Endian bitOrder )
26       QImage ( const QImage & image )
27       ~QImage ()
28       QImage & operator= ( const QImage & image )
29       QImage & operator= ( const QPixmap & pixmap )
30       bool operator== ( const QImage & i ) const
31       bool operator!= ( const QImage & i ) const
32       void detach ()
33       QImage copy () const
34       QImage copy ( int x, int y, int w, int h, int conversion_flags = 0 )
35           const
36       QImage copy ( const QRect & r ) const
37       bool isNull () const
38       int width () const
39       int height () const
40       QSize size () const
41       QRect rect () const
42       int depth () const
43       int numColors () const
44       Endian bitOrder () const
45       QRgb color ( int i ) const
46       void setColor ( int i, QRgb c )
47       void setNumColors ( int numColors )
48       bool hasAlphaBuffer () const
49       void setAlphaBuffer ( bool enable )
50       bool allGray () const
51       bool isGrayscale () const
52       uchar * bits () const
53       uchar * scanLine ( int i ) const
54       uchar ** jumpTable () const
55       QRgb * colorTable () const
56       int numBytes () const
57       int bytesPerLine () const
58       bool create ( int width, int height, int depth, int numColors = 0,
59           Endian bitOrder = IgnoreEndian )
60       bool create ( const QSize &, int depth, int numColors = 0, Endian
61           bitOrder = IgnoreEndian )
62       void reset ()
63       void fill ( uint pixel )
64       void invertPixels ( bool invertAlpha = TRUE )
65       QImage convertDepth ( int depth ) const
66       QImage convertDepthWithPalette ( int d, QRgb * palette, int
67           palette_count, int conversion_flags = 0 ) const
68       QImage convertDepth ( int depth, int conversion_flags ) const
69       QImage convertBitOrder ( Endian bitOrder ) const
70       enum ScaleMode { ScaleFree, ScaleMin, ScaleMax }
71       QImage smoothScale ( int w, int h, ScaleMode mode = ScaleFree ) const
72       QImage smoothScale ( const QSize & s, ScaleMode mode = ScaleFree )
73           const
74       QImage scale ( int w, int h, ScaleMode mode = ScaleFree ) const
75       QImage scale ( const QSize & s, ScaleMode mode = ScaleFree ) const
76       QImage scaleWidth ( int w ) const
77       QImage scaleHeight ( int h ) const
78       QImage xForm ( const QWMatrix & matrix ) const
79       QImage createAlphaMask ( int conversion_flags = 0 ) const
80       QImage createHeuristicMask ( bool clipTight = TRUE ) const
81       QImage mirror () const
82       QImage mirror ( bool horizontal, bool vertical ) const
83       QImage swapRGB () const
84       bool load ( const QString & fileName, const char * format = 0 )
85       bool loadFromData ( const uchar * buf, uint len, const char * format =
86           0 )
87       bool loadFromData ( QByteArray buf, const char * format = 0 )
88       bool save ( const QString & fileName, const char * format, int quality
89           = -1 ) const
90       bool save ( QIODevice * device, const char * format, int quality = -1 )
91           const
92       bool valid ( int x, int y ) const
93       int pixelIndex ( int x, int y ) const
94       QRgb pixel ( int x, int y ) const
95       void setPixel ( int x, int y, uint index_or_rgb )
96       int dotsPerMeterX () const
97       int dotsPerMeterY () const
98       void setDotsPerMeterX ( int x )
99       void setDotsPerMeterY ( int y )
100       QPoint offset () const
101       void setOffset ( const QPoint & p )
102       QValueList<QImageTextKeyLang> textList () const
103       QStringList textLanguages () const
104       QStringList textKeys () const
105       QString text ( const char * key, const char * lang = 0 ) const
106       QString text ( const QImageTextKeyLang & kl ) const
107       void setText ( const char * key, const char * lang, const QString & s )
108
109   Static Public Members
110       QImage fromMimeSource ( const QString & abs_name )
111       Endian systemBitOrder ()
112       Endian systemByteOrder ()
113       const char * imageFormat ( const QString & fileName )
114       QStrList inputFormats ()
115       QStrList outputFormats ()
116       QStringList inputFormatList ()
117       QStringList outputFormatList ()
118
120       QDataStream & operator<< ( QDataStream & s, const QImage & image )
121       QDataStream & operator>> ( QDataStream & s, QImage & image )
122       void bitBlt ( QImage * dst, int dx, int dy, const QImage * src, int sx,
123           int sy, int sw, int sh, int conversion_flags )
124

DESCRIPTION

126       The QImage class provides a hardware-independent pixmap representation
127       with direct access to the pixel data.
128
129       It is one of the two classes Qt provides for dealing with images, the
130       other being QPixmap. QImage is designed and optimized for I/O and for
131       direct pixel access/manipulation. QPixmap is designed and optimized for
132       drawing. There are (slow) functions to convert between QImage and
133       QPixmap: QPixmap::convertToImage() and QPixmap::convertFromImage().
134
135       An image has the parameters width, height and depth (bits per pixel,
136       bpp), a color table and the actual pixels. QImage supports 1-bpp, 8-bpp
137       and 32-bpp image data. 1-bpp and 8-bpp images use a color lookup table;
138       the pixel value is a color table index.
139
140       32-bpp images encode an RGB value in 24 bits and ignore the color
141       table. The most significant byte is used for the alpha buffer.
142
143       An entry in the color table is an RGB triplet encoded as a uint. Use
144       the qRed(), qGreen() and qBlue() functions (qcolor.h) to access the
145       components, and qRgb to make an RGB triplet (see the QColor class
146       documentation).
147
148       1-bpp (monochrome) images have a color table with a most two colors.
149       There are two different formats: big endian (MSB first) or little
150       endian (LSB first) bit order. To access a single bit you will must do
151       some bit shifts:
152
153           QImage image;
154           // sets bit at (x,y) to 1
155           if ( image.bitOrder() == QImage::LittleEndian )
156               *(image.scanLine(y) + (x >> 3)) |= 1 << (x & 7);
157           else
158               *(image.scanLine(y) + (x >> 3)) |= 1 << (7 - (x & 7));
159
160       If this looks complicated, it might be a good idea to convert the 1-bpp
161       image to an 8-bpp image using convertDepth().
162
163       8-bpp images are much easier to work with than 1-bpp images because
164       they have a single byte per pixel:
165
166           QImage image;
167           // set entry 19 in the color table to yellow
168           image.setColor( 19, qRgb(255,255,0) );
169           // set 8 bit pixel at (x,y) to value yellow (in color table)
170           *(image.scanLine(y) + x) = 19;
171
172       32-bpp images ignore the color table; instead, each pixel contains the
173       RGB triplet. 24 bits contain the RGB value; the most significant byte
174       is reserved for the alpha buffer.
175
176           QImage image;
177           // sets 32 bit pixel at (x,y) to yellow.
178           uint *p = (uint *)image.scanLine(y) + x;
179           *p = qRgb(255,255,0);
180
181       On Qt/Embedded, scanlines are aligned to the pixel depth and may be
182       padded to any degree, while on all other platforms, the scanlines are
183       32-bit aligned for all depths. The constructor taking a uchar* argument
184       always expects 32-bit aligned data. On Qt/Embedded, an additional
185       constructor allows the number of bytes-per-line to be specified.
186
187       QImage supports a variety of methods for getting information about the
188       image, for example, colorTable(), allGray(), isGrayscale(), bitOrder(),
189       bytesPerLine(), depth(), dotsPerMeterX() and dotsPerMeterY(),
190       hasAlphaBuffer(), numBytes(), numColors(), and width() and height().
191
192       Pixel colors are retrieved with pixel() and set with setPixel().
193
194       QImage also supports a number of functions for creating a new image
195       that is a transformed version of the original. For example, copy(),
196       convertBitOrder(), convertDepth(), createAlphaMask(),
197       createHeuristicMask(), mirror(), scale(), smoothScale(), swapRGB() and
198       xForm(). There are also functions for changing attributes of an image
199       in-place, for example, setAlphaBuffer(), setColor(), setDotsPerMeterX()
200       and setDotsPerMeterY() and setNumColors().
201
202       Images can be loaded and saved in the supported formats. Images are
203       saved to a file with save(). Images are loaded from a file with load()
204       (or in the constructor) or from an array of data with loadFromData().
205       The lists of supported formats are available from inputFormatList() and
206       outputFormatList().
207
208       Strings of text may be added to images using setText().
209
210       The QImage class uses explicit sharing, similar to that used by
211       QMemArray.
212
213       New image formats can be added as plugins.
214
215       See also QImageIO, QPixmap, Shared Classes, Graphics Classes, Image
216       Processing Classes, and Implicitly and Explicitly Shared Classes.
217
218   Member Type Documentation

QImage::Endian

220       This enum type is used to describe the endianness of the CPU and
221       graphics hardware.
222
223       QImage::IgnoreEndian - Endianness does not matter. Useful for some
224       operations that are independent of endianness.
225
226       QImage::BigEndian - Network byte order, as on SPARC and Motorola CPUs.
227
228       QImage::LittleEndian - PC/Alpha byte order.
229

QImage::ScaleMode

231       The functions scale() and smoothScale() use different modes for scaling
232       the image. The purpose of these modes is to retain the ratio of the
233       image if this is required.
234
235       <center>
236                                   [Image Omitted]
237
238       </center>
239
240       QImage::ScaleFree - The image is scaled freely: the resulting image
241       fits exactly into the specified size; the ratio will not necessarily be
242       preserved.
243
244       QImage::ScaleMin - The ratio of the image is preserved and the
245       resulting image is guaranteed to fit into the specified size (it is as
246       large as possible within these constraints) - the image might be
247       smaller than the requested size.
248
249       QImage::ScaleMax - The ratio of the image is preserved and the
250       resulting image fills the whole specified rectangle (it is as small as
251       possible within these constraints) - the image might be larger than the
252       requested size.
253

MEMBER FUNCTION DOCUMENTATION

QImage::QImage ()

256       Constructs a null image.
257
258       See also isNull().
259

QImage::QImage ( int w, int h, int depth, int numColors = 0, Endian bitOrder =

261       IgnoreEndian )
262       Constructs an image with w width, h height, depth bits per pixel,
263       numColors colors and bit order bitOrder.
264
265       Using this constructor is the same as first constructing a null image
266       and then calling the create() function.
267
268       See also create().
269

QImage::QImage ( const QSize & size, int depth, int numColors = 0, Endian

271       bitOrder = IgnoreEndian )
272       Constructs an image with size size pixels, depth depth bits, numColors
273       and bitOrder endianness.
274
275       Using this constructor is the same as first constructing a null image
276       and then calling the create() function.
277
278       See also create().
279

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

281       Constructs an image and tries to load the image from the file fileName.
282
283       If format is specified, the loader attempts to read the image using the
284       specified format. If format is not specified (which is the default),
285       the loader reads a few bytes from the header to guess the file format.
286
287       If the loading of the image failed, this object is a null image.
288
289       The QImageIO documentation lists the supported image formats and
290       explains how to add extra formats.
291
292       See also load(), isNull(), and QImageIO.
293

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

295       Constructs an image from xpm, which must be a valid XPM image.
296
297       Errors are silently ignored.
298
299       Note that it's possible to squeeze the XPM variable a little bit by
300       using an unusual declaration:
301
302               static const char * const start_xpm[]={
303                   "16 15 8 1",
304                   "a c #cec6bd",
305               ....
306
307       The extra const makes the entire definition read-only, which is
308       slightly more efficient (e.g. when the code is in a shared library) and
309       ROMable when the application is to be stored in ROM.
310

QImage::QImage ( const QByteArray & array )

312       Constructs an image from the binary data array. It tries to guess the
313       file format.
314
315       If the loading of the image failed, this object is a null image.
316
317       See also loadFromData(), isNull(), and imageFormat().
318

QImage::QImage ( uchar * yourdata, int w, int h, int depth, QRgb * colortable,

320       int numColors, Endian bitOrder )
321       Constructs an image w pixels wide, h pixels high with a color depth of
322       depth, that uses an existing memory buffer, yourdata. The buffer must
323       remain valid throughout the life of the QImage. The image does not
324       delete the buffer at destruction.
325
326       If colortable is 0, a color table sufficient for numColors will be
327       allocated (and destructed later).
328
329       Note that yourdata must be 32-bit aligned.
330
331       The endianness is given in bitOrder.
332

QImage::QImage ( uchar * yourdata, int w, int h, int depth, int bpl, QRgb *

334       colortable, int numColors, Endian bitOrder )
335       Constructs an image that uses an existing memory buffer. The buffer
336       must remain valid for the life of the QImage. The image does not delete
337       the buffer at destruction. The buffer is passed as yourdata. The
338       image's width is w and its height is h. The color depth is depth. bpl
339       specifies the number of bytes per line.
340
341       If colortable is 0, a color table sufficient for numColors will be
342       allocated (and destructed later).
343
344       The endianness is specified by bitOrder.
345
346       Warning: This constructor is only available on Qt/Embedded.
347

QImage::QImage ( const QImage & image )

349       Constructs a shallow copy of image.
350

QImage::~QImage ()

352       Destroys the image and cleans up.
353

bool QImage::allGray () const

355       Returns TRUE if all the colors in the image are shades of gray (i.e.
356       their red, green and blue components are equal); otherwise returns
357       FALSE.
358
359       This function is slow for large 16-bit (Qt/Embedded only) and 32-bit
360       images.
361
362       See also isGrayscale().
363

Endian QImage::bitOrder () const

365       Returns the bit order for the image.
366
367       If it is a 1-bpp image, this function returns either QImage::BigEndian
368       or QImage::LittleEndian.
369
370       If it is not a 1-bpp image, this function returns QImage::IgnoreEndian.
371
372       See also depth().
373

uchar * QImage::bits () const

375       Returns a pointer to the first pixel data. This is equivalent to
376       scanLine(0).
377
378       See also numBytes(), scanLine(), and jumpTable().
379
380       Example: opengl/texture/gltexobj.cpp.
381

int QImage::bytesPerLine () const

383       Returns the number of bytes per image scanline. This is equivalent to
384       numBytes()/height().
385
386       See also numBytes() and scanLine().
387

QRgb QImage::color ( int i ) const

389       Returns the color in the color table at index i. The first color is at
390       index 0.
391
392       A color value is an RGB triplet. Use the qRed(), qGreen() and qBlue()
393       functions (defined in qcolor.h) to get the color value components.
394
395       See also setColor(), numColors(), and QColor.
396
397       Example: themes/wood.cpp.
398

QRgb * QImage::colorTable () const

400       Returns a pointer to the color table.
401
402       See also numColors().
403

QImage QImage::convertBitOrder ( Endian bitOrder ) const

405       Converts the bit order of the image to bitOrder and returns the
406       converted image. The original image is not changed.
407
408       Returns *this if the bitOrder is equal to the image bit order, or a
409       null image if this image cannot be converted.
410
411       See also bitOrder(), systemBitOrder(), and isNull().
412

QImage QImage::convertDepth ( int depth, int conversion_flags ) const

414       Converts the depth (bpp) of the image to depth and returns the
415       converted image. The original image is not changed.
416
417       The depth argument must be 1, 8, 16 (Qt/Embedded only) or 32.
418
419       Returns *this if depth is equal to the image depth, or a null image if
420       this image cannot be converted.
421
422       If the image needs to be modified to fit in a lower-resolution result
423       (e.g. converting from 32-bit to 8-bit), use the conversion_flags to
424       specify how you'd prefer this to happen.
425
426       See also Qt::ImageConversionFlags, depth(), and isNull().
427

QImage QImage::convertDepth ( int depth ) const

429       This is an overloaded member function, provided for convenience. It
430       behaves essentially like the above function.
431

QImage QImage::convertDepthWithPalette ( int d, QRgb * palette, int

433       palette_count, int conversion_flags = 0 ) const
434       Returns an image with depth d, using the palette_count colors pointed
435       to by palette. If d is 1 or 8, the returned image will have its color
436       table ordered the same as palette.
437
438       If the image needs to be modified to fit in a lower-resolution result
439       (e.g. converting from 32-bit to 8-bit), use the conversion_flags to
440       specify how you'd prefer this to happen.
441
442       Note: currently no closest-color search is made. If colors are found
443       that are not in the palette, the palette may not be used at all. This
444       result should not be considered valid because it may change in future
445       implementations.
446
447       Currently inefficient for non-32-bit images.
448
449       See also Qt::ImageConversionFlags.
450

QImage QImage::copy () const

452       Returns a deep copy of the image.
453
454       See also detach().
455

QImage QImage::copy ( int x, int y, int w, int h, int conversion_flags = 0 )

457       const
458       This is an overloaded member function, provided for convenience. It
459       behaves essentially like the above function.
460
461       Returns a deep copy of a sub-area of the image.
462
463       The returned image is always w by h pixels in size, and is copied from
464       position x, y in this image. In areas beyond this image pixels are
465       filled with pixel 0.
466
467       If the image needs to be modified to fit in a lower-resolution result
468       (e.g. converting from 32-bit to 8-bit), use the conversion_flags to
469       specify how you'd prefer this to happen.
470
471       See also bitBlt() and Qt::ImageConversionFlags.
472

QImage QImage::copy ( const QRect & r ) const

474       This is an overloaded member function, provided for convenience. It
475       behaves essentially like the above function.
476
477       Returns a deep copy of a sub-area of the image.
478
479       The returned image always has the size of the rectangle r. In areas
480       beyond this image pixels are filled with pixel 0.
481

bool QImage::create ( int width, int height, int depth, int numColors = 0,

483       Endian bitOrder = IgnoreEndian )
484       Sets the image width, height, depth, its number of colors (in
485       numColors), and bit order. Returns TRUE if successful, or FALSE if the
486       parameters are incorrect or if memory cannot be allocated.
487
488       The width and height is limited to 32767. depth must be 1, 8, or 32. If
489       depth is 1, bitOrder must be set to either QImage::LittleEndian or
490       QImage::BigEndian. For other depths bitOrder must be
491       QImage::IgnoreEndian.
492
493       This function allocates a color table and a buffer for the image data.
494       The image data is not initialized.
495
496       The image buffer is allocated as a single block that consists of a
497       table of scanline pointers (jumpTable()) and the image data (bits()).
498
499       See also fill(), width(), height(), depth(), numColors(), bitOrder(),
500       jumpTable(), scanLine(), bits(), bytesPerLine(), and numBytes().
501

bool QImage::create ( const QSize &, int depth, int numColors = 0, Endian

503       bitOrder = IgnoreEndian )
504       This is an overloaded member function, provided for convenience. It
505       behaves essentially like the above function.
506

QImage QImage::createAlphaMask ( int conversion_flags = 0 ) const

508       Builds and returns a 1-bpp mask from the alpha buffer in this image.
509       Returns a null image if alpha buffer mode is disabled.
510
511       See QPixmap::convertFromImage() for a description of the
512       conversion_flags argument.
513
514       The returned image has little-endian bit order, which you can convert
515       to big-endianness using convertBitOrder().
516
517       See also createHeuristicMask(), hasAlphaBuffer(), and setAlphaBuffer().
518

QImage QImage::createHeuristicMask ( bool clipTight = TRUE ) const

520       Creates and returns a 1-bpp heuristic mask for this image. It works by
521       selecting a color from one of the corners, then chipping away pixels of
522       that color starting at all the edges.
523
524       The four corners vote for which color is to be masked away. In case of
525       a draw (this generally means that this function is not applicable to
526       the image), the result is arbitrary.
527
528       The returned image has little-endian bit order, which you can convert
529       to big-endianness using convertBitOrder().
530
531       If clipTight is TRUE the mask is just large enough to cover the pixels;
532       otherwise, the mask is larger than the data pixels.
533
534       This function disregards the alpha buffer.
535
536       See also createAlphaMask().
537

int QImage::depth () const

539       Returns the depth of the image.
540
541       The image depth is the number of bits used to encode a single pixel,
542       also called bits per pixel (bpp) or bit planes of an image.
543
544       The supported depths are 1, 8, 16 (Qt/Embedded only) and 32.
545
546       See also convertDepth().
547

void QImage::detach ()

549       Detaches from shared image data and makes sure that this image is the
550       only one referring to the data.
551
552       If multiple images share common data, this image makes a copy of the
553       data and detaches itself from the sharing mechanism. Nothing is done if
554       there is just a single reference.
555
556       See also copy().
557
558       Example: themes/wood.cpp.
559

int QImage::dotsPerMeterX () const

561       Returns the number of pixels that fit horizontally in a physical meter.
562       This and dotsPerMeterY() define the intended scale and aspect ratio of
563       the image.
564
565       See also setDotsPerMeterX().
566

int QImage::dotsPerMeterY () const

568       Returns the number of pixels that fit vertically in a physical meter.
569       This and dotsPerMeterX() define the intended scale and aspect ratio of
570       the image.
571
572       See also setDotsPerMeterY().
573

void QImage::fill ( uint pixel )

575       Fills the entire image with the pixel value pixel.
576
577       If the depth of this image is 1, only the lowest bit is used. If you
578       say fill(0), fill(2), etc., the image is filled with 0s. If you say
579       fill(1), fill(3), etc., the image is filled with 1s. If the depth is 8,
580       the lowest 8 bits are used.
581
582       If the depth is 32 and the image has no alpha buffer, the pixel value
583       is written to each pixel in the image. If the image has an alpha
584       buffer, only the 24 RGB bits are set and the upper 8 bits (alpha value)
585       are left unchanged.
586
587       Note: QImage::pixel() returns the color of the pixel at the given
588       coordinates; QColor::pixel() returns the pixel value of the underlying
589       window system (essentially an index value), so normally you will want
590       to use QImage::pixel() to use a color from an existing image or
591       QColor::rgb() to use a specific color.
592
593       See also invertPixels(), depth(), hasAlphaBuffer(), and create().
594

QImage QImage::fromMimeSource ( const QString & abs_name ) [static]

596       Convenience function. Gets the data associated with the absolute name
597       abs_name from the default mime source factory and decodes it to an
598       image.
599
600       See also QMimeSourceFactory, QImage::fromMimeSource(), and
601       QImageDrag::decode().
602

bool QImage::hasAlphaBuffer () const

604       Returns TRUE if alpha buffer mode is enabled; otherwise returns FALSE.
605
606       See also setAlphaBuffer().
607

int QImage::height () const

609       Returns the height of the image.
610
611       See also width(), size(), and rect().
612
613       Examples:
614

const char * QImage::imageFormat ( const QString & fileName ) [static]

616       Returns a string that specifies the image format of the file fileName,
617       or 0 if the file cannot be read or if the format is not recognized.
618
619       The QImageIO documentation lists the guaranteed supported image
620       formats, or use QImage::inputFormats() and QImage::outputFormats() to
621       get lists that include the installed formats.
622
623       See also load() and save().
624

QStringList QImage::inputFormatList () [static]

626       Returns a list of image formats that are supported for image input.
627
628       Note that if you want to iterate over the list, you should iterate over
629       a copy, e.g.
630
631           QStringList list = myImage.inputFormatList();
632           QStringList::Iterator it = list.begin();
633           while( it != list.end() ) {
634               myProcessing( *it );
635               ++it;
636           }
637
638       See also outputFormatList(), inputFormats(), and QImageIO.
639
640       Example: showimg/showimg.cpp.
641

QStrList QImage::inputFormats () [static]

643       Returns a list of image formats that are supported for image input.
644
645       See also outputFormats(), inputFormatList(), and QImageIO.
646

void QImage::invertPixels ( bool invertAlpha = TRUE )

648       Inverts all pixel values in the image.
649
650       If the depth is 32: if invertAlpha is TRUE, the alpha bits are also
651       inverted, otherwise they are left unchanged.
652
653       If the depth is not 32, the argument invertAlpha has no meaning.
654
655       Note that inverting an 8-bit image means to replace all pixels using
656       color index i with a pixel using color index 255 minus i. Similarly for
657       a 1-bit image. The color table is not changed.
658
659       See also fill(), depth(), and hasAlphaBuffer().
660

bool QImage::isGrayscale () const

662       For 16-bit (Qt/Embedded only) and 32-bit images, this function is
663       equivalent to allGray().
664
665       For 8-bpp images, this function returns TRUE if color(i) is QRgb(i,i,i)
666       for all indices of the color table; otherwise returns FALSE.
667
668       See also allGray() and depth().
669

bool QImage::isNull () const

671       Returns TRUE if it is a null image; otherwise returns FALSE.
672
673       A null image has all parameters set to zero and no allocated data.
674
675       Example: showimg/showimg.cpp.
676

uchar ** QImage::jumpTable () const

678       Returns a pointer to the scanline pointer table.
679
680       This is the beginning of the data block for the image.
681
682       See also bits() and scanLine().
683

bool QImage::load ( const QString & fileName, const char * format = 0 )

685       Loads an image from the file fileName. Returns TRUE if the image was
686       successfully loaded; otherwise returns FALSE.
687
688       If format is specified, the loader attempts to read the image using the
689       specified format. If format is not specified (which is the default),
690       the loader reads a few bytes from the header to guess the file format.
691
692       The QImageIO documentation lists the supported image formats and
693       explains how to add extra formats.
694
695       See also loadFromData(), save(), imageFormat(), QPixmap::load(), and
696       QImageIO.
697

bool QImage::loadFromData ( const uchar * buf, uint len, const char * format =

699       0 )
700       Loads an image from the first len bytes of binary data in buf. Returns
701       TRUE if the image was successfully loaded; otherwise returns FALSE.
702
703       If format is specified, the loader attempts to read the image using the
704       specified format. If format is not specified (which is the default),
705       the loader reads a few bytes from the header to guess the file format.
706
707       The QImageIO documentation lists the supported image formats and
708       explains how to add extra formats.
709
710       See also load(), save(), imageFormat(), QPixmap::loadFromData(), and
711       QImageIO.
712

bool QImage::loadFromData ( QByteArray buf, const char * format = 0 )

714       This is an overloaded member function, provided for convenience. It
715       behaves essentially like the above function.
716
717       Loads an image from the QByteArray buf.
718

QImage QImage::mirror () const

720       Returns a QImage which is a vertically mirrored copy of this image. The
721       original QImage is not changed.
722

QImage QImage::mirror ( bool horizontal, bool vertical ) const

724       This is an overloaded member function, provided for convenience. It
725       behaves essentially like the above function.
726
727       Returns a mirror of the image, mirrored in the horizontal and/or the
728       vertical direction depending on whether horizontal and vertical are set
729       to TRUE or FALSE. The original image is not changed.
730
731       See also smoothScale().
732

int QImage::numBytes () const

734       Returns the number of bytes occupied by the image data.
735
736       See also bytesPerLine() and bits().
737

int QImage::numColors () const

739       Returns the size of the color table for the image.
740
741       Notice that numColors() returns 0 for 16-bpp (Qt/Embedded only) and
742       32-bpp images because these images do not use color tables, but instead
743       encode pixel values as RGB triplets.
744
745       See also setNumColors() and colorTable().
746
747       Example: themes/wood.cpp.
748

QPoint QImage::offset () const

750       Returns the number of pixels by which the image is intended to be
751       offset by when positioning relative to other images.
752

bool QImage::operator!= ( const QImage & i ) const

754       Returns TRUE if this image and image i have different contents;
755       otherwise returns FALSE. The comparison can be slow, unless there is
756       some obvious difference, such as different widths, in which case the
757       function will return quickly.
758
759       See also operator=().
760

QImage & QImage::operator= ( const QImage & image )

762       Assigns a shallow copy of image to this image and returns a reference
763       to this image.
764
765       See also copy().
766

QImage & QImage::operator= ( const QPixmap & pixmap )

768       This is an overloaded member function, provided for convenience. It
769       behaves essentially like the above function.
770
771       Sets the image bits to the pixmap contents and returns a reference to
772       the image.
773
774       If the image shares data with other images, it will first dereference
775       the shared data.
776
777       Makes a call to QPixmap::convertToImage().
778

bool QImage::operator== ( const QImage & i ) const

780       Returns TRUE if this image and image i have the same contents;
781       otherwise returns FALSE. The comparison can be slow, unless there is
782       some obvious difference, such as different widths, in which case the
783       function will return quickly.
784
785       See also operator=().
786

QStringList QImage::outputFormatList () [static]

788       Returns a list of image formats that are supported for image output.
789
790       Note that if you want to iterate over the list, you should iterate over
791       a copy, e.g.
792
793           QStringList list = myImage.outputFormatList();
794           QStringList::Iterator it = list.begin();
795           while( it != list.end() ) {
796               myProcessing( *it );
797               ++it;
798           }
799
800       See also inputFormatList(), outputFormats(), and QImageIO.
801

QStrList QImage::outputFormats () [static]

803       Returns a list of image formats that are supported for image output.
804
805       See also inputFormats(), outputFormatList(), and QImageIO.
806
807       Example: showimg/showimg.cpp.
808

QRgb QImage::pixel ( int x, int y ) const

810       Returns the color of the pixel at the coordinates (x, y).
811
812       If (x, y) is not on the image, the results are undefined.
813
814       See also setPixel(), qRed(), qGreen(), qBlue(), and valid().
815
816       Examples:
817

int QImage::pixelIndex ( int x, int y ) const

819       Returns the pixel index at the given coordinates.
820
821       If (x, y) is not valid, or if the image is not a paletted image
822       (depth() > 8), the results are undefined.
823
824       See also valid() and depth().
825

QRect QImage::rect () const

827       Returns the enclosing rectangle (0, 0, width(), height()) of the image.
828
829       See also width(), height(), and size().
830

void QImage::reset ()

832       Resets all image parameters and deallocates the image data.
833

bool QImage::save ( const QString & fileName, const char * format, int quality

835       = -1 ) const
836       Saves the image to the file fileName, using the image file format
837       format and a quality factor of quality. quality must be in the range
838       0..100 or -1. Specify 0 to obtain small compressed files, 100 for large
839       uncompressed files, and -1 (the default) to use the default settings.
840
841       Returns TRUE if the image was successfully saved; otherwise returns
842       FALSE.
843
844       See also load(), loadFromData(), imageFormat(), QPixmap::save(), and
845       QImageIO.
846

bool QImage::save ( QIODevice * device, const char * format, int quality = -1

848       ) const
849       This is an overloaded member function, provided for convenience. It
850       behaves essentially like the above function.
851
852       This function writes a QImage to the QIODevice, device. This can be
853       used, for example, to save an image directly into a QByteArray:
854
855           QImage image;
856           QByteArray ba;
857           QBuffer buffer( ba );
858           buffer.open( IO_WriteOnly );
859           image.save( &buffer, "PNG" ); // writes image into ba in PNG format
860

QImage QImage::scale ( int w, int h, ScaleMode mode = ScaleFree ) const

862       Returns a copy of the image scaled to a rectangle of width w and height
863       h according to the ScaleMode mode.
864
865       If mode is ScaleFree, the image is scaled to (w, h).
866
867       If mode is ScaleMin, the image is scaled to a rectangle as large as
868       possible inside (w, h), preserving the aspect ratio.
869
870       If mode is ScaleMax, the image is scaled to a rectangle as small as
871       possible outside (w, h), preserving the aspect ratio.
872
873       If either the width w or the height h is 0 or negative, this function
874       returns a null image.
875
876       This function uses a simple, fast algorithm. If you need better
877       quality, use smoothScale() instead.
878
879       See also scaleWidth(), scaleHeight(), smoothScale(), and xForm().
880

QImage QImage::scale ( const QSize & s, ScaleMode mode = ScaleFree ) const

882       This is an overloaded member function, provided for convenience. It
883       behaves essentially like the above function.
884
885       The requested size of the image is s.
886

QImage QImage::scaleHeight ( int h ) const

888       Returns a scaled copy of the image. The returned image has a height of
889       h pixels. This function automatically calculates the width of the image
890       so that the ratio of the image is preserved.
891
892       If h is 0 or negative a null image is returned.
893
894       See also scale(), scaleWidth(), smoothScale(), and xForm().
895
896       Example: table/small-table-demo/main.cpp.
897

QImage QImage::scaleWidth ( int w ) const

899       Returns a scaled copy of the image. The returned image has a width of w
900       pixels. This function automatically calculates the height of the image
901       so that the ratio of the image is preserved.
902
903       If w is 0 or negative a null image is returned.
904
905       See also scale(), scaleHeight(), smoothScale(), and xForm().
906

uchar * QImage::scanLine ( int i ) const

908       Returns a pointer to the pixel data at the scanline with index i. The
909       first scanline is at index 0.
910
911       The scanline data is aligned on a 32-bit boundary.
912
913       Warning: If you are accessing 32-bpp image data, cast the returned
914       pointer to QRgb* (QRgb has a 32-bit size) and use it to read/write the
915       pixel value. You cannot use the uchar* pointer directly, because the
916       pixel format depends on the byte order on the underlying platform.
917       Hint: use qRed(), qGreen() and qBlue(), etc. (qcolor.h) to access the
918       pixels.
919
920       Warning: If you are accessing 16-bpp image data, you must handle
921       endianness yourself. (Qt/Embedded only)
922
923       See also bytesPerLine(), bits(), and jumpTable().
924
925       Example: desktop/desktop.cpp.
926

void QImage::setAlphaBuffer ( bool enable )

928       Enables alpha buffer mode if enable is TRUE, otherwise disables it. The
929       default setting is disabled.
930
931       An 8-bpp image has 8-bit pixels. A pixel is an index into the color
932       table, which contains 32-bit color values. In a 32-bpp image, the
933       32-bit pixels are the color values.
934
935       This 32-bit value is encoded as follows: The lower 24 bits are used for
936       the red, green, and blue components. The upper 8 bits contain the alpha
937       component.
938
939       The alpha component specifies the transparency of a pixel. 0 means
940       completely transparent and 255 means opaque. The alpha component is
941       ignored if you do not enable alpha buffer mode.
942
943       The alpha buffer is used to set a mask when a QImage is translated to a
944       QPixmap.
945
946       See also hasAlphaBuffer() and createAlphaMask().
947

void QImage::setColor ( int i, QRgb c )

949       Sets a color in the color table at index i to c.
950
951       A color value is an RGB triplet. Use the qRgb() function (defined in
952       qcolor.h) to make RGB triplets.
953
954       See also color(), setNumColors(), and numColors().
955
956       Examples:
957

void QImage::setDotsPerMeterX ( int x )

959       Sets the value returned by dotsPerMeterX() to x.
960

void QImage::setDotsPerMeterY ( int y )

962       Sets the value returned by dotsPerMeterY() to y.
963

void QImage::setNumColors ( int numColors )

965       Resizes the color table to numColors colors.
966
967       If the color table is expanded all the extra colors will be set to
968       black (RGB 0,0,0).
969
970       See also numColors(), color(), setColor(), and colorTable().
971

void QImage::setOffset ( const QPoint & p )

973       Sets the value returned by offset() to p.
974

void QImage::setPixel ( int x, int y, uint index_or_rgb )

976       Sets the pixel index or color at the coordinates (x, y) to
977       index_or_rgb.
978
979       If (x, y) is not valid, the result is undefined.
980
981       If the image is a paletted image (depth() <= 8) and index_or_rgb >=
982       numColors(), the result is undefined.
983
984       See also pixelIndex(), pixel(), qRgb(), qRgba(), and valid().
985

void QImage::setText ( const char * key, const char * lang, const QString & s

987       )
988       Records string s for the keyword key. The key should be a portable
989       keyword recognizable by other software - some suggested values can be
990       found in the PNG specification. s can be any text. lang should specify
991       the language code (see RFC 1766) or 0.
992

QSize QImage::size () const

994       Returns the size of the image, i.e. its width and height.
995
996       See also width(), height(), and rect().
997

QImage QImage::smoothScale ( int w, int h, ScaleMode mode = ScaleFree ) const

999       Returns a smoothly scaled copy of the image. The returned image has a
1000       size of width w by height h pixels if mode is ScaleFree. The modes
1001       ScaleMin and ScaleMax may be used to preserve the ratio of the image:
1002       if mode is ScaleMin, the returned image is guaranteed to fit into the
1003       rectangle specified by w and h (it is as large as possible within the
1004       constraints); if mode is ScaleMax, the returned image fits at least
1005       into the specified rectangle (it is a small as possible within the
1006       constraints).
1007
1008       For 32-bpp images and 1-bpp/8-bpp color images the result will be
1009       32-bpp, whereas all-gray images (including black-and-white 1-bpp) will
1010       produce 8-bit grayscale images with the palette spanning 256 grays from
1011       black to white.
1012
1013       This function uses code based on pnmscale.c by Jef Poskanzer.
1014
1015       pnmscale.c - read a portable anymap and scale it
1016
1017       Copyright (C) 1989, 1991 by Jef Poskanzer.
1018
1019       Permission to use, copy, modify, and distribute this software and its
1020       documentation for any purpose and without fee is hereby granted,
1021       provided that the above copyright notice appear in all copies and that
1022       both that copyright notice and this permission notice appear in
1023       supporting documentation. This software is provided "as is" without
1024       express or implied warranty.
1025
1026       See also scale() and mirror().
1027

QImage QImage::smoothScale ( const QSize & s, ScaleMode mode = ScaleFree )

1029       const
1030       This is an overloaded member function, provided for convenience. It
1031       behaves essentially like the above function.
1032
1033       The requested size of the image is s.
1034

QImage QImage::swapRGB () const

1036       Returns a QImage in which the values of the red and blue components of
1037       all pixels have been swapped, effectively converting an RGB image to a
1038       BGR image. The original QImage is not changed.
1039

Endian QImage::systemBitOrder () [static]

1041       Determines the bit order of the display hardware. Returns
1042       QImage::LittleEndian (LSB first) or QImage::BigEndian (MSB first).
1043
1044       See also systemByteOrder().
1045

Endian QImage::systemByteOrder () [static]

1047       Determines the host computer byte order. Returns QImage::LittleEndian
1048       (LSB first) or QImage::BigEndian (MSB first).
1049
1050       See also systemBitOrder().
1051

QString QImage::text ( const char * key, const char * lang = 0 ) const

1053       Returns the string recorded for the keyword key in language lang, or in
1054       a default language if lang is 0.
1055

QString QImage::text ( const QImageTextKeyLang & kl ) const

1057       This is an overloaded member function, provided for convenience. It
1058       behaves essentially like the above function.
1059
1060       Returns the string recorded for the keyword and language kl.
1061

QStringList QImage::textKeys () const

1063       Returns the keywords for which some texts are recorded.
1064
1065       Note that if you want to iterate over the list, you should iterate over
1066       a copy, e.g.
1067
1068           QStringList list = myImage.textKeys();
1069           QStringList::Iterator it = list.begin();
1070           while( it != list.end() ) {
1071               myProcessing( *it );
1072               ++it;
1073           }
1074
1075       See also textList(), text(), setText(), and textLanguages().
1076

QStringList QImage::textLanguages () const

1078       Returns the language identifiers for which some texts are recorded.
1079
1080       Note that if you want to iterate over the list, you should iterate over
1081       a copy, e.g.
1082
1083           QStringList list = myImage.textLanguages();
1084           QStringList::Iterator it = list.begin();
1085           while( it != list.end() ) {
1086               myProcessing( *it );
1087               ++it;
1088           }
1089
1090       See also textList(), text(), setText(), and textKeys().
1091

QValueList<QImageTextKeyLang> QImage::textList () const

1093       Returns a list of QImageTextKeyLang objects that enumerate all the
1094       texts key/language pairs set by setText() for this image.
1095
1096       Note that if you want to iterate over the list, you should iterate over
1097       a copy, e.g.
1098
1099           QValueList<QImageTextKeyLang> list = myImage.textList();
1100           QValueList<QImageTextKeyLang>::Iterator it = list.begin();
1101           while( it != list.end() ) {
1102               myProcessing( *it );
1103               ++it;
1104           }
1105

bool QImage::valid ( int x, int y ) const

1107       Returns TRUE if ( x, y ) is a valid coordinate in the image; otherwise
1108       returns FALSE.
1109
1110       See also width(), height(), and pixelIndex().
1111
1112       Examples:
1113

int QImage::width () const

1115       Returns the width of the image.
1116
1117       See also height(), size(), and rect().
1118
1119       Examples:
1120

QImage QImage::xForm ( const QWMatrix & matrix ) const

1122       Returns a copy of the image that is transformed using the
1123       transformation matrix, matrix.
1124
1125       The transformation matrix is internally adjusted to compensate for
1126       unwanted translation, i.e. xForm() returns the smallest image that
1127       contains all the transformed points of the original image.
1128
1129       See also scale(), QPixmap::xForm(), QPixmap::trueMatrix(), and
1130       QWMatrix.
1131

void bitBlt ( QImage * dst, int dx, int dy, const QImage * src, int sx, int

1134       sy, int sw, int sh, int conversion_flags )
1135       Copies a block of pixels from src to dst. The pixels copied from source
1136       (src) are converted according to conversion_flags if it is incompatible
1137       with the destination (dst).
1138
1139       sx, sy is the top-left pixel in src, dx, dy is the top-left position in
1140       dst and sw, \sh is the size of the copied block.
1141
1142       The copying is clipped if areas outside src or dst are specified.
1143
1144       If sw is -1, it is adjusted to src->width(). Similarly, if sh is -1, it
1145       is adjusted to src->height().
1146
1147       Currently inefficient for non 32-bit images.
1148

QDataStream & operator<< ( QDataStream & s, const QImage & image )

1150       Writes the image image to the stream s as a PNG image, or as a BMP
1151       image if the stream's version is 1.
1152
1153       Note that writing the stream to a file will not produce a valid image
1154       file.
1155
1156       See also QImage::save() and Format of the QDataStream operators.
1157

QDataStream & operator>> ( QDataStream & s, QImage & image )

1159       Reads an image from the stream s and stores it in image.
1160
1161       See also QImage::load() and Format of the QDataStream operators.
1162
1163

SEE ALSO

1165       http://doc.trolltech.com/qimage.html
1166       http://www.trolltech.com/faq/tech.html
1167
1169       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
1170       license file included in the distribution for a complete license
1171       statement.
1172

AUTHOR

1174       Generated automatically from the source code.
1175

BUGS

1177       If you find a bug in Qt, please report it as described in
1178       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
1179       help you. Thank you.
1180
1181       The definitive Qt documentation is provided in HTML format; it is
1182       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
1183       web browser. This man page is provided as a convenience for those users
1184       who prefer man pages, although this format is not officially supported
1185       by Trolltech.
1186
1187       If you find errors in this manual page, please report them to qt-
1188       bugs@trolltech.com.  Please include the name of the manual page
1189       (qimage.3qt) and the Qt version (3.3.8).
1190
1191
1192
1193Trolltech AS                    2 February 2007                    QImage(3qt)
Impressum