X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/198c264dbcf226b5df0eed219aef30d6fdc38a71..e02edc0e6ece01b0301164b57c9f6b76c66fdd5b:/interface/wx/image.h diff --git a/interface/wx/image.h b/interface/wx/image.h index 43dcf59028..e106e43061 100644 --- a/interface/wx/image.h +++ b/interface/wx/image.h @@ -3,7 +3,7 @@ // Purpose: interface of wxImageHandler and wxImage // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -55,7 +55,8 @@ 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. }; /** @@ -254,6 +255,20 @@ 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(); }; @@ -301,10 +316,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, 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 or TGA 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 +331,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 (including alpha support) and saving. + - wxTGAHandler: For loading and saving. Includes alpha support. - wxIFFHandler: For loading only. - wxXPMHandler: For loading and saving. - wxICOHandler: For loading and saving. @@ -335,6 +352,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} @@ -457,6 +476,10 @@ public: @param xpmData A pointer to XPM image data. + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ wxImage(const char* const* xpmData); @@ -724,6 +747,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 @@ -811,7 +841,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); @@ -837,8 +867,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); /** @@ -1392,6 +1423,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. @@ -1520,7 +1561,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); @@ -1612,7 +1665,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. @@ -1724,9 +1778,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 call 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