1QImage(3qt) QImage(3qt)
2
6 QImage - Hardware-independent pixmap representation with direct access
7 to the pixel data
8
10 #include <qimage.h>
11 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 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
126 The QImage class provides a hardware-independent pixmap representation
127 with direct access to the pixel data.
128 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 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 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 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 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 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 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 8-bpp images are much easier to work with than 1-bpp images because
164 they have a single byte per pixel:
165 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 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 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 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 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 Pixel colors are retrieved with pixel() and set with setPixel().
193 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 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 Strings of text may be added to images using setText().
209 The QImage class uses explicit sharing, similar to that used by
211 QMemArray.
212 New image formats can be added as plugins.
214 See also QImageIO, QPixmap, Shared Classes, Graphics Classes, Image
216 Processing Classes, and Implicitly and Explicitly Shared Classes.
217 Member Type Documentation
220 This enum type is used to describe the endianness of the CPU and
221 graphics hardware.
222 QImage::IgnoreEndian - Endianness does not matter. Useful for some
224 operations that are independent of endianness.
225 QImage::BigEndian - Network byte order, as on SPARC and Motorola CPUs.
227 QImage::LittleEndian - PC/Alpha byte order.
229
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 <center>
236 [Image Omitted]
237 </center>
239 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 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 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
256 Constructs a null image.
257 See also isNull().
259
261 IgnoreEndian )
262 Constructs an image with w width, h height, depth bits per pixel,
263 numColors colors and bit order bitOrder.
264 Using this constructor is the same as first constructing a null image
266 and then calling the create() function.
267 See also create().
269
271 bitOrder = IgnoreEndian )
272 Constructs an image with size size pixels, depth depth bits, numColors
273 and bitOrder endianness.
274 Using this constructor is the same as first constructing a null image
276 and then calling the create() function.
277 See also create().
279
281 Constructs an image and tries to load the image from the file fileName.
282 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 If the loading of the image failed, this object is a null image.
288 The QImageIO documentation lists the supported image formats and
290 explains how to add extra formats.
291 See also load(), isNull(), and QImageIO.
293
295 Constructs an image from xpm, which must be a valid XPM image.
296 Errors are silently ignored.
298 Note that it's possible to squeeze the XPM variable a little bit by
300 using an unusual declaration:
301 static const char * const start_xpm[]={
303 "16 15 8 1",
304 "a c #cec6bd",
305 ....
306 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
312 Constructs an image from the binary data array. It tries to guess the
313 file format.
314 If the loading of the image failed, this object is a null image.
316 See also loadFromData(), isNull(), and imageFormat().
318
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 If colortable is 0, a color table sufficient for numColors will be
327 allocated (and destructed later).
328 Note that yourdata must be 32-bit aligned.
330 The endianness is given in bitOrder.
332
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 If colortable is 0, a color table sufficient for numColors will be
342 allocated (and destructed later).
343 The endianness is specified by bitOrder.
345 Warning: This constructor is only available on Qt/Embedded.
347
349 Constructs a shallow copy of image.
350
352 Destroys the image and cleans up.
353
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 This function is slow for large 16-bit (Qt/Embedded only) and 32-bit
360 images.
361 See also isGrayscale().
363
365 Returns the bit order for the image.
366 If it is a 1-bpp image, this function returns either QImage::BigEndian
368 or QImage::LittleEndian.
369 If it is not a 1-bpp image, this function returns QImage::IgnoreEndian.
371 See also depth().
373
375 Returns a pointer to the first pixel data. This is equivalent to
376 scanLine(0).
377 See also numBytes(), scanLine(), and jumpTable().
379 Example: opengl/texture/gltexobj.cpp.
381
383 Returns the number of bytes per image scanline. This is equivalent to
384 numBytes()/height().
385 See also numBytes() and scanLine().
387
389 Returns the color in the color table at index i. The first color is at
390 index 0.
391 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 See also setColor(), numColors(), and QColor.
396 Example: themes/wood.cpp.
398
400 Returns a pointer to the color table.
401 See also numColors().
403
405 Converts the bit order of the image to bitOrder and returns the
406 converted image. The original image is not changed.
407 Returns *this if the bitOrder is equal to the image bit order, or a
409 null image if this image cannot be converted.
410 See also bitOrder(), systemBitOrder(), and isNull().
412
414 Converts the depth (bpp) of the image to depth and returns the
415 converted image. The original image is not changed.
416 The depth argument must be 1, 8, 16 (Qt/Embedded only) or 32.
418 Returns *this if depth is equal to the image depth, or a null image if
420 this image cannot be converted.
421 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 See also Qt::ImageConversionFlags, depth(), and isNull().
427
429 This is an overloaded member function, provided for convenience. It
430 behaves essentially like the above function.
431
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 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 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 Currently inefficient for non-32-bit images.
448 See also Qt::ImageConversionFlags.
450
452 Returns a deep copy of the image.
453 See also detach().
455
457 const
458 This is an overloaded member function, provided for convenience. It
459 behaves essentially like the above function.
460 Returns a deep copy of a sub-area of the image.
462 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 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 See also bitBlt() and Qt::ImageConversionFlags.
472
474 This is an overloaded member function, provided for convenience. It
475 behaves essentially like the above function.
476 Returns a deep copy of a sub-area of the image.
478 The returned image always has the size of the rectangle r. In areas
480 beyond this image pixels are filled with pixel 0.
481
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 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 This function allocates a color table and a buffer for the image data.
494 The image data is not initialized.
495 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 See also fill(), width(), height(), depth(), numColors(), bitOrder(),
500 jumpTable(), scanLine(), bits(), bytesPerLine(), and numBytes().
501
503 bitOrder = IgnoreEndian )
504 This is an overloaded member function, provided for convenience. It
505 behaves essentially like the above function.
506
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 See QPixmap::convertFromImage() for a description of the
512 conversion_flags argument.
513 The returned image has little-endian bit order, which you can convert
515 to big-endianness using convertBitOrder().
516 See also createHeuristicMask(), hasAlphaBuffer(), and setAlphaBuffer().
518
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 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 The returned image has little-endian bit order, which you can convert
529 to big-endianness using convertBitOrder().
530 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 This function disregards the alpha buffer.
535 See also createAlphaMask().
537
539 Returns the depth of the image.
540 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 The supported depths are 1, 8, 16 (Qt/Embedded only) and 32.
545 See also convertDepth().
547
549 Detaches from shared image data and makes sure that this image is the
550 only one referring to the data.
551 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 See also copy().
557 Example: themes/wood.cpp.
559
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 See also setDotsPerMeterX().
566
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 See also setDotsPerMeterY().
573
575 Fills the entire image with the pixel value pixel.
576 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 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 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 See also invertPixels(), depth(), hasAlphaBuffer(), and create().
594
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 See also QMimeSourceFactory, QImage::fromMimeSource(), and
601 QImageDrag::decode().
602
604 Returns TRUE if alpha buffer mode is enabled; otherwise returns FALSE.
605 See also setAlphaBuffer().
607
609 Returns the height of the image.
610 See also width(), size(), and rect().
612 Examples:
614
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 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 See also load() and save().
624
626 Returns a list of image formats that are supported for image input.
627 Note that if you want to iterate over the list, you should iterate over
629 a copy, e.g.
630 QStringList list = myImage.inputFormatList();
632 QStringList::Iterator it = list.begin();
633 while( it != list.end() ) {
634 myProcessing( *it );
635 ++it;
636 }
637 See also outputFormatList(), inputFormats(), and QImageIO.
639 Example: showimg/showimg.cpp.
641
643 Returns a list of image formats that are supported for image input.
644 See also outputFormats(), inputFormatList(), and QImageIO.
646
648 Inverts all pixel values in the image.
649 If the depth is 32: if invertAlpha is TRUE, the alpha bits are also
651 inverted, otherwise they are left unchanged.
652 If the depth is not 32, the argument invertAlpha has no meaning.
654 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 See also fill(), depth(), and hasAlphaBuffer().
660
662 For 16-bit (Qt/Embedded only) and 32-bit images, this function is
663 equivalent to allGray().
664 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 See also allGray() and depth().
669
671 Returns TRUE if it is a null image; otherwise returns FALSE.
672 A null image has all parameters set to zero and no allocated data.
674 Example: showimg/showimg.cpp.
676
678 Returns a pointer to the scanline pointer table.
679 This is the beginning of the data block for the image.
681 See also bits() and scanLine().
683
685 Loads an image from the file fileName. Returns TRUE if the image was
686 successfully loaded; otherwise returns FALSE.
687 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 The QImageIO documentation lists the supported image formats and
693 explains how to add extra formats.
694 See also loadFromData(), save(), imageFormat(), QPixmap::load(), and
696 QImageIO.
697
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 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 The QImageIO documentation lists the supported image formats and
708 explains how to add extra formats.
709 See also load(), save(), imageFormat(), QPixmap::loadFromData(), and
711 QImageIO.
712
714 This is an overloaded member function, provided for convenience. It
715 behaves essentially like the above function.
716 Loads an image from the QByteArray buf.
718
720 Returns a QImage which is a vertically mirrored copy of this image. The
721 original QImage is not changed.
722
724 This is an overloaded member function, provided for convenience. It
725 behaves essentially like the above function.
726 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 See also smoothScale().
732
734 Returns the number of bytes occupied by the image data.
735 See also bytesPerLine() and bits().
737
739 Returns the size of the color table for the image.
740 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 See also setNumColors() and colorTable().
746 Example: themes/wood.cpp.
748
750 Returns the number of pixels by which the image is intended to be
751 offset by when positioning relative to other images.
752
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 See also operator=().
760
762 Assigns a shallow copy of image to this image and returns a reference
763 to this image.
764 See also copy().
766
768 This is an overloaded member function, provided for convenience. It
769 behaves essentially like the above function.
770 Sets the image bits to the pixmap contents and returns a reference to
772 the image.
773 If the image shares data with other images, it will first dereference
775 the shared data.
776 Makes a call to QPixmap::convertToImage().
778
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 See also operator=().
786
788 Returns a list of image formats that are supported for image output.
789 Note that if you want to iterate over the list, you should iterate over
791 a copy, e.g.
792 QStringList list = myImage.outputFormatList();
794 QStringList::Iterator it = list.begin();
795 while( it != list.end() ) {
796 myProcessing( *it );
797 ++it;
798 }
799 See also inputFormatList(), outputFormats(), and QImageIO.
801
803 Returns a list of image formats that are supported for image output.
804 See also inputFormats(), outputFormatList(), and QImageIO.
806 Example: showimg/showimg.cpp.
808
810 Returns the color of the pixel at the coordinates (x, y).
811 If (x, y) is not on the image, the results are undefined.
813 See also setPixel(), qRed(), qGreen(), qBlue(), and valid().
815 Examples:
817
819 Returns the pixel index at the given coordinates.
820 If (x, y) is not valid, or if the image is not a paletted image
822 (depth() > 8), the results are undefined.
823 See also valid() and depth().
825
827 Returns the enclosing rectangle (0, 0, width(), height()) of the image.
828 See also width(), height(), and size().
830
832 Resets all image parameters and deallocates the image data.
833
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 Returns TRUE if the image was successfully saved; otherwise returns
842 FALSE.
843 See also load(), loadFromData(), imageFormat(), QPixmap::save(), and
845 QImageIO.
846
848 ) const
849 This is an overloaded member function, provided for convenience. It
850 behaves essentially like the above function.
851 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 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
862 Returns a copy of the image scaled to a rectangle of width w and height
863 h according to the ScaleMode mode.
864 If mode is ScaleFree, the image is scaled to (w, h).
866 If mode is ScaleMin, the image is scaled to a rectangle as large as
868 possible inside (w, h), preserving the aspect ratio.
869 If mode is ScaleMax, the image is scaled to a rectangle as small as
871 possible outside (w, h), preserving the aspect ratio.
872 If either the width w or the height h is 0 or negative, this function
874 returns a null image.
875 This function uses a simple, fast algorithm. If you need better
877 quality, use smoothScale() instead.
878 See also scaleWidth(), scaleHeight(), smoothScale(), and xForm().
880
882 This is an overloaded member function, provided for convenience. It
883 behaves essentially like the above function.
884 The requested size of the image is s.
886
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 If h is 0 or negative a null image is returned.
893 See also scale(), scaleWidth(), smoothScale(), and xForm().
895 Example: table/small-table-demo/main.cpp.
897
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 If w is 0 or negative a null image is returned.
904 See also scale(), scaleHeight(), smoothScale(), and xForm().
906
908 Returns a pointer to the pixel data at the scanline with index i. The
909 first scanline is at index 0.
910 The scanline data is aligned on a 32-bit boundary.
912 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 Warning: If you are accessing 16-bpp image data, you must handle
921 endianness yourself. (Qt/Embedded only)
922 See also bytesPerLine(), bits(), and jumpTable().
924 Example: desktop/desktop.cpp.
926
928 Enables alpha buffer mode if enable is TRUE, otherwise disables it. The
929 default setting is disabled.
930 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 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 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 The alpha buffer is used to set a mask when a QImage is translated to a
944 QPixmap.
945 See also hasAlphaBuffer() and createAlphaMask().
947
949 Sets a color in the color table at index i to c.
950 A color value is an RGB triplet. Use the qRgb() function (defined in
952 qcolor.h) to make RGB triplets.
953 See also color(), setNumColors(), and numColors().
955 Examples:
957
959 Sets the value returned by dotsPerMeterX() to x.
960
962 Sets the value returned by dotsPerMeterY() to y.
963
965 Resizes the color table to numColors colors.
966 If the color table is expanded all the extra colors will be set to
968 black (RGB 0,0,0).
969 See also numColors(), color(), setColor(), and colorTable().
971
973 Sets the value returned by offset() to p.
974
976 Sets the pixel index or color at the coordinates (x, y) to
977 index_or_rgb.
978 If (x, y) is not valid, the result is undefined.
980 If the image is a paletted image (depth() <= 8) and index_or_rgb >=
982 numColors(), the result is undefined.
983 See also pixelIndex(), pixel(), qRgb(), qRgba(), and valid().
985
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
994 Returns the size of the image, i.e. its width and height.
995 See also width(), height(), and rect().
997
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 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 This function uses code based on pnmscale.c by Jef Poskanzer.
1014 pnmscale.c - read a portable anymap and scale it
1016 Copyright (C) 1989, 1991 by Jef Poskanzer.
1018 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 See also scale() and mirror().
1027
1029 const
1030 This is an overloaded member function, provided for convenience. It
1031 behaves essentially like the above function.
1032 The requested size of the image is s.
1034
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
1041 Determines the bit order of the display hardware. Returns
1042 QImage::LittleEndian (LSB first) or QImage::BigEndian (MSB first).
1043 See also systemByteOrder().
1045
1047 Determines the host computer byte order. Returns QImage::LittleEndian
1048 (LSB first) or QImage::BigEndian (MSB first).
1049 See also systemBitOrder().
1051
1053 Returns the string recorded for the keyword key in language lang, or in
1054 a default language if lang is 0.
1055
1057 This is an overloaded member function, provided for convenience. It
1058 behaves essentially like the above function.
1059 Returns the string recorded for the keyword and language kl.
1061
1063 Returns the keywords for which some texts are recorded.
1064 Note that if you want to iterate over the list, you should iterate over
1066 a copy, e.g.
1067 QStringList list = myImage.textKeys();
1069 QStringList::Iterator it = list.begin();
1070 while( it != list.end() ) {
1071 myProcessing( *it );
1072 ++it;
1073 }
1074 See also textList(), text(), setText(), and textLanguages().
1076
1078 Returns the language identifiers for which some texts are recorded.
1079 Note that if you want to iterate over the list, you should iterate over
1081 a copy, e.g.
1082 QStringList list = myImage.textLanguages();
1084 QStringList::Iterator it = list.begin();
1085 while( it != list.end() ) {
1086 myProcessing( *it );
1087 ++it;
1088 }
1089 See also textList(), text(), setText(), and textKeys().
1091
1093 Returns a list of QImageTextKeyLang objects that enumerate all the
1094 texts key/language pairs set by setText() for this image.
1095 Note that if you want to iterate over the list, you should iterate over
1097 a copy, e.g.
1098 QValueList<QImageTextKeyLang> list = myImage.textList();
1100 QValueList<QImageTextKeyLang>::Iterator it = list.begin();
1101 while( it != list.end() ) {
1102 myProcessing( *it );
1103 ++it;
1104 }
1105
1107 Returns TRUE if ( x, y ) is a valid coordinate in the image; otherwise
1108 returns FALSE.
1109 See also width(), height(), and pixelIndex().
1111 Examples:
1113
1115 Returns the width of the image.
1116 See also height(), size(), and rect().
1118 Examples:
1120
1122 Returns a copy of the image that is transformed using the
1123 transformation matrix, matrix.
1124 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 See also scale(), QPixmap::xForm(), QPixmap::trueMatrix(), and
1130 QWMatrix.
1131
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 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 The copying is clipped if areas outside src or dst are specified.
1143 If sw is -1, it is adjusted to src->width(). Similarly, if sh is -1, it
1145 is adjusted to src->height().
1146 Currently inefficient for non 32-bit images.
1148
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 Note that writing the stream to a file will not produce a valid image
1154 file.
1155 See also QImage::save() and Format of the QDataStream operators.
1157
1159 Reads an image from the stream s and stores it in image.
1160 See also QImage::load() and Format of the QDataStream operators.
1162
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
1174 Generated automatically from the source code.
1175
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 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 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).
1190Trolltech AS 2 February 2007 QImage(3qt)