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