1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxImageHandler and wxImage
4 // Author: wxWidgets team
6 // Licence: wxWindows license
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 Possible values for PNG image type option.
29 @see wxImage::GetOptionInt().
33 wxPNG_TYPE_COLOUR
= 0, ///< Colour PNG image.
34 wxPNG_TYPE_GREY
= 2, ///< Greyscale PNG image converted from RGB.
35 wxPNG_TYPE_GREY_RED
= 3 ///< Greyscale PNG image using red as grey.
41 This is the base class for implementing image file loading/saving, and
42 image creation from data.
43 It is used within wxImage and is not normally seen by the application.
45 If you wish to extend the capabilities of wxImage, derive a class from
46 wxImageHandler and add the handler using wxImage::AddHandler in your
47 application initialisation.
49 Note that all wxImageHandlers provided by wxWidgets are part of
50 the @ref page_libs_wxcore library.
51 For details about the default handlers, please see the section
52 @ref image_handlers in the wxImage class documentation.
55 @section imagehandler_note Note (Legal Issue)
57 This software is based in part on the work of the Independent JPEG Group.
58 (Applies when wxWidgets is linked with JPEG support.
59 wxJPEGHandler uses libjpeg created by IJG.)
68 @see wxImage, wxInitAllImageHandlers()
70 class wxImageHandler
: public wxObject
76 In your own default constructor, initialise the members
77 m_name, m_extension and m_type.
82 Destroys the wxImageHandler object.
84 virtual ~wxImageHandler();
87 Gets the file extension associated with this handler.
89 const wxString
& GetExtension() const;
92 If the image file contains more than one image and the image handler is capable
93 of retrieving these individually, this function will return the number of
97 Opened input stream for reading image data.
98 Currently, the stream must support seeking.
100 @return Number of available images. For most image handlers, this is 1
101 (exceptions are TIFF and ICO formats).
103 virtual int GetImageCount(wxInputStream
& stream
);
106 Gets the MIME type associated with this handler.
108 const wxString
& GetMimeType() const;
111 Gets the name of this handler.
113 const wxString
& GetName() const;
116 Gets the image type associated with this handler.
118 wxBitmapType
GetType() const;
121 Loads a image from a stream, putting the resulting data into @a image.
123 If the image file contains more than one image and the image handler is
124 capable of retrieving these individually, @a index indicates which image
125 to read from the stream.
128 The image object which is to be affected by this operation.
130 Opened input stream for reading image data.
132 If set to @true, errors reported by the image handler will produce
135 The index of the image in the file (starting from zero).
137 @return @true if the operation succeeded, @false otherwise.
139 @see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
141 virtual bool LoadFile(wxImage
* image
, wxInputStream
& stream
,
142 bool verbose
= true, int index
= -1);
145 Saves a image in the output stream.
148 The image object which is to be affected by this operation.
150 Opened output stream for writing the data.
152 If set to @true, errors reported by the image handler will produce
155 @return @true if the operation succeeded, @false otherwise.
157 @see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
159 virtual bool SaveFile(wxImage
* image
, wxOutputStream
& stream
,
160 bool verbose
= true);
163 Sets the handler extension.
168 void SetExtension(const wxString
& extension
);
171 Sets the handler MIME type.
176 void SetMimeType(const wxString
& mimetype
);
179 Sets the handler name.
184 void SetName(const wxString
& name
);
189 Constant used to indicate the alpha value conventionally defined as
190 the complete transparency.
192 const unsigned char wxIMAGE_ALPHA_TRANSPARENT
= 0;
195 Constant used to indicate the alpha value conventionally defined as
196 the complete opacity.
198 const unsigned char wxIMAGE_ALPHA_OPAQUE
= 0xff;
203 This class encapsulates a platform-independent image.
205 An image can be created from data, or using wxBitmap::ConvertToImage.
206 An image can be loaded from a file in a variety of formats, and is extensible
207 to new formats via image format handlers. Functions are available to set and
208 get image bits, so it can be used for basic image manipulation.
210 A wxImage cannot (currently) be drawn directly to a wxDC.
211 Instead, a platform-specific wxBitmap object must be created from it using
212 the wxBitmap::wxBitmap(wxImage,int depth) constructor.
213 This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
215 One colour value of the image may be used as a mask colour which will lead to
216 the automatic creation of a wxMask object associated to the bitmap object.
219 @section image_alpha Alpha channel support
221 Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is
222 in addition to a byte for the red, green and blue colour components for each
223 pixel it also stores a byte representing the pixel opacity.
225 An alpha value of 0 corresponds to a transparent pixel (null opacity) while
226 a value of 255 means that the pixel is 100% opaque.
227 The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
228 used to indicate those values in a more readable form.
230 Unlike RGB data, not all images have an alpha channel and before using
231 wxImage::GetAlpha you should check if this image contains an alpha channel
232 with wxImage::HasAlpha. Note that currently only the PNG format has full
233 alpha channel support so only the images loaded from PNG files can have
234 alpha and, if you initialize the image alpha channel yourself using
235 wxImage::SetAlpha, you should save it in PNG format to avoid losing it.
238 @section image_handlers Available image handlers
240 The following image handlers are available.
241 wxBMPHandler is always installed by default.
242 To use other image formats, install the appropriate handler with
243 wxImage::AddHandler or call ::wxInitAllImageHandlers().
245 - wxBMPHandler: For loading and saving, always installed.
246 - wxPNGHandler: For loading (including alpha support) and saving.
247 - wxJPEGHandler: For loading and saving.
248 - wxGIFHandler: Only for loading, due to legal issues.
249 - wxPCXHandler: For loading and saving (see below).
250 - wxPNMHandler: For loading and saving (see below).
251 - wxTIFFHandler: For loading and saving.
252 - wxTGAHandler: For loading only.
253 - wxIFFHandler: For loading only.
254 - wxXPMHandler: For loading and saving.
255 - wxICOHandler: For loading and saving.
256 - wxCURHandler: For loading and saving.
257 - wxANIHandler: For loading only.
259 When saving in PCX format, wxPCXHandler will count the number of different
260 colours in the image; if there are 256 or less colours, it will save as 8 bit,
261 else it will save as 24 bit.
263 Loading PNMs only works for ASCII or raw RGB images.
264 When saving in PNM format, wxPNMHandler will always save as raw RGB.
273 @see wxBitmap, wxInitAllImageHandlers(), wxPixelData
275 class wxImage
: public wxObject
282 Constructor for RGBValue, an object that contains values for red, green
283 and blue which represent the value of a color.
285 It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which converts
286 between HSV color space and RGB color space.
288 RGBValue(unsigned char r
=0, unsigned char g
=0, unsigned char b
=0);
295 Constructor for HSVValue, an object that contains values for hue, saturation
296 and value which represent the value of a color.
298 It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which converts
299 between HSV color space and RGB color space.
301 HSVValue(double h
=0.0, double s
=0.0, double v
=0.0);
305 Creates an empty wxImage object without an alpha channel.
310 Creates an image with the given size and clears it if requested.
312 Does not create an alpha channel.
315 Specifies the width of the image.
317 Specifies the height of the image.
319 If @true, initialize the image to black.
321 wxImage(int width
, int height
, bool clear
= true);
324 Creates an image from data in memory. If @a static_data is @false
325 then the wxImage will take ownership of the data and free it
326 afterwards. For this, it has to be allocated with @e malloc.
329 Specifies the width of the image.
331 Specifies the height of the image.
333 A pointer to RGB data
335 Indicates if the data should be free'd after use
338 wxImage(int width
, int height
, unsigned char* data
, bool static_data
= false);
341 Creates an image from data in memory. If @a static_data is @false
342 then the wxImage will take ownership of the data and free it
343 afterwards. For this, it has to be allocated with @e malloc.
346 Specifies the width of the image.
348 Specifies the height of the image.
350 A pointer to RGB data
352 A pointer to alpha-channel data
354 Indicates if the data should be free'd after use
357 wxImage(int width
, int height
, unsigned char* data
, unsigned char* alpha
,
358 bool static_data
= false );
361 Creates an image from XPM data.
364 A pointer to XPM image data.
366 wxImage(const char* const* xpmData
);
369 Creates an image from a file.
372 Name of the file from which to load the image.
374 May be one of the following:
375 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
376 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
377 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
378 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
379 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
380 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
381 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
382 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
383 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
384 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
385 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
386 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
387 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
389 Index of the image to load in the case that the image file contains
390 multiple images. This is only used by GIF, ICO and TIFF handlers.
391 The default value (-1) means "choose the default image" and is
392 interpreted as the first image (index=0) by the GIF and TIFF handler
393 and as the largest and most colourful one by the ICO handler.
395 @remarks Depending on how wxWidgets has been configured and by which
396 handlers have been loaded, not all formats may be available.
397 Any handler other than BMP must be previously initialized with
398 wxImage::AddHandler or wxInitAllImageHandlers.
401 You can use GetOptionInt() to get the hotspot when loading cursor files:
403 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
404 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
409 wxImage(const wxString
& name
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1);
412 Creates an image from a file using MIME-types to specify the type.
415 Name of the file from which to load the image.
417 MIME type string (for example 'image/jpeg')
419 See description in wxImage(const wxString&, wxBitmapType, int) overload.
421 wxImage(const wxString
& name
, const wxString
& mimetype
, int index
= -1);
424 Creates an image from a stream.
427 Opened input stream from which to load the image. Currently,
428 the stream must support seeking.
430 See description in wxImage(const wxString&, wxBitmapType, int) overload.
432 See description in wxImage(const wxString&, wxBitmapType, int) overload.
434 wxImage(wxInputStream
& stream
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1);
437 Creates an image from a stream using MIME-types to specify the type.
440 Opened input stream from which to load the image. Currently,
441 the stream must support seeking.
443 MIME type string (for example 'image/jpeg')
445 See description in wxImage(const wxString&, wxBitmapType, int) overload.
447 wxImage(wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1);
453 See @ref overview_refcount_destruct "reference-counted object destruction"
459 Register an image handler.
461 static void AddHandler(wxImageHandler
* handler
);
464 Blurs the image in both horizontal and vertical directions by the
465 specified pixel @a blurRadius. This should not be used when using
466 a single mask colour for transparency.
468 @see BlurHorizontal(), BlurVertical()
470 wxImage
Blur(int blurRadius
) const;
473 Blurs the image in the horizontal direction only. This should not be used
474 when using a single mask colour for transparency.
476 @see Blur(), BlurVertical()
478 wxImage
BlurHorizontal(int blurRadius
) const;
481 Blurs the image in the vertical direction only. This should not be used
482 when using a single mask colour for transparency.
484 @see Blur(), BlurHorizontal()
486 wxImage
BlurVertical(int blurRadius
) const;
489 Returns @true if the current image handlers can read this file
491 static bool CanRead(const wxString
& filename
);
494 Deletes all image handlers.
495 This function is called by wxWidgets on exit.
497 static void CleanUpHandlers();
500 Computes the histogram of the image. @a histogram is a reference to
501 wxImageHistogram object. wxImageHistogram is a specialization of
502 wxHashMap "template" and is defined as follows:
505 class WXDLLEXPORT wxImageHistogramEntry
508 wxImageHistogramEntry() : index(0), value(0) {}
513 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
514 wxIntegerHash, wxIntegerEqual,
518 @return Returns number of colours in the histogram.
520 unsigned long ComputeHistogram(wxImageHistogram
& histogram
) const;
523 If the image has alpha channel, this method converts it to mask.
525 All pixels with alpha value less than @a threshold are replaced with mask
526 colour and the alpha channel is removed. Mask colour is chosen automatically
527 using FindFirstUnusedColour().
529 If the image image doesn't have alpha channel, ConvertAlphaToMask() does nothing.
531 @return @false if FindFirstUnusedColour returns @false, @true otherwise.
533 bool ConvertAlphaToMask(unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
536 Returns a greyscale version of the image.
538 The returned image uses the luminance component of the original to
539 calculate the greyscale. Defaults to using the standard ITU-T BT.601
540 when converting to YUV, where every pixel equals
541 (R * @a lr) + (G * @a lg) + (B * @a lb).
543 wxImage
ConvertToGreyscale(double lr
= 0.299, double lg
= 0.587, double lb
= 1.114) const;
546 Returns monochromatic version of the image.
548 The returned image has white colour where the original has @e (r,g,b)
549 colour and black colour everywhere else.
551 wxImage
ConvertToMono(unsigned char r
, unsigned char g
, unsigned char b
) const;
554 Returns an identical copy of the image.
556 wxImage
Copy() const;
559 Creates a fresh image.
561 If @a clear is @true, the new image will be initialized to black.
562 Otherwise, the image data will be uninitialized.
565 The width of the image in pixels.
567 The height of the image in pixels.
569 If @true, initialize the image data with zeros.
571 @return @true if the call succeeded, @false otherwise.
573 bool Create(int width
, int height
, bool clear
= true);
576 Destroys the image data.
581 Finds the first colour that is never used in the image.
582 The search begins at given initial colour and continues by increasing
583 R, G and B components (in this order) by 1 until an unused colour is
584 found or the colour space exhausted.
586 The parameters @a r, @a g, @a b are pointers to variables to save the colour.
588 The parameters @a startR, @a startG, @a startB define the initial values
590 The returned colour will have RGB values equal to or greater than these.
592 @return Returns @false if there is no unused colour left, @true on success.
595 This method involves computing the histogram, which is a
596 computationally intensive operation.
598 bool FindFirstUnusedColour(unsigned char* r
, unsigned char* g
,
599 unsigned char* b
, unsigned char startR
= 1,
600 unsigned char startG
= 0,
601 unsigned char startB
= 0) const;
604 Finds the handler with the given name.
609 @return A pointer to the handler if found, @NULL otherwise.
613 static wxImageHandler
* FindHandler(const wxString
& name
);
616 Finds the handler associated with the given extension and type.
619 The file extension, such as "bmp".
621 The image type; one of the ::wxBitmapType values.
623 @return A pointer to the handler if found, @NULL otherwise.
627 static wxImageHandler
* FindHandler(const wxString
& extension
,
628 wxBitmapType imageType
);
631 Finds the handler associated with the given image type.
634 The image type; one of the ::wxBitmapType values.
636 @return A pointer to the handler if found, @NULL otherwise.
640 static wxImageHandler
* FindHandler(wxBitmapType imageType
);
643 Finds the handler associated with the given MIME type.
648 @return A pointer to the handler if found, @NULL otherwise.
652 static wxImageHandler
* FindHandlerMime(const wxString
& mimetype
);
655 Return alpha value at given pixel location.
657 unsigned char GetAlpha(int x
, int y
) const;
660 Returns pointer to the array storing the alpha values for this image.
662 This pointer is @NULL for the images without the alpha channel. If the image
663 does have it, this pointer may be used to directly manipulate the alpha values
664 which are stored as the RGB ones.
666 unsigned char* GetAlpha() const;
669 Returns the blue intensity at the given coordinate.
671 unsigned char GetBlue(int x
, int y
) const;
674 Returns the image data as an array.
676 This is most often used when doing direct image manipulation.
677 The return value points to an array of characters in RGBRGBRGB... format
678 in the top-to-bottom, left-to-right order, that is the first RGB triplet
679 corresponds to the pixel first pixel of the first row, the second one ---
680 to the second pixel of the first row and so on until the end of the first
681 row, with second row following after it and so on.
683 You should not delete the returned pointer nor pass it to SetData().
685 unsigned char* GetData() const;
688 Returns the green intensity at the given coordinate.
690 unsigned char GetGreen(int x
, int y
) const;
693 Returns the static list of image format handlers.
697 static wxList
GetHandlers();
700 Gets the height of the image in pixels.
702 @see GetWidth(), GetSize()
704 int GetHeight() const;
708 If the image file contains more than one image and the image handler is
709 capable of retrieving these individually, this function will return the
710 number of available images.
712 For the overload taking the parameter @a filename, that's the name
713 of the file to query.
714 For the overload taking the parameter @a stream, that's the ppened input
715 stream with image data. Currently, the stream must support seeking.
717 The parameter @a type may be one of the following values:
718 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
719 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
720 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
721 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
722 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
723 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
724 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
725 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
726 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
727 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
728 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
729 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
730 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
732 @return Number of available images. For most image handlers, this is 1
733 (exceptions are TIFF and ICO formats).
735 static int GetImageCount(const wxString
& filename
,
736 wxBitmapType type
= wxBITMAP_TYPE_ANY
);
737 static int GetImageCount(wxInputStream
& stream
,
738 wxBitmapType type
= wxBITMAP_TYPE_ANY
);
742 Iterates all registered wxImageHandler objects, and returns a string containing
743 file extension masks suitable for passing to file open/save dialog boxes.
745 @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
746 It is usually a good idea to prepend a description before passing
747 the result to the dialog.
750 wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
751 _("Image Files ") + wxImage::GetImageExtWildcard(),
757 static wxString
GetImageExtWildcard();
760 Gets the blue value of the mask colour.
762 unsigned char GetMaskBlue() const;
765 Gets the green value of the mask colour.
767 unsigned char GetMaskGreen() const;
770 Gets the red value of the mask colour.
772 unsigned char GetMaskRed() const;
775 Gets a user-defined string-valued option.
777 Currently the only defined string option is
778 @li wxIMAGE_OPTION_FILENAME: The name of the file from which the image
781 @see SetOption(), GetOptionInt(), HasOption()
784 The name of the option, case-insensitive.
786 The value of the option or an empty string if not found. Use
787 HasOption() if an empty string can be a valid option value.
789 wxString
GetOption(const wxString
& name
) const;
792 Gets a user-defined integer-valued option.
794 The function is case-insensitive to @a name.
795 If the given option is not present, the function returns 0.
796 Use HasOption() is 0 is a possibly valid value for the option.
799 @li wxIMAGE_OPTION_MAX_WIDTH and wxIMAGE_OPTION_MAX_HEIGHT: If either
800 of these options is specified, the loaded image will be scaled down
801 (preserving its aspect ratio) so that its width is less than the
802 max width given if it is not 0 @em and its height is less than the
803 max height given if it is not 0. This is typically used for loading
804 thumbnails and the advantage of using these options compared to
805 calling Rescale() after loading is that some handlers (only JPEG
806 one right now) support rescaling the image during loading which is
807 vastly more efficient than loading the entire huge image and
808 rescaling it later (if these options are not supported by the
809 handler, this is still what happens however). These options must be
810 set before calling LoadFile() to have any effect.
812 @li wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
813 integer in 0..100 range with 0 meaning very poor and 100 excellent
814 (but very badly compressed). This option is currently ignored for
817 @li wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
818 whether the resolution of the image is specified in centimetres or
819 inches, see wxImageResolution enum elements.
821 @li wxIMAGE_OPTION_RESOLUTION, wxIMAGE_OPTION_RESOLUTIONX and
822 wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
823 the image in the units corresponding to wxIMAGE_OPTION_RESOLUTIONUNIT
824 options value. The first option can be set before saving the image
825 to set both horizontal and vertical resolution to the same value.
826 The X and Y options are set by the image handlers if they support
827 the image resolution (currently BMP, JPEG and TIFF handlers do) and
828 the image provides the resolution information and can be queried
829 after loading the image.
831 Options specific to wxPNGHandler:
832 @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
833 wxImagePNGType for the supported values.
834 @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
836 @see SetOption(), GetOption()
839 The name of the option, case-insensitive.
841 The value of the option or 0 if not found. Use HasOption() if 0
842 can be a valid option value.
844 int GetOptionInt(const wxString
& name
) const;
847 Get the current mask colour or find a suitable unused colour that could be
848 used as a mask colour. Returns @true if the image currently has a mask.
850 bool GetOrFindMaskColour(unsigned char* r
, unsigned char* g
,
851 unsigned char* b
) const;
854 Returns the palette associated with the image.
855 Currently the palette is only used when converting to wxBitmap under Windows.
857 Some of the wxImage handlers have been modified to set the palette if
858 one exists in the image file (usually 256 or less colour images in
861 const wxPalette
& GetPalette() const;
864 Returns the red intensity at the given coordinate.
866 unsigned char GetRed(int x
, int y
) const;
869 Returns a sub image of the current one as long as the rect belongs entirely
872 wxImage
GetSubImage(const wxRect
& rect
) const;
875 Returns the size of the image in pixels.
879 @see GetHeight(), GetWidth()
881 wxSize
GetSize() const;
884 Gets the type of image found by LoadFile() or specified with SaveFile().
888 wxBitmapType
GetType() const;
891 Gets the width of the image in pixels.
893 @see GetHeight(), GetSize()
895 int GetWidth() const;
898 Converts a color in HSV color space to RGB color space.
900 static wxImage::RGBValue
HSVtoRGB(const wxImage::HSVValue
& hsv
);
903 Returns @true if this image has alpha channel, @false otherwise.
905 @see GetAlpha(), SetAlpha()
907 bool HasAlpha() const;
910 Returns @true if there is a mask active, @false otherwise.
912 bool HasMask() const;
915 Returns @true if the given option is present.
916 The function is case-insensitive to @a name.
918 @see SetOption(), GetOption(), GetOptionInt()
920 bool HasOption(const wxString
& name
) const;
923 Initializes the image alpha channel data.
925 It is an error to call it if the image already has alpha data.
926 If it doesn't, alpha data will be by default initialized to all pixels
927 being fully opaque. But if the image has a mask colour, all mask pixels
928 will be completely transparent.
933 Internal use only. Adds standard image format handlers.
934 It only install wxBMPHandler for the time being, which is used by wxBitmap.
936 This function is called by wxWidgets on startup, and shouldn't be called by
939 @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
941 static void InitStandardHandlers();
944 Adds a handler at the start of the static list of format handlers.
947 A new image format handler object. There is usually only one instance
948 of a given handler class in an application session.
952 static void InsertHandler(wxImageHandler
* handler
);
955 Returns @true if image data is present.
960 Returns @true if the given pixel is transparent, i.e. either has the mask
961 colour if this image has a mask or if this image has alpha channel and alpha
962 value of this pixel is strictly less than @a threshold.
964 bool IsTransparent(int x
, int y
,
965 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
) const;
968 Loads an image from an input stream.
971 Opened input stream from which to load the image.
972 Currently, the stream must support seeking.
974 May be one of the following:
975 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
976 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
977 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
978 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
979 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
980 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
981 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
982 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
983 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
984 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
985 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
986 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
987 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
989 Index of the image to load in the case that the image file contains
990 multiple images. This is only used by GIF, ICO and TIFF handlers.
991 The default value (-1) means "choose the default image" and is
992 interpreted as the first image (index=0) by the GIF and TIFF handler
993 and as the largest and most colourful one by the ICO handler.
995 @return @true if the operation succeeded, @false otherwise.
996 If the optional index parameter is out of range, @false is
997 returned and a call to wxLogError() takes place.
999 @remarks Depending on how wxWidgets has been configured, not all formats
1003 You can use GetOptionInt() to get the hotspot when loading cursor files:
1005 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
1006 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
1011 virtual bool LoadFile(wxInputStream
& stream
,
1012 wxBitmapType type
= wxBITMAP_TYPE_ANY
,
1016 Loads an image from a file.
1017 If no handler type is provided, the library will try to autodetect the format.
1020 Name of the file from which to load the image.
1022 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1024 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1026 virtual bool LoadFile(const wxString
& name
,
1027 wxBitmapType type
= wxBITMAP_TYPE_ANY
,
1031 Loads an image from a file.
1032 If no handler type is provided, the library will try to autodetect the format.
1035 Name of the file from which to load the image.
1037 MIME type string (for example 'image/jpeg')
1039 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1041 virtual bool LoadFile(const wxString
& name
, const wxString
& mimetype
,
1046 Loads an image from an input stream.
1049 Opened input stream from which to load the image.
1050 Currently, the stream must support seeking.
1052 MIME type string (for example 'image/jpeg')
1054 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1056 virtual bool LoadFile(wxInputStream
& stream
, const wxString
& mimetype
,
1060 Returns a mirrored copy of the image.
1061 The parameter @a horizontally indicates the orientation.
1063 wxImage
Mirror(bool horizontally
= true) const;
1066 Copy the data of the given @a image to the specified position in this image.
1068 void Paste(const wxImage
& image
, int x
, int y
);
1071 Converts a color in RGB color space to HSV color space.
1073 static wxImage::HSVValue
RGBtoHSV(const wxImage::RGBValue
& rgb
);
1076 Finds the handler with the given name, and removes it.
1077 The handler is not deleted.
1082 @return @true if the handler was found and removed, @false otherwise.
1086 static bool RemoveHandler(const wxString
& name
);
1089 Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
1091 void Replace(unsigned char r1
, unsigned char g1
,
1092 unsigned char b1
, unsigned char r2
,
1093 unsigned char g2
, unsigned char b2
);
1096 Changes the size of the image in-place by scaling it: after a call to this
1097 function,the image will have the given width and height.
1099 For a description of the @a quality parameter, see the Scale() function.
1100 Returns the (modified) image itself.
1104 wxImage
& Rescale(int width
, int height
,
1105 int quality
= wxIMAGE_QUALITY_NORMAL
);
1108 Changes the size of the image in-place without scaling it by adding either a
1109 border with the given colour or cropping as necessary.
1111 The image is pasted into a new image with the given @a size and background
1112 colour at the position @a pos relative to the upper left of the new image.
1114 If @a red = green = blue = -1 then use either the current mask colour
1115 if set or find, use, and set a suitable mask colour for any newly exposed
1118 @return The (modified) image itself.
1122 wxImage
& Resize(const wxSize
& size
, const wxPoint
& pos
, int red
= -1,
1123 int green
= -1, int blue
= -1);
1126 Rotates the image about the given point, by @a angle radians.
1128 Passing @true to @a interpolating results in better image quality, but is slower.
1130 If the image has a mask, then the mask colour is used for the uncovered
1131 pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
1133 Returns the rotated image, leaving this image intact.
1135 wxImage
Rotate(double angle
, const wxPoint
& rotationCentre
,
1136 bool interpolating
= true,
1137 wxPoint
* offsetAfterRotation
= NULL
) const;
1140 Returns a copy of the image rotated 90 degrees in the direction
1141 indicated by @a clockwise.
1143 wxImage
Rotate90(bool clockwise
= true) const;
1146 Rotates the hue of each pixel in the image by @e angle, which is a double in
1147 the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
1148 corresponds to +360 degrees.
1150 void RotateHue(double angle
);
1153 Saves an image in the given stream.
1156 Opened output stream to save the image to.
1160 @return @true if the operation succeeded, @false otherwise.
1162 @remarks Depending on how wxWidgets has been configured, not all formats
1166 You can use SetOption() to set the hotspot when saving an image
1167 into a cursor file (default hotspot is in the centre of the image):
1169 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1170 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1175 virtual bool SaveFile(wxOutputStream
& stream
,
1176 const wxString
& mimetype
) const;
1179 Saves an image in the named file.
1182 Name of the file to save the image to.
1184 Currently these types can be used:
1185 @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1186 @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1187 @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1188 @li wxBITMAP_TYPE_PCX: Save a PCX image file
1189 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1190 @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1191 @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1192 @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1193 @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1194 The size may be up to 255 wide by 127 high. A single image is saved
1195 in 8 colors at the size supplied.
1196 @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1198 virtual bool SaveFile(const wxString
& name
, wxBitmapType type
) const;
1201 Saves an image in the named file.
1204 Name of the file to save the image to.
1208 virtual bool SaveFile(const wxString
& name
, const wxString
& mimetype
) const;
1211 Saves an image in the named file.
1213 File type is determined from the extension of the file name.
1214 Note that this function may fail if the extension is not recognized!
1215 You can use one of the forms above to save images to files with
1216 non-standard extensions.
1219 Name of the file to save the image to.
1221 virtual bool SaveFile(const wxString
& name
) const;
1224 Saves an image in the given stream.
1227 Opened output stream to save the image to.
1231 virtual bool SaveFile(wxOutputStream
& stream
, wxBitmapType type
) const;
1234 Returns a scaled version of the image.
1236 This is also useful for scaling bitmaps in general as the only other way
1237 to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
1239 The parameter @a quality determines what method to use for resampling the image.
1240 Can be one of the following:
1241 - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
1243 - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
1244 for upsampling and downsampling respectively
1246 It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
1247 looking results it is a slower method. Downsampling will use the box averaging
1248 method which seems to operate very fast. If you are upsampling larger images using
1249 this method you will most likely notice that it is a bit slower and in extreme
1250 cases it will be quite substantially slower as the bicubic algorithm has to process a
1253 It should also be noted that the high quality scaling may not work as expected
1254 when using a single mask colour for transparency, as the scaling will blur the
1255 image and will therefore remove the mask partially. Using the alpha channel
1260 // get the bitmap from somewhere
1263 // rescale it to have size of 32*32
1264 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
1266 wxImage image = bmp.ConvertToImage();
1267 bmp = wxBitmap(image.Scale(32, 32));
1269 // another possibility:
1270 image.Rescale(32, 32);
1277 wxImage
Scale(int width
, int height
,
1278 int quality
= wxIMAGE_QUALITY_NORMAL
) const;
1281 This function is similar to SetData() and has similar restrictions.
1283 The pointer passed to it may however be @NULL in which case the function
1284 will allocate the alpha array internally -- this is useful to add alpha
1285 channel data to an image which doesn't have any.
1287 If the pointer is not @NULL, it must have one byte for each image pixel
1288 and be allocated with malloc().
1289 wxImage takes ownership of the pointer and will free it unless @a static_data
1290 parameter is set to @true -- in this case the caller should do it.
1292 void SetAlpha(unsigned char* alpha
= NULL
,
1293 bool static_data
= false);
1296 Sets the alpha value for the given pixel.
1297 This function should only be called if the image has alpha channel data,
1298 use HasAlpha() to check for this.
1300 void SetAlpha(int x
, int y
, unsigned char alpha
);
1304 Sets the image data without performing checks.
1306 The data given must have the size (width*height*3) or results will be
1307 unexpected. Don't use this method if you aren't sure you know what you
1310 The data must have been allocated with @c malloc(), @b NOT with
1313 After this call the pointer to the data is owned by the wxImage object,
1314 that will be responsible for deleting it.
1315 Do not pass to this function a pointer obtained through GetData().
1317 void SetData(unsigned char* data
, bool static_data
= false);
1318 void SetData(unsigned char* data
, int new_width
, int new_height
,
1319 bool static_data
= false);
1323 Specifies whether there is a mask or not.
1325 The area of the mask is determined by the current mask colour.
1327 void SetMask(bool hasMask
= true);
1330 Sets the mask colour for this image (and tells the image to use the mask).
1332 void SetMaskColour(unsigned char red
, unsigned char green
,
1333 unsigned char blue
);
1336 Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1337 mask will be masked in the image.
1339 This is done by first finding an unused colour in the image, setting
1340 this colour as the mask colour and then using this colour to draw all
1341 pixels in the image who corresponding pixel in mask has given RGB value.
1343 The parameter @a mask is the mask image to extract mask shape from.
1344 It must have the same dimensions as the image.
1346 The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1347 mask that will be used to create the mask.
1349 @return Returns @false if mask does not have same dimensions as the image
1350 or if there is no unused colour left. Returns @true if the mask
1351 was successfully applied.
1354 Note that this method involves computing the histogram, which is a
1355 computationally intensive operation.
1357 bool SetMaskFromImage(const wxImage
& mask
, unsigned char mr
,
1363 Sets a user-defined option. The function is case-insensitive to @a name.
1365 For example, when saving as a JPEG file, the option @b quality is
1366 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1368 @see GetOption(), GetOptionInt(), HasOption()
1370 void SetOption(const wxString
& name
, const wxString
& value
);
1371 void SetOption(const wxString
& name
, int value
);
1375 Associates a palette with the image.
1377 The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1378 or in file save operations (none as yet).
1380 void SetPalette(const wxPalette
& palette
);
1383 Sets the colour of the pixels within the given rectangle.
1385 This routine performs bounds-checks for the coordinate so it can be considered
1386 a safe way to manipulate the data.
1388 void SetRGB(const wxRect
& rect
,
1390 unsigned char green
,
1391 unsigned char blue
);
1394 Set the type of image returned by GetType().
1396 This method is mostly used internally by the library but can also be
1397 called from the user code if the image was created from data in the
1398 given bitmap format without using LoadFile() (which would set the type
1399 correctly automatically).
1401 Notice that the image must be created before this function is called.
1406 One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1407 value for it and can be used to reset the bitmap type to default
1408 but @c wxBITMAP_TYPE_MAX is not allowed here.
1410 void SetType(wxBitmapType type
);
1413 Returns a resized version of this image without scaling it by adding either a
1414 border with the given colour or cropping as necessary.
1416 The image is pasted into a new image with the given @a size and background
1417 colour at the position @a pos relative to the upper left of the new image.
1419 If @a red = green = blue = -1 then the areas of the larger image not covered
1420 by this image are made transparent by filling them with the image mask colour
1421 (which will be allocated automatically if it isn't currently set).
1423 Otherwise, the areas will be filled with the colour with the specified RGB components.
1427 wxImage
Size(const wxSize
& size
, const wxPoint
& pos
, int red
= -1,
1428 int green
= -1, int blue
= -1) const;
1431 Assignment operator, using @ref overview_refcount "reference counting".
1436 @return Returns 'this' object.
1438 wxImage
& operator=(const wxImage
& image
);
1441 // ============================================================================
1442 // Global functions/macros
1443 // ============================================================================
1445 /** @ingroup group_funcmacro_appinitterm */
1449 Initializes all available image handlers. For a list of available handlers,
1452 @see wxImage, wxImageHandler
1456 void wxInitAllImageHandlers();