no changes, just correct the file name in the header (part of #10570)

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

diff --git a/interface/wx/image.h b/interface/wx/image.h
index 89a17138936fc5b08755de9a3622a78151d722d1..681609be666bebfab9350a9490a1feb4d86a5a0a 100644 (file)
--- a/interface/wx/image.h
+++ b/interface/wx/image.h
@@ -6,6 +6,35 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Possible values for the image resolution option.
+
+    @see wxImage::GetOptionInt().
+ */
+enum wxImageResolution
+{
+    /// Resolution not specified.
+    wxIMAGE_RESOLUTION_NONE = 0,
+
+    /// Resolution specified in inches.
+    wxIMAGE_RESOLUTION_INCHES = 1,
+
+    /// Resolution specified in centimetres.
+    wxIMAGE_RESOLUTION_CM = 2
+};
+
+/**
+    Possible values for PNG image type option.
+
+    @see wxImage::GetOptionInt().
+ */
+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.
+};
+

 /**
     @class wxImageHandler
 
 /**
     @class wxImageHandler
 


@@ -15,7 +44,7 @@
 
     If you wish to extend the capabilities of wxImage, derive a class from
     wxImageHandler and add the handler using wxImage::AddHandler in your
 
     If you wish to extend the capabilities of wxImage, derive a class from
     wxImageHandler and add the handler using wxImage::AddHandler in your

-    application initialisation.
+    application initialization.

 
     Note that all wxImageHandlers provided by wxWidgets are part of
     the @ref page_libs_wxcore library.
 
     Note that all wxImageHandlers provided by wxWidgets are part of
     the @ref page_libs_wxcore library.


@@ -34,7 +63,7 @@
     ::wxNullImage
 
     @library{wxcore}
     ::wxNullImage
 
     @library{wxcore}

-    @category{misc}
+    @category{gdi}

 
     @see wxImage, wxInitAllImageHandlers()
 */
 
     @see wxImage, wxInitAllImageHandlers()
 */


@@ -428,6 +457,7 @@ public:
 
     /**
         Register an image handler.
 
     /**
         Register an image handler.

+        See @ref image_handlers for a list of the available handlers.

     */
     static void AddHandler(wxImageHandler* handler);
 
     */
     static void AddHandler(wxImageHandler* handler);
 


@@ -490,25 +520,48 @@ public:
     */
     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 
     */
     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 

+    //@{

     /**
         If the image has alpha channel, this method converts it to mask.
 
     /**
         If the image has alpha channel, this method converts it to mask.
 

-        All pixels with alpha value less than @a threshold are replaced with mask
-        colour and the alpha channel is removed. Mask colour is chosen automatically
-        using FindFirstUnusedColour().
+        If the image has an alpha channel, all pixels with alpha value less
+        than @a threshold are replaced with the mask colour and the alpha
+        channel is removed. Otherwise nothing is done.

 
 

-        If the image image doesn't have alpha channel, ConvertAlphaToMask() does nothing.
+        The mask colour is chosen automatically using
+        FindFirstUnusedColour() by this function, see the overload below if you
+        this is not appropriate.

 
         @return @false if FindFirstUnusedColour returns @false, @true otherwise.
     */
     bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
 
     /**
 
         @return @false if FindFirstUnusedColour returns @false, @true otherwise.
     */
     bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
 
     /**

-        @deprecated
-        Use the equivalent @ref wxBitmap::wxBitmap "wxBitmap constructor"
-        (which takes wxImage and depth as its arguments) instead.
-    */
-    wxBitmap ConvertToBitmap() const;
+        If the image has alpha channel, this method converts it to mask using
+        the specified colour as the mask colour.
+
+        If the image has an alpha channel, all pixels with alpha value less
+        than @a threshold are replaced with the mask colour and the alpha
+        channel is removed. Otherwise nothing is done.
+
+        @since 2.9.0
+
+        @param mr
+            The red component of the mask colour.
+        @param mg
+            The green component of the mask colour.
+        @param mb
+            The blue component of the mask colour.
+        @param threshold
+            Pixels with alpha channel values below the given threshold are
+            considered to be transparent, i.e. the corresponding mask pixels
+            are set. Pixels with the alpha values above the threshold are
+            considered to be opaque.
+
+     */
+    void ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
+                            unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
+    //@}

 
     /**
         Returns a greyscale version of the image.
 
     /**
         Returns a greyscale version of the image.


@@ -544,12 +597,20 @@ public:
         @param height
             The height of the image in pixels.
         @param clear
         @param height
             The height of the image in pixels.
         @param clear

-            If @true, initialize the image data with zeros.
+            If @true, initialize the image data with zeroes.

 
         @return @true if the call succeeded, @false otherwise.
     */
     bool Create(int width, int height, bool clear = true);
 
 
         @return @true if the call succeeded, @false otherwise.
     */
     bool Create(int width, int height, bool clear = true);
 

+    /**
+        Initialize the image data with zeroes (the default) or with the
+        byte value given as @a value.
+
+        @since 2.9.0
+    */
+    void Clear(unsigned char value = 0);
+

     /**
         Destroys the image data.
     */
     /**
         Destroys the image data.
     */


@@ -672,10 +733,12 @@ public:
 
         @see wxImageHandler
     */
 
         @see wxImageHandler
     */

-    static wxList GetHandlers();
+    static wxList& GetHandlers();

 
     /**
         Gets the height of the image in pixels.
 
     /**
         Gets the height of the image in pixels.

+
+        @see GetWidth(), GetSize()

     */
     int GetHeight() const;
 
     */
     int GetHeight() const;
 


@@ -748,29 +811,91 @@ public:
     unsigned char GetMaskRed() const;
 
     /**
     unsigned char GetMaskRed() const;
 
     /**

-        Gets a user-defined option. The function is case-insensitive to @a name.
+        Gets a user-defined string-valued option.

 
 

-        For example, when saving as a JPEG file, the option @b quality is
-        used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
+        Currently the only defined string option is
+        @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
+            was loaded.
+
+        @param name
+            The name of the option, case-insensitive.
+        @return
+            The value of the option or an empty string if not found. Use
+            HasOption() if an empty string can be a valid option value.

 
         @see SetOption(), GetOptionInt(), HasOption()
     */
     wxString GetOption(const wxString& name) const;
 
     /**
 
         @see SetOption(), GetOptionInt(), HasOption()
     */
     wxString GetOption(const wxString& name) const;
 
     /**

-        Gets a user-defined option as an integer.
+        Gets a user-defined integer-valued option.
+

         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.
 
         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.
 

-        Options for wxPNGHandler:
-        @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file.
-        @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
+        Generic options:
+        @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
+            of these options is specified, the loaded image will be scaled down
+            (preserving its aspect ratio) so that its width is less than the
+            max width given if it is not 0 @em and its height is less than the
+            max height given if it is not 0. This is typically used for loading
+            thumbnails and the advantage of using these options compared to
+            calling Rescale() after loading is that some handlers (only JPEG
+            one right now) support rescaling the image during loading which is
+            vastly more efficient than loading the entire huge image and
+            rescaling it later (if these options are not supported by the
+            handler, this is still what happens however). These options must be
+            set before calling LoadFile() to have any effect.
+
+        @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
+            the other formats.
+
+        @li @c wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
+            whether the resolution of the image is specified in centimetres or
+            inches, see wxImageResolution enum elements.
+
+        @li @c wxIMAGE_OPTION_RESOLUTION, @c wxIMAGE_OPTION_RESOLUTIONX and
+            @c wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
+            the image in the units corresponding to @c wxIMAGE_OPTION_RESOLUTIONUNIT
+            options value. The first option can be set before saving the image
+            to set both horizontal and vertical resolution to the same value.
+            The X and Y options are set by the image handlers if they support
+            the image resolution (currently BMP, JPEG and TIFF handlers do) and
+            the image provides the resolution information and can be queried
+            after loading the image.
+
+        Options specific to wxPNGHandler:
+        @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
+            wxImagePNGType for the supported values.
+        @li @c wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
+        @li @c wxIMAGE_OPTION_PNG_FILTER: Filter for saving a PNG file, see libpng
+            (http://www.libpng.org/pub/png/libpng-1.2.5-manual.html) for possible values
+            (e.g. PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FILTER_UP, etc).
+        @li @c wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL: Compression level (0..9) for
+            saving a PNG file. An high value creates smaller-but-slower PNG file.
+            Note that unlike other formats (e.g. JPEG) the PNG format is always
+            lossless and thus this compression level doesn't tradeoff the image
+            quality.
+        @li @c wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL: Compression memory usage
+            level (1..9) for saving a PNG file. An high value means the saving
+            process consumes more memory, but may create smaller PNG file.
+        @li @c wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY: Possible values are 0 for
+            default strategy, 1 for filter, and 2 for Huffman-only.
+            You can use OptiPNG (http://optipng.sourceforge.net/) to get a suitable
+            value for your application.
+        @li @c wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE: Internal buffer size
+            (in bytes) for saving a PNG file. Ideally this should be as big as
+            the resulting PNG file. Use this option if your application produces
+            images with small size variation.

 
 

-        Supported values for wxIMAGE_OPTION_PNG_FORMAT:
-        @li wxPNG_TYPE_COLOUR: Stores RGB image.
-        @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.
-        @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey.
+        @param name
+            The name of the option, case-insensitive.
+        @return
+            The value of the option or 0 if not found.
+            Use HasOption() if 0 can be a valid option value.

 
         @see SetOption(), GetOption()
     */
 
         @see SetOption(), GetOption()
     */


@@ -804,6 +929,15 @@ public:
     */
     wxImage GetSubImage(const wxRect& rect) const;
 
     */
     wxImage GetSubImage(const wxRect& rect) const;
 

+    /**
+        Returns the size of the image in pixels.
+
+        @since 2.9.0
+
+        @see GetHeight(), GetWidth()
+    */
+    wxSize GetSize() const;
+

     /**
         Gets the type of image found by LoadFile() or specified with SaveFile().
 
     /**
         Gets the type of image found by LoadFile() or specified with SaveFile().
 


@@ -814,7 +948,7 @@ public:
     /**
         Gets the width of the image in pixels.
 
     /**
         Gets the width of the image in pixels.
 

-        @see GetHeight()
+        @see GetHeight(), GetSize()

     */
     int GetWidth() const;
 
     */
     int GetWidth() const;
 


@@ -839,6 +973,9 @@ public:
         Returns @true if the given option is present.
         The function is case-insensitive to @a name.
 
         Returns @true if the given option is present.
         The function is case-insensitive to @a name.
 

+        The lists of the currently supported options are in GetOption() and
+        GetOptionInt() function docs.
+

         @see SetOption(), GetOption(), GetOptionInt()
     */
     bool HasOption(const wxString& name) const;
         @see SetOption(), GetOption(), GetOptionInt()
     */
     bool HasOption(const wxString& name) const;


@@ -1289,6 +1426,9 @@ public:
         For example, when saving as a JPEG file, the option @b quality is
         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 
         For example, when saving as a JPEG file, the option @b quality is
         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 

+        The lists of the currently supported options are in GetOption() and
+        GetOptionInt() function docs.
+

         @see GetOption(), GetOptionInt(), HasOption()
     */
     void SetOption(const wxString& name, const wxString& value);
         @see GetOption(), GetOptionInt(), HasOption()
     */
     void SetOption(const wxString& name, const wxString& value);


@@ -1362,16 +1502,23 @@ public:
     wxImage& operator=(const wxImage& image);
 };
 
     wxImage& operator=(const wxImage& image);
 };
 

+/**
+    An instance of an empty image without an alpha channel.
+*/
+wxImage wxNullImage;
+
+

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */

 //@{
 
 /**
     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 

 
     @see wxImage, wxImageHandler
 
 
     @see wxImage, wxImageHandler