X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dd067e96c8bdb954e8448c654f7a45a0d6561b40..a0f4d36895556e3054e2256cb5f1787cc9fcf75c:/interface/image.h diff --git a/interface/image.h b/interface/image.h index 719731aaa6..74d814fde7 100644 --- a/interface/image.h +++ b/interface/image.h @@ -10,15 +10,17 @@ @class wxImageHandler @wxheader{image.h} - This is the base class for implementing image file loading/saving, and image - creation from data. + This is the base class for implementing image file loading/saving, and + image creation from data. It is used within wxImage and is not normally seen by the application. If you wish to extend the capabilities of wxImage, derive a class from - wxImageHandler - and add the handler using wxImage::AddHandler in your + wxImageHandler and add the handler using wxImage::AddHandler in your application initialisation. + @stdobjects + ::wxNullImage + @library{wxcore} @category{FIXME} @@ -141,18 +143,16 @@ public: @class wxImage @wxheader{image.h} - This class encapsulates a platform-independent image. An image can be created - from data, or using wxBitmap::ConvertToImage. An image - can be loaded from a file in a variety of formats, and is extensible to new - formats - via image format handlers. Functions are available to set and get image bits, so - it can be used for basic image manipulation. + This class encapsulates a platform-independent image. An image can be + created from data, or using wxBitmap::ConvertToImage. An image can be + loaded from a file in a variety of formats, and is extensible to new + formats via image format handlers. Functions are available to set and + get image bits, so it can be used for basic image manipulation. A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific wxBitmap object must be created from it using the wxBitmap::wxBitmap(wxImage,int depth) constructor. - This bitmap can then - be drawn in a device context, using wxDC::DrawBitmap. + This bitmap can then be drawn in a device context, using wxDC::DrawBitmap. One colour value of the image may be used as a mask colour which will lead to the automatic creation of a wxMask object associated to the bitmap object. @@ -163,12 +163,30 @@ public: @stdobjects ::wxNullImage - @see wxBitmap, wxInitAllImageHandlers() + @see wxBitmap, wxInitAllImageHandlers(), wxPixelData */ class wxImage : public wxObject { public: - //@{ + + /** + Creates an empty wxImage object without an alpha channel. + */ + wxImage(); + + /** + Creates an image with the given size and clears it if requested. + Does not create an alpha channel. + + @param width + Specifies the width of the image. + @param height + Specifies the height of the image. + @clear + Clear the image with zeros. + */ + wxImage(int width, int height, bool clear = true); + /** Creates an image from data in memory. If static_data is false then the wxImage will take ownership of the data and free it @@ -180,32 +198,30 @@ public: Specifies the height of the image. @param data A pointer to RGB data - @param apha - A pointer to alpha-channel data + @param static_data + Indicates if the data should be free'd after use */ - wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false ); wxImage(int width, int height, unsigned char* data, bool static_data = false); - //@} /** - Creates an image with the given size and clears it if requested. - Does not create an alpha channel. - */ - wxImage(int width, int height, bool clear = true); + Creates an image from data in memory. If static_data is false + then the wxImage will take ownership of the data and free it + afterwards. For this, it has to be allocated with @e malloc. - /** - Creates an empty wxImage object. Does not create - an alpha channel. - @param width Specifies the width of the image. @param height Specifies the height of the image. - @clear - Clear the image with zeros. + @param data + A pointer to RGB data + @param alpha + A pointer to alpha-channel data + @param static_data + Indicates if the data should be free'd after use + */ - wxImage(); + wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false ); /** Creates an image from XPM data. @@ -214,31 +230,27 @@ public: A pointer to XPM image data. */ wxImage(const char* const* xpmData); - //@{ + /** + Creates an image from a file. + @param name Name of the file from which to load the image. - @param stream - Opened input stream from which to load the image. Currently, - the stream must support seeking. @param type May be one of the following: - wxBITMAP_TYPE_BMP: Load a Windows bitmap file. - wxBITMAP_TYPE_GIF: Load a GIF bitmap file. - wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. - wxBITMAP_TYPE_PNG: Load a PNG bitmap file. - wxBITMAP_TYPE_PCX: Load a PCX bitmap file. - wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. - wxBITMAP_TYPE_TGA: Load a TGA bitmap file. - wxBITMAP_TYPE_XPM: Load a XPM bitmap file. - wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). - wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). - wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANY: Will try to autodetect the format. - - @param mimetype - MIME type string (for example 'image/jpeg') + @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. + @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. + @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. + @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. + @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. + @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. + @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. + @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. + @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). + @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). + @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). + @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. @param index Index of the image to load in the case that the image file contains multiple images. This is only used by GIF, ICO and TIFF handlers. @@ -252,10 +264,46 @@ public: @see LoadFile() */ wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1); + + /** + Creates an image from a file using MIME-types to specify the type. + + @param name + Name of the file from which to load the image. + @param type + See above + @param mimetype + MIME type string (for example 'image/jpeg') + @param index + See above + */ wxImage(const wxString& name, const wxString& mimetype, int index = -1); - wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1); + + /** + Creates an image from a stream. + + @param stream + Opened input stream from which to load the image. Currently, + the stream must support seeking. + @param type + See above + @param index + See above. + */ + wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1); + + /** + Creates an image from a stream using MIME-types to specify the type. + + @param stream + Opened input stream from which to load the image. Currently, + the stream must support seeking. + @param mimetype + MIME type string (for example 'image/jpeg') + @param index + See above. + */ wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1); - //@} /** @@ -265,21 +313,17 @@ public: */ ~wxImage(); - //@{ /** - returns @true if the current image handlers can read this file + Register an image handler. */ static void AddHandler(wxImageHandler* handler); - See also bool CanRead(const wxString& filename); - //@} /** - Blurs the image in both horizontal and vertical directions by the specified - pixel - @e blurRadius. This should not be used when using a single mask colour - for transparency. + Blurs the image in both horizontal and vertical directions by the + specified pixel @e blurRadius. This should not be used when using + a single mask colour for transparency. - @see @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical + @see BlurHorizontal(), BlurVertical() */ wxImage Blur(int blurRadius); @@ -287,7 +331,7 @@ public: Blurs the image in the horizontal direction only. This should not be used when using a single mask colour for transparency. - @see Blur(), @ref vertblur() BlurVertical + @see Blur(), BlurVertical() */ wxImage BlurHorizontal(int blurRadius); @@ -295,9 +339,14 @@ public: Blurs the image in the vertical direction only. This should not be used when using a single mask colour for transparency. - @see Blur(), @ref horzblur() BlurHorizontal + @see Blur(), BlurHorizontal() */ wxImage BlurVertical(int blurRadius); + + /** + Returns @true if the current image handlers can read this file + */ + bool CanRead(const wxString& filename); /** Deletes all image handlers. @@ -412,16 +461,18 @@ public: static wxImageHandler* FindHandlerMime(const wxString& mimetype); //@} - //@{ + /** + Return alpha value at given pixel location. + */ + unsigned char GetAlpha(int x, int y) const; + /** Returns pointer to the array storing the alpha values for this image. This pointer is @NULL for the images without the alpha channel. If the image does have it, this pointer may be used to directly manipulate the alpha values - which are stored as the @ref getdata() RGB ones. + which are stored as the RGB ones. */ - unsigned char GetAlpha(int x, int y) const; const unsigned char * GetAlpha() const; - //@} /** Returns the blue intensity at the given coordinate. @@ -471,19 +522,19 @@ public: support seeking. @param type May be one of the following: - wxBITMAP_TYPE_BMP: Load a Windows bitmap file. - wxBITMAP_TYPE_GIF: Load a GIF bitmap file. - wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. - wxBITMAP_TYPE_PNG: Load a PNG bitmap file. - wxBITMAP_TYPE_PCX: Load a PCX bitmap file. - wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. - wxBITMAP_TYPE_TGA: Load a TGA bitmap file. - wxBITMAP_TYPE_XPM: Load a XPM bitmap file. - wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). - wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). - wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANY: Will try to autodetect the format. + @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. + @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. + @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. + @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. + @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. + @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. + @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. + @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. + @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). + @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). + @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). + @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. @returns Number of available images. For most image handlers, this is 1 (exceptions are TIFF and ICO formats). @@ -531,34 +582,17 @@ public: wxString GetOption(const wxString& name) const; /** - Gets a user-defined option as an integer. The function is case-insensitive to - @e name. - If the given option is not present, the function returns 0. Use - HasOption() is 0 is a possibly valid value - for the option. + Gets a user-defined option as an integer. The function is case-insensitive + to @e 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 - - wxIMAGE_OPTION_PNG_FORMAT - - Format for saving a PNG file. - - wxIMAGE_OPTION_PNG_BITDEPTH - - Bit depth for every channel (R/G/B/A). - + @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). + Supported values for wxIMAGE_OPTION_PNG_FORMAT: - - wxPNG_TYPE_COLOUR - - Stores RGB image. - - wxPNG_TYPE_GREY - - Stores grey image, converts from RGB. - - wxPNG_TYPE_GREY_RED - - Stores grey image, uses red value as grey. + @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. @see SetOption(), GetOption() */ @@ -683,19 +717,19 @@ public: stream must support seeking. @param type May be one of the following: - wxBITMAP_TYPE_BMP: Load a Windows bitmap file. - wxBITMAP_TYPE_GIF: Load a GIF bitmap file. - wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. - wxBITMAP_TYPE_PNG: Load a PNG bitmap file. - wxBITMAP_TYPE_PCX: Load a PCX bitmap file. - wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. - wxBITMAP_TYPE_TGA: Load a TGA bitmap file. - wxBITMAP_TYPE_XPM: Load a XPM bitmap file. - wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). - wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). - wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANY: Will try to autodetect the format. + @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. + @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. + @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. + @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. + @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. + @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. + @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. + @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. + @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). + @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). + @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). + @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. @param mimetype MIME type string (for example 'image/jpeg') @param index @@ -835,18 +869,18 @@ public: Opened output stream to save the image to. @param type Currently these types can be used: - wxBITMAP_TYPE_BMP: Save a BMP image file. - wxBITMAP_TYPE_JPEG: Save a JPEG image file. - wxBITMAP_TYPE_PNG: Save a PNG image file. - wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible, + @li wxBITMAP_TYPE_BMP: Save a BMP image file. + @li wxBITMAP_TYPE_JPEG: Save a JPEG image file. + @li wxBITMAP_TYPE_PNG: Save a PNG image file. + @li wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise). - wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always). - wxBITMAP_TYPE_TIFF: Save a TIFF image file. - wxBITMAP_TYPE_XPM: Save a XPM image file. - wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may + @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always). + @li wxBITMAP_TYPE_TIFF: Save a TIFF image file. + @li wxBITMAP_TYPE_XPM: Save a XPM image file. + @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. A single image is saved in 8 colors at the size supplied). - wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR). + @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR). @param mimetype MIME type. @@ -887,11 +921,11 @@ public: @param 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 + Can be one of the following: + @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel replication - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling + @li wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods for upsampling and downsampling respectively @see Rescale() @@ -899,16 +933,20 @@ public: wxImage Scale(int width, int height, int quality = wxIMAGE_QUALITY_NORMAL) const; - //@{ - /** - Sets the alpha value for the given pixel. This function should only be called - if the image has alpha channel data, use HasAlpha() to - check for this. + /** + Assigns new data as alpha channel to the image. + If @e static_data is false the data will be + free()'d after use. */ void SetAlpha(unsigned char* alpha = NULL, bool static_data = false); + + /** + Sets the alpha value for the given pixel. This function should only be + called if the image has alpha channel data, use HasAlpha() to + check for this. + */ void SetAlpha(int x, int y, unsigned char alpha); - //@} /** Sets the image data without performing checks. The data given must have @@ -1006,12 +1044,6 @@ public: wxImage operator =(const wxImage& image); }; -/** - An empty wxImage. -*/ -wxImage wxNullImage; - - // ============================================================================ // Global functions/macros // ============================================================================