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