interface/wx/image.h

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