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