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