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