]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/image.h
Move SendIdleEvents() from wxApp to wxWindow.
[wxWidgets.git] / interface / wx / image.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: image.h
3 // Purpose: interface of wxImageHandler and wxImage
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 Possible values for the image resolution option.
11
12 @see wxImage::GetOptionInt().
13 */
14 enum wxImageResolution
15 {
16 /// Resolution not specified.
17 wxIMAGE_RESOLUTION_NONE = 0,
18
19 /// Resolution specified in inches.
20 wxIMAGE_RESOLUTION_INCHES = 1,
21
22 /// Resolution specified in centimetres.
23 wxIMAGE_RESOLUTION_CM = 2
24 };
25
26 /**
27 Image resize algorithm.
28
29 This is used with wxImage::Scale() and wxImage::Rescale().
30 */
31 enum wxImageResizeQuality
32 {
33 /// Simplest and fastest algorithm.
34 wxIMAGE_QUALITY_NEAREST,
35
36 /// Compromise between wxIMAGE_QUALITY_NEAREST and wxIMAGE_QUALITY_BICUBIC.
37 wxIMAGE_QUALITY_BILINEAR,
38
39 /// Highest quality but slowest execution time.
40 wxIMAGE_QUALITY_BICUBIC,
41
42 /// Default image resizing algorithm used by wxImage::Scale().
43 wxIMAGE_QUALITY_NORMAL,
44
45 /// Best image resizing algorithm, currently same as wxIMAGE_QUALITY_BICUBIC.
46 wxIMAGE_QUALITY_HIGH
47 };
48
49 /**
50 Possible values for PNG image type option.
51
52 @see wxImage::GetOptionInt().
53 */
54 enum wxImagePNGType
55 {
56 wxPNG_TYPE_COLOUR = 0, ///< Colour PNG image.
57 wxPNG_TYPE_GREY = 2, ///< Greyscale PNG image converted from RGB.
58 wxPNG_TYPE_GREY_RED = 3, ///< Greyscale PNG image using red as grey.
59 wxPNG_TYPE_PALETTE = 4 ///< Palette encoding.
60 };
61
62 /**
63 @class wxImageHandler
64
65 This is the base class for implementing image file loading/saving, and
66 image creation from data.
67 It is used within wxImage and is not normally seen by the application.
68
69 If you wish to extend the capabilities of wxImage, derive a class from
70 wxImageHandler and add the handler using wxImage::AddHandler in your
71 application initialization.
72
73 Note that all wxImageHandlers provided by wxWidgets are part of
74 the @ref page_libs_wxcore library.
75 For details about the default handlers, please see the section
76 @ref image_handlers in the wxImage class documentation.
77
78
79 @section imagehandler_note Note (Legal Issue)
80
81 This software is based in part on the work of the Independent JPEG Group.
82 (Applies when wxWidgets is linked with JPEG support.
83 wxJPEGHandler uses libjpeg created by IJG.)
84
85
86 @stdobjects
87 ::wxNullImage
88
89 @library{wxcore}
90 @category{gdi}
91
92 @see wxImage, wxInitAllImageHandlers()
93 */
94 class wxImageHandler : public wxObject
95 {
96 public:
97 /**
98 Default constructor.
99
100 In your own default constructor, initialise the members
101 m_name, m_extension and m_type.
102 */
103 wxImageHandler();
104
105 /**
106 Destroys the wxImageHandler object.
107 */
108 virtual ~wxImageHandler();
109
110 /**
111 Returns @true if this handler supports the image format contained in the
112 given stream.
113
114 This function doesn't modify the current stream position (because it
115 restores the original position before returning; this however requires the
116 stream to be seekable; see wxStreamBase::IsSeekable).
117 */
118 bool CanRead( wxInputStream& stream );
119
120 /**
121 Returns @true if this handler supports the image format contained in the
122 file with the given name.
123
124 This function doesn't modify the current stream position (because it
125 restores the original position before returning; this however requires the
126 stream to be seekable; see wxStreamBase::IsSeekable).
127 */
128 bool CanRead( const wxString& filename );
129
130 /**
131 Gets the preferred file extension associated with this handler.
132
133 @see GetAltExtensions()
134 */
135 const wxString& GetExtension() const;
136
137 /**
138 Returns the other file extensions associated with this handler.
139
140 The preferred extension for this handler is returned by GetExtension().
141
142 @since 2.9.0
143 */
144 const wxArrayString& GetAltExtensions() const;
145
146 /**
147 If the image file contains more than one image and the image handler is capable
148 of retrieving these individually, this function will return the number of
149 available images.
150
151 @param stream
152 Opened input stream for reading image data.
153 This function doesn't modify the current stream position (because it
154 restores the original position before returning; this however requires the
155 stream to be seekable; see wxStreamBase::IsSeekable).
156
157 @return Number of available images. For most image handlers, this is 1
158 (exceptions are TIFF and ICO formats as well as animated GIFs
159 for which this function returns the number of frames in the
160 animation).
161 */
162 virtual int GetImageCount(wxInputStream& stream);
163
164 /**
165 Gets the MIME type associated with this handler.
166 */
167 const wxString& GetMimeType() const;
168
169 /**
170 Gets the name of this handler.
171 */
172 const wxString& GetName() const;
173
174 /**
175 Gets the image type associated with this handler.
176 */
177 wxBitmapType GetType() const;
178
179 /**
180 Loads a image from a stream, putting the resulting data into @a image.
181
182 If the image file contains more than one image and the image handler is
183 capable of retrieving these individually, @a index indicates which image
184 to read from the stream.
185
186 @param image
187 The image object which is to be affected by this operation.
188 @param stream
189 Opened input stream for reading image data.
190 @param verbose
191 If set to @true, errors reported by the image handler will produce
192 wxLogMessages.
193 @param index
194 The index of the image in the file (starting from zero).
195
196 @return @true if the operation succeeded, @false otherwise.
197
198 @see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
199 */
200 virtual bool LoadFile(wxImage* image, wxInputStream& stream,
201 bool verbose = true, int index = -1);
202
203 /**
204 Saves a image in the output stream.
205
206 @param image
207 The image object which is to be affected by this operation.
208 @param stream
209 Opened output stream for writing the data.
210 @param verbose
211 If set to @true, errors reported by the image handler will produce
212 wxLogMessages.
213
214 @return @true if the operation succeeded, @false otherwise.
215
216 @see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
217 */
218 virtual bool SaveFile(wxImage* image, wxOutputStream& stream,
219 bool verbose = true);
220
221 /**
222 Sets the preferred file extension associated with this handler.
223
224 @param extension
225 File extension without leading dot.
226
227 @see SetAltExtensions()
228 */
229 void SetExtension(const wxString& extension);
230
231 /**
232 Sets the alternative file extensions associated with this handler.
233
234 @param extensions
235 Array of file extensions.
236
237 @see SetExtension()
238
239 @since 2.9.0
240 */
241 void SetAltExtensions(const wxArrayString& extensions);
242
243 /**
244 Sets the handler MIME type.
245
246 @param mimetype
247 Handler MIME type.
248 */
249 void SetMimeType(const wxString& mimetype);
250
251 /**
252 Sets the handler name.
253
254 @param name
255 Handler name.
256 */
257 void SetName(const wxString& name);
258
259 /**
260 Retrieve the version information about the image library used by this
261 handler.
262
263 This method is not present in wxImageHandler class itself but is
264 present in a few of the classes deriving from it, currently
265 wxJPEGHandler, wxPNGHandler and wxTIFFHandler. It returns the
266 information about the version of the image library being used for the
267 corresponding handler implementation.
268
269 @since 2.9.2
270 */
271 static wxVersionInfo GetLibraryVersionInfo();
272 };
273
274
275 /**
276 Constant used to indicate the alpha value conventionally defined as
277 the complete transparency.
278 */
279 const unsigned char wxIMAGE_ALPHA_TRANSPARENT = 0;
280
281 /**
282 Constant used to indicate the alpha value conventionally defined as
283 the complete opacity.
284 */
285 const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff;
286
287 /**
288 @class wxImage
289
290 This class encapsulates a platform-independent image.
291
292 An image can be created from data, or using wxBitmap::ConvertToImage.
293 An image can be loaded from a file in a variety of formats, and is extensible
294 to new formats via image format handlers. Functions are available to set and
295 get image bits, so it can be used for basic image manipulation.
296
297 A wxImage cannot (currently) be drawn directly to a wxDC.
298 Instead, a platform-specific wxBitmap object must be created from it using
299 the wxBitmap::wxBitmap(wxImage,int depth) constructor.
300 This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
301
302 One colour value of the image may be used as a mask colour which will lead to
303 the automatic creation of a wxMask object associated to the bitmap object.
304
305
306 @section image_alpha Alpha channel support
307
308 Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is
309 in addition to a byte for the red, green and blue colour components for each
310 pixel it also stores a byte representing the pixel opacity.
311
312 An alpha value of 0 corresponds to a transparent pixel (null opacity) while
313 a value of 255 means that the pixel is 100% opaque.
314 The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
315 used to indicate those values in a more readable form.
316
317 While all images have RGB data, not all images have an alpha channel. Before
318 using wxImage::GetAlpha you should check if this image contains an alpha
319 channel with wxImage::HasAlpha. Currently the BMP, PNG, and TIFF format
320 handlers have full alpha channel support for loading so if you want to use
321 alpha you have to use one of these formats. If you initialize the image
322 alpha channel yourself using wxImage::SetAlpha, you should save it in
323 either PNG or TGA format to avoid losing it as these are the only handlers
324 that currently support saving with alpha.
325
326
327 @section image_handlers Available image handlers
328
329 The following image handlers are available.
330 wxBMPHandler is always installed by default.
331 To use other image formats, install the appropriate handler with
332 wxImage::AddHandler or call ::wxInitAllImageHandlers().
333
334 - wxBMPHandler: For loading (including alpha support) and saving, always installed.
335 - wxPNGHandler: For loading and saving. Includes alpha support.
336 - wxJPEGHandler: For loading and saving.
337 - wxGIFHandler: Only for loading, due to legal issues.
338 - wxPCXHandler: For loading and saving (see below).
339 - wxPNMHandler: For loading and saving (see below).
340 - wxTIFFHandler: For loading (including alpha support) and saving.
341 - wxTGAHandler: For loading and saving. Includes alpha support.
342 - wxIFFHandler: For loading only.
343 - wxXPMHandler: For loading and saving.
344 - wxICOHandler: For loading and saving.
345 - wxCURHandler: For loading and saving.
346 - wxANIHandler: For loading only.
347
348 When saving in PCX format, wxPCXHandler will count the number of different
349 colours in the image; if there are 256 or less colours, it will save as 8 bit,
350 else it will save as 24 bit.
351
352 Loading PNMs only works for ASCII or raw RGB images.
353 When saving in PNM format, wxPNMHandler will always save as raw RGB.
354
355
356 @library{wxcore}
357 @category{gdi}
358
359 @stdobjects
360 ::wxNullImage
361
362 @see wxBitmap, wxInitAllImageHandlers(), wxPixelData
363 */
364 class wxImage : public wxObject
365 {
366 public:
367 /**
368 A simple class which stores red, green and blue values as 8 bit unsigned integers
369 in the range of 0-255.
370 */
371 class RGBValue
372 {
373 public:
374 /**
375 Constructor for RGBValue, an object that contains values for red, green
376 and blue which represent the value of a color.
377
378 It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which convert
379 between HSV color space and RGB color space.
380 */
381 RGBValue(unsigned char r=0, unsigned char g=0, unsigned char b=0);
382 };
383
384 /**
385 A simple class which stores hue, saturation and value as doubles in the range 0.0-1.0.
386 */
387 class HSVValue
388 {
389 public:
390 /**
391 Constructor for HSVValue, an object that contains values for hue, saturation
392 and value which represent the value of a color.
393
394 It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which convert
395 between HSV color space and RGB color space.
396 */
397 HSVValue(double h=0.0, double s=0.0, double v=0.0);
398 };
399
400 /**
401 Creates an empty wxImage object without an alpha channel.
402 */
403 wxImage();
404
405 /**
406 Creates an image with the given size and clears it if requested.
407
408 Does not create an alpha channel.
409
410 @param width
411 Specifies the width of the image.
412 @param height
413 Specifies the height of the image.
414 @param clear
415 If @true, initialize the image to black.
416 */
417 wxImage(int width, int height, bool clear = true);
418
419 /**
420 @overload
421 */
422 wxImage(const wxSize& sz, bool clear = true);
423
424 /**
425 Creates an image from data in memory. If @a static_data is @false
426 then the wxImage will take ownership of the data and free it
427 afterwards. For this, it has to be allocated with @e malloc.
428
429 @param width
430 Specifies the width of the image.
431 @param height
432 Specifies the height of the image.
433 @param data
434 A pointer to RGB data
435 @param static_data
436 Indicates if the data should be free'd after use
437
438 */
439 wxImage(int width, int height, unsigned char* data, bool static_data = false);
440
441 /**
442 @overload
443 */
444 wxImage(const wxSize& sz, unsigned char* data, bool static_data = false);
445
446 /**
447 Creates an image from data in memory. If @a static_data is @false
448 then the wxImage will take ownership of the data and free it
449 afterwards. For this, it has to be allocated with @e malloc.
450
451 @param width
452 Specifies the width of the image.
453 @param height
454 Specifies the height of the image.
455 @param data
456 A pointer to RGB data
457 @param alpha
458 A pointer to alpha-channel data
459 @param static_data
460 Indicates if the data should be free'd after use
461
462 */
463 wxImage(int width, int height, unsigned char* data, unsigned char* alpha,
464 bool static_data = false );
465
466 /**
467 @overload
468 */
469 wxImage(const wxSize& sz, unsigned char* data, unsigned char* data, unsigned char* alpha,
470 bool static_data = false);
471
472 /**
473 Creates an image from XPM data.
474
475 @param xpmData
476 A pointer to XPM image data.
477
478 @beginWxPerlOnly
479 Not supported by wxPerl.
480 @endWxPerlOnly
481 */
482 wxImage(const char* const* xpmData);
483
484 /**
485 Creates an image from a file.
486
487 @param name
488 Name of the file from which to load the image.
489 @param type
490 May be one of the following:
491 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
492 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
493 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
494 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
495 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
496 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
497 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
498 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
499 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
500 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
501 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
502 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
503 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
504 @param index
505 Index of the image to load in the case that the image file contains
506 multiple images. This is only used by GIF, ICO and TIFF handlers.
507 The default value (-1) means "choose the default image" and is
508 interpreted as the first image (index=0) by the GIF and TIFF handler
509 and as the largest and most colourful one by the ICO handler.
510
511 @remarks Depending on how wxWidgets has been configured and by which
512 handlers have been loaded, not all formats may be available.
513 Any handler other than BMP must be previously initialized with
514 wxImage::AddHandler or wxInitAllImageHandlers.
515
516 @note
517 You can use GetOptionInt() to get the hotspot when loading cursor files:
518 @code
519 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
520 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
521 @endcode
522
523 @see LoadFile()
524 */
525 wxImage(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
526
527 /**
528 Creates an image from a file using MIME-types to specify the type.
529
530 @param name
531 Name of the file from which to load the image.
532 @param mimetype
533 MIME type string (for example 'image/jpeg')
534 @param index
535 See description in wxImage(const wxString&, wxBitmapType, int) overload.
536 */
537 wxImage(const wxString& name, const wxString& mimetype, int index = -1);
538
539 /**
540 Creates an image from a stream.
541
542 @param stream
543 Opened input stream from which to load the image. Currently,
544 the stream must support seeking.
545 @param type
546 See description in wxImage(const wxString&, wxBitmapType, int) overload.
547 @param index
548 See description in wxImage(const wxString&, wxBitmapType, int) overload.
549 */
550 wxImage(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
551
552 /**
553 Creates an image from a stream using MIME-types to specify the type.
554
555 @param stream
556 Opened input stream from which to load the image. Currently,
557 the stream must support seeking.
558 @param mimetype
559 MIME type string (for example 'image/jpeg')
560 @param index
561 See description in wxImage(const wxString&, wxBitmapType, int) overload.
562 */
563 wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);
564
565 /**
566 Destructor.
567
568 See @ref overview_refcount_destruct "reference-counted object destruction"
569 for more info.
570 */
571 virtual ~wxImage();
572
573
574
575 /**
576 @name Image creation, initialization and deletion functions
577 */
578 //@{
579
580 /**
581 Returns an identical copy of this image.
582 */
583 wxImage Copy() const;
584
585 /**
586 Creates a fresh image.
587 See wxImage::wxImage(int,int,bool) for more info.
588
589 @return @true if the call succeeded, @false otherwise.
590 */
591 bool Create(int width, int height, bool clear = true);
592
593 /**
594 @overload
595 */
596 bool Create( const wxSize& sz, bool clear = true );
597
598 /**
599 Creates a fresh image.
600 See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
601
602 @return @true if the call succeeded, @false otherwise.
603 */
604 bool Create( int width, int height, unsigned char* data, bool static_data = false );
605
606 /**
607 @overload
608 */
609 bool Create( const wxSize& sz, unsigned char* data, bool static_data = false );
610
611 /**
612 Creates a fresh image.
613 See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
614
615 @return @true if the call succeeded, @false otherwise.
616 */
617 bool Create( int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
618
619 /**
620 @overload
621 */
622 bool Create( const wxSize& sz, unsigned char* data, unsigned char* alpha, bool static_data = false );
623
624 /**
625 Initialize the image data with zeroes (the default) or with the
626 byte value given as @a value.
627
628 @since 2.9.0
629 */
630 void Clear(unsigned char value = 0);
631
632 /**
633 Destroys the image data.
634 */
635 void Destroy();
636
637 /**
638 Initializes the image alpha channel data.
639
640 It is an error to call it if the image already has alpha data.
641 If it doesn't, alpha data will be by default initialized to all pixels
642 being fully opaque. But if the image has a mask colour, all mask pixels
643 will be completely transparent.
644 */
645 void InitAlpha();
646
647 //@}
648
649
650 /**
651 @name Image manipulation functions
652 */
653 //@{
654
655 /**
656 Blurs the image in both horizontal and vertical directions by the
657 specified pixel @a blurRadius. This should not be used when using
658 a single mask colour for transparency.
659
660 @see BlurHorizontal(), BlurVertical()
661 */
662 wxImage Blur(int blurRadius) const;
663
664 /**
665 Blurs the image in the horizontal direction only. This should not be used
666 when using a single mask colour for transparency.
667
668 @see Blur(), BlurVertical()
669 */
670 wxImage BlurHorizontal(int blurRadius) const;
671
672 /**
673 Blurs the image in the vertical direction only. This should not be used
674 when using a single mask colour for transparency.
675
676 @see Blur(), BlurHorizontal()
677 */
678 wxImage BlurVertical(int blurRadius) const;
679
680 /**
681 Returns a mirrored copy of the image.
682 The parameter @a horizontally indicates the orientation.
683 */
684 wxImage Mirror(bool horizontally = true) const;
685
686 /**
687 Copy the data of the given @a image to the specified position in this image.
688 */
689 void Paste(const wxImage& image, int x, int y);
690
691 /**
692 Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
693 */
694 void Replace(unsigned char r1, unsigned char g1,
695 unsigned char b1, unsigned char r2,
696 unsigned char g2, unsigned char b2);
697
698 /**
699 Changes the size of the image in-place by scaling it: after a call to this
700 function,the image will have the given width and height.
701
702 For a description of the @a quality parameter, see the Scale() function.
703 Returns the (modified) image itself.
704
705 @see Scale()
706 */
707 wxImage& Rescale(int width, int height,
708 wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL);
709
710 /**
711 Changes the size of the image in-place without scaling it by adding either a
712 border with the given colour or cropping as necessary.
713
714 The image is pasted into a new image with the given @a size and background
715 colour at the position @a pos relative to the upper left of the new image.
716
717 If @a red = green = blue = -1 then use either the current mask colour
718 if set or find, use, and set a suitable mask colour for any newly exposed
719 areas.
720
721 @return The (modified) image itself.
722
723 @see Size()
724 */
725 wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1,
726 int green = -1, int blue = -1);
727
728 /**
729 Rotates the image about the given point, by @a angle radians.
730
731 Passing @true to @a interpolating results in better image quality, but is slower.
732
733 If the image has a mask, then the mask colour is used for the uncovered
734 pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
735
736 Returns the rotated image, leaving this image intact.
737 */
738 wxImage Rotate(double angle, const wxPoint& rotationCentre,
739 bool interpolating = true,
740 wxPoint* offsetAfterRotation = NULL) const;
741
742 /**
743 Returns a copy of the image rotated 90 degrees in the direction
744 indicated by @a clockwise.
745 */
746 wxImage Rotate90(bool clockwise = true) const;
747
748 /**
749 Returns a copy of the image rotated by 180 degrees.
750
751 @since 2.9.2
752 */
753 wxImage Rotate180() const;
754
755 /**
756 Rotates the hue of each pixel in the image by @e angle, which is a double in
757 the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
758 corresponds to +360 degrees.
759 */
760 void RotateHue(double angle);
761
762 /**
763 Returns a scaled version of the image.
764
765 This is also useful for scaling bitmaps in general as the only other way
766 to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
767
768 The parameter @a quality determines what method to use for resampling
769 the image, see wxImageResizeQuality documentation.
770
771 It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
772 looking results it is a slower method. Downsampling will use the box averaging
773 method which seems to operate very fast. If you are upsampling larger images using
774 this method you will most likely notice that it is a bit slower and in extreme
775 cases it will be quite substantially slower as the bicubic algorithm has to process a
776 lot of data.
777
778 It should also be noted that the high quality scaling may not work as expected
779 when using a single mask colour for transparency, as the scaling will blur the
780 image and will therefore remove the mask partially. Using the alpha channel
781 will work.
782
783 Example:
784 @code
785 // get the bitmap from somewhere
786 wxBitmap bmp = ...;
787
788 // rescale it to have size of 32*32
789 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
790 {
791 wxImage image = bmp.ConvertToImage();
792 bmp = wxBitmap(image.Scale(32, 32));
793
794 // another possibility:
795 image.Rescale(32, 32);
796 bmp = image;
797 }
798 @endcode
799
800 @see Rescale()
801 */
802 wxImage Scale(int width, int height,
803 wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL) const;
804
805 /**
806 Returns a resized version of this image without scaling it by adding either a
807 border with the given colour or cropping as necessary.
808
809 The image is pasted into a new image with the given @a size and background
810 colour at the position @a pos relative to the upper left of the new image.
811
812 If @a red = green = blue = -1 then the areas of the larger image not covered
813 by this image are made transparent by filling them with the image mask colour
814 (which will be allocated automatically if it isn't currently set).
815
816 Otherwise, the areas will be filled with the colour with the specified RGB components.
817
818 @see Resize()
819 */
820 wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
821 int green = -1, int blue = -1) const;
822
823 //@}
824
825
826 /**
827 @name Conversion functions
828 */
829 //@{
830
831 /**
832 If the image has alpha channel, this method converts it to mask.
833
834 If the image has an alpha channel, all pixels with alpha value less
835 than @a threshold are replaced with the mask colour and the alpha
836 channel is removed. Otherwise nothing is done.
837
838 The mask colour is chosen automatically using
839 FindFirstUnusedColour() by this function, see the overload below if you
840 this is not appropriate.
841
842 @return Returns @true on success, @false on error.
843 */
844 bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
845
846 /**
847 If the image has alpha channel, this method converts it to mask using
848 the specified colour as the mask colour.
849
850 If the image has an alpha channel, all pixels with alpha value less
851 than @a threshold are replaced with the mask colour and the alpha
852 channel is removed. Otherwise nothing is done.
853
854 @since 2.9.0
855
856 @param mr
857 The red component of the mask colour.
858 @param mg
859 The green component of the mask colour.
860 @param mb
861 The blue component of the mask colour.
862 @param threshold
863 Pixels with alpha channel values below the given threshold are
864 considered to be transparent, i.e. the corresponding mask pixels
865 are set. Pixels with the alpha values above the threshold are
866 considered to be opaque.
867
868 @return Returns @true on success, @false on error.
869 */
870 bool ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
871 unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
872
873 /**
874 Returns a greyscale version of the image.
875
876 The returned image uses the luminance component of the original to
877 calculate the greyscale. Defaults to using the standard ITU-T BT.601
878 when converting to YUV, where every pixel equals
879 (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
880 */
881 wxImage ConvertToGreyscale(double weight_r, double weight_g, double weight_b) const;
882
883 /**
884 Returns a greyscale version of the image.
885 @since 2.9.0
886 */
887 wxImage ConvertToGreyscale() const;
888
889 /**
890 Returns monochromatic version of the image.
891
892 The returned image has white colour where the original has @e (r,g,b)
893 colour and black colour everywhere else.
894 */
895 wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
896
897 /**
898 Returns disabled (dimmed) version of the image.
899 @since 2.9.0
900 */
901 wxImage ConvertToDisabled(unsigned char brightness = 255) const;
902
903 //@}
904
905
906 /**
907 @name Miscellaneous functions
908 */
909 //@{
910
911 /**
912 Computes the histogram of the image. @a histogram is a reference to
913 wxImageHistogram object. wxImageHistogram is a specialization of
914 wxHashMap "template" and is defined as follows:
915
916 @code
917 class WXDLLEXPORT wxImageHistogramEntry
918 {
919 public:
920 wxImageHistogramEntry() : index(0), value(0) {}
921 unsigned long index;
922 unsigned long value;
923 };
924
925 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
926 wxIntegerHash, wxIntegerEqual,
927 wxImageHistogram);
928 @endcode
929
930 @return Returns number of colours in the histogram.
931 */
932 unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
933
934 /**
935 Finds the first colour that is never used in the image.
936 The search begins at given initial colour and continues by increasing
937 R, G and B components (in this order) by 1 until an unused colour is
938 found or the colour space exhausted.
939
940 The parameters @a r, @a g, @a b are pointers to variables to save the colour.
941
942 The parameters @a startR, @a startG, @a startB define the initial values
943 of the colour.
944 The returned colour will have RGB values equal to or greater than these.
945
946 @return Returns @false if there is no unused colour left, @true on success.
947
948 @note
949 This method involves computing the histogram, which is a
950 computationally intensive operation.
951 */
952 bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
953 unsigned char* b, unsigned char startR = 1,
954 unsigned char startG = 0,
955 unsigned char startB = 0) const;
956
957 /**
958 Assignment operator, using @ref overview_refcount "reference counting".
959
960 @param image
961 Image to assign.
962
963 @return Returns 'this' object.
964 */
965 wxImage& operator=(const wxImage& image);
966
967 //@}
968
969
970 /**
971 @name Getters
972 */
973 //@{
974
975 /**
976 Returns pointer to the array storing the alpha values for this image.
977
978 This pointer is @NULL for the images without the alpha channel. If the image
979 does have it, this pointer may be used to directly manipulate the alpha values
980 which are stored as the RGB ones.
981 */
982 unsigned char* GetAlpha() const;
983
984 /**
985 Returns the image data as an array.
986
987 This is most often used when doing direct image manipulation.
988 The return value points to an array of characters in RGBRGBRGB... format
989 in the top-to-bottom, left-to-right order, that is the first RGB triplet
990 corresponds to the pixel first pixel of the first row, the second one ---
991 to the second pixel of the first row and so on until the end of the first
992 row, with second row following after it and so on.
993
994 You should not delete the returned pointer nor pass it to SetData().
995 */
996 unsigned char* GetData() const;
997
998 /**
999 Return alpha value at given pixel location.
1000 */
1001 unsigned char GetAlpha(int x, int y) const;
1002
1003 /**
1004 Returns the red intensity at the given coordinate.
1005 */
1006 unsigned char GetRed(int x, int y) const;
1007
1008 /**
1009 Returns the green intensity at the given coordinate.
1010 */
1011 unsigned char GetGreen(int x, int y) const;
1012
1013 /**
1014 Returns the blue intensity at the given coordinate.
1015 */
1016 unsigned char GetBlue(int x, int y) const;
1017
1018 /**
1019 Gets the red value of the mask colour.
1020 */
1021 unsigned char GetMaskRed() const;
1022
1023 /**
1024 Gets the green value of the mask colour.
1025 */
1026 unsigned char GetMaskGreen() const;
1027
1028 /**
1029 Gets the blue value of the mask colour.
1030 */
1031 unsigned char GetMaskBlue() const;
1032
1033 /**
1034 Gets the width of the image in pixels.
1035
1036 @see GetHeight(), GetSize()
1037 */
1038 int GetWidth() const;
1039
1040 /**
1041 Gets the height of the image in pixels.
1042
1043 @see GetWidth(), GetSize()
1044 */
1045 int GetHeight() const;
1046
1047 /**
1048 Returns the size of the image in pixels.
1049
1050 @since 2.9.0
1051
1052 @see GetHeight(), GetWidth()
1053 */
1054 wxSize GetSize() const;
1055
1056 /**
1057 Gets a user-defined string-valued option.
1058
1059 Currently the only defined string option is
1060 @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
1061 was loaded.
1062
1063 @param name
1064 The name of the option, case-insensitive.
1065 @return
1066 The value of the option or an empty string if not found. Use
1067 HasOption() if an empty string can be a valid option value.
1068
1069 @see SetOption(), GetOptionInt(), HasOption()
1070 */
1071 wxString GetOption(const wxString& name) const;
1072
1073 /**
1074 Gets a user-defined integer-valued option.
1075
1076 The function is case-insensitive to @a name.
1077 If the given option is not present, the function returns 0.
1078 Use HasOption() is 0 is a possibly valid value for the option.
1079
1080 Generic options:
1081 @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
1082 of these options is specified, the loaded image will be scaled down
1083 (preserving its aspect ratio) so that its width is less than the
1084 max width given if it is not 0 @em and its height is less than the
1085 max height given if it is not 0. This is typically used for loading
1086 thumbnails and the advantage of using these options compared to
1087 calling Rescale() after loading is that some handlers (only JPEG
1088 one right now) support rescaling the image during loading which is
1089 vastly more efficient than loading the entire huge image and
1090 rescaling it later (if these options are not supported by the
1091 handler, this is still what happens however). These options must be
1092 set before calling LoadFile() to have any effect.
1093
1094 @li @c wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
1095 integer in 0..100 range with 0 meaning very poor and 100 excellent
1096 (but very badly compressed). This option is currently ignored for
1097 the other formats.
1098
1099 @li @c wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
1100 whether the resolution of the image is specified in centimetres or
1101 inches, see wxImageResolution enum elements.
1102
1103 @li @c wxIMAGE_OPTION_RESOLUTION, @c wxIMAGE_OPTION_RESOLUTIONX and
1104 @c wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
1105 the image in the units corresponding to @c wxIMAGE_OPTION_RESOLUTIONUNIT
1106 options value. The first option can be set before saving the image
1107 to set both horizontal and vertical resolution to the same value.
1108 The X and Y options are set by the image handlers if they support
1109 the image resolution (currently BMP, JPEG and TIFF handlers do) and
1110 the image provides the resolution information and can be queried
1111 after loading the image.
1112
1113 Options specific to wxPNGHandler:
1114 @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
1115 wxImagePNGType for the supported values.
1116 @li @c wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
1117 @li @c wxIMAGE_OPTION_PNG_FILTER: Filter for saving a PNG file, see libpng
1118 (http://www.libpng.org/pub/png/libpng-1.2.5-manual.html) for possible values
1119 (e.g. PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FILTER_UP, etc).
1120 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL: Compression level (0..9) for
1121 saving a PNG file. An high value creates smaller-but-slower PNG file.
1122 Note that unlike other formats (e.g. JPEG) the PNG format is always
1123 lossless and thus this compression level doesn't tradeoff the image
1124 quality.
1125 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL: Compression memory usage
1126 level (1..9) for saving a PNG file. An high value means the saving
1127 process consumes more memory, but may create smaller PNG file.
1128 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY: Possible values are 0 for
1129 default strategy, 1 for filter, and 2 for Huffman-only.
1130 You can use OptiPNG (http://optipng.sourceforge.net/) to get a suitable
1131 value for your application.
1132 @li @c wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE: Internal buffer size
1133 (in bytes) for saving a PNG file. Ideally this should be as big as
1134 the resulting PNG file. Use this option if your application produces
1135 images with small size variation.
1136
1137 @param name
1138 The name of the option, case-insensitive.
1139 @return
1140 The value of the option or 0 if not found.
1141 Use HasOption() if 0 can be a valid option value.
1142
1143 @see SetOption(), GetOption()
1144 */
1145 int GetOptionInt(const wxString& name) const;
1146
1147 /**
1148 Get the current mask colour or find a suitable unused colour that could be
1149 used as a mask colour. Returns @true if the image currently has a mask.
1150 */
1151 bool GetOrFindMaskColour(unsigned char* r, unsigned char* g,
1152 unsigned char* b) const;
1153
1154 /**
1155 Returns the palette associated with the image.
1156 Currently the palette is only used when converting to wxBitmap under Windows.
1157
1158 Some of the wxImage handlers have been modified to set the palette if
1159 one exists in the image file (usually 256 or less colour images in
1160 GIF or PNG format).
1161 */
1162 const wxPalette& GetPalette() const;
1163
1164 /**
1165 Returns a sub image of the current one as long as the rect belongs entirely
1166 to the image.
1167 */
1168 wxImage GetSubImage(const wxRect& rect) const;
1169
1170 /**
1171 Gets the type of image found by LoadFile() or specified with SaveFile().
1172
1173 @since 2.9.0
1174 */
1175 wxBitmapType GetType() const;
1176
1177 /**
1178 Returns @true if this image has alpha channel, @false otherwise.
1179
1180 @see GetAlpha(), SetAlpha()
1181 */
1182 bool HasAlpha() const;
1183
1184 /**
1185 Returns @true if there is a mask active, @false otherwise.
1186 */
1187 bool HasMask() const;
1188
1189 /**
1190 Returns @true if the given option is present.
1191 The function is case-insensitive to @a name.
1192
1193 The lists of the currently supported options are in GetOption() and
1194 GetOptionInt() function docs.
1195
1196 @see SetOption(), GetOption(), GetOptionInt()
1197 */
1198 bool HasOption(const wxString& name) const;
1199
1200 /**
1201 Returns @true if image data is present.
1202 */
1203 bool IsOk() const;
1204
1205 /**
1206 Returns @true if the given pixel is transparent, i.e. either has the mask
1207 colour if this image has a mask or if this image has alpha channel and alpha
1208 value of this pixel is strictly less than @a threshold.
1209 */
1210 bool IsTransparent(int x, int y,
1211 unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
1212
1213 //@}
1214
1215
1216 /**
1217 @name Loading and saving functions
1218 */
1219 //@{
1220
1221 /**
1222 Loads an image from an input stream.
1223
1224 @param stream
1225 Opened input stream from which to load the image.
1226 Currently, the stream must support seeking.
1227 @param type
1228 May be one of the following:
1229 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1230 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1231 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1232 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1233 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1234 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1235 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
1236 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1237 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1238 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1239 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1240 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1241 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1242 @param index
1243 Index of the image to load in the case that the image file contains
1244 multiple images. This is only used by GIF, ICO and TIFF handlers.
1245 The default value (-1) means "choose the default image" and is
1246 interpreted as the first image (index=0) by the GIF and TIFF handler
1247 and as the largest and most colourful one by the ICO handler.
1248
1249 @return @true if the operation succeeded, @false otherwise.
1250 If the optional index parameter is out of range, @false is
1251 returned and a call to wxLogError() takes place.
1252
1253 @remarks Depending on how wxWidgets has been configured, not all formats
1254 may be available.
1255
1256 @note
1257 You can use GetOptionInt() to get the hotspot when loading cursor files:
1258 @code
1259 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
1260 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
1261 @endcode
1262
1263 @see SaveFile()
1264 */
1265 virtual bool LoadFile(wxInputStream& stream,
1266 wxBitmapType type = wxBITMAP_TYPE_ANY,
1267 int index = -1);
1268
1269 /**
1270 Loads an image from a file.
1271 If no handler type is provided, the library will try to autodetect the format.
1272
1273 @param name
1274 Name of the file from which to load the image.
1275 @param type
1276 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1277 @param index
1278 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1279 */
1280 virtual bool LoadFile(const wxString& name,
1281 wxBitmapType type = wxBITMAP_TYPE_ANY,
1282 int index = -1);
1283
1284 /**
1285 Loads an image from a file.
1286 If no handler type is provided, the library will try to autodetect the format.
1287
1288 @param name
1289 Name of the file from which to load the image.
1290 @param mimetype
1291 MIME type string (for example 'image/jpeg')
1292 @param index
1293 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1294 */
1295 virtual bool LoadFile(const wxString& name, const wxString& mimetype,
1296 int index = -1);
1297
1298 /**
1299 Loads an image from an input stream.
1300
1301 @param stream
1302 Opened input stream from which to load the image.
1303 Currently, the stream must support seeking.
1304 @param mimetype
1305 MIME type string (for example 'image/jpeg')
1306 @param index
1307 See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1308 */
1309 virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
1310 int index = -1);
1311
1312 /**
1313 Saves an image in the given stream.
1314
1315 @param stream
1316 Opened output stream to save the image to.
1317 @param mimetype
1318 MIME type.
1319
1320 @return @true if the operation succeeded, @false otherwise.
1321
1322 @remarks Depending on how wxWidgets has been configured, not all formats
1323 may be available.
1324
1325 @note
1326 You can use SetOption() to set the hotspot when saving an image
1327 into a cursor file (default hotspot is in the centre of the image):
1328 @code
1329 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1330 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1331 @endcode
1332
1333 @see LoadFile()
1334 */
1335 virtual bool SaveFile(wxOutputStream& stream,
1336 const wxString& mimetype) const;
1337
1338 /**
1339 Saves an image in the named file.
1340
1341 @param name
1342 Name of the file to save the image to.
1343 @param type
1344 Currently these types can be used:
1345 @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1346 @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1347 @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1348 @li wxBITMAP_TYPE_PCX: Save a PCX image file
1349 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1350 @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1351 @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1352 @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1353 @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1354 The size may be up to 255 wide by 127 high. A single image is saved
1355 in 8 colors at the size supplied.
1356 @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1357 */
1358 virtual bool SaveFile(const wxString& name, wxBitmapType type) const;
1359
1360 /**
1361 Saves an image in the named file.
1362
1363 @param name
1364 Name of the file to save the image to.
1365 @param mimetype
1366 MIME type.
1367 */
1368 virtual bool SaveFile(const wxString& name, const wxString& mimetype) const;
1369
1370 /**
1371 Saves an image in the named file.
1372
1373 File type is determined from the extension of the file name.
1374 Note that this function may fail if the extension is not recognized!
1375 You can use one of the forms above to save images to files with
1376 non-standard extensions.
1377
1378 @param name
1379 Name of the file to save the image to.
1380 */
1381 virtual bool SaveFile(const wxString& name) const;
1382
1383 /**
1384 Saves an image in the given stream.
1385
1386 @param stream
1387 Opened output stream to save the image to.
1388 @param type
1389 MIME type.
1390 */
1391 virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
1392
1393 //@}
1394
1395
1396
1397 /**
1398 @name Setters
1399 */
1400 //@{
1401
1402 /**
1403 This function is similar to SetData() and has similar restrictions.
1404
1405 The pointer passed to it may however be @NULL in which case the function
1406 will allocate the alpha array internally -- this is useful to add alpha
1407 channel data to an image which doesn't have any.
1408
1409 If the pointer is not @NULL, it must have one byte for each image pixel
1410 and be allocated with malloc().
1411 wxImage takes ownership of the pointer and will free it unless @a static_data
1412 parameter is set to @true -- in this case the caller should do it.
1413 */
1414 void SetAlpha(unsigned char* alpha = NULL,
1415 bool static_data = false);
1416
1417 /**
1418 Sets the alpha value for the given pixel.
1419 This function should only be called if the image has alpha channel data,
1420 use HasAlpha() to check for this.
1421 */
1422 void SetAlpha(int x, int y, unsigned char alpha);
1423
1424 /**
1425 Removes the alpha channel from the image.
1426
1427 This function should only be called if the image has alpha channel data,
1428 use HasAlpha() to check for this.
1429
1430 @since 2.9.1
1431 */
1432 void ClearAlpha();
1433
1434 /**
1435 Sets the image data without performing checks.
1436
1437 The data given must have the size (width*height*3) or results will be
1438 unexpected. Don't use this method if you aren't sure you know what you
1439 are doing.
1440
1441 The data must have been allocated with @c malloc(), @b NOT with
1442 @c operator new.
1443
1444 If @a static_data is @false, after this call the pointer to the data is
1445 owned by the wxImage object, that will be responsible for deleting it.
1446 Do not pass to this function a pointer obtained through GetData().
1447 */
1448 void SetData(unsigned char* data, bool static_data = false);
1449
1450 /**
1451 @overload
1452 */
1453 void SetData(unsigned char* data, int new_width, int new_height,
1454 bool static_data = false);
1455
1456 /**
1457 Specifies whether there is a mask or not.
1458
1459 The area of the mask is determined by the current mask colour.
1460 */
1461 void SetMask(bool hasMask = true);
1462
1463 /**
1464 Sets the mask colour for this image (and tells the image to use the mask).
1465 */
1466 void SetMaskColour(unsigned char red, unsigned char green,
1467 unsigned char blue);
1468
1469 /**
1470 Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1471 mask will be masked in the image.
1472
1473 This is done by first finding an unused colour in the image, setting
1474 this colour as the mask colour and then using this colour to draw all
1475 pixels in the image who corresponding pixel in mask has given RGB value.
1476
1477 The parameter @a mask is the mask image to extract mask shape from.
1478 It must have the same dimensions as the image.
1479
1480 The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1481 mask that will be used to create the mask.
1482
1483 @return Returns @false if mask does not have same dimensions as the image
1484 or if there is no unused colour left. Returns @true if the mask
1485 was successfully applied.
1486
1487 @note
1488 Note that this method involves computing the histogram, which is a
1489 computationally intensive operation.
1490 */
1491 bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
1492 unsigned char mg,
1493 unsigned char mb);
1494
1495 /**
1496 Sets a user-defined option. The function is case-insensitive to @a name.
1497
1498 For example, when saving as a JPEG file, the option @b quality is
1499 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1500
1501 The lists of the currently supported options are in GetOption() and
1502 GetOptionInt() function docs.
1503
1504 @see GetOption(), GetOptionInt(), HasOption()
1505 */
1506 void SetOption(const wxString& name, const wxString& value);
1507
1508 /**
1509 @overload
1510 */
1511 void SetOption(const wxString& name, int value);
1512
1513 /**
1514 Associates a palette with the image.
1515
1516 The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1517 or in file save operations (none as yet).
1518 */
1519 void SetPalette(const wxPalette& palette);
1520
1521 /**
1522 Sets the colour of the pixels within the given rectangle.
1523
1524 This routine performs bounds-checks for the coordinate so it can be considered
1525 a safe way to manipulate the data.
1526 */
1527 void SetRGB(const wxRect& rect,
1528 unsigned char red,
1529 unsigned char green,
1530 unsigned char blue);
1531
1532 /**
1533 Set the type of image returned by GetType().
1534
1535 This method is mostly used internally by the library but can also be
1536 called from the user code if the image was created from data in the
1537 given bitmap format without using LoadFile() (which would set the type
1538 correctly automatically).
1539
1540 Notice that the image must be created before this function is called.
1541
1542 @since 2.9.0
1543
1544 @param type
1545 One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1546 value for it and can be used to reset the bitmap type to default
1547 but @c wxBITMAP_TYPE_MAX is not allowed here.
1548 */
1549 void SetType(wxBitmapType type);
1550
1551 //@}
1552
1553
1554
1555 /**
1556 @name Handler management functions
1557 */
1558 //@{
1559
1560 /**
1561 Register an image handler.
1562
1563 Typical example of use:
1564 @code
1565 wxImage::AddHandler(new wxPNGHandler);
1566 @endcode
1567
1568 See @ref image_handlers for a list of the available handlers. You can
1569 also use ::wxInitAllImageHandlers() to add handlers for all the image
1570 formats supported by wxWidgets at once.
1571
1572 @param handler
1573 A heap-allocated handler object which will be deleted by wxImage
1574 if it is removed later by RemoveHandler() or at program shutdown.
1575 */
1576 static void AddHandler(wxImageHandler* handler);
1577
1578 /**
1579 Deletes all image handlers.
1580 This function is called by wxWidgets on exit.
1581 */
1582 static void CleanUpHandlers();
1583
1584 /**
1585 Finds the handler with the given name.
1586
1587 @param name
1588 The handler name.
1589
1590 @return A pointer to the handler if found, @NULL otherwise.
1591
1592 @see wxImageHandler
1593 */
1594 static wxImageHandler* FindHandler(const wxString& name);
1595
1596 /**
1597 Finds the handler associated with the given extension and type.
1598
1599 @param extension
1600 The file extension, such as "bmp".
1601 @param imageType
1602 The image type; one of the ::wxBitmapType values.
1603
1604 @return A pointer to the handler if found, @NULL otherwise.
1605
1606 @see wxImageHandler
1607 */
1608 static wxImageHandler* FindHandler(const wxString& extension,
1609 wxBitmapType imageType);
1610
1611 /**
1612 Finds the handler associated with the given image type.
1613
1614 @param imageType
1615 The image type; one of the ::wxBitmapType values.
1616
1617 @return A pointer to the handler if found, @NULL otherwise.
1618
1619 @see wxImageHandler
1620 */
1621 static wxImageHandler* FindHandler(wxBitmapType imageType);
1622
1623 /**
1624 Finds the handler associated with the given MIME type.
1625
1626 @param mimetype
1627 MIME type.
1628
1629 @return A pointer to the handler if found, @NULL otherwise.
1630
1631 @see wxImageHandler
1632 */
1633 static wxImageHandler* FindHandlerMime(const wxString& mimetype);
1634
1635 /**
1636 Returns the static list of image format handlers.
1637
1638 @see wxImageHandler
1639 */
1640 static wxList& GetHandlers();
1641
1642 /**
1643 Internal use only. Adds standard image format handlers.
1644 It only install wxBMPHandler for the time being, which is used by wxBitmap.
1645
1646 This function is called by wxWidgets on startup, and shouldn't be called by
1647 the user.
1648
1649 @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
1650 */
1651 static void InitStandardHandlers();
1652
1653 /**
1654 Adds a handler at the start of the static list of format handlers.
1655
1656 @param handler
1657 A new image format handler object. There is usually only one instance
1658 of a given handler class in an application session.
1659
1660 @see wxImageHandler
1661 */
1662 static void InsertHandler(wxImageHandler* handler);
1663
1664 /**
1665 Finds the handler with the given name, and removes it.
1666
1667 The handler is also deleted.
1668
1669 @param name
1670 The handler name.
1671
1672 @return @true if the handler was found and removed, @false otherwise.
1673
1674 @see wxImageHandler
1675 */
1676 static bool RemoveHandler(const wxString& name);
1677
1678 //@}
1679
1680
1681 /**
1682 Returns @true if at least one of the available image handlers can read
1683 the file with the given name.
1684
1685 See wxImageHandler::CanRead for more info.
1686 */
1687 static bool CanRead(const wxString& filename);
1688
1689 /**
1690 Returns @true if at least one of the available image handlers can read
1691 the data in the given stream.
1692
1693 See wxImageHandler::CanRead for more info.
1694 */
1695 static bool CanRead(wxInputStream& stream);
1696
1697 //@{
1698 /**
1699 If the image file contains more than one image and the image handler is
1700 capable of retrieving these individually, this function will return the
1701 number of available images.
1702
1703 For the overload taking the parameter @a filename, that's the name
1704 of the file to query.
1705 For the overload taking the parameter @a stream, that's the opened input
1706 stream with image data.
1707
1708 See wxImageHandler::GetImageCount() for more info.
1709
1710 The parameter @a type may be one of the following values:
1711 @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1712 @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1713 @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1714 @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1715 @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1716 @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1717 @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
1718 @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1719 @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1720 @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1721 @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1722 @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1723 @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1724
1725 @return Number of available images. For most image handlers, this is 1
1726 (exceptions are TIFF and ICO formats as well as animated GIFs
1727 for which this function returns the number of frames in the
1728 animation).
1729 */
1730 static int GetImageCount(const wxString& filename,
1731 wxBitmapType type = wxBITMAP_TYPE_ANY);
1732 static int GetImageCount(wxInputStream& stream,
1733 wxBitmapType type = wxBITMAP_TYPE_ANY);
1734 //@}
1735
1736 /**
1737 Iterates all registered wxImageHandler objects, and returns a string containing
1738 file extension masks suitable for passing to file open/save dialog boxes.
1739
1740 @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
1741 It is usually a good idea to prepend a description before passing
1742 the result to the dialog.
1743 Example:
1744 @code
1745 wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
1746 _("Image Files ") + wxImage::GetImageExtWildcard(),
1747 wxFD_OPEN );
1748 @endcode
1749
1750 @see wxImageHandler
1751 */
1752 static wxString GetImageExtWildcard();
1753
1754 /**
1755 Converts a color in RGB color space to HSV color space.
1756 */
1757 static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
1758
1759 /**
1760 Converts a color in HSV color space to RGB color space.
1761 */
1762 static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv);
1763 };
1764
1765 /**
1766 An instance of an empty image without an alpha channel.
1767 */
1768 wxImage wxNullImage;
1769
1770
1771 // ============================================================================
1772 // Global functions/macros
1773 // ============================================================================
1774
1775 /** @addtogroup group_funcmacro_appinitterm */
1776 //@{
1777
1778 /**
1779 Initializes all available image handlers.
1780
1781 This function call wxImage::AddHandler() for all the available image
1782 handlers (see @ref image_handlers for the full list). Calling it is the
1783 simplest way to initialize wxImage but it creates and registers even the
1784 handlers your program may not use. If you want to avoid the overhead of
1785 doing this you need to call wxImage::AddHandler() manually just for the
1786 handlers that you do want to use.
1787
1788 @see wxImage, wxImageHandler
1789
1790 @header{wx/image.h}
1791 */
1792 void wxInitAllImageHandlers();
1793
1794 //@}
1795