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 Returns @true on success, @false on error.
 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         @return Returns @true on success, @false on error.
 845      */
 846     bool ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
 847                             unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
 848
 849     /**
 850         Returns a greyscale version of the image.
 851
 852         The returned image uses the luminance component of the original to
 853         calculate the greyscale. Defaults to using the standard ITU-T BT.601
 854         when converting to YUV, where every pixel equals
 855         (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
 856     */
 857     wxImage ConvertToGreyscale(double weight_r, double weight_g, double weight_b) const;
 858
 859     /**
 860         Returns a greyscale version of the image.
 861         @since 2.9.0
 862     */
 863     wxImage ConvertToGreyscale() const;
 864
 865     /**
 866         Returns monochromatic version of the image.
 867
 868         The returned image has white colour where the original has @e (r,g,b)
 869         colour and black colour everywhere else.
 870     */
 871     wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
 872
 873     /**
 874         Returns disabled (dimmed) version of the image.
 875         @since 2.9.0
 876     */
 877     wxImage ConvertToDisabled(unsigned char brightness = 255) const;
 878
 879     //@}
 880
 881
 882     /**
 883         @name Miscellaneous functions
 884     */
 885     //@{
 886
 887     /**
 888         Computes the histogram of the image. @a histogram is a reference to
 889         wxImageHistogram object. wxImageHistogram is a specialization of
 890         wxHashMap "template" and is defined as follows:
 891
 892         @code
 893         class WXDLLEXPORT wxImageHistogramEntry
 894         {
 895         public:
 896             wxImageHistogramEntry() : index(0), value(0) {}
 897             unsigned long index;
 898             unsigned long value;
 899         };
 900
 901         WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
 902                                     wxIntegerHash, wxIntegerEqual,
 903                                     wxImageHistogram);
 904         @endcode
 905
 906         @return Returns number of colours in the histogram.
 907     */
 908     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 909
 910     /**
 911         Finds the first colour that is never used in the image.
 912         The search begins at given initial colour and continues by increasing
 913         R, G and B components (in this order) by 1 until an unused colour is
 914         found or the colour space exhausted.
 915
 916         The parameters @a r, @a g, @a b are pointers to variables to save the colour.
 917
 918         The parameters @a startR, @a startG, @a startB define the initial values
 919         of the colour.
 920         The returned colour will have RGB values equal to or greater than these.
 921
 922         @return Returns @false if there is no unused colour left, @true on success.
 923
 924         @note
 925             This method involves computing the histogram, which is a
 926             computationally intensive operation.
 927     */
 928     bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
 929                                unsigned char* b, unsigned char startR = 1,
 930                                unsigned char startG = 0,
 931                                unsigned char startB = 0) const;
 932
 933     /**
 934         Assignment operator, using @ref overview_refcount "reference counting".
 935
 936         @param image
 937             Image to assign.
 938
 939         @return Returns 'this' object.
 940     */
 941     wxImage& operator=(const wxImage& image);
 942
 943     //@}
 944
 945
 946     /**
 947         @name Getters
 948     */
 949     //@{
 950
 951     /**
 952         Returns pointer to the array storing the alpha values for this image.
 953
 954         This pointer is @NULL for the images without the alpha channel. If the image
 955         does have it, this pointer may be used to directly manipulate the alpha values
 956         which are stored as the RGB ones.
 957     */
 958     unsigned char* GetAlpha() const;
 959
 960     /**
 961         Returns the image data as an array.
 962
 963         This is most often used when doing direct image manipulation.
 964         The return value points to an array of characters in RGBRGBRGB... format
 965         in the top-to-bottom, left-to-right order, that is the first RGB triplet
 966         corresponds to the pixel first pixel of the first row, the second one ---
 967         to the second pixel of the first row and so on until the end of the first
 968         row, with second row following after it and so on.
 969
 970         You should not delete the returned pointer nor pass it to SetData().
 971     */
 972     unsigned char* GetData() const;
 973
 974     /**
 975         Return alpha value at given pixel location.
 976     */
 977     unsigned char GetAlpha(int x, int y) const;
 978
 979     /**
 980         Returns the red intensity at the given coordinate.
 981     */
 982     unsigned char GetRed(int x, int y) const;
 983
 984     /**
 985         Returns the green intensity at the given coordinate.
 986     */
 987     unsigned char GetGreen(int x, int y) const;
 988
 989     /**
 990         Returns the blue intensity at the given coordinate.
 991     */
 992     unsigned char GetBlue(int x, int y) const;
 993
 994     /**
 995         Gets the red value of the mask colour.
 996     */
 997     unsigned char GetMaskRed() const;
 998
 999     /**
1000         Gets the green value of the mask colour.
1001     */
1002     unsigned char GetMaskGreen() const;
1003
1004     /**
1005         Gets the blue value of the mask colour.
1006     */
1007     unsigned char GetMaskBlue() const;
1008
1009     /**
1010         Gets the width of the image in pixels.
1011
1012         @see GetHeight(), GetSize()
1013     */
1014     int GetWidth() const;
1015
1016     /**
1017         Gets the height of the image in pixels.
1018
1019         @see GetWidth(), GetSize()
1020     */
1021     int GetHeight() const;
1022
1023     /**
1024         Returns the size of the image in pixels.
1025
1026         @since 2.9.0
1027
1028         @see GetHeight(), GetWidth()
1029     */
1030     wxSize GetSize() const;
1031
1032     /**
1033         Gets a user-defined string-valued option.
1034
1035         Currently the only defined string option is
1036         @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
1037             was loaded.
1038
1039         @param name
1040             The name of the option, case-insensitive.
1041         @return
1042             The value of the option or an empty string if not found. Use
1043             HasOption() if an empty string can be a valid option value.
1044
1045         @see SetOption(), GetOptionInt(), HasOption()
1046     */
1047     wxString GetOption(const wxString& name) const;
1048
1049     /**
1050         Gets a user-defined integer-valued option.
1051
1052         The function is case-insensitive to @a name.
1053         If the given option is not present, the function returns 0.
1054         Use HasOption() is 0 is a possibly valid value for the option.
1055
1056         Generic options:
1057         @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
1058             of these options is specified, the loaded image will be scaled down
1059             (preserving its aspect ratio) so that its width is less than the
1060             max width given if it is not 0 @em and its height is less than the
1061             max height given if it is not 0. This is typically used for loading
1062             thumbnails and the advantage of using these options compared to
1063             calling Rescale() after loading is that some handlers (only JPEG
1064             one right now) support rescaling the image during loading which is
1065             vastly more efficient than loading the entire huge image and
1066             rescaling it later (if these options are not supported by the
1067             handler, this is still what happens however). These options must be
1068             set before calling LoadFile() to have any effect.
1069
1070         @li @c wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
1071             integer in 0..100 range with 0 meaning very poor and 100 excellent
1072             (but very badly compressed). This option is currently ignored for
1073             the other formats.
1074
1075         @li @c wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
1076             whether the resolution of the image is specified in centimetres or
1077             inches, see wxImageResolution enum elements.
1078
1079         @li @c wxIMAGE_OPTION_RESOLUTION, @c wxIMAGE_OPTION_RESOLUTIONX and
1080             @c wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
1081             the image in the units corresponding to @c wxIMAGE_OPTION_RESOLUTIONUNIT
1082             options value. The first option can be set before saving the image
1083             to set both horizontal and vertical resolution to the same value.
1084             The X and Y options are set by the image handlers if they support
1085             the image resolution (currently BMP, JPEG and TIFF handlers do) and
1086             the image provides the resolution information and can be queried
1087             after loading the image.
1088
1089         Options specific to wxPNGHandler:
1090         @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
1091             wxImagePNGType for the supported values.
1092         @li @c wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
1093         @li @c wxIMAGE_OPTION_PNG_FILTER: Filter for saving a PNG file, see libpng
1094             (http://www.libpng.org/pub/png/libpng-1.2.5-manual.html) for possible values
1095             (e.g. PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FILTER_UP, etc).
1096         @li @c wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL: Compression level (0..9) for
1097             saving a PNG file. An high value creates smaller-but-slower PNG file.
1098             Note that unlike other formats (e.g. JPEG) the PNG format is always
1099             lossless and thus this compression level doesn't tradeoff the image
1100             quality.
1101         @li @c wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL: Compression memory usage
1102             level (1..9) for saving a PNG file. An high value means the saving
1103             process consumes more memory, but may create smaller PNG file.
1104         @li @c wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY: Possible values are 0 for
1105             default strategy, 1 for filter, and 2 for Huffman-only.
1106             You can use OptiPNG (http://optipng.sourceforge.net/) to get a suitable
1107             value for your application.
1108         @li @c wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE: Internal buffer size
1109             (in bytes) for saving a PNG file. Ideally this should be as big as
1110             the resulting PNG file. Use this option if your application produces
1111             images with small size variation.
1112
1113         @param name
1114             The name of the option, case-insensitive.
1115         @return
1116             The value of the option or 0 if not found.
1117             Use HasOption() if 0 can be a valid option value.
1118
1119         @see SetOption(), GetOption()
1120     */
1121     int GetOptionInt(const wxString& name) const;
1122
1123     /**
1124         Get the current mask colour or find a suitable unused colour that could be
1125         used as a mask colour. Returns @true if the image currently has a mask.
1126     */
1127     bool GetOrFindMaskColour(unsigned char* r, unsigned char* g,
1128                              unsigned char* b) const;
1129
1130     /**
1131         Returns the palette associated with the image.
1132         Currently the palette is only used when converting to wxBitmap under Windows.
1133
1134         Some of the wxImage handlers have been modified to set the palette if
1135         one exists in the image file (usually 256 or less colour images in
1136         GIF or PNG format).
1137     */
1138     const wxPalette& GetPalette() const;
1139
1140     /**
1141         Returns a sub image of the current one as long as the rect belongs entirely
1142         to the image.
1143     */
1144     wxImage GetSubImage(const wxRect& rect) const;
1145
1146     /**
1147         Gets the type of image found by LoadFile() or specified with SaveFile().
1148
1149         @since 2.9.0
1150     */
1151     wxBitmapType GetType() const;
1152
1153     /**
1154         Returns @true if this image has alpha channel, @false otherwise.
1155
1156         @see GetAlpha(), SetAlpha()
1157     */
1158     bool HasAlpha() const;
1159
1160     /**
1161         Returns @true if there is a mask active, @false otherwise.
1162     */
1163     bool HasMask() const;
1164
1165     /**
1166         Returns @true if the given option is present.
1167         The function is case-insensitive to @a name.
1168
1169         The lists of the currently supported options are in GetOption() and
1170         GetOptionInt() function docs.
1171
1172         @see SetOption(), GetOption(), GetOptionInt()
1173     */
1174     bool HasOption(const wxString& name) const;
1175
1176     /**
1177         Returns @true if image data is present.
1178     */
1179     bool IsOk() const;
1180
1181     /**
1182         Returns @true if the given pixel is transparent, i.e. either has the mask
1183         colour if this image has a mask or if this image has alpha channel and alpha
1184         value of this pixel is strictly less than @a threshold.
1185     */
1186     bool IsTransparent(int x, int y,
1187                        unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
1188
1189     //@}
1190
1191
1192     /**
1193         @name Loading and saving functions
1194     */
1195     //@{
1196
1197     /**
1198         Loads an image from an input stream.
1199
1200         @param stream
1201             Opened input stream from which to load the image.
1202             Currently, the stream must support seeking.
1203         @param type
1204             May be one of the following:
1205             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1206             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1207             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1208             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1209             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1210             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1211             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
1212             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1213             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1214             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1215             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1216             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1217             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1218         @param index
1219             Index of the image to load in the case that the image file contains
1220             multiple images. This is only used by GIF, ICO and TIFF handlers.
1221             The default value (-1) means "choose the default image" and is
1222             interpreted as the first image (index=0) by the GIF and TIFF handler
1223             and as the largest and most colourful one by the ICO handler.
1224
1225         @return @true if the operation succeeded, @false otherwise.
1226                 If the optional index parameter is out of range, @false is
1227                 returned and a call to wxLogError() takes place.
1228
1229         @remarks Depending on how wxWidgets has been configured, not all formats
1230                  may be available.
1231
1232         @note
1233             You can use GetOptionInt() to get the hotspot when loading cursor files:
1234             @code
1235             int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
1236             int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
1237             @endcode
1238
1239         @see SaveFile()
1240     */
1241     virtual bool LoadFile(wxInputStream& stream,
1242                           wxBitmapType type = wxBITMAP_TYPE_ANY,
1243                           int index = -1);
1244
1245     /**
1246         Loads an image from a file.
1247         If no handler type is provided, the library will try to autodetect the format.
1248
1249         @param name
1250             Name of the file from which to load the image.
1251         @param type
1252             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1253         @param index
1254             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1255     */
1256     virtual bool LoadFile(const wxString& name,
1257                           wxBitmapType type = wxBITMAP_TYPE_ANY,
1258                           int index = -1);
1259
1260     /**
1261         Loads an image from a file.
1262         If no handler type is provided, the library will try to autodetect the format.
1263
1264         @param name
1265             Name of the file from which to load the image.
1266         @param mimetype
1267             MIME type string (for example 'image/jpeg')
1268         @param index
1269             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1270     */
1271     virtual bool LoadFile(const wxString& name, const wxString& mimetype,
1272                           int index = -1);
1273
1274     /**
1275         Loads an image from an input stream.
1276
1277         @param stream
1278             Opened input stream from which to load the image.
1279             Currently, the stream must support seeking.
1280         @param mimetype
1281             MIME type string (for example 'image/jpeg')
1282         @param index
1283             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
1284     */
1285     virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
1286                           int index = -1);
1287
1288     /**
1289         Saves an image in the given stream.
1290
1291         @param stream
1292             Opened output stream to save the image to.
1293         @param mimetype
1294             MIME type.
1295
1296         @return @true if the operation succeeded, @false otherwise.
1297
1298         @remarks Depending on how wxWidgets has been configured, not all formats
1299                  may be available.
1300
1301         @note
1302             You can use SetOption() to set the hotspot when saving an image
1303             into a cursor file (default hotspot is in the centre of the image):
1304             @code
1305             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1306             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1307             @endcode
1308
1309         @see LoadFile()
1310     */
1311     virtual bool SaveFile(wxOutputStream& stream,
1312                           const wxString& mimetype) const;
1313
1314     /**
1315         Saves an image in the named file.
1316
1317         @param name
1318             Name of the file to save the image to.
1319         @param type
1320             Currently these types can be used:
1321             @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1322             @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1323             @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1324             @li wxBITMAP_TYPE_PCX: Save a PCX image file
1325                 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1326             @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1327             @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1328             @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1329             @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1330                 The size may be up to 255 wide by 127 high. A single image is saved
1331                 in 8 colors at the size supplied.
1332             @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1333     */
1334     virtual bool SaveFile(const wxString& name, wxBitmapType type) const;
1335
1336     /**
1337         Saves an image in the named file.
1338
1339         @param name
1340             Name of the file to save the image to.
1341         @param mimetype
1342             MIME type.
1343     */
1344     virtual bool SaveFile(const wxString& name, const wxString& mimetype) const;
1345
1346     /**
1347         Saves an image in the named file.
1348
1349         File type is determined from the extension of the file name.
1350         Note that this function may fail if the extension is not recognized!
1351         You can use one of the forms above to save images to files with
1352         non-standard extensions.
1353
1354         @param name
1355             Name of the file to save the image to.
1356     */
1357     virtual bool SaveFile(const wxString& name) const;
1358
1359     /**
1360         Saves an image in the given stream.
1361
1362         @param stream
1363             Opened output stream to save the image to.
1364         @param type
1365             MIME type.
1366     */
1367     virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
1368
1369     //@}
1370
1371
1372
1373     /**
1374         @name Setters
1375     */
1376     //@{
1377
1378     /**
1379        This function is similar to SetData() and has similar restrictions.
1380
1381         The pointer passed to it may however be @NULL in which case the function
1382         will allocate the alpha array internally -- this is useful to add alpha
1383         channel data to an image which doesn't have any.
1384
1385         If the pointer is not @NULL, it must have one byte for each image pixel
1386         and be allocated with malloc().
1387         wxImage takes ownership of the pointer and will free it unless @a static_data
1388         parameter is set to @true -- in this case the caller should do it.
1389     */
1390     void SetAlpha(unsigned char* alpha = NULL,
1391                   bool static_data = false);
1392
1393     /**
1394         Sets the alpha value for the given pixel.
1395         This function should only be called if the image has alpha channel data,
1396         use HasAlpha() to check for this.
1397     */
1398     void SetAlpha(int x, int y, unsigned char alpha);
1399
1400     /**
1401         Removes the alpha channel from the image.
1402
1403         This function should only be called if the image has alpha channel data,
1404         use HasAlpha() to check for this.
1405
1406         @since 2.9.1
1407     */
1408     void ClearAlpha();
1409
1410     /**
1411         Sets the image data without performing checks.
1412
1413         The data given must have the size (width*height*3) or results will be
1414         unexpected. Don't use this method if you aren't sure you know what you
1415         are doing.
1416
1417         The data must have been allocated with @c malloc(), @b NOT with
1418         @c operator new.
1419
1420         If @a static_data is @false, after this call the pointer to the data is
1421         owned by the wxImage object, that will be responsible for deleting it.
1422         Do not pass to this function a pointer obtained through GetData().
1423     */
1424     void SetData(unsigned char* data, bool static_data = false);
1425
1426     /**
1427         @overload
1428     */
1429     void SetData(unsigned char* data, int new_width, int new_height,
1430                  bool static_data = false);
1431
1432     /**
1433         Specifies whether there is a mask or not.
1434
1435         The area of the mask is determined by the current mask colour.
1436     */
1437     void SetMask(bool hasMask = true);
1438
1439     /**
1440         Sets the mask colour for this image (and tells the image to use the mask).
1441     */
1442     void SetMaskColour(unsigned char red, unsigned char green,
1443                        unsigned char blue);
1444
1445     /**
1446         Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1447         mask will be masked in the image.
1448
1449         This is done by first finding an unused colour in the image, setting
1450         this colour as the mask colour and then using this colour to draw all
1451         pixels in the image who corresponding pixel in mask has given RGB value.
1452
1453         The parameter @a mask is the mask image to extract mask shape from.
1454         It must have the same dimensions as the image.
1455
1456         The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1457         mask that will be used to create the mask.
1458
1459         @return Returns @false if mask does not have same dimensions as the image
1460                 or if there is no unused colour left. Returns @true if the mask
1461                 was successfully applied.
1462
1463         @note
1464             Note that this method involves computing the histogram, which is a
1465             computationally intensive operation.
1466     */
1467     bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
1468                           unsigned char mg,
1469                           unsigned char mb);
1470
1471     /**
1472         Sets a user-defined option. The function is case-insensitive to @a name.
1473
1474         For example, when saving as a JPEG file, the option @b quality is
1475         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1476
1477         The lists of the currently supported options are in GetOption() and
1478         GetOptionInt() function docs.
1479
1480         @see GetOption(), GetOptionInt(), HasOption()
1481     */
1482     void SetOption(const wxString& name, const wxString& value);
1483
1484     /**
1485         @overload
1486     */
1487     void SetOption(const wxString& name, int value);
1488
1489     /**
1490         Associates a palette with the image.
1491
1492         The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1493         or in file save operations (none as yet).
1494     */
1495     void SetPalette(const wxPalette& palette);
1496
1497     /**
1498         Sets the colour of the pixels within the given rectangle.
1499
1500         This routine performs bounds-checks for the coordinate so it can be considered
1501         a safe way to manipulate the data.
1502     */
1503     void SetRGB(const wxRect& rect,
1504                 unsigned char red,
1505                 unsigned char green,
1506                 unsigned char blue);
1507
1508     /**
1509         Set the type of image returned by GetType().
1510
1511         This method is mostly used internally by the library but can also be
1512         called from the user code if the image was created from data in the
1513         given bitmap format without using LoadFile() (which would set the type
1514         correctly automatically).
1515
1516         Notice that the image must be created before this function is called.
1517
1518         @since 2.9.0
1519
1520         @param type
1521             One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1522             value for it and can be used to reset the bitmap type to default
1523             but @c wxBITMAP_TYPE_MAX is not allowed here.
1524     */
1525     void SetType(wxBitmapType type);
1526
1527     //@}
1528
1529
1530
1531     /**
1532         @name Handler management functions
1533     */
1534     //@{
1535
1536     /**
1537         Register an image handler.
1538         See @ref image_handlers for a list of the available handlers.
1539     */
1540     static void AddHandler(wxImageHandler* handler);
1541
1542     /**
1543         Deletes all image handlers.
1544         This function is called by wxWidgets on exit.
1545     */
1546     static void CleanUpHandlers();
1547
1548     /**
1549         Finds the handler with the given name.
1550
1551         @param name
1552             The handler name.
1553
1554         @return A pointer to the handler if found, @NULL otherwise.
1555
1556         @see wxImageHandler
1557     */
1558     static wxImageHandler* FindHandler(const wxString& name);
1559
1560     /**
1561         Finds the handler associated with the given extension and type.
1562
1563         @param extension
1564             The file extension, such as "bmp".
1565         @param imageType
1566             The image type; one of the ::wxBitmapType values.
1567
1568         @return A pointer to the handler if found, @NULL otherwise.
1569
1570         @see wxImageHandler
1571     */
1572     static wxImageHandler* FindHandler(const wxString& extension,
1573                                        wxBitmapType imageType);
1574
1575     /**
1576         Finds the handler associated with the given image type.
1577
1578         @param imageType
1579             The image type; one of the ::wxBitmapType values.
1580
1581         @return A pointer to the handler if found, @NULL otherwise.
1582
1583         @see wxImageHandler
1584     */
1585     static wxImageHandler* FindHandler(wxBitmapType imageType);
1586
1587     /**
1588         Finds the handler associated with the given MIME type.
1589
1590         @param mimetype
1591             MIME type.
1592
1593         @return A pointer to the handler if found, @NULL otherwise.
1594
1595         @see wxImageHandler
1596     */
1597     static wxImageHandler* FindHandlerMime(const wxString& mimetype);
1598
1599     /**
1600         Returns the static list of image format handlers.
1601
1602         @see wxImageHandler
1603     */
1604     static wxList& GetHandlers();
1605
1606     /**
1607         Internal use only. Adds standard image format handlers.
1608         It only install wxBMPHandler for the time being, which is used by wxBitmap.
1609
1610         This function is called by wxWidgets on startup, and shouldn't be called by
1611         the user.
1612
1613         @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
1614     */
1615     static void InitStandardHandlers();
1616
1617     /**
1618         Adds a handler at the start of the static list of format handlers.
1619
1620         @param handler
1621             A new image format handler object. There is usually only one instance
1622             of a given handler class in an application session.
1623
1624         @see wxImageHandler
1625     */
1626     static void InsertHandler(wxImageHandler* handler);
1627
1628     /**
1629         Finds the handler with the given name, and removes it.
1630         The handler is not deleted.
1631
1632         @param name
1633             The handler name.
1634
1635         @return @true if the handler was found and removed, @false otherwise.
1636
1637         @see wxImageHandler
1638     */
1639     static bool RemoveHandler(const wxString& name);
1640
1641     //@}
1642
1643
1644     /**
1645         Returns @true if at least one of the available image handlers can read
1646         the file with the given name.
1647
1648         See wxImageHandler::CanRead for more info.
1649     */
1650     static bool CanRead(const wxString& filename);
1651
1652     /**
1653         Returns @true if at least one of the available image handlers can read
1654         the data in the given stream.
1655
1656         See wxImageHandler::CanRead for more info.
1657     */
1658     static bool CanRead(wxInputStream& stream);
1659
1660     //@{
1661     /**
1662         If the image file contains more than one image and the image handler is
1663         capable of retrieving these individually, this function will return the
1664         number of available images.
1665
1666         For the overload taking the parameter @a filename, that's the name
1667         of the file to query.
1668         For the overload taking the parameter @a stream, that's the opened input
1669         stream with image data.
1670
1671         See wxImageHandler::GetImageCount() for more info.
1672
1673         The parameter @a type may be one of the following values:
1674         @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
1675         @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
1676         @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
1677         @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
1678         @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
1679         @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
1680         @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
1681         @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
1682         @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
1683         @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
1684         @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
1685         @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
1686         @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
1687
1688         @return Number of available images. For most image handlers, this is 1
1689                 (exceptions are TIFF and ICO formats as well as animated GIFs
1690                 for which this function returns the number of frames in the
1691                 animation).
1692     */
1693     static int GetImageCount(const wxString& filename,
1694                              wxBitmapType type = wxBITMAP_TYPE_ANY);
1695     static int GetImageCount(wxInputStream& stream,
1696                              wxBitmapType type = wxBITMAP_TYPE_ANY);
1697     //@}
1698
1699     /**
1700         Iterates all registered wxImageHandler objects, and returns a string containing
1701         file extension masks suitable for passing to file open/save dialog boxes.
1702
1703         @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
1704                 It is usually a good idea to prepend a description before passing
1705                 the result to the dialog.
1706                 Example:
1707                 @code
1708                 wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
1709                                       _("Image Files ") + wxImage::GetImageExtWildcard(),
1710                                       wxFD_OPEN );
1711                 @endcode
1712
1713         @see wxImageHandler
1714     */
1715     static wxString GetImageExtWildcard();
1716
1717     /**
1718         Converts a color in RGB color space to HSV color space.
1719     */
1720     static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
1721
1722     /**
1723         Converts a color in HSV color space to RGB color space.
1724     */
1725     static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv);
1726 };
1727
1728 /**
1729     An instance of an empty image without an alpha channel.
1730 */
1731 wxImage wxNullImage;
1732
1733
1734 // ============================================================================
1735 // Global functions/macros
1736 // ============================================================================
1737
1738 /** @addtogroup group_funcmacro_appinitterm */
1739 //@{
1740
1741 /**
1742     Initializes all available image handlers. For a list of available handlers,
1743     see wxImage.
1744     If you don't need/want all image handlers loaded
1745
1746     @see wxImage, wxImageHandler
1747
1748     @header{wx/image.h}
1749 */
1750 void wxInitAllImageHandlers();
1751
1752 //@}
1753