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