interface/wx/image.h

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