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