qimage.3qt

Trolltech公司发布的基于C++图形开发环境

.ti -1c
.BI "QStringList \fBinputFormatList\fR () "
.br
.ti -1c
.BI "QStringList \fBoutputFormatList\fR () "
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
(Note that these are not member functions.)
.in +1c
.ti -1c
.BI "QDataStream & \fBoperator<<\fR (QDataStream & " "s" ", const QImage & " "image" ")"
.br
.ti -1c
.BI "QDataStream & \fBoperator>>\fR (QDataStream & " "s" ", QImage & " "image" ")"
.br
.in -1c
.SH DESCRIPTION
The QImage class provides a hardware-independent pixmap representation with direct access to the pixel data.
.PP
It is one of the two classes Qt provides for dealing with images, the other being QPixmap. QImage is designed and optimized for I/O and for direct pixel access/manipulation, QPixmap is designed and optimized for drawing. There are (slow) functions to convert between QImage and QPixmap; QPixmap::convertToImage() and QPixmap::convertFromImage().
.PP
An image has the parameters width, height and depth (bits per pixel, bpp), a color table and the actual pixels. QImage supports 1-bpp, 8-bpp and 32-bpp image data. 1-bpp and 8-bpp images use a color lookup table; the pixel value is a color table index.
.PP
32-bpp images encode an RGB value in 24 bits and ignore the color table. The most significant byte is used for the alpha buffer.
.PP
An entry in the color table is an RGB triplet encoded as \fCuint.\fR Use the qRed, qGreen and qBlue functions (qcolor.h) to access the components, and qRgb to make an RGB triplet (see the QColor class documentation).
.PP
1-bpp (monochrome) images have a color table with maximum 2 colors. There are two different formats; big endian (MSB first) or little endian (LSB first) bit order. To access a single bit, you will have to do some bitshifts:
.PP
.nf
.br
    QImage image;
.br
      // sets bit at (x,y) to 1
.br
    if ( image.bitOrder() == QImage::LittleEndian )
.br
        *(image.scanLine(y) + (x >> 3)) |= 1 << (x & 7);
.br
    else
.br
        *(image.scanLine(y) + (x >> 3)) |= 1 << (7 -(x & 7));
.fi
.PP
If this looks complicated, it might be a good idea to convert the 1-bpp image to an 8-bpp image using convertDepth().
.PP
8-bpp images are much easier to work with than 1-bpp images because they have a single byte per pixel:
.PP
.nf
.br
    QImage image;
.br
      // set entry 19 in the color table to yellow
.br
    image.setColor( 19, qRgb(255,255,0) );
.br
      // set 8 bit pixel at (x,y) to value yellow (in color table)
.br
    *(image.scanLine(y) + x) = 19;
.fi
.PP
32-bpp images ignore the color table, instead each pixel contains the RGB triplet. 24 bits contain the RGB value and the most significant byte is reserved for the alpha buffer.
.PP
.nf
.br
    QImage image;
.br
      // sets 32 bit pixel at (x,y) to yellow.
.br
    uint *p = (uint *)image.scanLine(y) + x;
.br
    *p = qRgb(255,255,0);
.fi
.PP
The scanlines are 32-bit aligned for all depths.
.PP
The QImage class uses explicit sharing, similar to that of QArray.
.PP
See also QImageIO, QPixmap and Shared Classes
.PP
Examples:
.(l
qtimage/qtimage.cpp qmag/qmag.cpp desktop/desktop.cpp
.)l
.SS "Member Type Documentation"
.SH "QImage::Endian"
This enum type is used to describe the endianness of the CPU and graphics hardware.
.PP
The current values are: 
.TP
\fCIgnoreEndian\fR - does not matter. Useful for some operations that are independent of endianness
.TP
\fCBigEndian\fR - network byte order, like on SPARC and Motorola CPUs.
.TP
\fCLittleEndian\fR - PC/Alpha byte order.
.IP
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QImage::QImage ()"
Constructs a null image.
.PP
See also isNull().
.SH "QImage::QImage ( const QByteArray & array )"
Constructs an image from \fIarray,\fR which must be in a supported image format image.
.PP
See also loadFromData().
.SH "QImage::QImage ( const QSize & size, int depth, int numColors=0, Endian bitOrder=IgnoreEndian )"
Constructs an image with size \fIsize\fR pixels, depth \fIdepth\fR bits, \fInumColors\fR and \fIbitOrder\fR endianness.
.SH "QImage::QImage ( const QString & fileName, const char * format=0 )"
Constructs an image from loading \fIfileName\fR and an optional \fIformat.\fR
.PP
See also load().
.SH "QImage::QImage ( const QImage & image )"
Constructs a shallow copy of \fIimage.\fR
.SH "QImage::QImage ( const char * xpm[] )"
Constructs an image from \fIxpm,\fR which must be a valid XPM image.
.PP
Errors are silently ignored.
.PP
Note that it's possible to squeeze the XPM variable a little bit by using an unusual declaration:
.PP
.nf
.br
    static const char * const start_xpm[]={
.br
        "16 15 8 1",
.br
        "a c #cec6bd",
.br
    ....
.fi
.PP
The extra \fCconst\fR makes the entire definition read-only, which is slightly more efficient e.g. when the code is in a shared library, and ROMable when the application is to be stored in ROM.
.PP
In order to use that sort of declaration, you must cast the variable back to <nobr>\fCconst char **\fR</nobr> when you create the QImage.
.SH "QImage::QImage ( int w, int h, int depth, int numColors=0, Endian bitOrder=IgnoreEndian )"
Constructs an image with \fIw\fR width, \fIh\fR height, \fIdepth\fR bits per pixel, \fInumColors\fR colors and bit order \fIbitOrder.\fR
.PP
Using this constructor is the same as first constructing a null image and then calling the create() function.
.PP
See also create().
.SH "QImage::QImage ( uchar * yourdata, int w, int h, int depth, QRgb * colortable, int numColors, Endian bitOrder )"
Constructs an image that uses an existing memory buffer. The buffer must remain valid for the life of the QImage. The image will not delete the buffer at destruction.
.PP
If colortable is 0, a color table sufficient for \fInumColors\fR will be allocated (and destructed later).
.SH "QImage::~QImage ()"
Destructs the image and cleans up.
.SH "bool QImage::allGray () const"
Returns TRUE if all the colors in the image are shades of gray, that is their R, G, and B components are equal. This function is slow for large 16-bit and 32-bit images.
.SH "QImage::Endian QImage::bitOrder() const"
Returns the bit order for the image.
.PP
If it is a 1-bpp image, this function returns either QImage::BigEndian or QImage::LittleEndian.
.PP
If it is not a 1-bpp image, this function returns QImage::IgnoreEndian.
.PP
See also depth().
.SH "uchar * QImage::bits () const"
Returns a pointer to the first pixel data. Equivalent to scanLine(0).
.PP
See also scanLine().
.SH "int QImage::bytesPerLine () const"
Returns the number of bytes per image scanline. This is equivalent to numBytes()/height().
.SH "QRgb QImage::color ( int i ) const"
Returns the color in the color table at index \fIi.\fR
.PP
A color value is an RGB triplet. Use the qRed(), qGreen() and qBlue() functions (defined in qcolor.h) to get the color value components.
.PP
See also setColor() and QColor.
.SH "QRgb * QImage::colorTable () const"
Returns a pointer to the color table.
.SH "QImage QImage::convertBitOrder ( Endian bitOrder ) const"
Converts the bit order of the image to \fIbitOrder\fR and returns the converted image.
.PP
Returns \fC*this\fR if the \fIbitOrder\fR is equal to the image bit order, or a null image if this image cannot be converted.
.PP
See also bitOrder() and systemBitOrder().
.SH "QImage QImage::convertDepth ( int depth, int conversion_flags ) const"
Converts the depth (bpp) of the image to \fIdepth\fR and returns the converted image. The original image is left undisturbed.
.PP
The \fIdepth\fR argument must be 1, 8, 16 or 32.
.PP
See QPixmap::convertFromImage for a description of the \fIconversion_flags\fR argument.
.PP
Returns \fC*this\fR if \fIdepth\fR is equal to the image depth, or a null image if this image cannot be converted.
.PP
See also depth() and isNull().
.SH "QImage QImage::convertDepth ( int depth ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QImage QImage::convertDepthWithPalette ( int d, QRgb * palette, int palette_count, int conversion_flags=0 ) const"
Note: currently no closest-color search is made. If colors are found that are not in the palette, the palette may not be used at all. This result should not be considered valid, as it may change in future implementations.
.PP
Currently inefficient for non 32-bit images.
.SH "QImage QImage::copy () const"
Returns a deep copy of the image.
.SH "QImage QImage::copy ( int x, int y, int w, int h, int conversion_flags=0 ) const"
Returns a deep copy of a sub-area of the image.
.PP
The returned image is always \fIw\fR by \fIh\fR pixels is size. If the area is beyond this image, the pixels are filled with pixel 0.
.PP
See also bitBlt().
.SH "QImage QImage::copy ( const QRect & r ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "bool QImage::create ( int width, int height, int depth, int numColors=0, Endian bitOrder=IgnoreEndian )"
Sets the image width, height, depth, number of colors and bit order. Returns TRUE if successful, or FALSE if the parameters are incorrect or if memory cannot be allocated.
.PP
The \fIwidth\fR and \fIheight\fR is limited to 32767. \fIdepth\fR must be 1, 8 or 32. If \fIdepth\fR is 1, then \fIbitOrder\fR must be set to either QImage::LittleEndian or QImage::BigEndian. For other depths, \fIbitOrder\fR must be QImage::IgnoreEndian.
.PP
This function allocates a color table and a buffer for the image data. The image data is not initialized.
.PP
The image buffer is allocated as a single block that consists of a table of scanline pointers (jumpTable()) and the image data (bits()).
.PP
See also width(), height(), depth(), numColors(), bitOrder(), jumpTable(), scanLine(), bits(), bytesPerLine() and numBytes().
.SH "bool QImage::create ( const QSize &, int depth, int numColors=0, Endian bitOrder=IgnoreEndian )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QImage QImage::createAlphaMask ( int conversion_flags=0 ) const"
Builds and returns a 1-bpp mask from the alpha buffer in this image. Returns a null image if alpha buffer mode is disabled.
.PP
See QPixmap::convertFromImage for a description of the \fIconversion_flags\fR argument.
.PP
The returned image has little-endian bit order, which you can convert to big-endianness using convertBitOrder().
.SH "QImage QImage::createHeuristicMask ( bool clipTight=TRUE ) const"
Creates and returns a 1-bpp heuristic mask for this image. It works by selecting a color from one of the corners, then chipping away pixels of that color, starting at all the edges.
.PP
The four corners vote over which color is to be masked away. In case of a draw (this generally means that this function is not applicable to the image) the voting results are undocumented.
.PP
The returned image has little-endian bit order, which you can convert to big-endianness using convertBitOrder().
.PP
This function disregards the alpha buffer.
.SH "int QImage::depth () const"
Returns the depth of the image.
.PP
The image depth is the number of bits used to encode a single pixel, also called bits per pixel (bpp) or bit planes of an image.
.PP
The supported depths are 1, 8, 16 and 32.
.SH "void QImage::detach ()"
Detaches from shared image data and makes sure that this image is the only one referring the data.
.PP
If multiple images share common data, this image makes a copy of the data and detaches itself from the sharing mechanism. Nothing is done if there is just a single reference.
.SH "int QImage::dotsPerMeterX () const"
Returns the number of pixels that fit horizontally in a physical meter. This and dotsPerMeterY() define the intended scale and aspect ratio of the image.
.PP
See also setDotsPerMeterX().
.SH "int QImage::dotsPerMeterY () const"
Returns the number of pixels that fit vertically in a physical meter. This and dotsPerMeterX() define the intended scale and aspect ratio of the image.
.PP
See also setDotsPerMeterY().
.SH "void QImage::fill ( uint pixel )"
Fills the entire image with the pixel value \fIpixel.\fR
.PP
If the depth of this image is 1, only the lowest bit is used. If you say fill(0), fill(2) etc., the image is filled with 0s. If you say fill(1), fill(3) etc., the image is filled with 1s. If the depth is 8, the lowest 8 bits are used.
.PP
If the depth is 32 and the image has no alpha buffer, the \fIpixel\fR value is written to each pixel in the image. If the image has an alpha buffer, only the 24 RGB bits are set and the upper 8 bits (alpha value) are left unchanged.
.SH "bool QImage::hasAlphaBuffer () const"
Returns TRUE if alpha buffer mode is enabled, otherwise FALSE.
.PP
See also setAlphaBuffer().
.SH "int QImage::height () const"
Returns the height of the image.
.PP
See also width(), size() and rect().
.SH "const char* QImage::imageFormat ( const QString & fileName ) \fC[static]\fR"