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