X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/90fbb09ae248c93b0cf62eb7cf4ecfd94f88023f..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/image.h diff --git a/interface/wx/image.h b/interface/wx/image.h index 77c7321e9d..9ae1bb0a06 100644 --- a/interface/wx/image.h +++ b/interface/wx/image.h @@ -2,8 +2,7 @@ // Name: image.h // Purpose: interface of wxImageHandler and wxImage // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -39,10 +38,25 @@ enum wxImageResizeQuality /// Highest quality but slowest execution time. wxIMAGE_QUALITY_BICUBIC, - /// Default image resizing algorithm used by wxImage::Scale(). + /** + Use surrounding pixels to calculate an average that will be used for + new pixels. This method is typically used when reducing the size of + an image. + */ + wxIMAGE_QUALITY_BOX_AVERAGE, + + /** + Default image resizing algorithm used by wxImage::Scale(). Currently + the same as wxIMAGE_QUALITY_NEAREST. + */ wxIMAGE_QUALITY_NORMAL, - /// Best image resizing algorithm, currently same as wxIMAGE_QUALITY_BICUBIC. + /** + Best image resizing algorithm. Since version 2.9.2 this results in + wxIMAGE_QUALITY_BOX_AVERAGE being used when reducing the size of the + image (meaning that both the new width and height will be smaller than + the original size). Otherwise wxIMAGE_QUALITY_BICUBIC is used. + */ wxIMAGE_QUALITY_HIGH }; @@ -55,9 +69,61 @@ enum wxImagePNGType { wxPNG_TYPE_COLOUR = 0, ///< Colour PNG image. wxPNG_TYPE_GREY = 2, ///< Greyscale PNG image converted from RGB. - wxPNG_TYPE_GREY_RED = 3 ///< Greyscale PNG image using red as grey. + wxPNG_TYPE_GREY_RED = 3, ///< Greyscale PNG image using red as grey. + wxPNG_TYPE_PALETTE = 4 ///< Palette encoding. }; + +/** + Image option names. +*/ +#define wxIMAGE_OPTION_QUALITY wxString("quality") +#define wxIMAGE_OPTION_FILENAME wxString("FileName") +#define wxIMAGE_OPTION_RESOLUTION wxString("Resolution") +#define wxIMAGE_OPTION_RESOLUTIONX wxString("ResolutionX") +#define wxIMAGE_OPTION_RESOLUTIONY wxString("ResolutionY") +#define wxIMAGE_OPTION_RESOLUTIONUNIT wxString("ResolutionUnit") +#define wxIMAGE_OPTION_MAX_WIDTH wxString("MaxWidth") +#define wxIMAGE_OPTION_MAX_HEIGHT wxString("MaxHeight") +#define wxIMAGE_OPTION_ORIGINAL_WIDTH wxString("OriginalWidth") +#define wxIMAGE_OPTION_ORIGINAL_HEIGHT wxString("OriginalHeight") + +#define wxIMAGE_OPTION_BMP_FORMAT wxString("wxBMP_FORMAT") +#define wxIMAGE_OPTION_CUR_HOTSPOT_X wxString("HotSpotX") +#define wxIMAGE_OPTION_CUR_HOTSPOT_Y wxString("HotSpotY") + +#define wxIMAGE_OPTION_GIF_COMMENT wxString("GifComment") + +#define wxIMAGE_OPTION_PNG_FORMAT wxString("PngFormat") +#define wxIMAGE_OPTION_PNG_BITDEPTH wxString("PngBitDepth") +#define wxIMAGE_OPTION_PNG_FILTER wxString("PngF") +#define wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL wxString("PngZL") +#define wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL wxString("PngZM") +#define wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY wxString("PngZS") +#define wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE wxString("PngZB") + +#define wxIMAGE_OPTION_TIFF_BITSPERSAMPLE wxString("BitsPerSample") +#define wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL wxString("SamplesPerPixel") +#define wxIMAGE_OPTION_TIFF_COMPRESSION wxString("Compression") +#define wxIMAGE_OPTION_TIFF_PHOTOMETRIC wxString("Photometric") +#define wxIMAGE_OPTION_TIFF_IMAGEDESCRIPTOR wxString("ImageDescriptor") + + +enum +{ + wxBMP_24BPP = 24, // default, do not need to set + //wxBMP_16BPP = 16, // wxQuantize can only do 236 colors? + wxBMP_8BPP = 8, // 8bpp, quantized colors + wxBMP_8BPP_GREY = 9, // 8bpp, rgb averaged to greys + wxBMP_8BPP_GRAY = wxBMP_8BPP_GREY, + wxBMP_8BPP_RED = 10, // 8bpp, red used as greyscale + wxBMP_8BPP_PALETTE = 11, // 8bpp, use the wxImage's palette + wxBMP_4BPP = 4, // 4bpp, quantized colors + wxBMP_1BPP = 1, // 1bpp, quantized "colors" + wxBMP_1BPP_BW = 2 // 1bpp, black & white from red +}; + + /** @class wxImageHandler @@ -254,6 +320,38 @@ public: Handler name. */ void SetName(const wxString& name); + + /** + Retrieve the version information about the image library used by this + handler. + + This method is not present in wxImageHandler class itself but is + present in a few of the classes deriving from it, currently + wxJPEGHandler, wxPNGHandler and wxTIFFHandler. It returns the + information about the version of the image library being used for the + corresponding handler implementation. + + @since 2.9.2 + */ + static wxVersionInfo GetLibraryVersionInfo(); + +protected: + /** + Called to get the number of images available in a multi-image file + type, if supported. + + NOTE: this function is allowed to change the current stream position + since GetImageCount() will take care of restoring it later + */ + virtual int DoGetImageCount( wxInputStream& stream ); + + /** + Called to test if this handler can read an image from the given stream. + + NOTE: this function is allowed to change the current stream position + since CallDoCanRead() will take care of restoring it later + */ + virtual bool DoCanRead( wxInputStream& stream ) = 0; }; @@ -269,6 +367,9 @@ const unsigned char wxIMAGE_ALPHA_TRANSPARENT = 0; */ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; +const unsigned char wxIMAGE_ALPHA_THRESHOLD = 0x80; + + /** @class wxImage @@ -284,6 +385,17 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; the wxBitmap::wxBitmap(wxImage,int depth) constructor. This bitmap can then be drawn in a device context, using wxDC::DrawBitmap. + More on the difference between wxImage and wxBitmap: wxImage is just a + buffer of RGB bytes with an optional buffer for the alpha bytes. It is all + generic, platform independent and image file format independent code. It + includes generic code for scaling, resizing, clipping, and other manipulations + of the image data. OTOH, wxBitmap is intended to be a wrapper of whatever is + the native image format that is quickest/easiest to draw to a DC or to be the + target of the drawing operations performed on a wxMemoryDC. By splitting the + responsibilities between wxImage/wxBitmap like this then it's easier to use + generic code shared by all platforms and image types for generic operations and + platform specific code where performance or compatibility is needed. + One colour value of the image may be used as a mask colour which will lead to the automatic creation of a wxMask object associated to the bitmap object. @@ -301,10 +413,12 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; While all images have RGB data, not all images have an alpha channel. Before using wxImage::GetAlpha you should check if this image contains an alpha - channel with wxImage::HasAlpha. Note that currently only the PNG format has - full alpha channel support so only the images loaded from PNG files can have - alpha and, if you initialize the image alpha channel yourself using - wxImage::SetAlpha, you should save it in PNG format to avoid losing it. + channel with wxImage::HasAlpha. Currently the BMP, PNG, TGA, and TIFF format + handlers have full alpha channel support for loading so if you want to use + alpha you have to use one of these formats. If you initialize the image + alpha channel yourself using wxImage::SetAlpha, you should save it in + either PNG, TGA, or TIFF format to avoid losing it as these are the only + handlers that currently support saving with alpha. @section image_handlers Available image handlers @@ -314,14 +428,14 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; To use other image formats, install the appropriate handler with wxImage::AddHandler or call ::wxInitAllImageHandlers(). - - wxBMPHandler: For loading and saving, always installed. - - wxPNGHandler: For loading (including alpha support) and saving. + - wxBMPHandler: For loading (including alpha support) and saving, always installed. + - wxPNGHandler: For loading and saving. Includes alpha support. - wxJPEGHandler: For loading and saving. - - wxGIFHandler: Only for loading, due to legal issues. + - wxGIFHandler: For loading and saving (see below). - wxPCXHandler: For loading and saving (see below). - wxPNMHandler: For loading and saving (see below). - - wxTIFFHandler: For loading and saving. - - wxTGAHandler: For loading only. + - wxTIFFHandler: For loading and saving. Includes alpha support. + - wxTGAHandler: For loading and saving. Includes alpha support. - wxIFFHandler: For loading only. - wxXPMHandler: For loading and saving. - wxICOHandler: For loading and saving. @@ -335,6 +449,8 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; Loading PNMs only works for ASCII or raw RGB images. When saving in PNM format, wxPNMHandler will always save as raw RGB. + Saving GIFs requires images of maximum 8 bpp (see wxQuantize), and the alpha channel converted to a mask (see wxImage::ConvertAlphaToMask). + Saving an animated GIF requires images of the same size (see wxGIFHandler::SaveAnimation) @library{wxcore} @category{gdi} @@ -362,6 +478,10 @@ public: between HSV color space and RGB color space. */ RGBValue(unsigned char r=0, unsigned char g=0, unsigned char b=0); + + unsigned char red; + unsigned char green; + unsigned char blue; }; /** @@ -378,6 +498,10 @@ public: between HSV color space and RGB color space. */ HSVValue(double h=0.0, double s=0.0, double v=0.0); + + double hue; + double saturation; + double value; }; /** @@ -449,7 +573,7 @@ public: /** @overload */ - wxImage(const wxSize& sz, unsigned char* data, unsigned char* data, unsigned char* alpha, + wxImage(const wxSize& sz, unsigned char* data, unsigned char* alpha, bool static_data = false); /** @@ -477,7 +601,7 @@ public: @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TIFF: Load a TIFF bitmap file. @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). @@ -728,6 +852,13 @@ public: */ wxImage Rotate90(bool clockwise = true) const; + /** + Returns a copy of the image rotated by 180 degrees. + + @since 2.9.2 + */ + wxImage Rotate180() const; + /** Rotates the hue of each pixel in the image by @e angle, which is a double in the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 @@ -815,7 +946,7 @@ public: FindFirstUnusedColour() by this function, see the overload below if you this is not appropriate. - @return @false if FindFirstUnusedColour returns @false, @true otherwise. + @return Returns @true on success, @false on error. */ bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD); @@ -841,8 +972,9 @@ public: are set. Pixels with the alpha values above the threshold are considered to be opaque. + @return Returns @true on success, @false on error. */ - void ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb, + bool ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb, unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD); /** @@ -962,7 +1094,7 @@ public: This is most often used when doing direct image manipulation. The return value points to an array of characters in RGBRGBRGB... format in the top-to-bottom, left-to-right order, that is the first RGB triplet - corresponds to the pixel first pixel of the first row, the second one --- + corresponds to the first pixel of the first row, the second one --- to the second pixel of the first row and so on until the end of the first row, with second row following after it and so on. @@ -1031,10 +1163,16 @@ public: /** Gets a user-defined string-valued option. - Currently the only defined string option is + Generic options: @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image was loaded. + Options specific to wxGIFHandler: + @li @c wxIMAGE_OPTION_GIF_COMMENT: The comment text that is read from + or written to the GIF file. In an animated GIF each frame can have + its own comment. If there is only a comment in the first frame of + a GIF it will not be repeated in other frames. + @param name The name of the option, case-insensitive. @return @@ -1050,7 +1188,7 @@ public: The function is case-insensitive to @a name. If the given option is not present, the function returns 0. - Use HasOption() is 0 is a possibly valid value for the option. + Use HasOption() if 0 is a possibly valid value for the option. Generic options: @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either @@ -1066,6 +1204,12 @@ public: handler, this is still what happens however). These options must be set before calling LoadFile() to have any effect. + @li @c wxIMAGE_OPTION_ORIGINAL_WIDTH and @c wxIMAGE_OPTION_ORIGINAL_HEIGHT: + These options will return the original size of the image if either + @c wxIMAGE_OPTION_MAX_WIDTH or @c wxIMAGE_OPTION_MAX_HEIGHT is + specified. + @since 2.9.3 + @li @c wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an integer in 0..100 range with 0 meaning very poor and 100 excellent (but very badly compressed). This option is currently ignored for @@ -1109,6 +1253,39 @@ public: the resulting PNG file. Use this option if your application produces images with small size variation. + Options specific to wxTIFFHandler: + @li @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE: Number of bits per + sample (channel). Currently values of 1 and 8 are supported. A + value of 1 results in a black and white image. A value of 8 (the + default) can mean greyscale or RGB, depending on the value of + @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL. + @li @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL: Number of samples + (channels) per pixel. Currently values of 1 and 3 are supported. + A value of 1 results in either a greyscale (by default) or black and + white image, depending on the value of + @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE. A value of 3 (the default) + will result in an RGB image. + @li @c wxIMAGE_OPTION_TIFF_COMPRESSION: Compression type. By default + it is set to 1 (COMPRESSION_NONE). Typical other values are + 5 (COMPRESSION_LZW) and 7 (COMPRESSION_JPEG). See tiff.h for more + options. + @li @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC: Specifies the photometric + interpretation. By default it is set to 2 (PHOTOMETRIC_RGB) for RGB + images and 0 (PHOTOMETRIC_MINISWHITE) for greyscale or black and + white images. It can also be set to 1 (PHOTOMETRIC_MINISBLACK) to + treat the lowest value as black and highest as white. + If you want a greyscale image it is also sufficient to only specify + @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC and set it to either + PHOTOMETRIC_MINISWHITE or PHOTOMETRIC_MINISBLACK. The other values + are taken care of. + + @note + Be careful when combining the options @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL, + @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE, and @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC. + While some measures are taken to prevent illegal combinations and/or + values, it is still easy to abuse them and come up with invalid + results in the form of either corrupted images or crashes. + @param name The name of the option, case-insensitive. @return @@ -1178,7 +1355,7 @@ public: bool IsOk() const; /** - Returns @true if the given pixel is transparent, i.e. either has the mask + Returns @true if the given pixel is transparent, i.e.\ either has the mask colour if this image has a mask or if this image has alpha channel and alpha value of this pixel is strictly less than @a threshold. */ @@ -1207,7 +1384,7 @@ public: @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TIFF: Load a TIFF bitmap file. @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). @@ -1534,7 +1711,19 @@ public: /** Register an image handler. - See @ref image_handlers for a list of the available handlers. + + Typical example of use: + @code + wxImage::AddHandler(new wxPNGHandler); + @endcode + + See @ref image_handlers for a list of the available handlers. You can + also use ::wxInitAllImageHandlers() to add handlers for all the image + formats supported by wxWidgets at once. + + @param handler + A heap-allocated handler object which will be deleted by wxImage + if it is removed later by RemoveHandler() or at program shutdown. */ static void AddHandler(wxImageHandler* handler); @@ -1626,7 +1815,8 @@ public: /** Finds the handler with the given name, and removes it. - The handler is not deleted. + + The handler is also deleted. @param name The handler name. @@ -1676,7 +1866,7 @@ public: @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TIFF: Load a TIFF bitmap file. @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). @@ -1724,6 +1914,30 @@ public: static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv); }; + +class wxImageHistogram : public wxImageHistogramBase +{ +public: + wxImageHistogram(); + + // get the key in the histogram for the given RGB values + static unsigned long MakeKey(unsigned char r, + unsigned char g, + unsigned char b); + + // find first colour that is not used in the image and has higher + // RGB values than RGB(startR, startG, startB) + // + // returns true and puts this colour in r, g, b (each of which may be NULL) + // on success or returns false if there are no more free colours + bool FindFirstUnusedColour(unsigned char *r, + unsigned char *g, + unsigned char *b, + unsigned char startR = 1, + unsigned char startG = 0, + unsigned char startB = 0 ) const; +}; + /** An instance of an empty image without an alpha channel. */ @@ -1738,9 +1952,14 @@ wxImage wxNullImage; //@{ /** - Initializes all available image handlers. For a list of available handlers, - see wxImage. - If you don't need/want all image handlers loaded + Initializes all available image handlers. + + This function calls wxImage::AddHandler() for all the available image + handlers (see @ref image_handlers for the full list). Calling it is the + simplest way to initialize wxImage but it creates and registers even the + handlers your program may not use. If you want to avoid the overhead of + doing this you need to call wxImage::AddHandler() manually just for the + handlers that you do want to use. @see wxImage, wxImageHandler