1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxImageHandler and wxImage
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 Possible values for the image resolution option.
12 @see wxImage::GetOptionInt().
14 enum wxImageResolution
16 /// Resolution not specified.
17 wxIMAGE_RESOLUTION_NONE
= 0,
19 /// Resolution specified in inches.
20 wxIMAGE_RESOLUTION_INCHES
= 1,
22 /// Resolution specified in centimetres.
23 wxIMAGE_RESOLUTION_CM
= 2
27 Image resize algorithm.
29 This is used with wxImage::Scale() and wxImage::Rescale().
31 enum wxImageResizeQuality
33 /// Simplest and fastest algorithm.
34 wxIMAGE_QUALITY_NEAREST
,
36 /// Compromise between wxIMAGE_QUALITY_NEAREST and wxIMAGE_QUALITY_BICUBIC.
37 wxIMAGE_QUALITY_BILINEAR
,
39 /// Highest quality but slowest execution time.
40 wxIMAGE_QUALITY_BICUBIC
,
42 /// Default image resizing algorithm used by wxImage::Scale().
43 wxIMAGE_QUALITY_NORMAL
,
45 /// Best image resizing algorithm, currently same as wxIMAGE_QUALITY_BICUBIC.
50 Possible values for PNG image type option.
52 @see wxImage::GetOptionInt().
56 wxPNG_TYPE_COLOUR
= 0, ///< Colour PNG image.
57 wxPNG_TYPE_GREY
= 2, ///< Greyscale PNG image converted from RGB.
58 wxPNG_TYPE_GREY_RED
= 3 ///< Greyscale PNG image using red as grey.
64 This is the base class for implementing image file loading/saving, and
65 image creation from data.
66 It is used within wxImage and is not normally seen by the application.
68 If you wish to extend the capabilities of wxImage, derive a class from
69 wxImageHandler and add the handler using wxImage::AddHandler in your
70 application initialization.
72 Note that all wxImageHandlers provided by wxWidgets are part of
73 the @ref page_libs_wxcore library.
74 For details about the default handlers, please see the section
75 @ref image_handlers in the wxImage class documentation.
78 @section imagehandler_note Note (Legal Issue)
80 This software is based in part on the work of the Independent JPEG Group.
81 (Applies when wxWidgets is linked with JPEG support.
82 wxJPEGHandler uses libjpeg created by IJG.)
91 @see wxImage, wxInitAllImageHandlers()
93 class wxImageHandler
: public wxObject
99 In your own default constructor, initialise the members
100 m_name, m_extension and m_type.
105 Destroys the wxImageHandler object.
107 virtual ~wxImageHandler();
110 Returns @true if this handler supports the image format contained in the
113 This function doesn't modify the current stream position (because it
114 restores the original position before returning; this however requires the
115 stream to be seekable; see wxStreamBase::IsSeekable).
117 bool CanRead( wxInputStream
& stream
);
120 Returns @true if this handler supports the image format contained in the
121 file with the given name.
123 This function doesn't modify the current stream position (because it
124 restores the original position before returning; this however requires the
125 stream to be seekable; see wxStreamBase::IsSeekable).
127 bool CanRead( const wxString
& filename
);
130 Gets the preferred file extension associated with this handler.
132 @see GetAltExtensions()
134 const wxString
& GetExtension() const;
137 Returns the other file extensions associated with this handler.
139 The preferred extension for this handler is returned by GetExtension().
143 const wxArrayString
& GetAltExtensions() const;
146 If the image file contains more than one image and the image handler is capable
147 of retrieving these individually, this function will return the number of
151 Opened input stream for reading image data.
152 This function doesn't modify the current stream position (because it
153 restores the original position before returning; this however requires the
154 stream to be seekable; see wxStreamBase::IsSeekable).
156 @return Number of available images. For most image handlers, this is 1
157 (exceptions are TIFF and ICO formats as well as animated GIFs
158 for which this function returns the number of frames in the
161 virtual int GetImageCount(wxInputStream
& stream
);
164 Gets the MIME type associated with this handler.
166 const wxString
& GetMimeType() const;
169 Gets the name of this handler.
171 const wxString
& GetName() const;
174 Gets the image type associated with this handler.
176 wxBitmapType
GetType() const;
179 Loads a image from a stream, putting the resulting data into @a image.
181 If the image file contains more than one image and the image handler is
182 capable of retrieving these individually, @a index indicates which image
183 to read from the stream.
186 The image object which is to be affected by this operation.
188 Opened input stream for reading image data.
190 If set to @true, errors reported by the image handler will produce
193 The index of the image in the file (starting from zero).
195 @return @true if the operation succeeded, @false otherwise.
197 @see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
199 virtual bool LoadFile(wxImage
* image
, wxInputStream
& stream
,
200 bool verbose
= true, int index
= -1);
203 Saves a image in the output stream.
206 The image object which is to be affected by this operation.
208 Opened output stream for writing the data.
210 If set to @true, errors reported by the image handler will produce
213 @return @true if the operation succeeded, @false otherwise.
215 @see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
217 virtual bool SaveFile(wxImage
* image
, wxOutputStream
& stream
,
218 bool verbose
= true);
221 Sets the preferred file extension associated with this handler.
224 File extension without leading dot.
226 @see SetAltExtensions()
228 void SetExtension(const wxString
& extension
);
231 Sets the alternative file extensions associated with this handler.
234 Array of file extensions.
240 void SetAltExtensions(const wxArrayString
& extensions
);
243 Sets the handler MIME type.
248 void SetMimeType(const wxString
& mimetype
);
251 Sets the handler name.
256 void SetName(const wxString
& name
);
261 Constant used to indicate the alpha value conventionally defined as
262 the complete transparency.
264 const unsigned char wxIMAGE_ALPHA_TRANSPARENT
= 0;
267 Constant used to indicate the alpha value conventionally defined as
268 the complete opacity.
270 const unsigned char wxIMAGE_ALPHA_OPAQUE
= 0xff;
275 This class encapsulates a platform-independent image.
277 An image can be created from data, or using wxBitmap::ConvertToImage.
278 An image can be loaded from a file in a variety of formats, and is extensible
279 to new formats via image format handlers. Functions are available to set and
280 get image bits, so it can be used for basic image manipulation.
282 A wxImage cannot (currently) be drawn directly to a wxDC.
283 Instead, a platform-specific wxBitmap object must be created from it using
284 the wxBitmap::wxBitmap(wxImage,int depth) constructor.
285 This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
287 One colour value of the image may be used as a mask colour which will lead to
288 the automatic creation of a wxMask object associated to the bitmap object.
291 @section image_alpha Alpha channel support
293 Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is
294 in addition to a byte for the red, green and blue colour components for each
295 pixel it also stores a byte representing the pixel opacity.
297 An alpha value of 0 corresponds to a transparent pixel (null opacity) while
298 a value of 255 means that the pixel is 100% opaque.
299 The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
300 used to indicate those values in a more readable form.
302 While all images have RGB data, not all images have an alpha channel. Before
303 using wxImage::GetAlpha you should check if this image contains an alpha
304 channel with wxImage::HasAlpha. Note that currently only the PNG format has
305 full alpha channel support so only the images loaded from PNG files can have
306 alpha and, if you initialize the image alpha channel yourself using
307 wxImage::SetAlpha, you should save it in PNG format to avoid losing it.
310 @section image_handlers Available image handlers
312 The following image handlers are available.
313 wxBMPHandler is always installed by default.
314 To use other image formats, install the appropriate handler with
315 wxImage::AddHandler or call ::wxInitAllImageHandlers().
317 - wxBMPHandler: For loading and saving, always installed.
318 - wxPNGHandler: For loading (including alpha support) and saving.
319 - wxJPEGHandler: For loading and saving.
320 - wxGIFHandler: Only for loading, due to legal issues.
321 - wxPCXHandler: For loading and saving (see below).
322 - wxPNMHandler: For loading and saving (see below).
323 - wxTIFFHandler: For loading and saving.
324 - wxTGAHandler: For loading only.
325 - wxIFFHandler: For loading only.
326 - wxXPMHandler: For loading and saving.
327 - wxICOHandler: For loading and saving.
328 - wxCURHandler: For loading and saving.
329 - wxANIHandler: For loading only.
331 When saving in PCX format, wxPCXHandler will count the number of different
332 colours in the image; if there are 256 or less colours, it will save as 8 bit,
333 else it will save as 24 bit.
335 Loading PNMs only works for ASCII or raw RGB images.
336 When saving in PNM format, wxPNMHandler will always save as raw RGB.
345 @see wxBitmap, wxInitAllImageHandlers(), wxPixelData
347 class wxImage
: public wxObject
351 A simple class which stores red, green and blue values as 8 bit unsigned integers
352 in the range of 0-255.
358 Constructor for RGBValue, an object that contains values for red, green
359 and blue which represent the value of a color.
361 It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which convert
362 between HSV color space and RGB color space.
364 RGBValue(unsigned char r
=0, unsigned char g
=0, unsigned char b
=0);
368 A simple class which stores hue, saturation and value as doubles in the range 0.0-1.0.
374 Constructor for HSVValue, an object that contains values for hue, saturation
375 and value which represent the value of a color.
377 It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which convert
378 between HSV color space and RGB color space.
380 HSVValue(double h
=0.0, double s
=0.0, double v
=0.0);
384 Creates an empty wxImage object without an alpha channel.
389 Creates an image with the given size and clears it if requested.
391 Does not create an alpha channel.
394 Specifies the width of the image.
396 Specifies the height of the image.
398 If @true, initialize the image to black.
400 wxImage(int width
, int height
, bool clear
= true);
405 wxImage(const wxSize
& sz
, bool clear
= true);
408 Creates an image from data in memory. If @a static_data is @false
409 then the wxImage will take ownership of the data and free it
410 afterwards. For this, it has to be allocated with @e malloc.
413 Specifies the width of the image.
415 Specifies the height of the image.
417 A pointer to RGB data
419 Indicates if the data should be free'd after use
422 wxImage(int width
, int height
, unsigned char* data
, bool static_data
= false);
427 wxImage(const wxSize
& sz
, unsigned char* data
, bool static_data
= false);
430 Creates an image from data in memory. If @a static_data is @false
431 then the wxImage will take ownership of the data and free it
432 afterwards. For this, it has to be allocated with @e malloc.
435 Specifies the width of the image.
437 Specifies the height of the image.
439 A pointer to RGB data
441 A pointer to alpha-channel data
443 Indicates if the data should be free'd after use
446 wxImage(int width
, int height
, unsigned char* data
, unsigned char* alpha
,
447 bool static_data
= false );
452 wxImage(const wxSize
& sz
, unsigned char* data
, unsigned char* data
, unsigned char* alpha
,
453 bool static_data
= false);
456 Creates an image from XPM data.
459 A pointer to XPM image data.
462 Not supported by wxPerl.
465 wxImage(const char* const* xpmData
);
468 Creates an image from a file.
471 Name of the file from which to load the image.
473 May be one of the following:
474 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
475 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
476 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
477 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
478 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
479 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
480 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
481 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
482 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
483 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
484 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
485 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
486 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
488 Index of the image to load in the case that the image file contains
489 multiple images. This is only used by GIF, ICO and TIFF handlers.
490 The default value (-1) means "choose the default image" and is
491 interpreted as the first image (index=0) by the GIF and TIFF handler
492 and as the largest and most colourful one by the ICO handler.
494 @remarks Depending on how wxWidgets has been configured and by which
495 handlers have been loaded, not all formats may be available.
496 Any handler other than BMP must be previously initialized with
497 wxImage::AddHandler or wxInitAllImageHandlers.
500 You can use GetOptionInt() to get the hotspot when loading cursor files:
502 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
503 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
508 wxImage(const wxString
& name
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1);
511 Creates an image from a file using MIME-types to specify the type.
514 Name of the file from which to load the image.
516 MIME type string (for example 'image/jpeg')
518 See description in wxImage(const wxString&, wxBitmapType, int) overload.
520 wxImage(const wxString
& name
, const wxString
& mimetype
, int index
= -1);
523 Creates an image from a stream.
526 Opened input stream from which to load the image. Currently,
527 the stream must support seeking.
529 See description in wxImage(const wxString&, wxBitmapType, int) overload.
531 See description in wxImage(const wxString&, wxBitmapType, int) overload.
533 wxImage(wxInputStream
& stream
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1);
536 Creates an image from a stream using MIME-types to specify the type.
539 Opened input stream from which to load the image. Currently,
540 the stream must support seeking.
542 MIME type string (for example 'image/jpeg')
544 See description in wxImage(const wxString&, wxBitmapType, int) overload.
546 wxImage(wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1);
551 See @ref overview_refcount_destruct "reference-counted object destruction"
559 @name Image creation, initialization and deletion functions
564 Returns an identical copy of this image.
566 wxImage
Copy() const;
569 Creates a fresh image.
570 See wxImage::wxImage(int,int,bool) for more info.
572 @return @true if the call succeeded, @false otherwise.
574 bool Create(int width
, int height
, bool clear
= true);
579 bool Create( const wxSize
& sz
, bool clear
= true );
582 Creates a fresh image.
583 See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
585 @return @true if the call succeeded, @false otherwise.
587 bool Create( int width
, int height
, unsigned char* data
, bool static_data
= false );
592 bool Create( const wxSize
& sz
, unsigned char* data
, bool static_data
= false );
595 Creates a fresh image.
596 See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
598 @return @true if the call succeeded, @false otherwise.
600 bool Create( int width
, int height
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
605 bool Create( const wxSize
& sz
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
608 Initialize the image data with zeroes (the default) or with the
609 byte value given as @a value.
613 void Clear(unsigned char value
= 0);
616 Destroys the image data.
621 Initializes the image alpha channel data.
623 It is an error to call it if the image already has alpha data.
624 If it doesn't, alpha data will be by default initialized to all pixels
625 being fully opaque. But if the image has a mask colour, all mask pixels
626 will be completely transparent.
634 @name Image manipulation functions
639 Blurs the image in both horizontal and vertical directions by the
640 specified pixel @a blurRadius. This should not be used when using
641 a single mask colour for transparency.
643 @see BlurHorizontal(), BlurVertical()
645 wxImage
Blur(int blurRadius
) const;
648 Blurs the image in the horizontal direction only. This should not be used
649 when using a single mask colour for transparency.
651 @see Blur(), BlurVertical()
653 wxImage
BlurHorizontal(int blurRadius
) const;
656 Blurs the image in the vertical direction only. This should not be used
657 when using a single mask colour for transparency.
659 @see Blur(), BlurHorizontal()
661 wxImage
BlurVertical(int blurRadius
) const;
664 Returns a mirrored copy of the image.
665 The parameter @a horizontally indicates the orientation.
667 wxImage
Mirror(bool horizontally
= true) const;
670 Copy the data of the given @a image to the specified position in this image.
672 void Paste(const wxImage
& image
, int x
, int y
);
675 Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
677 void Replace(unsigned char r1
, unsigned char g1
,
678 unsigned char b1
, unsigned char r2
,
679 unsigned char g2
, unsigned char b2
);
682 Changes the size of the image in-place by scaling it: after a call to this
683 function,the image will have the given width and height.
685 For a description of the @a quality parameter, see the Scale() function.
686 Returns the (modified) image itself.
690 wxImage
& Rescale(int width
, int height
,
691 wxImageResizeQuality quality
= wxIMAGE_QUALITY_NORMAL
);
694 Changes the size of the image in-place without scaling it by adding either a
695 border with the given colour or cropping as necessary.
697 The image is pasted into a new image with the given @a size and background
698 colour at the position @a pos relative to the upper left of the new image.
700 If @a red = green = blue = -1 then use either the current mask colour
701 if set or find, use, and set a suitable mask colour for any newly exposed
704 @return The (modified) image itself.
708 wxImage
& Resize(const wxSize
& size
, const wxPoint
& pos
, int red
= -1,
709 int green
= -1, int blue
= -1);
712 Rotates the image about the given point, by @a angle radians.
714 Passing @true to @a interpolating results in better image quality, but is slower.
716 If the image has a mask, then the mask colour is used for the uncovered
717 pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
719 Returns the rotated image, leaving this image intact.
721 wxImage
Rotate(double angle
, const wxPoint
& rotationCentre
,
722 bool interpolating
= true,
723 wxPoint
* offsetAfterRotation
= NULL
) const;
726 Returns a copy of the image rotated 90 degrees in the direction
727 indicated by @a clockwise.
729 wxImage
Rotate90(bool clockwise
= true) const;
732 Rotates the hue of each pixel in the image by @e angle, which is a double in
733 the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
734 corresponds to +360 degrees.
736 void RotateHue(double angle
);
739 Returns a scaled version of the image.
741 This is also useful for scaling bitmaps in general as the only other way
742 to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
744 The parameter @a quality determines what method to use for resampling
745 the image, see wxImageResizeQuality documentation.
747 It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
748 looking results it is a slower method. Downsampling will use the box averaging
749 method which seems to operate very fast. If you are upsampling larger images using
750 this method you will most likely notice that it is a bit slower and in extreme
751 cases it will be quite substantially slower as the bicubic algorithm has to process a
754 It should also be noted that the high quality scaling may not work as expected
755 when using a single mask colour for transparency, as the scaling will blur the
756 image and will therefore remove the mask partially. Using the alpha channel
761 // get the bitmap from somewhere
764 // rescale it to have size of 32*32
765 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
767 wxImage image = bmp.ConvertToImage();
768 bmp = wxBitmap(image.Scale(32, 32));
770 // another possibility:
771 image.Rescale(32, 32);
778 wxImage
Scale(int width
, int height
,
779 wxImageResizeQuality quality
= wxIMAGE_QUALITY_NORMAL
) const;
782 Returns a resized version of this image without scaling it by adding either a
783 border with the given colour or cropping as necessary.
785 The image is pasted into a new image with the given @a size and background
786 colour at the position @a pos relative to the upper left of the new image.
788 If @a red = green = blue = -1 then the areas of the larger image not covered
789 by this image are made transparent by filling them with the image mask colour
790 (which will be allocated automatically if it isn't currently set).
792 Otherwise, the areas will be filled with the colour with the specified RGB components.
796 wxImage
Size(const wxSize
& size
, const wxPoint
& pos
, int red
= -1,
797 int green
= -1, int blue
= -1) const;
803 @name Conversion functions
808 If the image has alpha channel, this method converts it to mask.
810 If the image has an alpha channel, all pixels with alpha value less
811 than @a threshold are replaced with the mask colour and the alpha
812 channel is removed. Otherwise nothing is done.
814 The mask colour is chosen automatically using
815 FindFirstUnusedColour() by this function, see the overload below if you
816 this is not appropriate.
818 @return Returns @true on success, @false on error.
820 bool ConvertAlphaToMask(unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
823 If the image has alpha channel, this method converts it to mask using
824 the specified colour as the mask colour.
826 If the image has an alpha channel, all pixels with alpha value less
827 than @a threshold are replaced with the mask colour and the alpha
828 channel is removed. Otherwise nothing is done.
833 The red component of the mask colour.
835 The green component of the mask colour.
837 The blue component of the mask colour.
839 Pixels with alpha channel values below the given threshold are
840 considered to be transparent, i.e. the corresponding mask pixels
841 are set. Pixels with the alpha values above the threshold are
842 considered to be opaque.
844 @return Returns @true on success, @false on error.
846 bool ConvertAlphaToMask(unsigned char mr
, unsigned char mg
, unsigned char mb
,
847 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
850 Returns a greyscale version of the image.
852 The returned image uses the luminance component of the original to
853 calculate the greyscale. Defaults to using the standard ITU-T BT.601
854 when converting to YUV, where every pixel equals
855 (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
857 wxImage
ConvertToGreyscale(double weight_r
, double weight_g
, double weight_b
) const;
860 Returns a greyscale version of the image.
863 wxImage
ConvertToGreyscale() const;
866 Returns monochromatic version of the image.
868 The returned image has white colour where the original has @e (r,g,b)
869 colour and black colour everywhere else.
871 wxImage
ConvertToMono(unsigned char r
, unsigned char g
, unsigned char b
) const;
874 Returns disabled (dimmed) version of the image.
877 wxImage
ConvertToDisabled(unsigned char brightness
= 255) const;
883 @name Miscellaneous functions
888 Computes the histogram of the image. @a histogram is a reference to
889 wxImageHistogram object. wxImageHistogram is a specialization of
890 wxHashMap "template" and is defined as follows:
893 class WXDLLEXPORT wxImageHistogramEntry
896 wxImageHistogramEntry() : index(0), value(0) {}
901 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
902 wxIntegerHash, wxIntegerEqual,
906 @return Returns number of colours in the histogram.
908 unsigned long ComputeHistogram(wxImageHistogram
& histogram
) const;
911 Finds the first colour that is never used in the image.
912 The search begins at given initial colour and continues by increasing
913 R, G and B components (in this order) by 1 until an unused colour is
914 found or the colour space exhausted.
916 The parameters @a r, @a g, @a b are pointers to variables to save the colour.
918 The parameters @a startR, @a startG, @a startB define the initial values
920 The returned colour will have RGB values equal to or greater than these.
922 @return Returns @false if there is no unused colour left, @true on success.
925 This method involves computing the histogram, which is a
926 computationally intensive operation.
928 bool FindFirstUnusedColour(unsigned char* r
, unsigned char* g
,
929 unsigned char* b
, unsigned char startR
= 1,
930 unsigned char startG
= 0,
931 unsigned char startB
= 0) const;
934 Assignment operator, using @ref overview_refcount "reference counting".
939 @return Returns 'this' object.
941 wxImage
& operator=(const wxImage
& image
);
952 Returns pointer to the array storing the alpha values for this image.
954 This pointer is @NULL for the images without the alpha channel. If the image
955 does have it, this pointer may be used to directly manipulate the alpha values
956 which are stored as the RGB ones.
958 unsigned char* GetAlpha() const;
961 Returns the image data as an array.
963 This is most often used when doing direct image manipulation.
964 The return value points to an array of characters in RGBRGBRGB... format
965 in the top-to-bottom, left-to-right order, that is the first RGB triplet
966 corresponds to the pixel first pixel of the first row, the second one ---
967 to the second pixel of the first row and so on until the end of the first
968 row, with second row following after it and so on.
970 You should not delete the returned pointer nor pass it to SetData().
972 unsigned char* GetData() const;
975 Return alpha value at given pixel location.
977 unsigned char GetAlpha(int x
, int y
) const;
980 Returns the red intensity at the given coordinate.
982 unsigned char GetRed(int x
, int y
) const;
985 Returns the green intensity at the given coordinate.
987 unsigned char GetGreen(int x
, int y
) const;
990 Returns the blue intensity at the given coordinate.
992 unsigned char GetBlue(int x
, int y
) const;
995 Gets the red value of the mask colour.
997 unsigned char GetMaskRed() const;
1000 Gets the green value of the mask colour.
1002 unsigned char GetMaskGreen() const;
1005 Gets the blue value of the mask colour.
1007 unsigned char GetMaskBlue() const;
1010 Gets the width of the image in pixels.
1012 @see GetHeight(), GetSize()
1014 int GetWidth() const;
1017 Gets the height of the image in pixels.
1019 @see GetWidth(), GetSize()
1021 int GetHeight() const;
1024 Returns the size of the image in pixels.
1028 @see GetHeight(), GetWidth()
1030 wxSize
GetSize() const;
1033 Gets a user-defined string-valued option.
1035 Currently the only defined string option is
1036 @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
1040 The name of the option, case-insensitive.
1042 The value of the option or an empty string if not found. Use
1043 HasOption() if an empty string can be a valid option value.
1045 @see SetOption(), GetOptionInt(), HasOption()
1047 wxString
GetOption(const wxString
& name
) const;
1050 Gets a user-defined integer-valued option.
1052 The function is case-insensitive to @a name.
1053 If the given option is not present, the function returns 0.
1054 Use HasOption() is 0 is a possibly valid value for the option.
1057 @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
1058 of these options is specified, the loaded image will be scaled down
1059 (preserving its aspect ratio) so that its width is less than the
1060 max width given if it is not 0 @em and its height is less than the
1061 max height given if it is not 0. This is typically used for loading
1062 thumbnails and the advantage of using these options compared to
1063 calling Rescale() after loading is that some handlers (only JPEG
1064 one right now) support rescaling the image during loading which is
1065 vastly more efficient than loading the entire huge image and
1066 rescaling it later (if these options are not supported by the
1067 handler, this is still what happens however). These options must be
1068 set before calling LoadFile() to have any effect.
1070 @li @c wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
1071 integer in 0..100 range with 0 meaning very poor and 100 excellent
1072 (but very badly compressed). This option is currently ignored for
1075 @li @c wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
1076 whether the resolution of the image is specified in centimetres or
1077 inches, see wxImageResolution enum elements.
1079 @li @c wxIMAGE_OPTION_RESOLUTION, @c wxIMAGE_OPTION_RESOLUTIONX and
1080 @c wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
1081 the image in the units corresponding to @c wxIMAGE_OPTION_RESOLUTIONUNIT
1082 options value. The first option can be set before saving the image
1083 to set both horizontal and vertical resolution to the same value.
1084 The X and Y options are set by the image handlers if they support
1085 the image resolution (currently BMP, JPEG and TIFF handlers do) and
1086 the image provides the resolution information and can be queried
1087 after loading the image.
1089 Options specific to wxPNGHandler:
1090 @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
1091 wxImagePNGType for the supported values.
1092 @li @c wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
1093 @li @c wxIMAGE_OPTION_PNG_FILTER: Filter for saving a PNG file, see libpng
1094 (http://www.libpng.org/pub/png/libpng-1.2.5-manual.html) for possible values
1095 (e.g. PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FILTER_UP, etc).
1096 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL: Compression level (0..9) for
1097 saving a PNG file. An high value creates smaller-but-slower PNG file.
1098 Note that unlike other formats (e.g. JPEG) the PNG format is always
1099 lossless and thus this compression level doesn't tradeoff the image
1101 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL: Compression memory usage
1102 level (1..9) for saving a PNG file. An high value means the saving
1103 process consumes more memory, but may create smaller PNG file.
1104 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY: Possible values are 0 for
1105 default strategy, 1 for filter, and 2 for Huffman-only.
1106 You can use OptiPNG (http://optipng.sourceforge.net/) to get a suitable
1107 value for your application.
1108 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE: Internal buffer size
1109 (in bytes) for saving a PNG file. Ideally this should be as big as
1110 the resulting PNG file. Use this option if your application produces
1111 images with small size variation.
1114 The name of the option, case-insensitive.
1116 The value of the option or 0 if not found.
1117 Use HasOption() if 0 can be a valid option value.
1119 @see SetOption(), GetOption()
1121 int GetOptionInt(const wxString
& name
) const;
1124 Get the current mask colour or find a suitable unused colour that could be
1125 used as a mask colour. Returns @true if the image currently has a mask.
1127 bool GetOrFindMaskColour(unsigned char* r
, unsigned char* g
,
1128 unsigned char* b
) const;
1131 Returns the palette associated with the image.
1132 Currently the palette is only used when converting to wxBitmap under Windows.
1134 Some of the wxImage handlers have been modified to set the palette if
1135 one exists in the image file (usually 256 or less colour images in
1138 const wxPalette
& GetPalette() const;
1141 Returns a sub image of the current one as long as the rect belongs entirely
1144 wxImage
GetSubImage(const wxRect
& rect
) const;
1147 Gets the type of image found by LoadFile() or specified with SaveFile().
1151 wxBitmapType
GetType() const;
1154 Returns @true if this image has alpha channel, @false otherwise.
1156 @see GetAlpha(), SetAlpha()
1158 bool HasAlpha() const;
1161 Returns @true if there is a mask active, @false otherwise.
1163 bool HasMask() const;
1166 Returns @true if the given option is present.
1167 The function is case-insensitive to @a name.
1169 The lists of the currently supported options are in GetOption() and
1170 GetOptionInt() function docs.
1172 @see SetOption(), GetOption(), GetOptionInt()
1174 bool HasOption(const wxString
& name
) const;
1177 Returns @true if image data is present.
1182 Returns @true if the given pixel is transparent, i.e. either has the mask
1183 colour if this image has a mask or if this image has alpha channel and alpha
1184 value of this pixel is strictly less than @a threshold.
1186 bool IsTransparent(int x
, int y
,
1187 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
) const;
1193 @name Loading and saving functions
1198 Loads an image from an input stream.
1201 Opened input stream from which to load the image.
1202 Currently, the stream must support seeking.
1204 May be one of the following:
1205 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1206 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1207 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1208 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1209 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1210 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1211 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
1212 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1213 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1214 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1215 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1216 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1217 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1219 Index of the image to load in the case that the image file contains
1220 multiple images. This is only used by GIF, ICO and TIFF handlers.
1221 The default value (-1) means "choose the default image" and is
1222 interpreted as the first image (index=0) by the GIF and TIFF handler
1223 and as the largest and most colourful one by the ICO handler.
1225 @return @true if the operation succeeded, @false otherwise.
1226 If the optional index parameter is out of range, @false is
1227 returned and a call to wxLogError() takes place.
1229 @remarks Depending on how wxWidgets has been configured, not all formats
1233 You can use GetOptionInt() to get the hotspot when loading cursor files:
1235 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
1236 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
1241 virtual bool LoadFile(wxInputStream
& stream
,
1242 wxBitmapType type
= wxBITMAP_TYPE_ANY
,
1246 Loads an image from a file.
1247 If no handler type is provided, the library will try to autodetect the format.
1250 Name of the file from which to load the image.
1252 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1254 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1256 virtual bool LoadFile(const wxString
& name
,
1257 wxBitmapType type
= wxBITMAP_TYPE_ANY
,
1261 Loads an image from a file.
1262 If no handler type is provided, the library will try to autodetect the format.
1265 Name of the file from which to load the image.
1267 MIME type string (for example 'image/jpeg')
1269 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1271 virtual bool LoadFile(const wxString
& name
, const wxString
& mimetype
,
1275 Loads an image from an input stream.
1278 Opened input stream from which to load the image.
1279 Currently, the stream must support seeking.
1281 MIME type string (for example 'image/jpeg')
1283 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1285 virtual bool LoadFile(wxInputStream
& stream
, const wxString
& mimetype
,
1289 Saves an image in the given stream.
1292 Opened output stream to save the image to.
1296 @return @true if the operation succeeded, @false otherwise.
1298 @remarks Depending on how wxWidgets has been configured, not all formats
1302 You can use SetOption() to set the hotspot when saving an image
1303 into a cursor file (default hotspot is in the centre of the image):
1305 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1306 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1311 virtual bool SaveFile(wxOutputStream
& stream
,
1312 const wxString
& mimetype
) const;
1315 Saves an image in the named file.
1318 Name of the file to save the image to.
1320 Currently these types can be used:
1321 @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1322 @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1323 @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1324 @li wxBITMAP_TYPE_PCX: Save a PCX image file
1325 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1326 @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1327 @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1328 @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1329 @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1330 The size may be up to 255 wide by 127 high. A single image is saved
1331 in 8 colors at the size supplied.
1332 @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1334 virtual bool SaveFile(const wxString
& name
, wxBitmapType type
) const;
1337 Saves an image in the named file.
1340 Name of the file to save the image to.
1344 virtual bool SaveFile(const wxString
& name
, const wxString
& mimetype
) const;
1347 Saves an image in the named file.
1349 File type is determined from the extension of the file name.
1350 Note that this function may fail if the extension is not recognized!
1351 You can use one of the forms above to save images to files with
1352 non-standard extensions.
1355 Name of the file to save the image to.
1357 virtual bool SaveFile(const wxString
& name
) const;
1360 Saves an image in the given stream.
1363 Opened output stream to save the image to.
1367 virtual bool SaveFile(wxOutputStream
& stream
, wxBitmapType type
) const;
1379 This function is similar to SetData() and has similar restrictions.
1381 The pointer passed to it may however be @NULL in which case the function
1382 will allocate the alpha array internally -- this is useful to add alpha
1383 channel data to an image which doesn't have any.
1385 If the pointer is not @NULL, it must have one byte for each image pixel
1386 and be allocated with malloc().
1387 wxImage takes ownership of the pointer and will free it unless @a static_data
1388 parameter is set to @true -- in this case the caller should do it.
1390 void SetAlpha(unsigned char* alpha
= NULL
,
1391 bool static_data
= false);
1394 Sets the alpha value for the given pixel.
1395 This function should only be called if the image has alpha channel data,
1396 use HasAlpha() to check for this.
1398 void SetAlpha(int x
, int y
, unsigned char alpha
);
1401 Removes the alpha channel from the image.
1403 This function should only be called if the image has alpha channel data,
1404 use HasAlpha() to check for this.
1411 Sets the image data without performing checks.
1413 The data given must have the size (width*height*3) or results will be
1414 unexpected. Don't use this method if you aren't sure you know what you
1417 The data must have been allocated with @c malloc(), @b NOT with
1420 If @a static_data is @false, after this call the pointer to the data is
1421 owned by the wxImage object, that will be responsible for deleting it.
1422 Do not pass to this function a pointer obtained through GetData().
1424 void SetData(unsigned char* data
, bool static_data
= false);
1429 void SetData(unsigned char* data
, int new_width
, int new_height
,
1430 bool static_data
= false);
1433 Specifies whether there is a mask or not.
1435 The area of the mask is determined by the current mask colour.
1437 void SetMask(bool hasMask
= true);
1440 Sets the mask colour for this image (and tells the image to use the mask).
1442 void SetMaskColour(unsigned char red
, unsigned char green
,
1443 unsigned char blue
);
1446 Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1447 mask will be masked in the image.
1449 This is done by first finding an unused colour in the image, setting
1450 this colour as the mask colour and then using this colour to draw all
1451 pixels in the image who corresponding pixel in mask has given RGB value.
1453 The parameter @a mask is the mask image to extract mask shape from.
1454 It must have the same dimensions as the image.
1456 The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1457 mask that will be used to create the mask.
1459 @return Returns @false if mask does not have same dimensions as the image
1460 or if there is no unused colour left. Returns @true if the mask
1461 was successfully applied.
1464 Note that this method involves computing the histogram, which is a
1465 computationally intensive operation.
1467 bool SetMaskFromImage(const wxImage
& mask
, unsigned char mr
,
1472 Sets a user-defined option. The function is case-insensitive to @a name.
1474 For example, when saving as a JPEG file, the option @b quality is
1475 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1477 The lists of the currently supported options are in GetOption() and
1478 GetOptionInt() function docs.
1480 @see GetOption(), GetOptionInt(), HasOption()
1482 void SetOption(const wxString
& name
, const wxString
& value
);
1487 void SetOption(const wxString
& name
, int value
);
1490 Associates a palette with the image.
1492 The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1493 or in file save operations (none as yet).
1495 void SetPalette(const wxPalette
& palette
);
1498 Sets the colour of the pixels within the given rectangle.
1500 This routine performs bounds-checks for the coordinate so it can be considered
1501 a safe way to manipulate the data.
1503 void SetRGB(const wxRect
& rect
,
1505 unsigned char green
,
1506 unsigned char blue
);
1509 Set the type of image returned by GetType().
1511 This method is mostly used internally by the library but can also be
1512 called from the user code if the image was created from data in the
1513 given bitmap format without using LoadFile() (which would set the type
1514 correctly automatically).
1516 Notice that the image must be created before this function is called.
1521 One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1522 value for it and can be used to reset the bitmap type to default
1523 but @c wxBITMAP_TYPE_MAX is not allowed here.
1525 void SetType(wxBitmapType type
);
1532 @name Handler management functions
1537 Register an image handler.
1538 See @ref image_handlers for a list of the available handlers.
1540 static void AddHandler(wxImageHandler
* handler
);
1543 Deletes all image handlers.
1544 This function is called by wxWidgets on exit.
1546 static void CleanUpHandlers();
1549 Finds the handler with the given name.
1554 @return A pointer to the handler if found, @NULL otherwise.
1558 static wxImageHandler
* FindHandler(const wxString
& name
);
1561 Finds the handler associated with the given extension and type.
1564 The file extension, such as "bmp".
1566 The image type; one of the ::wxBitmapType values.
1568 @return A pointer to the handler if found, @NULL otherwise.
1572 static wxImageHandler
* FindHandler(const wxString
& extension
,
1573 wxBitmapType imageType
);
1576 Finds the handler associated with the given image type.
1579 The image type; one of the ::wxBitmapType values.
1581 @return A pointer to the handler if found, @NULL otherwise.
1585 static wxImageHandler
* FindHandler(wxBitmapType imageType
);
1588 Finds the handler associated with the given MIME type.
1593 @return A pointer to the handler if found, @NULL otherwise.
1597 static wxImageHandler
* FindHandlerMime(const wxString
& mimetype
);
1600 Returns the static list of image format handlers.
1604 static wxList
& GetHandlers();
1607 Internal use only. Adds standard image format handlers.
1608 It only install wxBMPHandler for the time being, which is used by wxBitmap.
1610 This function is called by wxWidgets on startup, and shouldn't be called by
1613 @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
1615 static void InitStandardHandlers();
1618 Adds a handler at the start of the static list of format handlers.
1621 A new image format handler object. There is usually only one instance
1622 of a given handler class in an application session.
1626 static void InsertHandler(wxImageHandler
* handler
);
1629 Finds the handler with the given name, and removes it.
1630 The handler is not deleted.
1635 @return @true if the handler was found and removed, @false otherwise.
1639 static bool RemoveHandler(const wxString
& name
);
1645 Returns @true if at least one of the available image handlers can read
1646 the file with the given name.
1648 See wxImageHandler::CanRead for more info.
1650 static bool CanRead(const wxString
& filename
);
1653 Returns @true if at least one of the available image handlers can read
1654 the data in the given stream.
1656 See wxImageHandler::CanRead for more info.
1658 static bool CanRead(wxInputStream
& stream
);
1662 If the image file contains more than one image and the image handler is
1663 capable of retrieving these individually, this function will return the
1664 number of available images.
1666 For the overload taking the parameter @a filename, that's the name
1667 of the file to query.
1668 For the overload taking the parameter @a stream, that's the opened input
1669 stream with image data.
1671 See wxImageHandler::GetImageCount() for more info.
1673 The parameter @a type may be one of the following values:
1674 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1675 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1676 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1677 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1678 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1679 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1680 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
1681 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1682 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1683 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1684 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1685 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1686 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1688 @return Number of available images. For most image handlers, this is 1
1689 (exceptions are TIFF and ICO formats as well as animated GIFs
1690 for which this function returns the number of frames in the
1693 static int GetImageCount(const wxString
& filename
,
1694 wxBitmapType type
= wxBITMAP_TYPE_ANY
);
1695 static int GetImageCount(wxInputStream
& stream
,
1696 wxBitmapType type
= wxBITMAP_TYPE_ANY
);
1700 Iterates all registered wxImageHandler objects, and returns a string containing
1701 file extension masks suitable for passing to file open/save dialog boxes.
1703 @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
1704 It is usually a good idea to prepend a description before passing
1705 the result to the dialog.
1708 wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
1709 _("Image Files ") + wxImage::GetImageExtWildcard(),
1715 static wxString
GetImageExtWildcard();
1718 Converts a color in RGB color space to HSV color space.
1720 static wxImage::HSVValue
RGBtoHSV(const wxImage::RGBValue
& rgb
);
1723 Converts a color in HSV color space to RGB color space.
1725 static wxImage::RGBValue
HSVtoRGB(const wxImage::HSVValue
& hsv
);
1729 An instance of an empty image without an alpha channel.
1731 wxImage wxNullImage
;
1734 // ============================================================================
1735 // Global functions/macros
1736 // ============================================================================
1738 /** @addtogroup group_funcmacro_appinitterm */
1742 Initializes all available image handlers. For a list of available handlers,
1744 If you don't need/want all image handlers loaded
1746 @see wxImage, wxImageHandler
1750 void wxInitAllImageHandlers();