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