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