interface/wx/image.h

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