Add a detailed explanation of possible error reasons to wx/chkconf.h.

[wxWidgets.git] / interface / wx / image.h

diff --git a/interface/wx/image.h b/interface/wx/image.h
index 92cd47e91718c2adffb52ea47cb6ca28ded5b6b9..43dcf59028a67b3b92150e770d96518de25364be 100644 (file)
--- a/interface/wx/image.h
+++ b/interface/wx/image.h
@@ -23,6 +23,29 @@ enum wxImageResolution
     wxIMAGE_RESOLUTION_CM = 2
 };
 
     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,
+
+    /// Default image resizing algorithm used by wxImage::Scale().
+    wxIMAGE_QUALITY_NORMAL,
+
+    /// Best image resizing algorithm, currently same as wxIMAGE_QUALITY_BICUBIC.
+    wxIMAGE_QUALITY_HIGH
+};
+

 /**
     Possible values for PNG image type option.
 
 /**
     Possible values for PNG image type option.
 


@@ -86,23 +109,23 @@ public:
     /**
         Returns @true if this handler supports the image format contained in the
         given stream.
     /**
         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).
     */
         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.
 
     /**
         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 );
         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.
 
     /**
         Gets the preferred file extension associated with this handler.
 


@@ -276,10 +299,10 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff;
     The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
     used to indicate those values in a more readable form.
 
     The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
     used to indicate those values in a more readable form.
 

-    Unlike RGB data, not all images have an alpha channel and 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
+    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.
 
     alpha and, if you initialize the image alpha channel yourself using
     wxImage::SetAlpha, you should save it in PNG format to avoid losing it.
 


@@ -325,7 +348,7 @@ class wxImage : public wxObject
 {
 public:
     /**
 {
 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
         in the range of 0-255.
     */
     class RGBValue


@@ -375,7 +398,7 @@ public:
             If @true, initialize the image to black.
     */
     wxImage(int width, int height, bool clear = true);
             If @true, initialize the image to black.
     */
     wxImage(int width, int height, bool clear = true);

-    
+

     /**
         @overload
     */
     /**
         @overload
     */


@@ -402,7 +425,7 @@ public:
         @overload
     */
     wxImage(const wxSize& sz, unsigned char* data, bool static_data = false);
         @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
     /**
         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


@@ -428,7 +451,7 @@ public:
     */
     wxImage(const wxSize& sz, unsigned char* data, unsigned char* data, unsigned char* alpha,
             bool static_data = false);
     */
     wxImage(const wxSize& sz, unsigned char* data, unsigned char* data, unsigned char* alpha,
             bool static_data = false);

-    
+

     /**
         Creates an image from XPM data.
 
     /**
         Creates an image from XPM data.
 


@@ -526,13 +549,13 @@ public:
     */
     virtual ~wxImage();
 
     */
     virtual ~wxImage();
 

-    
-    
+
+

     /**
         @name Image creation, initialization and deletion functions
     */
     //@{
     /**
         @name Image creation, initialization and deletion functions
     */
     //@{

-    
+

     /**
         Returns an identical copy of this image.
     */
     /**
         Returns an identical copy of this image.
     */


@@ -554,7 +577,7 @@ public:
     /**
         Creates a fresh image.
         See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
     /**
         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 );
         @return @true if the call succeeded, @false otherwise.
     */
     bool Create( int width, int height, unsigned char* data, bool static_data = false );


@@ -567,16 +590,16 @@ public:
     /**
         Creates a fresh image.
         See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
     /**
         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 );
         @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 );
     /**
         @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.
     /**
         Initialize the image data with zeroes (the default) or with the
         byte value given as @a value.


@@ -589,7 +612,7 @@ public:
         Destroys the image data.
     */
     void Destroy();
         Destroys the image data.
     */
     void Destroy();

-    
+

     /**
         Initializes the image alpha channel data.
 
     /**
         Initializes the image alpha channel data.
 


@@ -661,7 +684,7 @@ public:
         @see Scale()
     */
     wxImage& Rescale(int width, int height,
         @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
 
     /**
         Changes the size of the image in-place without scaling it by adding either a


@@ -714,12 +737,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.
 
         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
 
         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 +772,8 @@ public:
         @see Rescale()
     */
     wxImage Scale(int width, int height,
         @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.
     /**
         Returns a resized version of this image without scaling it by adding either a
         border with the given colour or cropping as necessary.


@@ -828,9 +847,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
         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 weight_r, double weight_g, double weight_b) const;
+
+    /**
+        Returns a greyscale version of the image.
+        @since 2.9.0

     */
     */

-    wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
+    wxImage ConvertToGreyscale() const;

 
     /**
         Returns monochromatic version of the image.
 
     /**
         Returns monochromatic version of the image.


@@ -839,15 +864,21 @@ public:
         colour and black colour everywhere else.
     */
     wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
         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
     */
     //@{
     /**
         @name Miscellaneous functions
     */
     //@{

-    
+

     /**
         Computes the histogram of the image. @a histogram is a reference to
         wxImageHistogram object. wxImageHistogram is a specialization of
     /**
         Computes the histogram of the image. @a histogram is a reference to
         wxImageHistogram object. wxImageHistogram is a specialization of


@@ -870,7 +901,7 @@ public:
         @return Returns number of colours in the histogram.
     */
     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
         @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
     /**
         Finds the first colour that is never used in the image.
         The search begins at given initial colour and continues by increasing


@@ -903,10 +934,10 @@ public:
         @return Returns 'this' object.
     */
     wxImage& operator=(const wxImage& image);
         @return Returns 'this' object.
     */
     wxImage& operator=(const wxImage& image);

-    
+

     //@}
     //@}

-    
-    
+
+

     /**
         @name Getters
     */
     /**
         @name Getters
     */


@@ -992,7 +1023,7 @@ public:
         @see GetHeight(), GetWidth()
     */
     wxSize GetSize() const;
         @see GetHeight(), GetWidth()
     */
     wxSize GetSize() const;

-    
+

     /**
         Gets a user-defined string-valued option.
 
     /**
         Gets a user-defined string-valued option.
 


@@ -1371,12 +1402,12 @@ public:
         The data must have been allocated with @c malloc(), @b NOT with
         @c operator new.
 
         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);
         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
     */
     /**
         @overload
     */


@@ -1434,8 +1465,8 @@ public:
         @see GetOption(), GetOptionInt(), HasOption()
     */
     void SetOption(const wxString& name, const wxString& value);
         @see GetOption(), GetOptionInt(), HasOption()
     */
     void SetOption(const wxString& name, const wxString& value);

-    
-    /** 
+
+    /**

         @overload
     */
     void SetOption(const wxString& name, int value);
         @overload
     */
     void SetOption(const wxString& name, int value);


@@ -1479,14 +1510,14 @@ public:
     void SetType(wxBitmapType type);
 
     //@}
     void SetType(wxBitmapType type);
 
     //@}

-    
-    
-    
+
+
+

     /**
         @name Handler management functions
     */
     //@{
     /**
         @name Handler management functions
     */
     //@{

-    
+

     /**
         Register an image handler.
         See @ref image_handlers for a list of the available handlers.
     /**
         Register an image handler.
         See @ref image_handlers for a list of the available handlers.


@@ -1498,7 +1529,7 @@ public:
         This function is called by wxWidgets on exit.
     */
     static void CleanUpHandlers();
         This function is called by wxWidgets on exit.
     */
     static void CleanUpHandlers();

-    
+

     /**
         Finds the handler with the given name.
 
     /**
         Finds the handler with the given name.
 


@@ -1591,22 +1622,22 @@ public:
         @see wxImageHandler
     */
     static bool RemoveHandler(const wxString& name);
         @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.
         the file with the given name.

-        
+

         See wxImageHandler::CanRead for more info.
     */
     static bool CanRead(const wxString& filename);
         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.
         the data in the given stream.

-        
+

         See wxImageHandler::CanRead for more info.
     */
     static bool CanRead(wxInputStream& stream);
         See wxImageHandler::CanRead for more info.
     */
     static bool CanRead(wxInputStream& stream);


@@ -1621,7 +1652,7 @@ public:
         of the file to query.
         For the overload taking the parameter @a stream, that's the opened input
         stream with image data.
         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:
         See wxImageHandler::GetImageCount() for more info.
 
         The parameter @a type may be one of the following values:


@@ -1667,12 +1698,12 @@ public:
         @see wxImageHandler
     */
     static wxString GetImageExtWildcard();
         @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 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.
     */
     /**
         Converts a color in HSV color space to RGB color space.
     */


@@ -1695,7 +1726,7 @@ wxImage wxNullImage;
 /**
     Initializes all available image handlers. For a list of available handlers,
     see wxImage.
 /**
     Initializes all available image handlers. For a list of available handlers,
     see wxImage.

-    If you don't need/want all image handlers loaded 
+    If you don't need/want all image handlers loaded

 
     @see wxImage, wxImageHandler
 
 
     @see wxImage, wxImageHandler