X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/85fcb94fc99880e8fdb127ea1fc6cb0aefa6986d..45aa63c28877bbe4584f47b768af903d85f7642b:/interface/wx/image.h diff --git a/interface/wx/image.h b/interface/wx/image.h index 80c8100f2c..34808c5c15 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 ///////////////////////////////////////////////////////////////////////////// /** @@ -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,7 +70,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. }; /** @@ -83,6 +122,26 @@ public: */ virtual ~wxImageHandler(); + /** + 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 ); + + /** + 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. @@ -106,7 +165,9 @@ public: @param stream Opened input stream for reading image data. - Currently, the stream must support seeking. + 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). @return Number of available images. For most image handlers, this is 1 (exceptions are TIFF and ICO formats as well as animated GIFs @@ -209,6 +270,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(); }; @@ -254,12 +329,14 @@ 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. - 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 - alpha and, if you initialize the image alpha channel yourself using - wxImage::SetAlpha, you should save it in PNG format to avoid losing it. + 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. 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 @@ -269,14 +346,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. @@ -290,6 +367,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} @@ -303,7 +382,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 @@ -353,7 +432,7 @@ public: If @true, initialize the image to black. */ wxImage(int width, int height, bool clear = true); - + /** @overload */ @@ -380,7 +459,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 @@ -406,12 +485,16 @@ public: */ wxImage(const wxSize& sz, unsigned char* data, 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); @@ -504,13 +587,13 @@ public: */ virtual ~wxImage(); - - + + /** @name Image creation, initialization and deletion functions */ //@{ - + /** Returns an identical copy of this image. */ @@ -532,7 +615,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 ); @@ -545,16 +628,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. @@ -567,7 +650,7 @@ public: Destroys the image data. */ void Destroy(); - + /** Initializes the image alpha channel data. @@ -639,7 +722,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 @@ -679,6 +762,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 @@ -692,12 +782,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 @@ -731,8 +817,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. @@ -770,7 +856,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); @@ -796,8 +882,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); /** @@ -806,9 +893,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 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. @@ -817,15 +910,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 @@ -848,7 +947,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 @@ -881,10 +980,10 @@ public: @return Returns 'this' object. */ wxImage& operator=(const wxImage& image); - + //@} - - + + /** @name Getters */ @@ -970,7 +1069,7 @@ public: @see GetHeight(), GetWidth() */ wxSize GetSize() const; - + /** Gets a user-defined string-valued option. @@ -993,7 +1092,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 @@ -1052,6 +1151,12 @@ public: the resulting PNG file. Use this option if your application produces images with small size variation. + 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 @@ -1339,6 +1444,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. @@ -1349,12 +1464,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 */ @@ -1412,8 +1527,8 @@ public: @see GetOption(), GetOptionInt(), HasOption() */ void SetOption(const wxString& name, const wxString& value); - - /** + + /** @overload */ void SetOption(const wxString& name, int value); @@ -1457,17 +1572,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); @@ -1476,7 +1603,7 @@ public: This function is called by wxWidgets on exit. */ static void CleanUpHandlers(); - + /** Finds the handler with the given name. @@ -1559,7 +1686,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. @@ -1569,15 +1697,26 @@ public: @see wxImageHandler */ static bool RemoveHandler(const wxString& name); - + //@} - - + + /** - Returns @true if the current image handlers can read this file + 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 + the data in the given stream. + + See wxImageHandler::CanRead for more info. + */ + static bool CanRead(wxInputStream& stream); + //@{ /** If the image file contains more than one image and the image handler is @@ -1586,8 +1725,10 @@ public: For the overload taking the parameter @a filename, that's the name of the file to query. - For the overload taking the parameter @a stream, that's the ppened input - stream with image data. Currently, the stream must support seeking. + 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: @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. @@ -1632,12 +1773,12 @@ 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. */ @@ -1658,9 +1799,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