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