interface/wx/image.h

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