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     virtual bool LoadFile(wxImage* image, wxInputStream& stream,
 113                           bool verbose = true, int index = -1);
 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     virtual bool SaveFile(wxImage* image, wxOutputStream& stream,
 128                           bool verbose = true);
 129
 130     /**
 131         Sets the handler extension.
 132
 133         @param extension
 134             Handler extension.
 135     */
 136     void SetExtension(const wxString& extension);
 137
 138     /**
 139         Sets the handler MIME type.
 140
 141         @param mimetype
 142             Handler MIME type.
 143     */
 144     void SetMimeType(const wxString& mimetype);
 145
 146     /**
 147         Sets the handler name.
 148
 149         @param name
 150             Handler name.
 151     */
 152     void SetName(const wxString& name);
 153 };
 154
 155
 156 /**
 157     Constant used to indicate the alpha value conventionally defined as
 158     the complete transparency.
 159 */
 160 const unsigned char wxIMAGE_ALPHA_TRANSPARENT = 0;
 161
 162 /**
 163     Constant used to indicate the alpha value conventionally defined as
 164     the complete opacity.
 165 */
 166 const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff;
 167
 168 /**
 169     @class wxImage
 170
 171     This class encapsulates a platform-independent image.
 172
 173     An image can be created from data, or using wxBitmap::ConvertToImage.
 174     An image can be loaded from a file in a variety of formats, and is extensible
 175     to new formats via image format handlers. Functions are available to set and
 176     get image bits, so it can be used for basic image manipulation.
 177
 178     A wxImage cannot (currently) be drawn directly to a wxDC.
 179     Instead, a platform-specific wxBitmap object must be created from it using
 180     the wxBitmap::wxBitmap(wxImage,int depth) constructor.
 181     This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
 182
 183     One colour value of the image may be used as a mask colour which will lead to
 184     the automatic creation of a wxMask object associated to the bitmap object.
 185
 186
 187     @section image_alpha Alpha channel support
 188
 189     Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is
 190     in addition to a byte for the red, green and blue colour components for each
 191     pixel it also stores a byte representing the pixel opacity.
 192
 193     An alpha value of 0 corresponds to a transparent pixel (null opacity) while
 194     a value of 255 means that the pixel is 100% opaque.
 195     The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
 196     used to indicate those values in a more readable form.
 197
 198     Unlike RGB data, not all images have an alpha channel and before using
 199     wxImage::GetAlpha you should check if this image contains an alpha channel
 200     with wxImage::HasAlpha. Note that currently only the PNG format has full
 201     alpha channel support so only the images loaded from PNG files can have
 202     alpha and, if you initialize the image alpha channel yourself using
 203     wxImage::SetAlpha, you should save it in PNG format to avoid losing it.
 204
 205
 206     @section image_handlers Available image handlers
 207
 208     The following image handlers are available.
 209     wxBMPHandler is always installed by default.
 210     To use other image formats, install the appropriate handler with
 211     wxImage::AddHandler or call ::wxInitAllImageHandlers().
 212
 213     - wxBMPHandler: For loading and saving, always installed.
 214     - wxPNGHandler: For loading (including alpha support) and saving.
 215     - wxJPEGHandler: For loading and saving.
 216     - wxGIFHandler: Only for loading, due to legal issues.
 217     - wxPCXHandler: For loading and saving (see below).
 218     - wxPNMHandler: For loading and saving (see below).
 219     - wxTIFFHandler: For loading and saving.
 220     - wxTGAHandler: For loading only.
 221     - wxIFFHandler: For loading only.
 222     - wxXPMHandler: For loading and saving.
 223     - wxICOHandler: For loading and saving.
 224     - wxCURHandler: For loading and saving.
 225     - wxANIHandler: For loading only.
 226
 227     When saving in PCX format, wxPCXHandler will count the number of different
 228     colours in the image; if there are 256 or less colours, it will save as 8 bit,
 229     else it will save as 24 bit.
 230
 231     Loading PNMs only works for ASCII or raw RGB images.
 232     When saving in PNM format, wxPNMHandler will always save as raw RGB.
 233
 234
 235     @library{wxcore}
 236     @category{gdi}
 237
 238     @stdobjects
 239     ::wxNullImage
 240
 241     @see wxBitmap, wxInitAllImageHandlers(), wxPixelData
 242 */
 243 class wxImage : public wxObject
 244 {
 245 public:
 246     class RGBValue
 247     {
 248     public:
 249         /**
 250             Constructor for RGBValue, an object that contains values for red, green
 251             and blue which represent the value of a color.
 252
 253             It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which converts
 254             between HSV color space and RGB color space.
 255         */
 256         RGBValue(unsigned char r=0, unsigned char g=0, unsigned char b=0);
 257     };
 258
 259     class HSVValue
 260     {
 261     public:
 262         /**
 263             Constructor for HSVValue, an object that contains values for hue, saturation
 264             and value which represent the value of a color.
 265
 266             It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which converts
 267             between HSV color space and RGB color space.
 268         */
 269         HSVValue(double h=0.0, double s=0.0, double v=0.0);
 270     };
 271
 272     /**
 273         Creates an empty wxImage object without an alpha channel.
 274     */
 275     wxImage();
 276
 277     /**
 278         Creates an image with the given size and clears it if requested.
 279
 280         Does not create an alpha channel.
 281
 282         @param width
 283             Specifies the width of the image.
 284         @param height
 285             Specifies the height of the image.
 286         @param clear
 287             If @true, initialize the image to black.
 288     */
 289     wxImage(int width, int height, bool clear = true);
 290
 291     /**
 292         Creates an image from data in memory. If @a static_data is @false
 293         then the wxImage will take ownership of the data and free it
 294         afterwards. For this, it has to be allocated with @e malloc.
 295
 296         @param width
 297             Specifies the width of the image.
 298         @param height
 299             Specifies the height of the image.
 300         @param data
 301             A pointer to RGB data
 302         @param static_data
 303             Indicates if the data should be free'd after use
 304
 305     */
 306     wxImage(int width, int height, unsigned char* data,  bool static_data = false);
 307
 308     /**
 309         Creates an image from data in memory. If @a static_data is @false
 310         then the wxImage will take ownership of the data and free it
 311         afterwards. For this, it has to be allocated with @e malloc.
 312
 313         @param width
 314             Specifies the width of the image.
 315         @param height
 316             Specifies the height of the image.
 317         @param data
 318             A pointer to RGB data
 319         @param alpha
 320             A pointer to alpha-channel data
 321         @param static_data
 322             Indicates if the data should be free'd after use
 323
 324     */
 325     wxImage(int width, int height, unsigned char* data, unsigned char* alpha,
 326             bool static_data = false );
 327
 328     /**
 329         Creates an image from XPM data.
 330
 331         @param xpmData
 332             A pointer to XPM image data.
 333     */
 334     wxImage(const char* const* xpmData);
 335
 336     /**
 337         Creates an image from a file.
 338
 339         @param name
 340             Name of the file from which to load the image.
 341         @param type
 342             May be one of the following:
 343             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 344             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 345             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 346             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 347             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 348             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 349             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 350             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 351             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 352             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 353             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 354             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 355             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 356         @param index
 357             Index of the image to load in the case that the image file contains
 358             multiple images. This is only used by GIF, ICO and TIFF handlers.
 359             The default value (-1) means "choose the default image" and is
 360             interpreted as the first image (index=0) by the GIF and TIFF handler
 361             and as the largest and most colourful one by the ICO handler.
 362
 363         @remarks Depending on how wxWidgets has been configured and by which
 364                  handlers have been loaded, not all formats may be available.
 365                  Any handler other than BMP must be previously initialized with
 366                 wxImage::AddHandler or wxInitAllImageHandlers.
 367
 368         @note
 369             You can use GetOptionInt() to get the hotspot when loading cursor files:
 370             @code
 371             int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
 372             int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
 373             @endcode
 374
 375         @see LoadFile()
 376     */
 377     wxImage(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
 378
 379     /**
 380         Creates an image from a file using MIME-types to specify the type.
 381
 382         @param name
 383             Name of the file from which to load the image.
 384         @param mimetype
 385             MIME type string (for example 'image/jpeg')
 386         @param index
 387             See description in wxImage(const wxString&, wxBitmapType, int) overload.
 388     */
 389     wxImage(const wxString& name, const wxString& mimetype, int index = -1);
 390
 391     /**
 392         Creates an image from a stream.
 393
 394         @param stream
 395             Opened input stream from which to load the image. Currently,
 396             the stream must support seeking.
 397         @param type
 398             See description in wxImage(const wxString&, wxBitmapType, int) overload.
 399         @param index
 400             See description in wxImage(const wxString&, wxBitmapType, int) overload.
 401     */
 402     wxImage(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
 403
 404     /**
 405         Creates an image from a stream using MIME-types to specify the type.
 406
 407         @param stream
 408             Opened input stream from which to load the image. Currently,
 409             the stream must support seeking.
 410         @param mimetype
 411             MIME type string (for example 'image/jpeg')
 412         @param index
 413             See description in wxImage(const wxString&, wxBitmapType, int) overload.
 414     */
 415     wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);
 416
 417
 418     /**
 419         Destructor.
 420
 421         See @ref overview_refcount_destruct "reference-counted object destruction"
 422         for more info.
 423     */
 424     virtual ~wxImage();
 425
 426     /**
 427         Register an image handler.
 428     */
 429     static void AddHandler(wxImageHandler* handler);
 430
 431     /**
 432         Blurs the image in both horizontal and vertical directions by the
 433         specified pixel @a blurRadius. This should not be used when using
 434         a single mask colour for transparency.
 435
 436         @see BlurHorizontal(), BlurVertical()
 437     */
 438     wxImage Blur(int blurRadius) const;
 439
 440     /**
 441         Blurs the image in the horizontal direction only. This should not be used
 442         when using a single mask colour for transparency.
 443
 444         @see Blur(), BlurVertical()
 445     */
 446     wxImage BlurHorizontal(int blurRadius) const;
 447
 448     /**
 449         Blurs the image in the vertical direction only. This should not be used
 450         when using a single mask colour for transparency.
 451
 452         @see Blur(), BlurHorizontal()
 453     */
 454     wxImage BlurVertical(int blurRadius) const;
 455
 456     /**
 457         Returns @true if the current image handlers can read this file
 458     */
 459     static bool CanRead(const wxString& filename);
 460
 461     /**
 462         Deletes all image handlers.
 463         This function is called by wxWidgets on exit.
 464     */
 465     static void CleanUpHandlers();
 466
 467     /**
 468         Computes the histogram of the image. @a histogram is a reference to
 469         wxImageHistogram object. wxImageHistogram is a specialization of
 470         wxHashMap "template" and is defined as follows:
 471
 472         @code
 473         class WXDLLEXPORT wxImageHistogramEntry
 474         {
 475         public:
 476             wxImageHistogramEntry() : index(0), value(0) {}
 477             unsigned long index;
 478             unsigned long value;
 479         };
 480
 481         WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
 482                                     wxIntegerHash, wxIntegerEqual,
 483                                     wxImageHistogram);
 484         @endcode
 485
 486         @return Returns number of colours in the histogram.
 487     */
 488     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 489
 490     /**
 491         If the image has alpha channel, this method converts it to mask.
 492
 493         All pixels with alpha value less than @a threshold are replaced with mask
 494         colour and the alpha channel is removed. Mask colour is chosen automatically
 495         using FindFirstUnusedColour().
 496
 497         If the image image doesn't have alpha channel, ConvertAlphaToMask() does nothing.
 498
 499         @return @false if FindFirstUnusedColour returns @false, @true otherwise.
 500     */
 501     bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
 502
 503     /**
 504         @deprecated
 505         Use the equivalent @ref wxBitmap::wxBitmap "wxBitmap constructor"
 506         (which takes wxImage and depth as its arguments) instead.
 507     */
 508     wxBitmap ConvertToBitmap() const;
 509
 510     /**
 511         Returns a greyscale version of the image.
 512
 513         The returned image uses the luminance component of the original to
 514         calculate the greyscale. Defaults to using the standard ITU-T BT.601
 515         when converting to YUV, where every pixel equals
 516         (R * @a lr) + (G * @a lg) + (B * @a lb).
 517     */
 518     wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.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     static 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,
 886                        unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
 887
 888     /**
 889         Loads an image from an input stream.
 890
 891         @param stream
 892             Opened input stream from which to load the image.
 893             Currently, the stream must support seeking.
 894         @param type
 895             May be one of the following:
 896             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 897             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 898             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 899             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 900             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 901             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 902             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 903             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 904             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 905             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 906             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 907             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 908             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 909         @param index
 910             Index of the image to load in the case that the image file contains
 911             multiple images. This is only used by GIF, ICO and TIFF handlers.
 912             The default value (-1) means "choose the default image" and is
 913             interpreted as the first image (index=0) by the GIF and TIFF handler
 914             and as the largest and most colourful one by the ICO handler.
 915
 916         @return @true if the operation succeeded, @false otherwise.
 917                 If the optional index parameter is out of range, @false is
 918                 returned and a call to wxLogError() takes place.
 919
 920         @remarks Depending on how wxWidgets has been configured, not all formats
 921                  may be available.
 922
 923         @note
 924             You can use GetOptionInt() to get the hotspot when loading cursor files:
 925             @code
 926             int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
 927             int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
 928             @endcode
 929
 930         @see SaveFile()
 931     */
 932     bool LoadFile(wxInputStream& stream, wxBitmapType type, int index = -1);
 933
 934     /**
 935         Loads an image from a file.
 936         If no handler type is provided, the library will try to autodetect the format.
 937
 938         @param name
 939             Name of the file from which to load the image.
 940         @param type
 941             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 942         @param index
 943             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 944     */
 945     virtual bool LoadFile(const wxString& name,
 946                           wxBitmapType type = wxBITMAP_TYPE_ANY,
 947                           int index = -1);
 948
 949     /**
 950         Loads an image from a file.
 951         If no handler type is provided, the library will try to autodetect the format.
 952
 953         @param name
 954             Name of the file from which to load the image.
 955         @param mimetype
 956             MIME type string (for example 'image/jpeg')
 957         @param index
 958             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 959     */
 960     virtual bool LoadFile(const wxString& name, const wxString& mimetype,
 961                           int index = -1);
 962
 963
 964     /**
 965         Loads an image from an input stream.
 966
 967         @param stream
 968             Opened input stream from which to load the image.
 969             Currently, the stream must support seeking.
 970         @param mimetype
 971             MIME type string (for example 'image/jpeg')
 972         @param index
 973             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 974     */
 975     virtual bool LoadFile(wxInputStream& stream, 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     static 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, int red = -1,
1042                     int green = -1, int blue = -1);
1043
1044     /**
1045         Rotates the image about the given point, by @a angle radians.
1046
1047         Passing @true to @a interpolating results in better image quality, but is slower.
1048
1049         If the image has a mask, then the mask colour is used for the uncovered
1050         pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
1051
1052         Returns the rotated image, leaving this image intact.
1053     */
1054     wxImage Rotate(double angle, const wxPoint& rotationCentre,
1055                    bool interpolating = true,
1056                    wxPoint* offsetAfterRotation = NULL) const;
1057
1058     /**
1059         Returns a copy of the image rotated 90 degrees in the direction
1060         indicated by @a clockwise.
1061     */
1062     wxImage Rotate90(bool clockwise = true) const;
1063
1064     /**
1065         Rotates the hue of each pixel in the image by @e angle, which is a double in
1066         the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
1067         corresponds to +360 degrees.
1068     */
1069     void RotateHue(double angle);
1070
1071     /**
1072         Saves an image in the given stream.
1073
1074         @param stream
1075             Opened output stream to save the image to.
1076         @param mimetype
1077             MIME type.
1078
1079         @return @true if the operation succeeded, @false otherwise.
1080
1081         @remarks Depending on how wxWidgets has been configured, not all formats
1082                  may be available.
1083
1084         @note
1085             You can use SetOption() to set the hotspot when saving an image
1086             into a cursor file (default hotspot is in the centre of the image):
1087             @code
1088             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1089             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1090             @endcode
1091
1092         @see LoadFile()
1093     */
1094     virtual bool SaveFile(wxOutputStream& stream,
1095                           const wxString& mimetype) const;
1096
1097     /**
1098         Saves an image in the named file.
1099
1100         @param name
1101             Name of the file to save the image to.
1102         @param type
1103             Currently these types can be used:
1104             @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1105             @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1106             @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1107             @li wxBITMAP_TYPE_PCX: Save a PCX image file
1108                 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1109             @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1110             @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1111             @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1112             @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1113                 The size may be up to 255 wide by 127 high. A single image is saved
1114                 in 8 colors at the size supplied.
1115             @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1116     */
1117     virtual bool SaveFile(const wxString& name, wxBitmapType type) const;
1118
1119     /**
1120         Saves an image in the named file.
1121
1122         @param name
1123             Name of the file to save the image to.
1124         @param mimetype
1125             MIME type.
1126     */
1127     virtual bool SaveFile(const wxString& name, const wxString& mimetype) const;
1128
1129     /**
1130         Saves an image in the named file.
1131
1132         File type is determined from the extension of the file name.
1133         Note that this function may fail if the extension is not recognized!
1134         You can use one of the forms above to save images to files with
1135         non-standard extensions.
1136
1137         @param name
1138             Name of the file to save the image to.
1139     */
1140     virtual bool SaveFile(const wxString& name) const;
1141
1142     /**
1143         Saves an image in the given stream.
1144
1145         @param stream
1146             Opened output stream to save the image to.
1147         @param type
1148             MIME type.
1149     */
1150     virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
1151
1152     /**
1153         Returns a scaled version of the image.
1154
1155         This is also useful for scaling bitmaps in general as the only other way
1156         to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
1157
1158         The parameter @a quality determines what method to use for resampling the image.
1159         Can be one of the following:
1160         - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
1161                                   replication
1162         - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
1163                                 for upsampling and downsampling respectively
1164
1165         It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
1166         looking results it is a slower method. Downsampling will use the box averaging
1167         method which seems to operate very fast. If you are upsampling larger images using
1168         this method you will most likely notice that it is a bit slower and in extreme
1169         cases it will be quite substantially slower as the bicubic algorithm has to process a
1170         lot of data.
1171
1172         It should also be noted that the high quality scaling may not work as expected
1173         when using a single mask colour for transparency, as the scaling will blur the
1174         image and will therefore remove the mask partially. Using the alpha channel
1175         will work.
1176
1177         Example:
1178         @code
1179         // get the bitmap from somewhere
1180         wxBitmap bmp = ...;
1181
1182         // rescale it to have size of 32*32
1183         if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
1184         {
1185             wxImage image = bmp.ConvertToImage();
1186             bmp = wxBitmap(image.Scale(32, 32));
1187
1188             // another possibility:
1189             image.Rescale(32, 32);
1190             bmp = image;
1191         }
1192         @endcode
1193
1194         @see Rescale()
1195     */
1196     wxImage Scale(int width, int height,
1197                   int quality = wxIMAGE_QUALITY_NORMAL) const;
1198
1199     /**
1200        This function is similar to SetData() and has similar restrictions.
1201
1202         The pointer passed to it may however be @NULL in which case the function
1203         will allocate the alpha array internally -- this is useful to add alpha
1204         channel data to an image which doesn't have any.
1205
1206         If the pointer is not @NULL, it must have one byte for each image pixel
1207         and be allocated with malloc().
1208         wxImage takes ownership of the pointer and will free it unless @a static_data
1209         parameter is set to @true -- in this case the caller should do it.
1210     */
1211     void SetAlpha(unsigned char* alpha = NULL,
1212                   bool static_data = false);
1213
1214     /**
1215         Sets the alpha value for the given pixel.
1216         This function should only be called if the image has alpha channel data,
1217         use HasAlpha() to check for this.
1218     */
1219     void SetAlpha(int x, int y, unsigned char alpha);
1220
1221     /**
1222         Sets the image data without performing checks.
1223
1224         The data given must have the size (width*height*3) or results will be
1225         unexpected. Don't use this method if you aren't sure you know what you
1226         are doing.
1227
1228         The data must have been allocated with @c malloc(), @b NOT with
1229         @c operator new.
1230
1231         After this call the pointer to the data is owned by the wxImage object,
1232         that will be responsible for deleting it.
1233         Do not pass to this function a pointer obtained through GetData().
1234     */
1235     void SetData(unsigned char* data);
1236
1237     /**
1238         Specifies whether there is a mask or not.
1239
1240         The area of the mask is determined by the current mask colour.
1241     */
1242     void SetMask(bool hasMask = true);
1243
1244     /**
1245         Sets the mask colour for this image (and tells the image to use the mask).
1246     */
1247     void SetMaskColour(unsigned char red, unsigned char green,
1248                        unsigned char blue);
1249
1250     /**
1251         Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1252         mask will be masked in the image.
1253
1254         This is done by first finding an unused colour in the image, setting
1255         this colour as the mask colour and then using this colour to draw all
1256         pixels in the image who corresponding pixel in mask has given RGB value.
1257
1258         The parameter @a mask is the mask image to extract mask shape from.
1259         It must have the same dimensions as the image.
1260
1261         The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1262         mask that will be used to create the mask.
1263
1264         @return Returns @false if mask does not have same dimensions as the image
1265                 or if there is no unused colour left. Returns @true if the mask
1266                 was successfully applied.
1267
1268         @note
1269             Note that this method involves computing the histogram, which is a
1270             computationally intensive operation.
1271     */
1272     bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
1273                           unsigned char mg,
1274                           unsigned char mb);
1275
1276     //@{
1277     /**
1278         Sets a user-defined option. The function is case-insensitive to @a name.
1279
1280         For example, when saving as a JPEG file, the option @b quality is
1281         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1282
1283         @see GetOption(), GetOptionInt(), HasOption()
1284     */
1285     void SetOption(const wxString& name, const wxString& value);
1286     void SetOption(const wxString& name, int value);
1287     //@}
1288
1289     /**
1290         Associates a palette with the image.
1291
1292         The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1293         or in file save operations (none as yet).
1294     */
1295     void SetPalette(const wxPalette& palette);
1296
1297     /**
1298         Sets the colour of the pixels within the given rectangle.
1299
1300         This routine performs bounds-checks for the coordinate so it can be considered
1301         a safe way to manipulate the data.
1302     */
1303     void SetRGB(wxRect& rect, unsigned char red,
1304                 unsigned char green,
1305                 unsigned char blue);
1306
1307     /**
1308         Set the type of image returned by GetType().
1309
1310         This method is mostly used internally by the library but can also be
1311         called from the user code if the image was created from data in the
1312         given bitmap format without using LoadFile() (which would set the type
1313         correctly automatically).
1314
1315         Notice that the image must be created before this function is called.
1316
1317         @since 2.9.0
1318
1319         @param type
1320             One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1321             value for it and can be used to reset the bitmap type to default
1322             but @c wxBITMAP_TYPE_MAX is not allowed here.
1323     */
1324     void SetType(wxBitmapType type);
1325
1326     /**
1327         Returns a resized version of this image without scaling it by adding either a
1328         border with the given colour or cropping as necessary.
1329
1330         The image is pasted into a new image with the given @a size and background
1331         colour at the position @a pos relative to the upper left of the new image.
1332
1333         If @a red = green = blue = -1 then the areas of the larger image not covered
1334         by this image are made transparent by filling them with the image mask colour
1335         (which will be allocated automatically if it isn't currently set).
1336
1337         Otherwise, the areas will be filled with the colour with the specified RGB components.
1338
1339         @see Resize()
1340     */
1341     wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
1342                  int green = -1, int blue = -1) const;
1343
1344     /**
1345         Assignment operator, using @ref overview_refcount "reference counting".
1346
1347         @param image
1348             Image to assign.
1349
1350         @return Returns 'this' object.
1351     */
1352     wxImage& operator=(const wxImage& image);
1353 };
1354
1355 // ============================================================================
1356 // Global functions/macros
1357 // ============================================================================
1358
1359 /** @ingroup group_funcmacro_appinitterm */
1360 //@{
1361
1362 /**
1363     Initializes all available image handlers. For a list of available handlers,
1364     see wxImage.
1365
1366     @see wxImage, wxImageHandler
1367
1368     @header{wx/image.h}
1369 */
1370 void wxInitAllImageHandlers();
1371
1372 //@}
1373