interface/wx/image.h

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