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