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     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     virtual bool LoadFile(wxInputStream& stream,
 936                           wxBitmapType type = wxBITMAP_TYPE_ANY,
 937                           int index = -1);
 938
 939     /**
 940         Loads an image from a file.
 941         If no handler type is provided, the library will try to autodetect the format.
 942
 943         @param name
 944             Name of the file from which to load the image.
 945         @param type
 946             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 947         @param index
 948             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 949     */
 950     virtual bool LoadFile(const wxString& name,
 951                           wxBitmapType type = wxBITMAP_TYPE_ANY,
 952                           int index = -1);
 953
 954     /**
 955         Loads an image from a file.
 956         If no handler type is provided, the library will try to autodetect the format.
 957
 958         @param name
 959             Name of the file from which to load the image.
 960         @param mimetype
 961             MIME type string (for example 'image/jpeg')
 962         @param index
 963             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 964     */
 965     virtual bool LoadFile(const wxString& name, const wxString& mimetype,
 966                           int index = -1);
 967
 968
 969     /**
 970         Loads an image from an input stream.
 971
 972         @param stream
 973             Opened input stream from which to load the image.
 974             Currently, the stream must support seeking.
 975         @param mimetype
 976             MIME type string (for example 'image/jpeg')
 977         @param index
 978             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 979     */
 980     virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
 981                           int index = -1);
 982
 983     /**
 984         Returns a mirrored copy of the image.
 985         The parameter @a horizontally indicates the orientation.
 986     */
 987     wxImage Mirror(bool horizontally = true) const;
 988
 989     /**
 990         Copy the data of the given @a image to the specified position in this image.
 991     */
 992     void Paste(const wxImage& image, int x, int y);
 993
 994     /**
 995         Converts a color in RGB color space to HSV color space.
 996     */
 997     static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
 998
 999     /**
1000         Finds the handler with the given name, and removes it.
1001         The handler is not deleted.
1002
1003         @param name
1004             The handler name.
1005
1006         @return @true if the handler was found and removed, @false otherwise.
1007
1008         @see wxImageHandler
1009     */
1010     static bool RemoveHandler(const wxString& name);
1011
1012     /**
1013         Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
1014     */
1015     void Replace(unsigned char r1, unsigned char g1,
1016                  unsigned char b1, unsigned char r2,
1017                  unsigned char g2, unsigned char b2);
1018
1019     /**
1020         Changes the size of the image in-place by scaling it: after a call to this
1021         function,the image will have the given width and height.
1022
1023         For a description of the @a quality parameter, see the Scale() function.
1024         Returns the (modified) image itself.
1025
1026         @see Scale()
1027     */
1028     wxImage& Rescale(int width, int height,
1029                     int quality = wxIMAGE_QUALITY_NORMAL);
1030
1031     /**
1032         Changes the size of the image in-place without scaling it by adding either a
1033         border with the given colour or cropping as necessary.
1034
1035         The image is pasted into a new image with the given @a size and background
1036         colour at the position @a pos relative to the upper left of the new image.
1037
1038         If @a red = green = blue = -1 then use either the  current mask colour
1039         if set or find, use, and set a suitable mask colour for any newly exposed
1040         areas.
1041
1042         @return The (modified) image itself.
1043
1044         @see Size()
1045     */
1046     wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1,
1047                     int green = -1, int blue = -1);
1048
1049     /**
1050         Rotates the image about the given point, by @a angle radians.
1051
1052         Passing @true to @a interpolating results in better image quality, but is slower.
1053
1054         If the image has a mask, then the mask colour is used for the uncovered
1055         pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
1056
1057         Returns the rotated image, leaving this image intact.
1058     */
1059     wxImage Rotate(double angle, const wxPoint& rotationCentre,
1060                    bool interpolating = true,
1061                    wxPoint* offsetAfterRotation = NULL) const;
1062
1063     /**
1064         Returns a copy of the image rotated 90 degrees in the direction
1065         indicated by @a clockwise.
1066     */
1067     wxImage Rotate90(bool clockwise = true) const;
1068
1069     /**
1070         Rotates the hue of each pixel in the image by @e angle, which is a double in
1071         the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
1072         corresponds to +360 degrees.
1073     */
1074     void RotateHue(double angle);
1075
1076     /**
1077         Saves an image in the given stream.
1078
1079         @param stream
1080             Opened output stream to save the image to.
1081         @param mimetype
1082             MIME type.
1083
1084         @return @true if the operation succeeded, @false otherwise.
1085
1086         @remarks Depending on how wxWidgets has been configured, not all formats
1087                  may be available.
1088
1089         @note
1090             You can use SetOption() to set the hotspot when saving an image
1091             into a cursor file (default hotspot is in the centre of the image):
1092             @code
1093             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1094             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1095             @endcode
1096
1097         @see LoadFile()
1098     */
1099     virtual bool SaveFile(wxOutputStream& stream,
1100                           const wxString& mimetype) const;
1101
1102     /**
1103         Saves an image in the named file.
1104
1105         @param name
1106             Name of the file to save the image to.
1107         @param type
1108             Currently these types can be used:
1109             @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1110             @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1111             @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1112             @li wxBITMAP_TYPE_PCX: Save a PCX image file
1113                 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1114             @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1115             @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1116             @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1117             @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1118                 The size may be up to 255 wide by 127 high. A single image is saved
1119                 in 8 colors at the size supplied.
1120             @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1121     */
1122     virtual bool SaveFile(const wxString& name, wxBitmapType type) const;
1123
1124     /**
1125         Saves an image in the named file.
1126
1127         @param name
1128             Name of the file to save the image to.
1129         @param mimetype
1130             MIME type.
1131     */
1132     virtual bool SaveFile(const wxString& name, const wxString& mimetype) const;
1133
1134     /**
1135         Saves an image in the named file.
1136
1137         File type is determined from the extension of the file name.
1138         Note that this function may fail if the extension is not recognized!
1139         You can use one of the forms above to save images to files with
1140         non-standard extensions.
1141
1142         @param name
1143             Name of the file to save the image to.
1144     */
1145     virtual bool SaveFile(const wxString& name) const;
1146
1147     /**
1148         Saves an image in the given stream.
1149
1150         @param stream
1151             Opened output stream to save the image to.
1152         @param type
1153             MIME type.
1154     */
1155     virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
1156
1157     /**
1158         Returns a scaled version of the image.
1159
1160         This is also useful for scaling bitmaps in general as the only other way
1161         to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
1162
1163         The parameter @a quality determines what method to use for resampling the image.
1164         Can be one of the following:
1165         - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
1166                                   replication
1167         - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
1168                                 for upsampling and downsampling respectively
1169
1170         It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
1171         looking results it is a slower method. Downsampling will use the box averaging
1172         method which seems to operate very fast. If you are upsampling larger images using
1173         this method you will most likely notice that it is a bit slower and in extreme
1174         cases it will be quite substantially slower as the bicubic algorithm has to process a
1175         lot of data.
1176
1177         It should also be noted that the high quality scaling may not work as expected
1178         when using a single mask colour for transparency, as the scaling will blur the
1179         image and will therefore remove the mask partially. Using the alpha channel
1180         will work.
1181
1182         Example:
1183         @code
1184         // get the bitmap from somewhere
1185         wxBitmap bmp = ...;
1186
1187         // rescale it to have size of 32*32
1188         if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
1189         {
1190             wxImage image = bmp.ConvertToImage();
1191             bmp = wxBitmap(image.Scale(32, 32));
1192
1193             // another possibility:
1194             image.Rescale(32, 32);
1195             bmp = image;
1196         }
1197         @endcode
1198
1199         @see Rescale()
1200     */
1201     wxImage Scale(int width, int height,
1202                   int quality = wxIMAGE_QUALITY_NORMAL) const;
1203
1204     /**
1205        This function is similar to SetData() and has similar restrictions.
1206
1207         The pointer passed to it may however be @NULL in which case the function
1208         will allocate the alpha array internally -- this is useful to add alpha
1209         channel data to an image which doesn't have any.
1210
1211         If the pointer is not @NULL, it must have one byte for each image pixel
1212         and be allocated with malloc().
1213         wxImage takes ownership of the pointer and will free it unless @a static_data
1214         parameter is set to @true -- in this case the caller should do it.
1215     */
1216     void SetAlpha(unsigned char* alpha = NULL,
1217                   bool static_data = false);
1218
1219     /**
1220         Sets the alpha value for the given pixel.
1221         This function should only be called if the image has alpha channel data,
1222         use HasAlpha() to check for this.
1223     */
1224     void SetAlpha(int x, int y, unsigned char alpha);
1225
1226     //@{
1227     /**
1228         Sets the image data without performing checks.
1229
1230         The data given must have the size (width*height*3) or results will be
1231         unexpected. Don't use this method if you aren't sure you know what you
1232         are doing.
1233
1234         The data must have been allocated with @c malloc(), @b NOT with
1235         @c operator new.
1236
1237         After this call the pointer to the data is owned by the wxImage object,
1238         that will be responsible for deleting it.
1239         Do not pass to this function a pointer obtained through GetData().
1240     */
1241     void SetData(unsigned char* data, bool static_data = false);
1242     void SetData(unsigned char* data, int new_width, int new_height,
1243                  bool static_data = false);
1244     //@}
1245
1246     /**
1247         Specifies whether there is a mask or not.
1248
1249         The area of the mask is determined by the current mask colour.
1250     */
1251     void SetMask(bool hasMask = true);
1252
1253     /**
1254         Sets the mask colour for this image (and tells the image to use the mask).
1255     */
1256     void SetMaskColour(unsigned char red, unsigned char green,
1257                        unsigned char blue);
1258
1259     /**
1260         Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1261         mask will be masked in the image.
1262
1263         This is done by first finding an unused colour in the image, setting
1264         this colour as the mask colour and then using this colour to draw all
1265         pixels in the image who corresponding pixel in mask has given RGB value.
1266
1267         The parameter @a mask is the mask image to extract mask shape from.
1268         It must have the same dimensions as the image.
1269
1270         The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1271         mask that will be used to create the mask.
1272
1273         @return Returns @false if mask does not have same dimensions as the image
1274                 or if there is no unused colour left. Returns @true if the mask
1275                 was successfully applied.
1276
1277         @note
1278             Note that this method involves computing the histogram, which is a
1279             computationally intensive operation.
1280     */
1281     bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
1282                           unsigned char mg,
1283                           unsigned char mb);
1284
1285     //@{
1286     /**
1287         Sets a user-defined option. The function is case-insensitive to @a name.
1288
1289         For example, when saving as a JPEG file, the option @b quality is
1290         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1291
1292         @see GetOption(), GetOptionInt(), HasOption()
1293     */
1294     void SetOption(const wxString& name, const wxString& value);
1295     void SetOption(const wxString& name, int value);
1296     //@}
1297
1298     /**
1299         Associates a palette with the image.
1300
1301         The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1302         or in file save operations (none as yet).
1303     */
1304     void SetPalette(const wxPalette& palette);
1305
1306     /**
1307         Sets the colour of the pixels within the given rectangle.
1308
1309         This routine performs bounds-checks for the coordinate so it can be considered
1310         a safe way to manipulate the data.
1311     */
1312     void SetRGB(const wxRect& rect,
1313                 unsigned char red,
1314                 unsigned char green,
1315                 unsigned char blue);
1316
1317     /**
1318         Set the type of image returned by GetType().
1319
1320         This method is mostly used internally by the library but can also be
1321         called from the user code if the image was created from data in the
1322         given bitmap format without using LoadFile() (which would set the type
1323         correctly automatically).
1324
1325         Notice that the image must be created before this function is called.
1326
1327         @since 2.9.0
1328
1329         @param type
1330             One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1331             value for it and can be used to reset the bitmap type to default
1332             but @c wxBITMAP_TYPE_MAX is not allowed here.
1333     */
1334     void SetType(wxBitmapType type);
1335
1336     /**
1337         Returns a resized version of this image without scaling it by adding either a
1338         border with the given colour or cropping as necessary.
1339
1340         The image is pasted into a new image with the given @a size and background
1341         colour at the position @a pos relative to the upper left of the new image.
1342
1343         If @a red = green = blue = -1 then the areas of the larger image not covered
1344         by this image are made transparent by filling them with the image mask colour
1345         (which will be allocated automatically if it isn't currently set).
1346
1347         Otherwise, the areas will be filled with the colour with the specified RGB components.
1348
1349         @see Resize()
1350     */
1351     wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
1352                  int green = -1, int blue = -1) const;
1353
1354     /**
1355         Assignment operator, using @ref overview_refcount "reference counting".
1356
1357         @param image
1358             Image to assign.
1359
1360         @return Returns 'this' object.
1361     */
1362     wxImage& operator=(const wxImage& image);
1363 };
1364
1365 // ============================================================================
1366 // Global functions/macros
1367 // ============================================================================
1368
1369 /** @ingroup group_funcmacro_appinitterm */
1370 //@{
1371
1372 /**
1373     Initializes all available image handlers. For a list of available handlers,
1374     see wxImage.
1375
1376     @see wxImage, wxImageHandler
1377
1378     @header{wx/image.h}
1379 */
1380 void wxInitAllImageHandlers();
1381
1382 //@}
1383