avoid infinite recursion for richtooltops, (hopefully) fixes #15070
[wxWidgets.git] / interface / wx / image.h
index c14f9f95954468719e2bc3382e21a7dd828f3ad8..1a2ae82c79a5ab1580398ad9936c13e5120c2838 100644 (file)
@@ -39,10 +39,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 +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
 
@@ -254,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;
 };
 
 
@@ -269,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
 
@@ -284,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.
 
@@ -301,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
@@ -314,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.
@@ -335,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}
@@ -362,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;
     };
 
     /**
@@ -378,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;        
     };
 
     /**
@@ -449,7 +574,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 +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).
@@ -728,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
@@ -815,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);
 
@@ -841,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);
 
     /**
@@ -962,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.
 
@@ -1031,10 +1164,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 +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
@@ -1066,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
@@ -1109,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
@@ -1178,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.
     */
@@ -1207,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).
@@ -1534,7 +1712,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 +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.
@@ -1676,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).
@@ -1724,6 +1915,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 +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