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