X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/427c415b933075ab9be91d7116c6db80858e0b78..232b2162776e08c0b16d5280b90f5c075f38c667:/interface/wx/image.h diff --git a/interface/wx/image.h b/interface/wx/image.h index f1bd3ffc02..56739044b0 100644 --- a/interface/wx/image.h +++ b/interface/wx/image.h @@ -6,6 +6,35 @@ // 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 @@ -109,8 +138,8 @@ public: @see wxImage::LoadFile, wxImage::SaveFile, SaveFile() */ - bool LoadFile(wxImage* image, wxInputStream& stream, - bool verbose = true, int index = 0); + virtual bool LoadFile(wxImage* image, wxInputStream& stream, + bool verbose = true, int index = -1); /** Saves a image in the output stream. @@ -119,12 +148,16 @@ public: The image object which is to be affected by this operation. @param stream Opened output stream for writing the data. + @param verbose + If set to @true, errors reported by the image handler will produce + wxLogMessages. @return @true if the operation succeeded, @false otherwise. @see wxImage::LoadFile, wxImage::SaveFile, LoadFile() */ - bool SaveFile(wxImage* image, wxOutputStream& stream); + virtual bool SaveFile(wxImage* image, wxOutputStream& stream, + bool verbose = true); /** Sets the handler extension. @@ -497,14 +530,7 @@ public: @return @false if FindFirstUnusedColour returns @false, @true otherwise. */ - bool ConvertAlphaToMask(unsigned char threshold = 128); - - /** - @deprecated - Use the equivalent @ref wxBitmap::wxBitmap "wxBitmap constructor" - (which takes wxImage and depth as its arguments) instead. - */ - wxBitmap ConvertToBitmap() const; + bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD); /** Returns a greyscale version of the image. @@ -514,8 +540,7 @@ public: when converting to YUV, where every pixel equals (R * @a lr) + (G * @a lg) + (B * @a lb). */ - wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, - double lb = 0.114) const; + wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const; /** Returns monochromatic version of the image. @@ -541,12 +566,20 @@ public: @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); + /** + 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. */ @@ -638,7 +671,7 @@ public: does have it, this pointer may be used to directly manipulate the alpha values which are stored as the RGB ones. */ - const unsigned char * GetAlpha() const; + unsigned char* GetAlpha() const; /** Returns the blue intensity at the given coordinate. @@ -669,10 +702,12 @@ public: @see wxImageHandler */ - static wxList GetHandlers(); + static wxList& GetHandlers(); /** Gets the height of the image in pixels. + + @see GetWidth(), GetSize() */ int GetHeight() const; @@ -745,29 +780,91 @@ public: 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; /** - 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. - 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() */ @@ -777,8 +874,8 @@ public: Get the current mask colour or find a suitable unused colour that could be used as a mask colour. Returns @true if the image currently has a mask. */ - bool GetOrFindMaskColour(unsigned char r, unsigned char g, - unsigned char b) const; + bool GetOrFindMaskColour(unsigned char* r, unsigned char* g, + unsigned char* b) const; /** Returns the palette associated with the image. @@ -801,6 +898,15 @@ public: */ 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(). @@ -811,14 +917,14 @@ public: /** Gets the width of the image in pixels. - @see GetHeight() + @see GetHeight(), GetSize() */ int GetWidth() const; /** Converts a color in HSV color space to RGB color space. */ - wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue & hsv); + static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv); /** Returns @true if this image has alpha channel, @false otherwise. @@ -836,6 +942,9 @@ public: 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; @@ -882,7 +991,8 @@ public: 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. */ - bool IsTransparent(int x, int y, unsigned char threshold = 128) const; + bool IsTransparent(int x, int y, + unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const; /** Loads an image from an input stream. @@ -928,7 +1038,9 @@ public: @see SaveFile() */ - bool LoadFile(wxInputStream& stream, wxBitmapType type, int index = -1); + virtual bool LoadFile(wxInputStream& stream, + wxBitmapType type = wxBITMAP_TYPE_ANY, + int index = -1); /** Loads an image from a file. @@ -941,9 +1053,9 @@ public: @param index See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. */ - bool LoadFile(const wxString& name, - wxBitmapType type = wxBITMAP_TYPE_ANY, - int index = -1); + virtual bool LoadFile(const wxString& name, + wxBitmapType type = wxBITMAP_TYPE_ANY, + int index = -1); /** Loads an image from a file. @@ -956,8 +1068,8 @@ public: @param index See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. */ - bool LoadFile(const wxString& name, const wxString& mimetype, - int index = -1); + virtual bool LoadFile(const wxString& name, const wxString& mimetype, + int index = -1); /** @@ -971,9 +1083,8 @@ public: @param index See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. */ - bool LoadFile(wxInputStream& stream, - const wxString& mimetype, - int index = -1); + virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype, + int index = -1); /** Returns a mirrored copy of the image. @@ -989,7 +1100,7 @@ public: /** Converts a color in RGB color space to HSV color space. */ - wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb); + static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb); /** Finds the handler with the given name, and removes it. @@ -1020,7 +1131,7 @@ public: @see Scale() */ - wxImage Rescale(int width, int height, + wxImage& Rescale(int width, int height, int quality = wxIMAGE_QUALITY_NORMAL); /** @@ -1038,9 +1149,8 @@ public: @see Size() */ - wxImage Resize(const wxSize& size, const wxPoint& pos, - int red = -1, int green = -1, - int blue = -1); + wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1, + int green = -1, int blue = -1); /** Rotates the image about the given point, by @a angle radians. @@ -1092,8 +1202,8 @@ public: @see LoadFile() */ - bool SaveFile(wxOutputStream& stream, - const wxString& mimetype) const; + virtual bool SaveFile(wxOutputStream& stream, + const wxString& mimetype) const; /** Saves an image in the named file. @@ -1115,7 +1225,7 @@ public: in 8 colors at the size supplied. @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR). */ - bool SaveFile(const wxString& name, wxBitmapType type) const; + virtual bool SaveFile(const wxString& name, wxBitmapType type) const; /** Saves an image in the named file. @@ -1125,8 +1235,7 @@ public: @param mimetype MIME type. */ - bool SaveFile(const wxString& name, - const wxString& mimetype) const; + virtual bool SaveFile(const wxString& name, const wxString& mimetype) const; /** Saves an image in the named file. @@ -1139,7 +1248,7 @@ public: @param name Name of the file to save the image to. */ - bool SaveFile(const wxString& name) const; + virtual bool SaveFile(const wxString& name) const; /** Saves an image in the given stream. @@ -1149,7 +1258,7 @@ public: @param type MIME type. */ - bool SaveFile(wxOutputStream& stream, wxBitmapType type) const; + virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const; /** Returns a scaled version of the image. @@ -1220,6 +1329,7 @@ public: */ void SetAlpha(int x, int y, unsigned char alpha); + //@{ /** Sets the image data without performing checks. @@ -1234,7 +1344,10 @@ public: that will be responsible for deleting it. Do not pass to this function a pointer obtained through GetData(). */ - void SetData(unsigned char* data); + void SetData(unsigned char* data, bool static_data = false); + void SetData(unsigned char* data, int new_width, int new_height, + bool static_data = false); + //@} /** Specifies whether there is a mask or not. @@ -1282,6 +1395,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). + 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); @@ -1302,7 +1418,8 @@ public: This routine performs bounds-checks for the coordinate so it can be considered a safe way to manipulate the data. */ - void SetRGB(wxRect& rect, unsigned char red, + void SetRGB(const wxRect& rect, + unsigned char red, unsigned char green, unsigned char blue); @@ -1351,14 +1468,20 @@ public: @return Returns 'this' object. */ - 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 // ============================================================================ -/** @ingroup group_funcmacro_appinitterm */ +/** @addtogroup group_funcmacro_appinitterm */ //@{ /**