interface/wx/image.h

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