]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/image.h
avoid infinite recursion for richtooltops, (hopefully) fixes #15070
[wxWidgets.git] / interface / wx / image.h
index 4a9f0fd13f41e1ae4a47b30fa2a46202275771b0..1a2ae82c79a5ab1580398ad9936c13e5120c2838 100644 (file)
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxImageHandler and wxImage
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -23,6 +23,44 @@ enum wxImageResolution
     wxIMAGE_RESOLUTION_CM = 2
 };
 
+/**
+    Image resize algorithm.
+
+    This is used with wxImage::Scale() and wxImage::Rescale().
+ */
+enum wxImageResizeQuality
+{
+    /// Simplest and fastest algorithm.
+    wxIMAGE_QUALITY_NEAREST,
+
+    /// Compromise between wxIMAGE_QUALITY_NEAREST and wxIMAGE_QUALITY_BICUBIC.
+    wxIMAGE_QUALITY_BILINEAR,
+
+    /// Highest quality but slowest execution time.
+    wxIMAGE_QUALITY_BICUBIC,
+
+    /**
+    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. 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
+};
+
 /**
     Possible values for PNG image type option.
 
@@ -32,9 +70,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
 
@@ -86,23 +176,23 @@ public:
     /**
         Returns @true if this handler supports the image format contained in the
         given stream.
-        
+
         This function doesn't modify the current stream position (because it
         restores the original position before returning; this however requires the
         stream to be seekable; see wxStreamBase::IsSeekable).
     */
-    bool CanRead( wxInputStream& stream );    
+    bool CanRead( wxInputStream& stream );
 
     /**
         Returns @true if this handler supports the image format contained in the
         file with the given name.
-        
+
         This function doesn't modify the current stream position (because it
         restores the original position before returning; this however requires the
         stream to be seekable; see wxStreamBase::IsSeekable).
     */
     bool CanRead( const wxString& filename );
-    
+
     /**
         Gets the preferred file extension associated with this handler.
 
@@ -231,6 +321,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;
 };
 
 
@@ -246,6 +368,9 @@ const unsigned char wxIMAGE_ALPHA_TRANSPARENT = 0;
 */
 const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff;
 
+const unsigned char wxIMAGE_ALPHA_THRESHOLD = 0x80;
+
+
 /**
     @class wxImage
 
@@ -261,6 +386,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.
 
@@ -278,10 +414,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
@@ -291,14 +429,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.
@@ -312,6 +450,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}
@@ -325,7 +465,7 @@ class wxImage : public wxObject
 {
 public:
     /**
-        A simple class which stores red, green and blue values as 8 bit unsigned integers 
+        A simple class which stores red, green and blue values as 8 bit unsigned integers
         in the range of 0-255.
     */
     class RGBValue
@@ -339,6 +479,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;
     };
 
     /**
@@ -355,6 +499,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;        
     };
 
     /**
@@ -375,7 +523,7 @@ public:
             If @true, initialize the image to black.
     */
     wxImage(int width, int height, bool clear = true);
-    
+
     /**
         @overload
     */
@@ -402,7 +550,7 @@ public:
         @overload
     */
     wxImage(const wxSize& sz, unsigned char* data, bool static_data = false);
-    
+
     /**
         Creates an image from data in memory. If @a static_data is @false
         then the wxImage will take ownership of the data and free it
@@ -426,14 +574,18 @@ 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);
-    
+
     /**
         Creates an image from XPM data.
 
         @param xpmData
             A pointer to XPM image data.
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
     */
     wxImage(const char* const* xpmData);
 
@@ -450,7 +602,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).
@@ -526,13 +678,13 @@ public:
     */
     virtual ~wxImage();
 
-    
-    
+
+
     /**
         @name Image creation, initialization and deletion functions
     */
     //@{
-    
+
     /**
         Returns an identical copy of this image.
     */
@@ -554,7 +706,7 @@ public:
     /**
         Creates a fresh image.
         See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
-        
+
         @return @true if the call succeeded, @false otherwise.
     */
     bool Create( int width, int height, unsigned char* data, bool static_data = false );
@@ -567,16 +719,16 @@ public:
     /**
         Creates a fresh image.
         See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
-        
+
         @return @true if the call succeeded, @false otherwise.
     */
     bool Create( int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
-    
+
     /**
         @overload
     */
     bool Create( const wxSize& sz, unsigned char* data, unsigned char* alpha, bool static_data = false );
-        
+
     /**
         Initialize the image data with zeroes (the default) or with the
         byte value given as @a value.
@@ -589,7 +741,7 @@ public:
         Destroys the image data.
     */
     void Destroy();
-    
+
     /**
         Initializes the image alpha channel data.
 
@@ -661,7 +813,7 @@ public:
         @see Scale()
     */
     wxImage& Rescale(int width, int height,
-                    int quality = wxIMAGE_QUALITY_NORMAL);
+                     wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL);
 
     /**
         Changes the size of the image in-place without scaling it by adding either a
@@ -701,6 +853,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
@@ -714,12 +873,8 @@ public:
         This is also useful for scaling bitmaps in general as the only other way
         to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
 
-        The parameter @a quality determines what method to use for resampling the image.
-        Can be one of the following:
-        - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
-                                  replication
-        - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
-                                for upsampling and downsampling respectively
+        The parameter @a quality determines what method to use for resampling
+        the image, see wxImageResizeQuality documentation.
 
         It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
         looking results it is a slower method. Downsampling will use the box averaging
@@ -753,8 +908,8 @@ public:
         @see Rescale()
     */
     wxImage Scale(int width, int height,
-                  int quality = wxIMAGE_QUALITY_NORMAL) const;
-    
+                   wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL) const;
+
     /**
         Returns a resized version of this image without scaling it by adding either a
         border with the given colour or cropping as necessary.
@@ -792,7 +947,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);
 
@@ -818,8 +973,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);
 
     /**
@@ -828,9 +984,15 @@ public:
         The returned image uses the luminance component of the original to
         calculate the greyscale. Defaults to using the standard ITU-T BT.601
         when converting to YUV, where every pixel equals
-        (R * @a lr) + (G * @a lg) + (B * @a lb).
+        (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
     */
-    wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
+    wxImage ConvertToGreyscale(double weight_r, double weight_g, double weight_b) const;
+
+    /**
+        Returns a greyscale version of the image.
+        @since 2.9.0
+    */
+    wxImage ConvertToGreyscale() const;
 
     /**
         Returns monochromatic version of the image.
@@ -839,15 +1001,21 @@ public:
         colour and black colour everywhere else.
     */
     wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
-    
+
+    /**
+        Returns disabled (dimmed) version of the image.
+        @since 2.9.0
+    */
+    wxImage ConvertToDisabled(unsigned char brightness = 255) const;
+
     //@}
-    
-    
+
+
     /**
         @name Miscellaneous functions
     */
     //@{
-    
+
     /**
         Computes the histogram of the image. @a histogram is a reference to
         wxImageHistogram object. wxImageHistogram is a specialization of
@@ -870,7 +1038,7 @@ public:
         @return Returns number of colours in the histogram.
     */
     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
-    
+
     /**
         Finds the first colour that is never used in the image.
         The search begins at given initial colour and continues by increasing
@@ -903,10 +1071,10 @@ public:
         @return Returns 'this' object.
     */
     wxImage& operator=(const wxImage& image);
-    
+
     //@}
-    
-    
+
+
     /**
         @name Getters
     */
@@ -927,7 +1095,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.
 
@@ -992,14 +1160,20 @@ public:
         @see GetHeight(), GetWidth()
     */
     wxSize GetSize() const;
-    
+
     /**
         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
@@ -1015,7 +1189,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
@@ -1031,6 +1205,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
@@ -1074,6 +1254,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
@@ -1143,7 +1356,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.
     */
@@ -1172,7 +1385,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).
@@ -1361,6 +1574,16 @@ public:
     */
     void SetAlpha(int x, int y, unsigned char alpha);
 
+    /**
+        Removes the alpha channel from the image.
+
+        This function should only be called if the image has alpha channel data,
+        use HasAlpha() to check for this.
+
+        @since 2.9.1
+    */
+    void ClearAlpha();
+
     /**
         Sets the image data without performing checks.
 
@@ -1371,12 +1594,12 @@ public:
         The data must have been allocated with @c malloc(), @b NOT with
         @c operator new.
 
-        If @a static_data is @false, after this call the pointer to the data is 
+        If @a static_data is @false, after this call the pointer to the data is
         owned by the wxImage object, that will be responsible for deleting it.
         Do not pass to this function a pointer obtained through GetData().
     */
     void SetData(unsigned char* data, bool static_data = false);
-    
+
     /**
         @overload
     */
@@ -1434,8 +1657,8 @@ public:
         @see GetOption(), GetOptionInt(), HasOption()
     */
     void SetOption(const wxString& name, const wxString& value);
-    
-    /** 
+
+    /**
         @overload
     */
     void SetOption(const wxString& name, int value);
@@ -1479,17 +1702,29 @@ public:
     void SetType(wxBitmapType type);
 
     //@}
-    
-    
-    
+
+
+
     /**
         @name Handler management functions
     */
     //@{
-    
+
     /**
         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);
 
@@ -1498,7 +1733,7 @@ public:
         This function is called by wxWidgets on exit.
     */
     static void CleanUpHandlers();
-    
+
     /**
         Finds the handler with the given name.
 
@@ -1581,7 +1816,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.
@@ -1591,22 +1827,22 @@ public:
         @see wxImageHandler
     */
     static bool RemoveHandler(const wxString& name);
-    
+
     //@}
-    
-    
+
+
     /**
-        Returns @true if at least one of the available image handlers can read 
+        Returns @true if at least one of the available image handlers can read
         the file with the given name.
-        
+
         See wxImageHandler::CanRead for more info.
     */
     static bool CanRead(const wxString& filename);
-    
+
     /**
-        Returns @true if at least one of the available image handlers can read 
+        Returns @true if at least one of the available image handlers can read
         the data in the given stream.
-        
+
         See wxImageHandler::CanRead for more info.
     */
     static bool CanRead(wxInputStream& stream);
@@ -1621,7 +1857,7 @@ public:
         of the file to query.
         For the overload taking the parameter @a stream, that's the opened input
         stream with image data.
-        
+
         See wxImageHandler::GetImageCount() for more info.
 
         The parameter @a type may be one of the following values:
@@ -1631,7 +1867,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).
@@ -1667,18 +1903,42 @@ public:
         @see wxImageHandler
     */
     static wxString GetImageExtWildcard();
-    
+
     /**
         Converts a color in RGB color space to HSV color space.
     */
     static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
-    
+
     /**
         Converts a color in HSV color space to RGB color space.
     */
     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.
 */
@@ -1693,9 +1953,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