]> git.saurik.com Git - wxWidgets.git/blob - interface/image.h
oops, added missing #endif
[wxWidgets.git] / interface / image.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: image.h
3 // Purpose: interface of wxImageHandler
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxImageHandler
11 @wxheader{image.h}
12
13 This is the base class for implementing image file loading/saving, and image
14 creation from data.
15 It is used within wxImage and is not normally seen by the application.
16
17 If you wish to extend the capabilities of wxImage, derive a class from
18 wxImageHandler
19 and add the handler using wxImage::AddHandler in your
20 application initialisation.
21
22 @library{wxcore}
23 @category{FIXME}
24
25 @see wxImage, wxInitAllImageHandlers()
26 */
27 class wxImageHandler : public wxObject
28 {
29 public:
30 /**
31 Default constructor. In your own default constructor, initialise the members
32 m_name, m_extension and m_type.
33 */
34 wxImageHandler();
35
36 /**
37 Destroys the wxImageHandler object.
38 */
39 ~wxImageHandler();
40
41 /**
42 Gets the file extension associated with this handler.
43 */
44 const wxString GetExtension() const;
45
46 /**
47 If the image file contains more than one image and the image handler is capable
48 of retrieving these individually, this function will return the number of
49 available images.
50
51 @param stream
52 Opened input stream for reading image data. Currently, the stream must
53 support seeking.
54
55 @returns Number of available images. For most image handlers, this is 1
56 (exceptions are TIFF and ICO formats).
57 */
58 int GetImageCount(wxInputStream& stream);
59
60 /**
61 Gets the MIME type associated with this handler.
62 */
63 const wxString GetMimeType() const;
64
65 /**
66 Gets the name of this handler.
67 */
68 const wxString GetName() const;
69
70 /**
71 Gets the image type associated with this handler.
72 */
73 long GetType() const;
74
75 /**
76 Loads a image from a stream, putting the resulting data into @e image. If the
77 image file contains
78 more than one image and the image handler is capable of retrieving these
79 individually, @e index
80 indicates which image to read from the stream.
81
82 @param image
83 The image object which is to be affected by this operation.
84 @param stream
85 Opened input stream for reading image data.
86 @param verbose
87 If set to @true, errors reported by the image handler will produce
88 wxLogMessages.
89 @param index
90 The index of the image in the file (starting from zero).
91
92 @returns @true if the operation succeeded, @false otherwise.
93
94 @see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
95 */
96 bool LoadFile(wxImage* image, wxInputStream& stream,
97 bool verbose = true, int index = 0);
98
99 /**
100 Saves a image in the output stream.
101
102 @param image
103 The image object which is to be affected by this operation.
104 @param stream
105 Opened output stream for writing the data.
106
107 @returns @true if the operation succeeded, @false otherwise.
108
109 @see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
110 */
111 bool SaveFile(wxImage* image, wxOutputStream& stream);
112
113 /**
114 Sets the handler extension.
115
116 @param extension
117 Handler extension.
118 */
119 void SetExtension(const wxString& extension);
120
121 /**
122 Sets the handler MIME type.
123
124 @param mimename
125 Handler MIME type.
126 */
127 void SetMimeType(const wxString& mimetype);
128
129 /**
130 Sets the handler name.
131
132 @param name
133 Handler name.
134 */
135 void SetName(const wxString& name);
136 };
137
138
139
140 /**
141 @class wxImage
142 @wxheader{image.h}
143
144 This class encapsulates a platform-independent image. An image can be created
145 from data, or using wxBitmap::ConvertToImage. An image
146 can be loaded from a file in a variety of formats, and is extensible to new
147 formats
148 via image format handlers. Functions are available to set and get image bits, so
149 it can be used for basic image manipulation.
150
151 A wxImage cannot (currently) be drawn directly to a wxDC. Instead,
152 a platform-specific wxBitmap object must be created from it using
153 the wxBitmap::wxBitmap(wxImage,int depth) constructor.
154 This bitmap can then
155 be drawn in a device context, using wxDC::DrawBitmap.
156
157 One colour value of the image may be used as a mask colour which will lead to
158 the automatic creation of a wxMask object associated to the bitmap object.
159
160 @library{wxcore}
161 @category{gdi}
162
163 @stdobjects
164 ::wxNullImage
165
166 @see wxBitmap, wxInitAllImageHandlers()
167 */
168 class wxImage : public wxObject
169 {
170 public:
171 //@{
172 /**
173 Creates an image from XPM data.
174
175 @param width
176 Specifies the width of the image.
177 @param height
178 Specifies the height of the image.
179 @param name
180 Name of the file from which to load the image.
181 @param stream
182 Opened input stream from which to load the image. Currently, the stream
183 must support seeking.
184 @param type
185 May be one of the following:
186
187
188
189
190
191
192 wxBITMAP_TYPE_BMP
193
194
195
196
197 Load a Windows bitmap file.
198
199
200
201
202
203 wxBITMAP_TYPE_GIF
204
205
206
207
208 Load a GIF bitmap file.
209
210
211
212
213
214 wxBITMAP_TYPE_JPEG
215
216
217
218
219 Load a JPEG bitmap file.
220
221
222
223
224
225 wxBITMAP_TYPE_PNG
226
227
228
229
230 Load a PNG bitmap file.
231
232
233
234
235
236 wxBITMAP_TYPE_PCX
237
238
239
240
241 Load a PCX bitmap file.
242
243
244
245
246
247 wxBITMAP_TYPE_PNM
248
249
250
251
252 Load a PNM bitmap file.
253
254
255
256
257
258 wxBITMAP_TYPE_TIF
259
260
261
262
263 Load a TIFF bitmap file.
264
265
266
267
268
269 wxBITMAP_TYPE_TGA
270
271
272
273
274 Load a TGA bitmap file.
275
276
277
278
279
280 wxBITMAP_TYPE_XPM
281
282
283
284
285 Load a XPM bitmap file.
286
287
288
289
290
291 wxBITMAP_TYPE_ICO
292
293
294
295
296 Load a Windows icon file (ICO).
297
298
299
300
301
302 wxBITMAP_TYPE_CUR
303
304
305
306
307 Load a Windows cursor file (CUR).
308
309
310
311
312
313 wxBITMAP_TYPE_ANI
314
315
316
317
318 Load a Windows animated cursor file (ANI).
319
320
321
322
323
324 wxBITMAP_TYPE_ANY
325
326
327
328
329 Will try to autodetect the format.
330 @param mimetype
331 MIME type string (for example 'image/jpeg')
332 @param index
333 Index of the image to load in the case that the image file contains
334 multiple images.
335 This is only used by GIF, ICO and TIFF handlers. The default value (-1)
336 means
337 "choose the default image" and is interpreted as the first image (index=0)
338 by
339 the GIF and TIFF handler and as the largest and most colourful one by the
340 ICO handler.
341 @param xpmData
342 A pointer to XPM image data.
343
344 @remarks Depending on how wxWidgets has been configured, not all formats
345 may be available.
346
347 @see LoadFile()
348 */
349 wxImage();
350 wxImage(const wxImage& image);
351 wxImage(const wxBitmap& bitmap);
352 wxImage(int width, int height, bool clear = true);
353 wxImage(int width, int height, unsigned char* data,
354 bool static_data = false);
355 wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY,
356 int index = -1);
357 wxImage(const wxString& name, const wxString& mimetype,
358 int index = -1);
359 wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY,
360 int index = -1);
361 wxImage(wxInputStream& stream, const wxString& mimetype,
362 int index = -1);
363 wxImage(const char* const* xpmData);
364 //@}
365
366 /**
367 Destructor.
368 See @ref overview_refcountdestruct "reference-counted object destruction" for
369 more info.
370 */
371 ~wxImage();
372
373 //@{
374 /**
375 returns @true if the current image handlers can read this file
376 */
377 static void AddHandler(wxImageHandler* handler);
378 See also bool CanRead(const wxString& filename);
379 //@}
380
381 /**
382 Blurs the image in both horizontal and vertical directions by the specified
383 pixel
384 @e blurRadius. This should not be used when using a single mask colour
385 for transparency.
386
387 @see @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical
388 */
389 wxImage Blur(int blurRadius);
390
391 /**
392 Blurs the image in the horizontal direction only. This should not be used
393 when using a single mask colour for transparency.
394
395 @see Blur(), @ref vertblur() BlurVertical
396 */
397 wxImage BlurHorizontal(int blurRadius);
398
399 /**
400 Blurs the image in the vertical direction only. This should not be used
401 when using a single mask colour for transparency.
402
403 @see Blur(), @ref horzblur() BlurHorizontal
404 */
405 wxImage BlurVertical(int blurRadius);
406
407 /**
408 Deletes all image handlers.
409 This function is called by wxWidgets on exit.
410 */
411 static void CleanUpHandlers();
412
413 /**
414 Computes the histogram of the image. @a histogram is a reference to
415 wxImageHistogram object. wxImageHistogram is a specialization of
416 wxHashMap "template" and is defined as follows:
417
418 @returns Returns number of colours in the histogram.
419 */
420 unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
421
422 /**
423 If the image has alpha channel, this method converts it to mask. All pixels
424 with alpha value less than @a threshold are replaced with mask colour
425 and the alpha channel is removed. Mask colour is chosen automatically using
426 FindFirstUnusedColour().
427 If the image image doesn't have alpha channel,
428 ConvertAlphaToMask does nothing.
429
430 @returns @false if FindFirstUnusedColour returns @false, @true otherwise.
431 */
432 bool ConvertAlphaToMask(unsigned char threshold = 128);
433
434 /**
435 Deprecated, use equivalent @ref wxBitmap::ctor "wxBitmap constructor"
436 (which takes wxImage and depth as its arguments) instead.
437 */
438 wxBitmap ConvertToBitmap() const;
439
440 /**
441 Returns a greyscale version of the image. The returned image uses the luminance
442 component of the original to calculate the greyscale. Defaults to using
443 ITU-T BT.601 when converting to YUV, where every pixel equals
444 (R * @e lr) + (G * @e lg) + (B * @e lb).
445 */
446 wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587,
447 double lb = 0.114) const;
448
449 /**
450 Returns monochromatic version of the image. The returned image has white
451 colour where the original has @e (r,g,b) colour and black colour
452 everywhere else.
453 */
454 wxImage ConvertToMono(unsigned char r, unsigned char g,
455 unsigned char b) const;
456
457 /**
458 Returns an identical copy of the image.
459 */
460 wxImage Copy() const;
461
462 /**
463 Creates a fresh image. If @a clear is @true, the new image will be initialized
464 to black.
465 Otherwise, the image data will be uninitialized.
466
467 @param width
468 The width of the image in pixels.
469 @param height
470 The height of the image in pixels.
471
472 @returns @true if the call succeeded, @false otherwise.
473 */
474 bool Create(int width, int height, bool clear = true);
475
476 /**
477 Destroys the image data.
478 */
479 void Destroy();
480
481 /**
482 @param r,g,b
483 Pointers to variables to save the colour.
484 @param startR,startG,startB
485 Initial values of the colour. Returned colour
486 will have RGB values equal to or greater than these.
487
488 @returns Returns @false if there is no unused colour left, @true on success.
489 */
490 bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
491 unsigned char* b,
492 unsigned char startR = 1,
493 unsigned char startG = 0,
494 unsigned char startB = 0);
495
496 //@{
497 /**
498 Finds the handler associated with the given MIME type.
499
500 @param name
501 The handler name.
502 @param extension
503 The file extension, such as "bmp".
504 @param imageType
505 The image type, such as wxBITMAP_TYPE_BMP.
506 @param mimetype
507 MIME type.
508
509 @returns A pointer to the handler if found, @NULL otherwise.
510
511 @see wxImageHandler
512 */
513 static wxImageHandler* FindHandler(const wxString& name);
514 static wxImageHandler* FindHandler(const wxString& extension,
515 long imageType);
516 static wxImageHandler* FindHandler(long imageType);
517 static wxImageHandler* FindHandlerMime(const wxString& mimetype);
518 //@}
519
520 //@{
521 /**
522 Returns pointer to the array storing the alpha values for this image. This
523 pointer is @NULL for the images without the alpha channel. If the image
524 does have it, this pointer may be used to directly manipulate the alpha values
525 which are stored as the @ref getdata() RGB ones.
526 */
527 unsigned char GetAlpha(int x, int y) const;
528 const unsigned char * GetAlpha() const;
529 //@}
530
531 /**
532 Returns the blue intensity at the given coordinate.
533 */
534 unsigned char GetBlue(int x, int y) const;
535
536 /**
537 Returns the image data as an array. This is most often used when doing
538 direct image manipulation. The return value points to an array of
539 characters in RGBRGBRGB... format in the top-to-bottom, left-to-right
540 order, that is the first RGB triplet corresponds to the pixel first pixel of
541 the first row, the second one --- to the second pixel of the first row and so
542 on until the end of the first row, with second row following after it and so
543 on.
544 You should not delete the returned pointer nor pass it to
545 SetData().
546 */
547 unsigned char* GetData() const;
548
549 /**
550 Returns the green intensity at the given coordinate.
551 */
552 unsigned char GetGreen(int x, int y) const;
553
554 /**
555 Returns the static list of image format handlers.
556
557 @see wxImageHandler
558 */
559 static wxList GetHandlers();
560
561 /**
562 Gets the height of the image in pixels.
563 */
564 int GetHeight() const;
565
566 //@{
567 /**
568 If the image file contains more than one image and the image handler is capable
569 of retrieving these individually, this function will return the number of
570 available images.
571
572 @param name
573 Name of the file to query.
574 @param stream
575 Opened input stream with image data. Currently, the stream must support
576 seeking.
577 @param type
578 May be one of the following:
579
580
581
582
583
584
585 wxBITMAP_TYPE_BMP
586
587
588
589
590 Load a Windows bitmap file.
591
592
593
594
595
596 wxBITMAP_TYPE_GIF
597
598
599
600
601 Load a GIF bitmap file.
602
603
604
605
606
607 wxBITMAP_TYPE_JPEG
608
609
610
611
612 Load a JPEG bitmap file.
613
614
615
616
617
618 wxBITMAP_TYPE_PNG
619
620
621
622
623 Load a PNG bitmap file.
624
625
626
627
628
629 wxBITMAP_TYPE_PCX
630
631
632
633
634 Load a PCX bitmap file.
635
636
637
638
639
640 wxBITMAP_TYPE_PNM
641
642
643
644
645 Load a PNM bitmap file.
646
647
648
649
650
651 wxBITMAP_TYPE_TIF
652
653
654
655
656 Load a TIFF bitmap file.
657
658
659
660
661
662 wxBITMAP_TYPE_XPM
663
664
665
666
667 Load a XPM bitmap file.
668
669
670
671
672
673 wxBITMAP_TYPE_ICO
674
675
676
677
678 Load a Windows icon file (ICO).
679
680
681
682
683
684 wxBITMAP_TYPE_CUR
685
686
687
688
689 Load a Windows cursor file (CUR).
690
691
692
693
694
695 wxBITMAP_TYPE_ANI
696
697
698
699
700 Load a Windows animated cursor file (ANI).
701
702
703
704
705
706 wxBITMAP_TYPE_ANY
707
708
709
710
711 Will try to autodetect the format.
712
713 @returns Number of available images. For most image handlers, this is 1
714 (exceptions are TIFF and ICO formats).
715 */
716 static int GetImageCount(const wxString& filename,
717 long type = wxBITMAP_TYPE_ANY);
718 static int GetImageCount(wxInputStream& stream,
719 long type = wxBITMAP_TYPE_ANY);
720 //@}
721
722 /**
723 Iterates all registered wxImageHandler objects, and returns a string containing
724 file extension masks
725 suitable for passing to file open/save dialog boxes.
726
727 @returns The format of the returned string is
728 "(*.ext1;*.ext2)|*.ext1;*.ext2".
729
730 @see wxImageHandler
731 */
732 static wxString GetImageExtWildcard();
733
734 /**
735 Gets the blue value of the mask colour.
736 */
737 unsigned char GetMaskBlue() const;
738
739 /**
740 Gets the green value of the mask colour.
741 */
742 unsigned char GetMaskGreen() const;
743
744 /**
745 Gets the red value of the mask colour.
746 */
747 unsigned char GetMaskRed() const;
748
749 /**
750 Gets a user-defined option. The function is case-insensitive to @e name.
751 For example, when saving as a JPEG file, the option @b quality is
752 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
753
754 @see SetOption(), GetOptionInt(), HasOption()
755 */
756 wxString GetOption(const wxString& name) const;
757
758 /**
759 Gets a user-defined option as an integer. The function is case-insensitive to
760 @e name.
761 If the given option is not present, the function returns 0. Use
762 HasOption() is 0 is a possibly valid value
763 for the option.
764 Options for wxPNGHandler
765
766 wxIMAGE_OPTION_PNG_FORMAT
767
768 Format for saving a PNG file.
769
770 wxIMAGE_OPTION_PNG_BITDEPTH
771
772 Bit depth for every channel (R/G/B/A).
773
774 Supported values for wxIMAGE_OPTION_PNG_FORMAT:
775
776 wxPNG_TYPE_COLOUR
777
778 Stores RGB image.
779
780 wxPNG_TYPE_GREY
781
782 Stores grey image, converts from RGB.
783
784 wxPNG_TYPE_GREY_RED
785
786 Stores grey image, uses red value as grey.
787
788 @see SetOption(), GetOption()
789 */
790 int GetOptionInt(const wxString& name) const;
791
792 /**
793 Get the current mask colour or find a suitable unused colour that could be
794 used as a mask colour. Returns @true if the image currently has a mask.
795 */
796 bool GetOrFindMaskColour(unsigned char r, unsigned char g,
797 unsigned char b) const;
798
799 /**
800 Returns the palette associated with the image. Currently the palette is only
801 used when converting to wxBitmap under Windows. Some of the wxImage handlers
802 have been modified to set the palette if one exists in the image file (usually
803 256 or less colour images in GIF or PNG format).
804 */
805 const wxPalette GetPalette() const;
806
807 /**
808 Returns the red intensity at the given coordinate.
809 */
810 unsigned char GetRed(int x, int y) const;
811
812 /**
813 Returns a sub image of the current one as long as the rect belongs entirely to
814 the image.
815 */
816 wxImage GetSubImage(const wxRect& rect) const;
817
818 /**
819 Gets the width of the image in pixels.
820
821 @see GetHeight()
822 */
823 int GetWidth() const;
824
825 /**
826 Constructor for HSVValue, an object that contains values for hue, saturation
827 and value which
828 represent the value of a color. It is used by HSVtoRGB()
829 and RGBtoHSV(), which
830 converts between HSV color space and RGB color space.
831 */
832 HSVValue(double h = 0.0, double s = 0.0, double v = 0.0);
833
834 /**
835 Converts a color in HSV color space to RGB color space.
836 */
837 #define wxImage::RGBValue HSVtoRGB(const HSVValue& hsv) /* implementation is private */
838
839 /**
840 Returns @true if this image has alpha channel, @false otherwise.
841
842 @see GetAlpha(), SetAlpha()
843 */
844 bool HasAlpha() const;
845
846 /**
847 Returns @true if there is a mask active, @false otherwise.
848 */
849 bool HasMask() const;
850
851 /**
852 Returns @true if the given option is present. The function is case-insensitive
853 to @e name.
854
855 @see SetOption(), GetOption(), GetOptionInt()
856 */
857 bool HasOption(const wxString& name) const;
858
859 /**
860 Initializes the image alpha channel data. It is an error to call it
861 if the image already has alpha data. If it doesn't, alpha data will be
862 by default initialized to all pixels being fully opaque. But if the image has a
863 a mask colour, all mask pixels will be completely transparent.
864 */
865 void InitAlpha();
866
867 /**
868 Internal use only. Adds standard image format handlers. It only install BMP
869 for the time being, which is used by wxBitmap.
870 This function is called by wxWidgets on startup, and shouldn't be called by
871 the user.
872
873 @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
874 */
875 static void InitStandardHandlers();
876
877 /**
878 Adds a handler at the start of the static list of format handlers.
879
880 @param handler
881 A new image format handler object. There is usually only one instance
882 of a given handler class in an application session.
883
884 @see wxImageHandler
885 */
886 static void InsertHandler(wxImageHandler* handler);
887
888 /**
889 Returns @true if image data is present.
890 */
891 bool IsOk() const;
892
893 /**
894 Returns @true if the given pixel is transparent, i.e. either has the mask
895 colour if this image has a mask or if this image has alpha channel and alpha
896 value of this pixel is strictly less than @e threshold.
897 */
898 bool IsTransparent(int x, int y, unsigned char threshold = 128) const;
899
900 //@{
901 /**
902 Loads an image from an input stream.
903
904 @param name
905 Name of the file from which to load the image.
906 @param stream
907 Opened input stream from which to load the image. Currently, the stream
908 must support seeking.
909 @param type
910 One of the following values:
911
912
913
914
915
916
917 wxBITMAP_TYPE_BMP
918
919
920
921
922 Load a Windows image file.
923
924
925
926
927
928 wxBITMAP_TYPE_GIF
929
930
931
932
933 Load a GIF image file.
934
935
936
937
938
939 wxBITMAP_TYPE_JPEG
940
941
942
943
944 Load a JPEG image file.
945
946
947
948
949
950 wxBITMAP_TYPE_PCX
951
952
953
954
955 Load a PCX image file.
956
957
958
959
960
961 wxBITMAP_TYPE_PNG
962
963
964
965
966 Load a PNG image file.
967
968
969
970
971
972 wxBITMAP_TYPE_PNM
973
974
975
976
977 Load a PNM image file.
978
979
980
981
982
983 wxBITMAP_TYPE_TIF
984
985
986
987
988 Load a TIFF image file.
989
990
991
992
993
994 wxBITMAP_TYPE_XPM
995
996
997
998
999 Load a XPM image file.
1000
1001
1002
1003
1004
1005 wxBITMAP_TYPE_ICO
1006
1007
1008
1009
1010 Load a Windows icon file (ICO).
1011
1012
1013
1014
1015
1016 wxBITMAP_TYPE_CUR
1017
1018
1019
1020
1021 Load a Windows cursor file (CUR).
1022
1023
1024
1025
1026
1027 wxBITMAP_TYPE_ANI
1028
1029
1030
1031
1032 Load a Windows animated cursor file (ANI).
1033
1034
1035
1036
1037
1038 wxBITMAP_TYPE_ANY
1039
1040
1041
1042
1043 Will try to autodetect the format.
1044 @param mimetype
1045 MIME type string (for example 'image/jpeg')
1046 @param index
1047 Index of the image to load in the case that the image file contains
1048 multiple images.
1049 This is only used by GIF, ICO and TIFF handlers. The default value (-1)
1050 means
1051 "choose the default image" and is interpreted as the first image (index=0)
1052 by
1053 the GIF and TIFF handler and as the largest and most colourful one by the
1054 ICO handler.
1055
1056 @returns @true if the operation succeeded, @false otherwise. If the
1057 optional index parameter is out of range, @false is
1058 returned and a call to wxLogError() takes place.
1059
1060 @remarks Depending on how wxWidgets has been configured, not all formats
1061 may be available.
1062
1063 @see SaveFile()
1064 */
1065 bool LoadFile(const wxString& name,
1066 long type = wxBITMAP_TYPE_ANY,
1067 int index = -1);
1068 bool LoadFile(const wxString& name, const wxString& mimetype,
1069 int index = -1);
1070 bool LoadFile(wxInputStream& stream, long type,
1071 int index = -1);
1072 bool LoadFile(wxInputStream& stream,
1073 const wxString& mimetype,
1074 int index = -1);
1075 //@}
1076
1077 /**
1078 Returns a mirrored copy of the image. The parameter @e horizontally
1079 indicates the orientation.
1080 */
1081 wxImage Mirror(bool horizontally = true) const;
1082
1083 /**
1084 Copy the data of the given @a image to the specified position in this image.
1085 */
1086 void Paste(const wxImage& image, int x, int y);
1087
1088 /**
1089 Constructor for RGBValue, an object that contains values for red, green and
1090 blue which
1091 represent the value of a color. It is used by HSVtoRGB()
1092 and RGBtoHSV(), which
1093 converts between HSV color space and RGB color space.
1094 */
1095 RGBValue(unsigned char r = 0, unsigned char g = 0,
1096 unsigned char b = 0);
1097
1098 /**
1099 Converts a color in RGB color space to HSV color space.
1100 */
1101 #define wxImage::HSVValue RGBtoHSV(const RGBValue& rgb) /* implementation is private */
1102
1103 /**
1104 Finds the handler with the given name, and removes it. The handler
1105 is not deleted.
1106
1107 @param name
1108 The handler name.
1109
1110 @returns @true if the handler was found and removed, @false otherwise.
1111
1112 @see wxImageHandler
1113 */
1114 static bool RemoveHandler(const wxString& name);
1115
1116 /**
1117 Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
1118 */
1119 void Replace(unsigned char r1, unsigned char g1,
1120 unsigned char b1, unsigned char r2,
1121 unsigned char g2, unsigned char b2);
1122
1123 /**
1124 Changes the size of the image in-place by scaling it: after a call to this
1125 function,
1126 the image will have the given width and height.
1127 For a description of the @a quality parameter, see the Scale() function.
1128 Returns the (modified) image itself.
1129
1130 @see Scale()
1131 */
1132 wxImage Rescale(int width, int height,
1133 int quality = wxIMAGE_QUALITY_NORMAL);
1134
1135 /**
1136 Changes the size of the image in-place without scaling it by adding either a
1137 border
1138 with the given colour or cropping as necessary. The image is pasted into a new
1139 image with the given @a size and background colour at the position @e pos
1140 relative to the upper left of the new image. If @a red = green = blue = -1
1141 then use either the current mask colour if set or find, use, and set a
1142 suitable mask colour for any newly exposed areas.
1143 Returns the (modified) image itself.
1144
1145 @see Size()
1146 */
1147 wxImage Resize(const wxSize& size, const wxPoint pos,
1148 int red = -1, int green = -1,
1149 int blue = -1);
1150
1151 /**
1152 Rotates the image about the given point, by @a angle radians. Passing @true
1153 to @a interpolating results in better image quality, but is slower. If the
1154 image has a mask, then the mask colour is used for the uncovered pixels in the
1155 rotated image background. Else, black (rgb 0, 0, 0) will be used.
1156 Returns the rotated image, leaving this image intact.
1157 */
1158 wxImage Rotate(double angle, const wxPoint& rotationCentre,
1159 bool interpolating = true,
1160 wxPoint* offsetAfterRotation = NULL);
1161
1162 /**
1163 Returns a copy of the image rotated 90 degrees in the direction
1164 indicated by @e clockwise.
1165 */
1166 wxImage Rotate90(bool clockwise = true) const;
1167
1168 /**
1169 Rotates the hue of each pixel in the image by @e angle, which is a double in
1170 the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
1171 corresponds
1172 to +360 degrees.
1173 */
1174 void RotateHue(double angle);
1175
1176 //@{
1177 /**
1178 Saves an image in the given stream.
1179
1180 @param name
1181 Name of the file to save the image to.
1182 @param stream
1183 Opened output stream to save the image to.
1184 @param type
1185 Currently these types can be used:
1186
1187
1188
1189
1190
1191
1192 wxBITMAP_TYPE_BMP
1193
1194
1195
1196
1197 Save a BMP image file.
1198
1199
1200
1201
1202
1203 wxBITMAP_TYPE_JPEG
1204
1205
1206
1207
1208 Save a JPEG image file.
1209
1210
1211
1212
1213
1214 wxBITMAP_TYPE_PNG
1215
1216
1217
1218
1219 Save a PNG image file.
1220
1221
1222
1223
1224
1225 wxBITMAP_TYPE_PCX
1226
1227
1228
1229
1230 Save a PCX image file (tries to save as 8-bit if possible, falls back to
1231 24-bit otherwise).
1232
1233
1234
1235
1236
1237 wxBITMAP_TYPE_PNM
1238
1239
1240
1241
1242 Save a PNM image file (as raw RGB always).
1243
1244
1245
1246
1247
1248 wxBITMAP_TYPE_TIFF
1249
1250
1251
1252
1253 Save a TIFF image file.
1254
1255
1256
1257
1258
1259 wxBITMAP_TYPE_XPM
1260
1261
1262
1263
1264 Save a XPM image file.
1265
1266
1267
1268
1269
1270 wxBITMAP_TYPE_ICO
1271
1272
1273
1274
1275 Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high.
1276 A single image is saved in 8 colors at the size supplied).
1277
1278
1279
1280
1281
1282 wxBITMAP_TYPE_CUR
1283
1284
1285
1286
1287 Save a Windows cursor file (CUR).
1288 @param mimetype
1289 MIME type.
1290
1291 @returns @true if the operation succeeded, @false otherwise.
1292
1293 @remarks Depending on how wxWidgets has been configured, not all formats
1294 may be available.
1295
1296 @see LoadFile()
1297 */
1298 bool SaveFile(const wxString& name, int type) const;
1299 const bool SaveFile(const wxString& name,
1300 const wxString& mimetype) const;
1301 const bool SaveFile(const wxString& name) const;
1302 const bool SaveFile(wxOutputStream& stream, int type) const;
1303 const bool SaveFile(wxOutputStream& stream,
1304 const wxString& mimetype) const;
1305 //@}
1306
1307 /**
1308 Returns a scaled version of the image. This is also useful for
1309 scaling bitmaps in general as the only other way to scale bitmaps
1310 is to blit a wxMemoryDC into another wxMemoryDC.
1311 It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer
1312 looking results it is a slower method. Downsampling will use the box averaging
1313 method
1314 which seems to operate very fast. If you are upsampling larger images using
1315 this method you will most likely notice that it is a bit slower and in extreme
1316 cases
1317 it will be quite substantially slower as the bicubic algorithm has to process a
1318 lot of
1319 data.
1320 It should also be noted that the high quality scaling may not work as expected
1321 when using a single mask colour for transparency, as the scaling will blur the
1322 image and will therefore remove the mask partially. Using the alpha channel
1323 will work.
1324 Example:
1325
1326 @param quality
1327 Determines what method to use for resampling the image. Can be one of the
1328 following:
1329
1330
1331
1332
1333
1334
1335 wxIMAGE_QUALITY_NORMAL
1336
1337
1338
1339
1340 Uses the normal default scaling method of pixel replication
1341
1342
1343
1344
1345
1346 wxIMAGE_QUALITY_HIGH
1347
1348
1349
1350
1351 Uses bicubic and box averaging resampling methods for upsampling and
1352 downsampling respectively
1353
1354 @see Rescale()
1355 */
1356 wxImage Scale(int width, int height,
1357 int quality = wxIMAGE_QUALITY_NORMAL) const;
1358
1359 //@{
1360 /**
1361 Sets the alpha value for the given pixel. This function should only be called
1362 if the image has alpha channel data, use HasAlpha() to
1363 check for this.
1364 */
1365 void SetAlpha(unsigned char* alpha = NULL,
1366 bool static_data = false);
1367 void SetAlpha(int x, int y, unsigned char alpha);
1368 //@}
1369
1370 /**
1371 Sets the image data without performing checks. The data given must have
1372 the size (width*height*3) or results will be unexpected. Don't use this
1373 method if you aren't sure you know what you are doing.
1374 The data must have been allocated with @c malloc(), @b NOT with
1375 @c operator new.
1376 After this call the pointer to the data is owned by the wxImage object,
1377 that will be responsible for deleting it.
1378 Do not pass to this function a pointer obtained through
1379 GetData().
1380 */
1381 void SetData(unsigned char* data);
1382
1383 /**
1384 Specifies whether there is a mask or not. The area of the mask is determined by
1385 the current mask colour.
1386 */
1387 void SetMask(bool hasMask = true);
1388
1389 /**
1390 Sets the mask colour for this image (and tells the image to use the mask).
1391 */
1392 void SetMaskColour(unsigned char red, unsigned char green,
1393 unsigned char blue);
1394
1395 /**
1396 @param mask
1397 The mask image to extract mask shape from. Must have same dimensions as the
1398 image.
1399 @param mr,mg,mb
1400 RGB value of pixels in mask that will be used to create the mask.
1401
1402 @returns Returns @false if mask does not have same dimensions as the image
1403 or if there is no unused colour left. Returns @true if
1404 the mask was successfully applied.
1405 */
1406 bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
1407 unsigned char mg,
1408 unsigned char mb);
1409
1410 //@{
1411 /**
1412 Sets a user-defined option. The function is case-insensitive to @e name.
1413 For example, when saving as a JPEG file, the option @b quality is
1414 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1415
1416 @see GetOption(), GetOptionInt(), HasOption()
1417 */
1418 void SetOption(const wxString& name, const wxString& value);
1419 void SetOption(const wxString& name, int value);
1420 //@}
1421
1422 /**
1423 Associates a palette with the image. The palette may be used when converting
1424 wxImage to wxBitmap (MSW only at present) or in file save operations (none as
1425 yet).
1426 */
1427 void SetPalette(const wxPalette& palette);
1428
1429 /**
1430 Sets the colour of the pixels within the given rectangle. This routine performs
1431 bounds-checks for the coordinate so it can be considered a safe way to
1432 manipulate the
1433 data.
1434 */
1435 void SetRGB(wxRect& rect, unsigned char red,
1436 unsigned char green,
1437 unsigned char blue);
1438
1439 /**
1440 Returns a resized version of this image without scaling it by adding either a
1441 border
1442 with the given colour or cropping as necessary. The image is pasted into a new
1443 image with the given @a size and background colour at the position @e pos
1444 relative to the upper left of the new image. If @a red = green = blue = -1
1445 then the areas of the larger image not covered by this image are made
1446 transparent by filling them with the image mask colour (which will be allocated
1447 automatically if it isn't currently set). Otherwise, the areas will be filled
1448 with the colour with the specified RGB components.
1449
1450 @see Resize()
1451 */
1452 wxImage Size(const wxSize& size, const wxPoint pos, int red = -1,
1453 int green = -1, int blue = -1) const;
1454
1455 /**
1456 Assignment operator, using @ref overview_trefcount "reference counting".
1457
1458 @param image
1459 Image to assign.
1460
1461 @returns Returns 'this' object.
1462 */
1463 wxImage operator =(const wxImage& image);
1464 };
1465
1466 /**
1467 An empty wxImage.
1468 */
1469 wxImage wxNullImage;
1470
1471
1472 // ============================================================================
1473 // Global functions/macros
1474 // ============================================================================
1475
1476 /** @ingroup group_funcmacro_appinitterm */
1477 //@{
1478
1479 /**
1480 Initializes all available image handlers. For a list of available handlers,
1481 see wxImage.
1482
1483 @see wxImage, wxImageHandler
1484
1485 @header{wx/image.h}
1486 */
1487 void wxInitAllImageHandlers();
1488
1489 //@}
1490