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
,
43 Use surrounding pixels to calculate an average that will be used for
44 new pixels. This method is typically used when reducing the size of
47 wxIMAGE_QUALITY_BOX_AVERAGE
,
50 Default image resizing algorithm used by wxImage::Scale(). Currently
51 the same as wxIMAGE_QUALITY_NEAREST.
53 wxIMAGE_QUALITY_NORMAL
,
56 Best image resizing algorithm. Since version 2.9.2 this results in
57 wxIMAGE_QUALITY_BOX_AVERAGE being used when reducing the size of the
58 image (meaning that both the new width and height will be smaller than
59 the original size). Otherwise wxIMAGE_QUALITY_BICUBIC is used.
65 Possible values for PNG image type option.
67 @see wxImage::GetOptionInt().
71 wxPNG_TYPE_COLOUR
= 0, ///< Colour PNG image.
72 wxPNG_TYPE_GREY
= 2, ///< Greyscale PNG image converted from RGB.
73 wxPNG_TYPE_GREY_RED
= 3, ///< Greyscale PNG image using red as grey.
74 wxPNG_TYPE_PALETTE
= 4 ///< Palette encoding.
80 This is the base class for implementing image file loading/saving, and
81 image creation from data.
82 It is used within wxImage and is not normally seen by the application.
84 If you wish to extend the capabilities of wxImage, derive a class from
85 wxImageHandler and add the handler using wxImage::AddHandler in your
86 application initialization.
88 Note that all wxImageHandlers provided by wxWidgets are part of
89 the @ref page_libs_wxcore library.
90 For details about the default handlers, please see the section
91 @ref image_handlers in the wxImage class documentation.
94 @section imagehandler_note Note (Legal Issue)
96 This software is based in part on the work of the Independent JPEG Group.
97 (Applies when wxWidgets is linked with JPEG support.
98 wxJPEGHandler uses libjpeg created by IJG.)
107 @see wxImage, wxInitAllImageHandlers()
109 class wxImageHandler
: public wxObject
115 In your own default constructor, initialise the members
116 m_name, m_extension and m_type.
121 Destroys the wxImageHandler object.
123 virtual ~wxImageHandler();
126 Returns @true if this handler supports the image format contained in the
129 This function doesn't modify the current stream position (because it
130 restores the original position before returning; this however requires the
131 stream to be seekable; see wxStreamBase::IsSeekable).
133 bool CanRead( wxInputStream
& stream
);
136 Returns @true if this handler supports the image format contained in the
137 file with the given name.
139 This function doesn't modify the current stream position (because it
140 restores the original position before returning; this however requires the
141 stream to be seekable; see wxStreamBase::IsSeekable).
143 bool CanRead( const wxString
& filename
);
146 Gets the preferred file extension associated with this handler.
148 @see GetAltExtensions()
150 const wxString
& GetExtension() const;
153 Returns the other file extensions associated with this handler.
155 The preferred extension for this handler is returned by GetExtension().
159 const wxArrayString
& GetAltExtensions() const;
162 If the image file contains more than one image and the image handler is capable
163 of retrieving these individually, this function will return the number of
167 Opened input stream for reading image data.
168 This function doesn't modify the current stream position (because it
169 restores the original position before returning; this however requires the
170 stream to be seekable; see wxStreamBase::IsSeekable).
172 @return Number of available images. For most image handlers, this is 1
173 (exceptions are TIFF and ICO formats as well as animated GIFs
174 for which this function returns the number of frames in the
177 virtual int GetImageCount(wxInputStream
& stream
);
180 Gets the MIME type associated with this handler.
182 const wxString
& GetMimeType() const;
185 Gets the name of this handler.
187 const wxString
& GetName() const;
190 Gets the image type associated with this handler.
192 wxBitmapType
GetType() const;
195 Loads a image from a stream, putting the resulting data into @a image.
197 If the image file contains more than one image and the image handler is
198 capable of retrieving these individually, @a index indicates which image
199 to read from the stream.
202 The image object which is to be affected by this operation.
204 Opened input stream for reading image data.
206 If set to @true, errors reported by the image handler will produce
209 The index of the image in the file (starting from zero).
211 @return @true if the operation succeeded, @false otherwise.
213 @see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
215 virtual bool LoadFile(wxImage
* image
, wxInputStream
& stream
,
216 bool verbose
= true, int index
= -1);
219 Saves a image in the output stream.
222 The image object which is to be affected by this operation.
224 Opened output stream for writing the data.
226 If set to @true, errors reported by the image handler will produce
229 @return @true if the operation succeeded, @false otherwise.
231 @see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
233 virtual bool SaveFile(wxImage
* image
, wxOutputStream
& stream
,
234 bool verbose
= true);
237 Sets the preferred file extension associated with this handler.
240 File extension without leading dot.
242 @see SetAltExtensions()
244 void SetExtension(const wxString
& extension
);
247 Sets the alternative file extensions associated with this handler.
250 Array of file extensions.
256 void SetAltExtensions(const wxArrayString
& extensions
);
259 Sets the handler MIME type.
264 void SetMimeType(const wxString
& mimetype
);
267 Sets the handler name.
272 void SetName(const wxString
& name
);
275 Retrieve the version information about the image library used by this
278 This method is not present in wxImageHandler class itself but is
279 present in a few of the classes deriving from it, currently
280 wxJPEGHandler, wxPNGHandler and wxTIFFHandler. It returns the
281 information about the version of the image library being used for the
282 corresponding handler implementation.
286 static wxVersionInfo
GetLibraryVersionInfo();
291 Constant used to indicate the alpha value conventionally defined as
292 the complete transparency.
294 const unsigned char wxIMAGE_ALPHA_TRANSPARENT
= 0;
297 Constant used to indicate the alpha value conventionally defined as
298 the complete opacity.
300 const unsigned char wxIMAGE_ALPHA_OPAQUE
= 0xff;
305 This class encapsulates a platform-independent image.
307 An image can be created from data, or using wxBitmap::ConvertToImage.
308 An image can be loaded from a file in a variety of formats, and is extensible
309 to new formats via image format handlers. Functions are available to set and
310 get image bits, so it can be used for basic image manipulation.
312 A wxImage cannot (currently) be drawn directly to a wxDC.
313 Instead, a platform-specific wxBitmap object must be created from it using
314 the wxBitmap::wxBitmap(wxImage,int depth) constructor.
315 This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
317 More on the difference between wxImage and wxBitmap: wxImage is just a
318 buffer of RGB bytes with an optional buffer for the alpha bytes. It is all
319 generic, platform independent and image file format independent code. It
320 includes generic code for scaling, resizing, clipping, and other manipulations
321 of the image data. OTOH, wxBitmap is intended to be a wrapper of whatever is
322 the native image format that is quickest/easiest to draw to a DC or to be the
323 target of the drawing operations performed on a wxMemoryDC. By splitting the
324 responsibilities between wxImage/wxBitmap like this then it's easier to use
325 generic code shared by all platforms and image types for generic operations and
326 platform specific code where performance or compatibility is needed.
328 One colour value of the image may be used as a mask colour which will lead to
329 the automatic creation of a wxMask object associated to the bitmap object.
332 @section image_alpha Alpha channel support
334 Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is
335 in addition to a byte for the red, green and blue colour components for each
336 pixel it also stores a byte representing the pixel opacity.
338 An alpha value of 0 corresponds to a transparent pixel (null opacity) while
339 a value of 255 means that the pixel is 100% opaque.
340 The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
341 used to indicate those values in a more readable form.
343 While all images have RGB data, not all images have an alpha channel. Before
344 using wxImage::GetAlpha you should check if this image contains an alpha
345 channel with wxImage::HasAlpha. Currently the BMP, PNG, TGA, and TIFF format
346 handlers have full alpha channel support for loading so if you want to use
347 alpha you have to use one of these formats. If you initialize the image
348 alpha channel yourself using wxImage::SetAlpha, you should save it in
349 either PNG, TGA, or TIFF format to avoid losing it as these are the only
350 handlers that currently support saving with alpha.
353 @section image_handlers Available image handlers
355 The following image handlers are available.
356 wxBMPHandler is always installed by default.
357 To use other image formats, install the appropriate handler with
358 wxImage::AddHandler or call ::wxInitAllImageHandlers().
360 - wxBMPHandler: For loading (including alpha support) and saving, always installed.
361 - wxPNGHandler: For loading and saving. Includes alpha support.
362 - wxJPEGHandler: For loading and saving.
363 - wxGIFHandler: For loading and saving (see below).
364 - wxPCXHandler: For loading and saving (see below).
365 - wxPNMHandler: For loading and saving (see below).
366 - wxTIFFHandler: For loading and saving. Includes alpha support.
367 - wxTGAHandler: For loading and saving. Includes alpha support.
368 - wxIFFHandler: For loading only.
369 - wxXPMHandler: For loading and saving.
370 - wxICOHandler: For loading and saving.
371 - wxCURHandler: For loading and saving.
372 - wxANIHandler: For loading only.
374 When saving in PCX format, wxPCXHandler will count the number of different
375 colours in the image; if there are 256 or less colours, it will save as 8 bit,
376 else it will save as 24 bit.
378 Loading PNMs only works for ASCII or raw RGB images.
379 When saving in PNM format, wxPNMHandler will always save as raw RGB.
381 Saving GIFs requires images of maximum 8 bpp (see wxQuantize), and the alpha channel converted to a mask (see wxImage::ConvertAlphaToMask).
382 Saving an animated GIF requires images of the same size (see wxGIFHandler::SaveAnimation)
390 @see wxBitmap, wxInitAllImageHandlers(), wxPixelData
392 class wxImage
: public wxObject
396 A simple class which stores red, green and blue values as 8 bit unsigned integers
397 in the range of 0-255.
403 Constructor for RGBValue, an object that contains values for red, green
404 and blue which represent the value of a color.
406 It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which convert
407 between HSV color space and RGB color space.
409 RGBValue(unsigned char r
=0, unsigned char g
=0, unsigned char b
=0);
413 A simple class which stores hue, saturation and value as doubles in the range 0.0-1.0.
419 Constructor for HSVValue, an object that contains values for hue, saturation
420 and value which represent the value of a color.
422 It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which convert
423 between HSV color space and RGB color space.
425 HSVValue(double h
=0.0, double s
=0.0, double v
=0.0);
429 Creates an empty wxImage object without an alpha channel.
434 Creates an image with the given size and clears it if requested.
436 Does not create an alpha channel.
439 Specifies the width of the image.
441 Specifies the height of the image.
443 If @true, initialize the image to black.
445 wxImage(int width
, int height
, bool clear
= true);
450 wxImage(const wxSize
& sz
, bool clear
= true);
453 Creates an image from data in memory. If @a static_data is @false
454 then the wxImage will take ownership of the data and free it
455 afterwards. For this, it has to be allocated with @e malloc.
458 Specifies the width of the image.
460 Specifies the height of the image.
462 A pointer to RGB data
464 Indicates if the data should be free'd after use
467 wxImage(int width
, int height
, unsigned char* data
, bool static_data
= false);
472 wxImage(const wxSize
& sz
, unsigned char* data
, bool static_data
= false);
475 Creates an image from data in memory. If @a static_data is @false
476 then the wxImage will take ownership of the data and free it
477 afterwards. For this, it has to be allocated with @e malloc.
480 Specifies the width of the image.
482 Specifies the height of the image.
484 A pointer to RGB data
486 A pointer to alpha-channel data
488 Indicates if the data should be free'd after use
491 wxImage(int width
, int height
, unsigned char* data
, unsigned char* alpha
,
492 bool static_data
= false );
497 wxImage(const wxSize
& sz
, unsigned char* data
, unsigned char* alpha
,
498 bool static_data
= false);
501 Creates an image from XPM data.
504 A pointer to XPM image data.
507 Not supported by wxPerl.
510 wxImage(const char* const* xpmData
);
513 Creates an image from a file.
516 Name of the file from which to load the image.
518 May be one of the following:
519 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
520 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
521 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
522 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
523 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
524 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
525 @li wxBITMAP_TYPE_TIFF: Load a TIFF bitmap file.
526 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
527 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
528 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
529 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
530 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
531 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
533 Index of the image to load in the case that the image file contains
534 multiple images. This is only used by GIF, ICO and TIFF handlers.
535 The default value (-1) means "choose the default image" and is
536 interpreted as the first image (index=0) by the GIF and TIFF handler
537 and as the largest and most colourful one by the ICO handler.
539 @remarks Depending on how wxWidgets has been configured and by which
540 handlers have been loaded, not all formats may be available.
541 Any handler other than BMP must be previously initialized with
542 wxImage::AddHandler or wxInitAllImageHandlers.
545 You can use GetOptionInt() to get the hotspot when loading cursor files:
547 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
548 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
553 wxImage(const wxString
& name
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1);
556 Creates an image from a file using MIME-types to specify the type.
559 Name of the file from which to load the image.
561 MIME type string (for example 'image/jpeg')
563 See description in wxImage(const wxString&, wxBitmapType, int) overload.
565 wxImage(const wxString
& name
, const wxString
& mimetype
, int index
= -1);
568 Creates an image from a stream.
571 Opened input stream from which to load the image. Currently,
572 the stream must support seeking.
574 See description in wxImage(const wxString&, wxBitmapType, int) overload.
576 See description in wxImage(const wxString&, wxBitmapType, int) overload.
578 wxImage(wxInputStream
& stream
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1);
581 Creates an image from a stream using MIME-types to specify the type.
584 Opened input stream from which to load the image. Currently,
585 the stream must support seeking.
587 MIME type string (for example 'image/jpeg')
589 See description in wxImage(const wxString&, wxBitmapType, int) overload.
591 wxImage(wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1);
596 See @ref overview_refcount_destruct "reference-counted object destruction"
604 @name Image creation, initialization and deletion functions
609 Returns an identical copy of this image.
611 wxImage
Copy() const;
614 Creates a fresh image.
615 See wxImage::wxImage(int,int,bool) for more info.
617 @return @true if the call succeeded, @false otherwise.
619 bool Create(int width
, int height
, bool clear
= true);
624 bool Create( const wxSize
& sz
, bool clear
= true );
627 Creates a fresh image.
628 See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
630 @return @true if the call succeeded, @false otherwise.
632 bool Create( int width
, int height
, unsigned char* data
, bool static_data
= false );
637 bool Create( const wxSize
& sz
, unsigned char* data
, bool static_data
= false );
640 Creates a fresh image.
641 See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
643 @return @true if the call succeeded, @false otherwise.
645 bool Create( int width
, int height
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
650 bool Create( const wxSize
& sz
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
653 Initialize the image data with zeroes (the default) or with the
654 byte value given as @a value.
658 void Clear(unsigned char value
= 0);
661 Destroys the image data.
666 Initializes the image alpha channel data.
668 It is an error to call it if the image already has alpha data.
669 If it doesn't, alpha data will be by default initialized to all pixels
670 being fully opaque. But if the image has a mask colour, all mask pixels
671 will be completely transparent.
679 @name Image manipulation functions
684 Blurs the image in both horizontal and vertical directions by the
685 specified pixel @a blurRadius. This should not be used when using
686 a single mask colour for transparency.
688 @see BlurHorizontal(), BlurVertical()
690 wxImage
Blur(int blurRadius
) const;
693 Blurs the image in the horizontal direction only. This should not be used
694 when using a single mask colour for transparency.
696 @see Blur(), BlurVertical()
698 wxImage
BlurHorizontal(int blurRadius
) const;
701 Blurs the image in the vertical direction only. This should not be used
702 when using a single mask colour for transparency.
704 @see Blur(), BlurHorizontal()
706 wxImage
BlurVertical(int blurRadius
) const;
709 Returns a mirrored copy of the image.
710 The parameter @a horizontally indicates the orientation.
712 wxImage
Mirror(bool horizontally
= true) const;
715 Copy the data of the given @a image to the specified position in this image.
717 void Paste(const wxImage
& image
, int x
, int y
);
720 Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
722 void Replace(unsigned char r1
, unsigned char g1
,
723 unsigned char b1
, unsigned char r2
,
724 unsigned char g2
, unsigned char b2
);
727 Changes the size of the image in-place by scaling it: after a call to this
728 function,the image will have the given width and height.
730 For a description of the @a quality parameter, see the Scale() function.
731 Returns the (modified) image itself.
735 wxImage
& Rescale(int width
, int height
,
736 wxImageResizeQuality quality
= wxIMAGE_QUALITY_NORMAL
);
739 Changes the size of the image in-place without scaling it by adding either a
740 border with the given colour or cropping as necessary.
742 The image is pasted into a new image with the given @a size and background
743 colour at the position @a pos relative to the upper left of the new image.
745 If @a red = green = blue = -1 then use either the current mask colour
746 if set or find, use, and set a suitable mask colour for any newly exposed
749 @return The (modified) image itself.
753 wxImage
& Resize(const wxSize
& size
, const wxPoint
& pos
, int red
= -1,
754 int green
= -1, int blue
= -1);
757 Rotates the image about the given point, by @a angle radians.
759 Passing @true to @a interpolating results in better image quality, but is slower.
761 If the image has a mask, then the mask colour is used for the uncovered
762 pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
764 Returns the rotated image, leaving this image intact.
766 wxImage
Rotate(double angle
, const wxPoint
& rotationCentre
,
767 bool interpolating
= true,
768 wxPoint
* offsetAfterRotation
= NULL
) const;
771 Returns a copy of the image rotated 90 degrees in the direction
772 indicated by @a clockwise.
774 wxImage
Rotate90(bool clockwise
= true) const;
777 Returns a copy of the image rotated by 180 degrees.
781 wxImage
Rotate180() const;
784 Rotates the hue of each pixel in the image by @e angle, which is a double in
785 the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
786 corresponds to +360 degrees.
788 void RotateHue(double angle
);
791 Returns a scaled version of the image.
793 This is also useful for scaling bitmaps in general as the only other way
794 to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
796 The parameter @a quality determines what method to use for resampling
797 the image, see wxImageResizeQuality documentation.
799 It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
800 looking results it is a slower method. Downsampling will use the box averaging
801 method which seems to operate very fast. If you are upsampling larger images using
802 this method you will most likely notice that it is a bit slower and in extreme
803 cases it will be quite substantially slower as the bicubic algorithm has to process a
806 It should also be noted that the high quality scaling may not work as expected
807 when using a single mask colour for transparency, as the scaling will blur the
808 image and will therefore remove the mask partially. Using the alpha channel
813 // get the bitmap from somewhere
816 // rescale it to have size of 32*32
817 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
819 wxImage image = bmp.ConvertToImage();
820 bmp = wxBitmap(image.Scale(32, 32));
822 // another possibility:
823 image.Rescale(32, 32);
830 wxImage
Scale(int width
, int height
,
831 wxImageResizeQuality quality
= wxIMAGE_QUALITY_NORMAL
) const;
834 Returns a resized version of this image without scaling it by adding either a
835 border with the given colour or cropping as necessary.
837 The image is pasted into a new image with the given @a size and background
838 colour at the position @a pos relative to the upper left of the new image.
840 If @a red = green = blue = -1 then the areas of the larger image not covered
841 by this image are made transparent by filling them with the image mask colour
842 (which will be allocated automatically if it isn't currently set).
844 Otherwise, the areas will be filled with the colour with the specified RGB components.
848 wxImage
Size(const wxSize
& size
, const wxPoint
& pos
, int red
= -1,
849 int green
= -1, int blue
= -1) const;
855 @name Conversion functions
860 If the image has alpha channel, this method converts it to mask.
862 If the image has an alpha channel, all pixels with alpha value less
863 than @a threshold are replaced with the mask colour and the alpha
864 channel is removed. Otherwise nothing is done.
866 The mask colour is chosen automatically using
867 FindFirstUnusedColour() by this function, see the overload below if you
868 this is not appropriate.
870 @return Returns @true on success, @false on error.
872 bool ConvertAlphaToMask(unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
875 If the image has alpha channel, this method converts it to mask using
876 the specified colour as the mask colour.
878 If the image has an alpha channel, all pixels with alpha value less
879 than @a threshold are replaced with the mask colour and the alpha
880 channel is removed. Otherwise nothing is done.
885 The red component of the mask colour.
887 The green component of the mask colour.
889 The blue component of the mask colour.
891 Pixels with alpha channel values below the given threshold are
892 considered to be transparent, i.e. the corresponding mask pixels
893 are set. Pixels with the alpha values above the threshold are
894 considered to be opaque.
896 @return Returns @true on success, @false on error.
898 bool ConvertAlphaToMask(unsigned char mr
, unsigned char mg
, unsigned char mb
,
899 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
902 Returns a greyscale version of the image.
904 The returned image uses the luminance component of the original to
905 calculate the greyscale. Defaults to using the standard ITU-T BT.601
906 when converting to YUV, where every pixel equals
907 (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
909 wxImage
ConvertToGreyscale(double weight_r
, double weight_g
, double weight_b
) const;
912 Returns a greyscale version of the image.
915 wxImage
ConvertToGreyscale() const;
918 Returns monochromatic version of the image.
920 The returned image has white colour where the original has @e (r,g,b)
921 colour and black colour everywhere else.
923 wxImage
ConvertToMono(unsigned char r
, unsigned char g
, unsigned char b
) const;
926 Returns disabled (dimmed) version of the image.
929 wxImage
ConvertToDisabled(unsigned char brightness
= 255) const;
935 @name Miscellaneous functions
940 Computes the histogram of the image. @a histogram is a reference to
941 wxImageHistogram object. wxImageHistogram is a specialization of
942 wxHashMap "template" and is defined as follows:
945 class WXDLLEXPORT wxImageHistogramEntry
948 wxImageHistogramEntry() : index(0), value(0) {}
953 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
954 wxIntegerHash, wxIntegerEqual,
958 @return Returns number of colours in the histogram.
960 unsigned long ComputeHistogram(wxImageHistogram
& histogram
) const;
963 Finds the first colour that is never used in the image.
964 The search begins at given initial colour and continues by increasing
965 R, G and B components (in this order) by 1 until an unused colour is
966 found or the colour space exhausted.
968 The parameters @a r, @a g, @a b are pointers to variables to save the colour.
970 The parameters @a startR, @a startG, @a startB define the initial values
972 The returned colour will have RGB values equal to or greater than these.
974 @return Returns @false if there is no unused colour left, @true on success.
977 This method involves computing the histogram, which is a
978 computationally intensive operation.
980 bool FindFirstUnusedColour(unsigned char* r
, unsigned char* g
,
981 unsigned char* b
, unsigned char startR
= 1,
982 unsigned char startG
= 0,
983 unsigned char startB
= 0) const;
986 Assignment operator, using @ref overview_refcount "reference counting".
991 @return Returns 'this' object.
993 wxImage
& operator=(const wxImage
& image
);
1004 Returns pointer to the array storing the alpha values for this image.
1006 This pointer is @NULL for the images without the alpha channel. If the image
1007 does have it, this pointer may be used to directly manipulate the alpha values
1008 which are stored as the RGB ones.
1010 unsigned char* GetAlpha() const;
1013 Returns the image data as an array.
1015 This is most often used when doing direct image manipulation.
1016 The return value points to an array of characters in RGBRGBRGB... format
1017 in the top-to-bottom, left-to-right order, that is the first RGB triplet
1018 corresponds to the pixel first pixel of the first row, the second one ---
1019 to the second pixel of the first row and so on until the end of the first
1020 row, with second row following after it and so on.
1022 You should not delete the returned pointer nor pass it to SetData().
1024 unsigned char* GetData() const;
1027 Return alpha value at given pixel location.
1029 unsigned char GetAlpha(int x
, int y
) const;
1032 Returns the red intensity at the given coordinate.
1034 unsigned char GetRed(int x
, int y
) const;
1037 Returns the green intensity at the given coordinate.
1039 unsigned char GetGreen(int x
, int y
) const;
1042 Returns the blue intensity at the given coordinate.
1044 unsigned char GetBlue(int x
, int y
) const;
1047 Gets the red value of the mask colour.
1049 unsigned char GetMaskRed() const;
1052 Gets the green value of the mask colour.
1054 unsigned char GetMaskGreen() const;
1057 Gets the blue value of the mask colour.
1059 unsigned char GetMaskBlue() const;
1062 Gets the width of the image in pixels.
1064 @see GetHeight(), GetSize()
1066 int GetWidth() const;
1069 Gets the height of the image in pixels.
1071 @see GetWidth(), GetSize()
1073 int GetHeight() const;
1076 Returns the size of the image in pixels.
1080 @see GetHeight(), GetWidth()
1082 wxSize
GetSize() const;
1085 Gets a user-defined string-valued option.
1088 @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
1091 Options specific to wxGIFHandler:
1092 @li @c wxIMAGE_OPTION_GIF_COMMENT: The comment text that is read from
1093 or written to the GIF file. In an animated GIF each frame can have
1094 its own comment. If there is only a comment in the first frame of
1095 a GIF it will not be repeated in other frames.
1098 The name of the option, case-insensitive.
1100 The value of the option or an empty string if not found. Use
1101 HasOption() if an empty string can be a valid option value.
1103 @see SetOption(), GetOptionInt(), HasOption()
1105 wxString
GetOption(const wxString
& name
) const;
1108 Gets a user-defined integer-valued option.
1110 The function is case-insensitive to @a name.
1111 If the given option is not present, the function returns 0.
1112 Use HasOption() if 0 is a possibly valid value for the option.
1115 @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
1116 of these options is specified, the loaded image will be scaled down
1117 (preserving its aspect ratio) so that its width is less than the
1118 max width given if it is not 0 @em and its height is less than the
1119 max height given if it is not 0. This is typically used for loading
1120 thumbnails and the advantage of using these options compared to
1121 calling Rescale() after loading is that some handlers (only JPEG
1122 one right now) support rescaling the image during loading which is
1123 vastly more efficient than loading the entire huge image and
1124 rescaling it later (if these options are not supported by the
1125 handler, this is still what happens however). These options must be
1126 set before calling LoadFile() to have any effect.
1128 @li @c wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
1129 integer in 0..100 range with 0 meaning very poor and 100 excellent
1130 (but very badly compressed). This option is currently ignored for
1133 @li @c wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
1134 whether the resolution of the image is specified in centimetres or
1135 inches, see wxImageResolution enum elements.
1137 @li @c wxIMAGE_OPTION_RESOLUTION, @c wxIMAGE_OPTION_RESOLUTIONX and
1138 @c wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
1139 the image in the units corresponding to @c wxIMAGE_OPTION_RESOLUTIONUNIT
1140 options value. The first option can be set before saving the image
1141 to set both horizontal and vertical resolution to the same value.
1142 The X and Y options are set by the image handlers if they support
1143 the image resolution (currently BMP, JPEG and TIFF handlers do) and
1144 the image provides the resolution information and can be queried
1145 after loading the image.
1147 Options specific to wxPNGHandler:
1148 @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
1149 wxImagePNGType for the supported values.
1150 @li @c wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
1151 @li @c wxIMAGE_OPTION_PNG_FILTER: Filter for saving a PNG file, see libpng
1152 (http://www.libpng.org/pub/png/libpng-1.2.5-manual.html) for possible values
1153 (e.g. PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FILTER_UP, etc).
1154 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL: Compression level (0..9) for
1155 saving a PNG file. An high value creates smaller-but-slower PNG file.
1156 Note that unlike other formats (e.g. JPEG) the PNG format is always
1157 lossless and thus this compression level doesn't tradeoff the image
1159 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL: Compression memory usage
1160 level (1..9) for saving a PNG file. An high value means the saving
1161 process consumes more memory, but may create smaller PNG file.
1162 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY: Possible values are 0 for
1163 default strategy, 1 for filter, and 2 for Huffman-only.
1164 You can use OptiPNG (http://optipng.sourceforge.net/) to get a suitable
1165 value for your application.
1166 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE: Internal buffer size
1167 (in bytes) for saving a PNG file. Ideally this should be as big as
1168 the resulting PNG file. Use this option if your application produces
1169 images with small size variation.
1171 Options specific to wxTIFFHandler:
1172 @li @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE: Number of bits per
1173 sample (channel). Currently values of 1 and 8 are supported. A
1174 value of 1 results in a black and white image. A value of 8 (the
1175 default) can mean greyscale or RGB, depending on the value of
1176 @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL.
1177 @li @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL: Number of samples
1178 (channels) per pixel. Currently values of 1 and 3 are supported.
1179 A value of 1 results in either a greyscale (by default) or black and
1180 white image, depending on the value of
1181 @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE. A value of 3 (the default)
1182 will result in an RGB image.
1183 @li @c wxIMAGE_OPTION_TIFF_COMPRESSION: Compression type. By default
1184 it is set to 1 (COMPRESSION_NONE). Typical other values are
1185 5 (COMPRESSION_LZW) and 7 (COMPRESSION_JPEG). See tiff.h for more
1187 @li @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC: Specifies the photometric
1188 interpretation. By default it is set to 2 (PHOTOMETRIC_RGB) for RGB
1189 images and 0 (PHOTOMETRIC_MINISWHITE) for greyscale or black and
1190 white images. It can also be set to 1 (PHOTOMETRIC_MINISBLACK) to
1191 treat the lowest value as black and highest as white.
1192 If you want a greyscale image it is also sufficient to only specify
1193 @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC and set it to either
1194 PHOTOMETRIC_MINISWHITE or PHOTOMETRIC_MINISBLACK. The other values
1198 Be careful when combining the options @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL,
1199 @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE, and @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC.
1200 While some measures are taken to prevent illegal combinations and/or
1201 values, it is still easy to abuse them and come up with invalid
1202 results in the form of either corrupted images or crashes.
1205 The name of the option, case-insensitive.
1207 The value of the option or 0 if not found.
1208 Use HasOption() if 0 can be a valid option value.
1210 @see SetOption(), GetOption()
1212 int GetOptionInt(const wxString
& name
) const;
1215 Get the current mask colour or find a suitable unused colour that could be
1216 used as a mask colour. Returns @true if the image currently has a mask.
1218 bool GetOrFindMaskColour(unsigned char* r
, unsigned char* g
,
1219 unsigned char* b
) const;
1222 Returns the palette associated with the image.
1223 Currently the palette is only used when converting to wxBitmap under Windows.
1225 Some of the wxImage handlers have been modified to set the palette if
1226 one exists in the image file (usually 256 or less colour images in
1229 const wxPalette
& GetPalette() const;
1232 Returns a sub image of the current one as long as the rect belongs entirely
1235 wxImage
GetSubImage(const wxRect
& rect
) const;
1238 Gets the type of image found by LoadFile() or specified with SaveFile().
1242 wxBitmapType
GetType() const;
1245 Returns @true if this image has alpha channel, @false otherwise.
1247 @see GetAlpha(), SetAlpha()
1249 bool HasAlpha() const;
1252 Returns @true if there is a mask active, @false otherwise.
1254 bool HasMask() const;
1257 Returns @true if the given option is present.
1258 The function is case-insensitive to @a name.
1260 The lists of the currently supported options are in GetOption() and
1261 GetOptionInt() function docs.
1263 @see SetOption(), GetOption(), GetOptionInt()
1265 bool HasOption(const wxString
& name
) const;
1268 Returns @true if image data is present.
1273 Returns @true if the given pixel is transparent, i.e. either has the mask
1274 colour if this image has a mask or if this image has alpha channel and alpha
1275 value of this pixel is strictly less than @a threshold.
1277 bool IsTransparent(int x
, int y
,
1278 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
) const;
1284 @name Loading and saving functions
1289 Loads an image from an input stream.
1292 Opened input stream from which to load the image.
1293 Currently, the stream must support seeking.
1295 May be one of the following:
1296 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1297 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1298 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1299 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1300 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1301 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1302 @li wxBITMAP_TYPE_TIFF: Load a TIFF bitmap file.
1303 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1304 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1305 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1306 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1307 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1308 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1310 Index of the image to load in the case that the image file contains
1311 multiple images. This is only used by GIF, ICO and TIFF handlers.
1312 The default value (-1) means "choose the default image" and is
1313 interpreted as the first image (index=0) by the GIF and TIFF handler
1314 and as the largest and most colourful one by the ICO handler.
1316 @return @true if the operation succeeded, @false otherwise.
1317 If the optional index parameter is out of range, @false is
1318 returned and a call to wxLogError() takes place.
1320 @remarks Depending on how wxWidgets has been configured, not all formats
1324 You can use GetOptionInt() to get the hotspot when loading cursor files:
1326 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
1327 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
1332 virtual bool LoadFile(wxInputStream
& stream
,
1333 wxBitmapType type
= wxBITMAP_TYPE_ANY
,
1337 Loads an image from a file.
1338 If no handler type is provided, the library will try to autodetect the format.
1341 Name of the file from which to load the image.
1343 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1345 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1347 virtual bool LoadFile(const wxString
& name
,
1348 wxBitmapType type
= wxBITMAP_TYPE_ANY
,
1352 Loads an image from a file.
1353 If no handler type is provided, the library will try to autodetect the format.
1356 Name of the file from which to load the image.
1358 MIME type string (for example 'image/jpeg')
1360 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1362 virtual bool LoadFile(const wxString
& name
, const wxString
& mimetype
,
1366 Loads an image from an input stream.
1369 Opened input stream from which to load the image.
1370 Currently, the stream must support seeking.
1372 MIME type string (for example 'image/jpeg')
1374 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1376 virtual bool LoadFile(wxInputStream
& stream
, const wxString
& mimetype
,
1380 Saves an image in the given stream.
1383 Opened output stream to save the image to.
1387 @return @true if the operation succeeded, @false otherwise.
1389 @remarks Depending on how wxWidgets has been configured, not all formats
1393 You can use SetOption() to set the hotspot when saving an image
1394 into a cursor file (default hotspot is in the centre of the image):
1396 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1397 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1402 virtual bool SaveFile(wxOutputStream
& stream
,
1403 const wxString
& mimetype
) const;
1406 Saves an image in the named file.
1409 Name of the file to save the image to.
1411 Currently these types can be used:
1412 @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1413 @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1414 @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1415 @li wxBITMAP_TYPE_PCX: Save a PCX image file
1416 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1417 @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1418 @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1419 @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1420 @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1421 The size may be up to 255 wide by 127 high. A single image is saved
1422 in 8 colors at the size supplied.
1423 @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1425 virtual bool SaveFile(const wxString
& name
, wxBitmapType type
) const;
1428 Saves an image in the named file.
1431 Name of the file to save the image to.
1435 virtual bool SaveFile(const wxString
& name
, const wxString
& mimetype
) const;
1438 Saves an image in the named file.
1440 File type is determined from the extension of the file name.
1441 Note that this function may fail if the extension is not recognized!
1442 You can use one of the forms above to save images to files with
1443 non-standard extensions.
1446 Name of the file to save the image to.
1448 virtual bool SaveFile(const wxString
& name
) const;
1451 Saves an image in the given stream.
1454 Opened output stream to save the image to.
1458 virtual bool SaveFile(wxOutputStream
& stream
, wxBitmapType type
) const;
1470 This function is similar to SetData() and has similar restrictions.
1472 The pointer passed to it may however be @NULL in which case the function
1473 will allocate the alpha array internally -- this is useful to add alpha
1474 channel data to an image which doesn't have any.
1476 If the pointer is not @NULL, it must have one byte for each image pixel
1477 and be allocated with malloc().
1478 wxImage takes ownership of the pointer and will free it unless @a static_data
1479 parameter is set to @true -- in this case the caller should do it.
1481 void SetAlpha(unsigned char* alpha
= NULL
,
1482 bool static_data
= false);
1485 Sets the alpha value for the given pixel.
1486 This function should only be called if the image has alpha channel data,
1487 use HasAlpha() to check for this.
1489 void SetAlpha(int x
, int y
, unsigned char alpha
);
1492 Removes the alpha channel from the image.
1494 This function should only be called if the image has alpha channel data,
1495 use HasAlpha() to check for this.
1502 Sets the image data without performing checks.
1504 The data given must have the size (width*height*3) or results will be
1505 unexpected. Don't use this method if you aren't sure you know what you
1508 The data must have been allocated with @c malloc(), @b NOT with
1511 If @a static_data is @false, after this call the pointer to the data is
1512 owned by the wxImage object, that will be responsible for deleting it.
1513 Do not pass to this function a pointer obtained through GetData().
1515 void SetData(unsigned char* data
, bool static_data
= false);
1520 void SetData(unsigned char* data
, int new_width
, int new_height
,
1521 bool static_data
= false);
1524 Specifies whether there is a mask or not.
1526 The area of the mask is determined by the current mask colour.
1528 void SetMask(bool hasMask
= true);
1531 Sets the mask colour for this image (and tells the image to use the mask).
1533 void SetMaskColour(unsigned char red
, unsigned char green
,
1534 unsigned char blue
);
1537 Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1538 mask will be masked in the image.
1540 This is done by first finding an unused colour in the image, setting
1541 this colour as the mask colour and then using this colour to draw all
1542 pixels in the image who corresponding pixel in mask has given RGB value.
1544 The parameter @a mask is the mask image to extract mask shape from.
1545 It must have the same dimensions as the image.
1547 The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1548 mask that will be used to create the mask.
1550 @return Returns @false if mask does not have same dimensions as the image
1551 or if there is no unused colour left. Returns @true if the mask
1552 was successfully applied.
1555 Note that this method involves computing the histogram, which is a
1556 computationally intensive operation.
1558 bool SetMaskFromImage(const wxImage
& mask
, unsigned char mr
,
1563 Sets a user-defined option. The function is case-insensitive to @a name.
1565 For example, when saving as a JPEG file, the option @b quality is
1566 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1568 The lists of the currently supported options are in GetOption() and
1569 GetOptionInt() function docs.
1571 @see GetOption(), GetOptionInt(), HasOption()
1573 void SetOption(const wxString
& name
, const wxString
& value
);
1578 void SetOption(const wxString
& name
, int value
);
1581 Associates a palette with the image.
1583 The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1584 or in file save operations (none as yet).
1586 void SetPalette(const wxPalette
& palette
);
1589 Sets the colour of the pixels within the given rectangle.
1591 This routine performs bounds-checks for the coordinate so it can be considered
1592 a safe way to manipulate the data.
1594 void SetRGB(const wxRect
& rect
,
1596 unsigned char green
,
1597 unsigned char blue
);
1600 Set the type of image returned by GetType().
1602 This method is mostly used internally by the library but can also be
1603 called from the user code if the image was created from data in the
1604 given bitmap format without using LoadFile() (which would set the type
1605 correctly automatically).
1607 Notice that the image must be created before this function is called.
1612 One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1613 value for it and can be used to reset the bitmap type to default
1614 but @c wxBITMAP_TYPE_MAX is not allowed here.
1616 void SetType(wxBitmapType type
);
1623 @name Handler management functions
1628 Register an image handler.
1630 Typical example of use:
1632 wxImage::AddHandler(new wxPNGHandler);
1635 See @ref image_handlers for a list of the available handlers. You can
1636 also use ::wxInitAllImageHandlers() to add handlers for all the image
1637 formats supported by wxWidgets at once.
1640 A heap-allocated handler object which will be deleted by wxImage
1641 if it is removed later by RemoveHandler() or at program shutdown.
1643 static void AddHandler(wxImageHandler
* handler
);
1646 Deletes all image handlers.
1647 This function is called by wxWidgets on exit.
1649 static void CleanUpHandlers();
1652 Finds the handler with the given name.
1657 @return A pointer to the handler if found, @NULL otherwise.
1661 static wxImageHandler
* FindHandler(const wxString
& name
);
1664 Finds the handler associated with the given extension and type.
1667 The file extension, such as "bmp".
1669 The image type; one of the ::wxBitmapType values.
1671 @return A pointer to the handler if found, @NULL otherwise.
1675 static wxImageHandler
* FindHandler(const wxString
& extension
,
1676 wxBitmapType imageType
);
1679 Finds the handler associated with the given image type.
1682 The image type; one of the ::wxBitmapType values.
1684 @return A pointer to the handler if found, @NULL otherwise.
1688 static wxImageHandler
* FindHandler(wxBitmapType imageType
);
1691 Finds the handler associated with the given MIME type.
1696 @return A pointer to the handler if found, @NULL otherwise.
1700 static wxImageHandler
* FindHandlerMime(const wxString
& mimetype
);
1703 Returns the static list of image format handlers.
1707 static wxList
& GetHandlers();
1710 Internal use only. Adds standard image format handlers.
1711 It only install wxBMPHandler for the time being, which is used by wxBitmap.
1713 This function is called by wxWidgets on startup, and shouldn't be called by
1716 @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
1718 static void InitStandardHandlers();
1721 Adds a handler at the start of the static list of format handlers.
1724 A new image format handler object. There is usually only one instance
1725 of a given handler class in an application session.
1729 static void InsertHandler(wxImageHandler
* handler
);
1732 Finds the handler with the given name, and removes it.
1734 The handler is also deleted.
1739 @return @true if the handler was found and removed, @false otherwise.
1743 static bool RemoveHandler(const wxString
& name
);
1749 Returns @true if at least one of the available image handlers can read
1750 the file with the given name.
1752 See wxImageHandler::CanRead for more info.
1754 static bool CanRead(const wxString
& filename
);
1757 Returns @true if at least one of the available image handlers can read
1758 the data in the given stream.
1760 See wxImageHandler::CanRead for more info.
1762 static bool CanRead(wxInputStream
& stream
);
1766 If the image file contains more than one image and the image handler is
1767 capable of retrieving these individually, this function will return the
1768 number of available images.
1770 For the overload taking the parameter @a filename, that's the name
1771 of the file to query.
1772 For the overload taking the parameter @a stream, that's the opened input
1773 stream with image data.
1775 See wxImageHandler::GetImageCount() for more info.
1777 The parameter @a type may be one of the following values:
1778 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1779 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1780 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1781 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1782 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1783 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1784 @li wxBITMAP_TYPE_TIFF: Load a TIFF bitmap file.
1785 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1786 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1787 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1788 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1789 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1790 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1792 @return Number of available images. For most image handlers, this is 1
1793 (exceptions are TIFF and ICO formats as well as animated GIFs
1794 for which this function returns the number of frames in the
1797 static int GetImageCount(const wxString
& filename
,
1798 wxBitmapType type
= wxBITMAP_TYPE_ANY
);
1799 static int GetImageCount(wxInputStream
& stream
,
1800 wxBitmapType type
= wxBITMAP_TYPE_ANY
);
1804 Iterates all registered wxImageHandler objects, and returns a string containing
1805 file extension masks suitable for passing to file open/save dialog boxes.
1807 @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
1808 It is usually a good idea to prepend a description before passing
1809 the result to the dialog.
1812 wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
1813 _("Image Files ") + wxImage::GetImageExtWildcard(),
1819 static wxString
GetImageExtWildcard();
1822 Converts a color in RGB color space to HSV color space.
1824 static wxImage::HSVValue
RGBtoHSV(const wxImage::RGBValue
& rgb
);
1827 Converts a color in HSV color space to RGB color space.
1829 static wxImage::RGBValue
HSVtoRGB(const wxImage::HSVValue
& hsv
);
1833 class wxImageHistogram
: public wxImageHistogramBase
1838 // get the key in the histogram for the given RGB values
1839 static unsigned long MakeKey(unsigned char r
,
1843 // find first colour that is not used in the image and has higher
1844 // RGB values than RGB(startR, startG, startB)
1846 // returns true and puts this colour in r, g, b (each of which may be NULL)
1847 // on success or returns false if there are no more free colours
1848 bool FindFirstUnusedColour(unsigned char *r
,
1851 unsigned char startR
= 1,
1852 unsigned char startG
= 0,
1853 unsigned char startB
= 0 ) const;
1857 An instance of an empty image without an alpha channel.
1859 wxImage wxNullImage
;
1862 // ============================================================================
1863 // Global functions/macros
1864 // ============================================================================
1866 /** @addtogroup group_funcmacro_appinitterm */
1870 Initializes all available image handlers.
1872 This function calls wxImage::AddHandler() for all the available image
1873 handlers (see @ref image_handlers for the full list). Calling it is the
1874 simplest way to initialize wxImage but it creates and registers even the
1875 handlers your program may not use. If you want to avoid the overhead of
1876 doing this you need to call wxImage::AddHandler() manually just for the
1877 handlers that you do want to use.
1879 @see wxImage, wxImageHandler
1883 void wxInitAllImageHandlers();