qimage.3qt

linux下GUI编程工具qt的在线连接帮助手册

    else
.br
        *(image.scanLine(y) + (x >> 3)) |= 1 << (7 -(x & 7));
.br
.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;
.br
.fi
.PP
32-bpp images ignore the color table; instead, each pixel contains the RGB triplet. 24 bits contain the RGB value; 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);
.br
.fi
.PP
On Qt/Embedded, scanlines are aligned to the pixel depth and may be padded to any degree, while on all other platforms, the scanlines are 32-bit aligned for all depths. The constructor taking a
.PP
.nf
.br
 uchar*
.fi
argument always expects 32-bit aligned data. On Qt/Embedded, an additional constructor allows the number of byte-per-line to be specified.
.PP
QImage supports a variety of methods for getting information about the image, for example, colorTable(), allGray(), isGrayscale(), bitOrder(), bytesPerLine(), depth(), dotsPerMeterX() and dotsPerMeterY(), hasAlphaBuffer(), numBytes(), numColors(), and width() and height().
.PP
Pixel colors are retrieved with pixel() and set with setPixel().
.PP
QImage also supports a number of functions for creating a new image that is a transformed version of the original. For example, copy(), convertBitOrder(), convertDepth(), createAlphaMask(), createHeuristicMask(), mirror(), scale(), smoothScale(), swapRGB() and xForm(). There are also functions for changing attributes of an image in-place, for example, setAlphaBuffer(), setColor(), setDotsPerMeterX() and setDotsPerMeterY() and setNumColors().
.PP
Images can be loaded and saved in the supported formats. Images are saved to a file with save(). Images are loaded from a file with load() (or in the constructor) or from an array of data with loadFromData(). The lists of supported formats are available from inputFormatList() and outputFormatList().
.PP
Strings of text may be added to images using setText().
.PP
The QImage class uses explicit sharing, similar to that used by QMemArray.
.PP
New image formats can be added as plugins.
.PP
See also QImageIO, QPixmap, Shared Classes, Graphics Classes, Image Processing Classes and Implicitly and Explicitly Shared Classes.
.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
\fCQImage::IgnoreEndian\fR - Endianness does not matter. Useful for some operations that are independent of endianness.
.TP
\fCQImage::BigEndian\fR - Network byte order, as on SPARC and Motorola CPUs.
.TP
\fCQImage::LittleEndian\fR - PC/Alpha byte order.
.SH "QImage::ScaleMode"
The functions scale() and smoothScale() use different modes for scaling the image. The purpose of these modes is to retain the ratio of the image if this is required.
.TP
\fCQImage::ScaleFree\fR - The image is scaled freely: the resulting image fits exactly into the specified size; the ratio will not necessarily be preserved.
.TP
\fCQImage::ScaleMin\fR - The ratio of the image is preserved and the resulting image is guaranteed to fit into the specified size (it is as large as possible within these constraints) - the image might be smaller than the requested size.
.TP
\fCQImage::ScaleMax\fR - The ratio of the image is preserved and the resulting image fills the whole specified rectangle (it is as small as possible within these constraints) - the image might be larger than the requested size.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QImage::QImage ()"
Constructs a null image.
.PP
See also isNull().
.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 ( 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.
.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 ( const QString & fileName, const char * format = 0 )"
Constructs an image and tries to load it image from the file \fIfileName\fR.
.PP
If \fIformat\fR is specified, the loader attempts to read the image using the specified format. If \fIformat\fR is not specified (which is the default), the loader reads a few bytes from the header to guess the file format.
.PP
If the loading of the image failed, this object is a null image.
.PP
The QImageIO documentation lists the supported image formats and explains how to add extra formats.
.PP
See also load(), isNull() and QImageIO.
.SH "QImage::QImage ( const char * const 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
    ....
.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.
.SH "QImage::QImage ( const QByteArray & array )"
Constructs an image from the binary data \fIarray\fR. It tries to guess the file format.
.PP
If the loading of the image failed, this object is a null image.
.PP
See also loadFromData(), isNull() and imageFormat().
.SH "QImage::QImage ( uchar * yourdata, int w, int h, int depth, QRgb * colortable, int numColors, Endian bitOrder )"
Constructs an image \fIw\fR pixels wide, \fIh\fR pixels high with a color depth of \fIdepth\fR, that uses an existing memory buffer, \fIyourdata\fR. The buffer must remain valid throughout the life of the QImage. The image does not delete the buffer at destruction.
.PP
If \fIcolortable\fR is 0, a color table sufficient for \fInumColors\fR will be allocated (and destructed later).
.PP
Note that \fIyourdata\fR must be 32-bit aligned.
.PP
The endianness is given in \fIbitOrder\fR.
.SH "QImage::QImage ( const QImage & image )"
Constructs a shallow copy of \fIimage\fR.
.SH "QImage::~QImage ()"
Destroys the image and cleans up.
.SH "bool QImage::allGray () const"
Returns TRUE if all the colors in the image are shades of gray (i.e., their red, green and blue components are equal).
.PP
This function is slow for large 16-bit and 32-bit images.
.PP
See also isGrayscale().
.SH "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. This is equivalent to scanLine(0).
.PP
See also numBytes(), scanLine() and jumpTable().
.PP
Example: opengl/texture/gltexobj.cpp.
.SH "int QImage::bytesPerLine () const"
Returns the number of bytes per image scanline. This is equivalent to numBytes()/height().
.PP
See also numBytes() and scanLine().
.SH "QRgb QImage::color ( int i ) const"
Returns the color in the color table at index \fIi\fR. The first color is at index 0.
.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(), numColors() and QColor.
.PP
Example: themes/wood.cpp.
.SH "QRgb * QImage::colorTable () const"
Returns a pointer to the color table.
.PP
See also numColors().
.SH "QImage QImage::convertBitOrder ( Endian bitOrder ) const"
Converts the bit order of the image to \fIbitOrder\fR and returns the converted image. The original image is not changed.
.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(), systemBitOrder() and isNull().
.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 not changed.
.PP
The \fIdepth\fR argument must be 1, 8, 16 or 32.
.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
If the image needs to be modified to fit in a lower-resolution result (eg. converting from 32-bit to 8-bit), use the \fIconversion_flags\fR to specify how you'd prefer this to happen.
.PP
See also Qt::ImageConversionFlags, depth() and isNull().
.SH "QImage QImage::convertDepth ( int depth ) const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.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 because it may change in future implementations.
.PP
Currently inefficient for non-32-bit images.
.PP
Returns an image with depth \fId\fR, using the \fIpalette_count\fR colors pointed to by \fIpalette\fR. If \fId\fR is 1 or 8, the returned image will have its color table ordered the same as \fIpalette\fR.
.PP
If the image needs to be modified to fit in a lower-resolution result (eg. converting from 32-bit to 8-bit), use the \fIconversion_flags\fR to specify how you'd prefer this to happen.
.PP
See also Qt::ImageConversionFlags.
.SH "QImage QImage::copy () const"
Returns a deep copy of the image.
.PP
See also detach().
.SH "QImage QImage::copy ( int x, int y, int w, int h, int conversion_flags = 0 ) const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns a deep copy of a sub-area of the image.
.PP
The returned image is always \fIw\fR by \fIh\fR pixels in size, and is copied from position \fIx\fR, \fIy\fR in this image. In areas beyond this image pixels are filled with pixel 0.
.PP
If the image needs to be modified to fit in a lower-resolution result (eg. converting from 32-bit to 8-bit), use the \fIconversion_flags\fR to specify how you'd prefer this to happen.
.PP
See also bitBlt() and Qt::ImageConversionFlags.
.SH "QImage QImage::copy ( const QRect & r ) const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns a deep copy of a sub-area of the image.
.PP
The returned image has always the size of the rectangle \fIr\fR. In areas beyond this image pixels are filled with pixel 0.
.SH "bool QImage::create ( int width, int height, int depth, int numColors = 0, Endian bitOrder = IgnoreEndian )"
Sets the image \fIwidth\fR, \fIheight\fR, \fIdepth\fR, its number of colors (in \fInumColors\fR), 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, \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 fill(), 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 behaves essentially like the above function.
.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().
.PP
See also createHeuristicMask(), hasAlphaBuffer() and setAlphaBuffer().
.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 for 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 result is arbitrary.
.PP
The returned image has little-endian bit order, which you can convert to big-endianness using convertBitOrder().
.PP
If \fIclipTight\fR is TRUE the mask is just large enough to cover the pixels; otherwise, the mask is larger than the data pixels.
.PP
This function disregards the alpha buffer.
.PP
See also createAlphaMask().
.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.
.PP
See also convertDepth().
.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.
.PP
See also copy().
.PP
Example: themes/wood.cpp.
.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.
.PP
See also invertPixels(), depth(), hasAlphaBuffer() and create().
.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().
.PP
Example: opengl/texture/gltexobj.cpp.
.SH "const char * QImage::imageFormat ( const QString & fileName )\fC [static]\fR"
Returns a string that specifies the image format of the file \fIfileName\fR, or null if the file cannot be read or if the format is not recognized.
.PP
The QImageIO documentation lists the guaranteed supported image formats, or use QImage::inputFormats() and QImage::outputFormats() to get lists that include the installed formats.
.PP
See also load() and save().
.SH "QStringList QImage::inputFormatList ()\fC [static]\fR"
Returns a list of image formats that are supported for image input.
.PP
See also outputFormatList(), inputFormats() and QImageIO.
.PP
Example: showimg/showimg.cpp.