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