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 common to all formats:
 767         @li wxIMAGE_OPTION_MAX_WIDTH and wxIMAGE_OPTION_MAX_HEIGHT: If either
 768             of these options is specified, the loaded image will be scaled down
 769             (preserving its aspect ratio) so that its width is less than the
 770             max width given if it is not 0 @em and its height is less than the
 771             max height given if it is not 0. This is typically used for loading
 772             thumbnails and the advantage of using these options compared to
 773             calling Rescale() after loading is that some handlers (only JPEG
 774             one right now) support rescaling the image during loading which is
 775             vastly more efficient than loading the entire huge image and
 776             rescaling it later (if these options are not supported by the
 777             handler, this is still what happens however). These options must be
 778             set before calling LoadFile() to have any effect.
 779
 780         Options for wxPNGHandler:
 781         @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file.
 782         @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
 783
 784         Supported values for wxIMAGE_OPTION_PNG_FORMAT:
 785         @li wxPNG_TYPE_COLOUR: Stores RGB image.
 786         @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.
 787         @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey.
 788
 789         @see SetOption(), GetOption()
 790     */
 791     int GetOptionInt(const wxString& name) const;
 792
 793     /**
 794         Get the current mask colour or find a suitable unused colour that could be
 795         used as a mask colour. Returns @true if the image currently has a mask.
 796     */
 797     bool GetOrFindMaskColour(unsigned char* r, unsigned char* g,
 798                              unsigned char* b) const;
 799
 800     /**
 801         Returns the palette associated with the image.
 802         Currently the palette is only used when converting to wxBitmap under Windows.
 803
 804         Some of the wxImage handlers have been modified to set the palette if
 805         one exists in the image file (usually 256 or less colour images in
 806         GIF or PNG format).
 807     */
 808     const wxPalette& GetPalette() const;
 809
 810     /**
 811         Returns the red intensity at the given coordinate.
 812     */
 813     unsigned char GetRed(int x, int y) const;
 814
 815     /**
 816         Returns a sub image of the current one as long as the rect belongs entirely
 817         to the image.
 818     */
 819     wxImage GetSubImage(const wxRect& rect) const;
 820
 821     /**
 822         Gets the type of image found by LoadFile() or specified with SaveFile().
 823
 824         @since 2.9.0
 825     */
 826     wxBitmapType GetType() const;
 827
 828     /**
 829         Gets the width of the image in pixels.
 830
 831         @see GetHeight()
 832     */
 833     int GetWidth() const;
 834
 835     /**
 836         Converts a color in HSV color space to RGB color space.
 837     */
 838     static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv);
 839
 840     /**
 841         Returns @true if this image has alpha channel, @false otherwise.
 842
 843         @see GetAlpha(), SetAlpha()
 844     */
 845     bool HasAlpha() const;
 846
 847     /**
 848         Returns @true if there is a mask active, @false otherwise.
 849     */
 850     bool HasMask() const;
 851
 852     /**
 853         Returns @true if the given option is present.
 854         The function is case-insensitive to @a name.
 855
 856         @see SetOption(), GetOption(), GetOptionInt()
 857     */
 858     bool HasOption(const wxString& name) const;
 859
 860     /**
 861         Initializes the image alpha channel data.
 862
 863         It is an error to call it if the image already has alpha data.
 864         If it doesn't, alpha data will be by default initialized to all pixels
 865         being fully opaque. But if the image has a mask colour, all mask pixels
 866         will be completely transparent.
 867     */
 868     void InitAlpha();
 869
 870     /**
 871         Internal use only. Adds standard image format handlers.
 872         It only install wxBMPHandler for the time being, which is used by wxBitmap.
 873
 874         This function is called by wxWidgets on startup, and shouldn't be called by
 875         the user.
 876
 877         @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
 878     */
 879     static void InitStandardHandlers();
 880
 881     /**
 882         Adds a handler at the start of the static list of format handlers.
 883
 884         @param handler
 885             A new image format handler object. There is usually only one instance
 886             of a given handler class in an application session.
 887
 888         @see wxImageHandler
 889     */
 890     static void InsertHandler(wxImageHandler* handler);
 891
 892     /**
 893         Returns @true if image data is present.
 894     */
 895     bool IsOk() const;
 896
 897     /**
 898         Returns @true if the given pixel is transparent, i.e. either has the mask
 899         colour if this image has a mask or if this image has alpha channel and alpha
 900         value of this pixel is strictly less than @a threshold.
 901     */
 902     bool IsTransparent(int x, int y,
 903                        unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
 904
 905     /**
 906         Loads an image from an input stream.
 907
 908         @param stream
 909             Opened input stream from which to load the image.
 910             Currently, the stream must support seeking.
 911         @param type
 912             May be one of the following:
 913             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 914             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 915             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 916             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 917             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 918             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 919             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 920             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 921             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 922             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 923             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 924             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 925             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 926         @param index
 927             Index of the image to load in the case that the image file contains
 928             multiple images. This is only used by GIF, ICO and TIFF handlers.
 929             The default value (-1) means "choose the default image" and is
 930             interpreted as the first image (index=0) by the GIF and TIFF handler
 931             and as the largest and most colourful one by the ICO handler.
 932
 933         @return @true if the operation succeeded, @false otherwise.
 934                 If the optional index parameter is out of range, @false is
 935                 returned and a call to wxLogError() takes place.
 936
 937         @remarks Depending on how wxWidgets has been configured, not all formats
 938                  may be available.
 939
 940         @note
 941             You can use GetOptionInt() to get the hotspot when loading cursor files:
 942             @code
 943             int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
 944             int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
 945             @endcode
 946
 947         @see SaveFile()
 948     */
 949     virtual bool LoadFile(wxInputStream& stream,
 950                           wxBitmapType type = wxBITMAP_TYPE_ANY,
 951                           int index = -1);
 952
 953     /**
 954         Loads an image from a file.
 955         If no handler type is provided, the library will try to autodetect the format.
 956
 957         @param name
 958             Name of the file from which to load the image.
 959         @param type
 960             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 961         @param index
 962             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 963     */
 964     virtual bool LoadFile(const wxString& name,
 965                           wxBitmapType type = wxBITMAP_TYPE_ANY,
 966                           int index = -1);
 967
 968     /**
 969         Loads an image from a file.
 970         If no handler type is provided, the library will try to autodetect the format.
 971
 972         @param name
 973             Name of the file from which to load the image.
 974         @param mimetype
 975             MIME type string (for example 'image/jpeg')
 976         @param index
 977             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 978     */
 979     virtual bool LoadFile(const wxString& name, const wxString& mimetype,
 980                           int index = -1);
 981
 982
 983     /**
 984         Loads an image from an input stream.
 985
 986         @param stream
 987             Opened input stream from which to load the image.
 988             Currently, the stream must support seeking.
 989         @param mimetype
 990             MIME type string (for example 'image/jpeg')
 991         @param index
 992             See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
 993     */
 994     virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
 995                           int index = -1);
 996
 997     /**
 998         Returns a mirrored copy of the image.
 999         The parameter @a horizontally indicates the orientation.
1000     */
1001     wxImage Mirror(bool horizontally = true) const;
1002
1003     /**
1004         Copy the data of the given @a image to the specified position in this image.
1005     */
1006     void Paste(const wxImage& image, int x, int y);
1007
1008     /**
1009         Converts a color in RGB color space to HSV color space.
1010     */
1011     static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
1012
1013     /**
1014         Finds the handler with the given name, and removes it.
1015         The handler is not deleted.
1016
1017         @param name
1018             The handler name.
1019
1020         @return @true if the handler was found and removed, @false otherwise.
1021
1022         @see wxImageHandler
1023     */
1024     static bool RemoveHandler(const wxString& name);
1025
1026     /**
1027         Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
1028     */
1029     void Replace(unsigned char r1, unsigned char g1,
1030                  unsigned char b1, unsigned char r2,
1031                  unsigned char g2, unsigned char b2);
1032
1033     /**
1034         Changes the size of the image in-place by scaling it: after a call to this
1035         function,the image will have the given width and height.
1036
1037         For a description of the @a quality parameter, see the Scale() function.
1038         Returns the (modified) image itself.
1039
1040         @see Scale()
1041     */
1042     wxImage& Rescale(int width, int height,
1043                     int quality = wxIMAGE_QUALITY_NORMAL);
1044
1045     /**
1046         Changes the size of the image in-place without scaling it by adding either a
1047         border with the given colour or cropping as necessary.
1048
1049         The image is pasted into a new image with the given @a size and background
1050         colour at the position @a pos relative to the upper left of the new image.
1051
1052         If @a red = green = blue = -1 then use either the  current mask colour
1053         if set or find, use, and set a suitable mask colour for any newly exposed
1054         areas.
1055
1056         @return The (modified) image itself.
1057
1058         @see Size()
1059     */
1060     wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1,
1061                     int green = -1, int blue = -1);
1062
1063     /**
1064         Rotates the image about the given point, by @a angle radians.
1065
1066         Passing @true to @a interpolating results in better image quality, but is slower.
1067
1068         If the image has a mask, then the mask colour is used for the uncovered
1069         pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
1070
1071         Returns the rotated image, leaving this image intact.
1072     */
1073     wxImage Rotate(double angle, const wxPoint& rotationCentre,
1074                    bool interpolating = true,
1075                    wxPoint* offsetAfterRotation = NULL) const;
1076
1077     /**
1078         Returns a copy of the image rotated 90 degrees in the direction
1079         indicated by @a clockwise.
1080     */
1081     wxImage Rotate90(bool clockwise = true) const;
1082
1083     /**
1084         Rotates the hue of each pixel in the image by @e angle, which is a double in
1085         the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
1086         corresponds to +360 degrees.
1087     */
1088     void RotateHue(double angle);
1089
1090     /**
1091         Saves an image in the given stream.
1092
1093         @param stream
1094             Opened output stream to save the image to.
1095         @param mimetype
1096             MIME type.
1097
1098         @return @true if the operation succeeded, @false otherwise.
1099
1100         @remarks Depending on how wxWidgets has been configured, not all formats
1101                  may be available.
1102
1103         @note
1104             You can use SetOption() to set the hotspot when saving an image
1105             into a cursor file (default hotspot is in the centre of the image):
1106             @code
1107             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1108             image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1109             @endcode
1110
1111         @see LoadFile()
1112     */
1113     virtual bool SaveFile(wxOutputStream& stream,
1114                           const wxString& mimetype) const;
1115
1116     /**
1117         Saves an image in the named file.
1118
1119         @param name
1120             Name of the file to save the image to.
1121         @param type
1122             Currently these types can be used:
1123             @li wxBITMAP_TYPE_BMP: Save a BMP image file.
1124             @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
1125             @li wxBITMAP_TYPE_PNG: Save a PNG image file.
1126             @li wxBITMAP_TYPE_PCX: Save a PCX image file
1127                 (tries to save as 8-bit if possible, falls back to 24-bit otherwise).
1128             @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
1129             @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
1130             @li wxBITMAP_TYPE_XPM: Save a XPM image file.
1131             @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO).
1132                 The size may be up to 255 wide by 127 high. A single image is saved
1133                 in 8 colors at the size supplied.
1134             @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
1135     */
1136     virtual bool SaveFile(const wxString& name, wxBitmapType type) const;
1137
1138     /**
1139         Saves an image in the named file.
1140
1141         @param name
1142             Name of the file to save the image to.
1143         @param mimetype
1144             MIME type.
1145     */
1146     virtual bool SaveFile(const wxString& name, const wxString& mimetype) const;
1147
1148     /**
1149         Saves an image in the named file.
1150
1151         File type is determined from the extension of the file name.
1152         Note that this function may fail if the extension is not recognized!
1153         You can use one of the forms above to save images to files with
1154         non-standard extensions.
1155
1156         @param name
1157             Name of the file to save the image to.
1158     */
1159     virtual bool SaveFile(const wxString& name) const;
1160
1161     /**
1162         Saves an image in the given stream.
1163
1164         @param stream
1165             Opened output stream to save the image to.
1166         @param type
1167             MIME type.
1168     */
1169     virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
1170
1171     /**
1172         Returns a scaled version of the image.
1173
1174         This is also useful for scaling bitmaps in general as the only other way
1175         to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
1176
1177         The parameter @a quality determines what method to use for resampling the image.
1178         Can be one of the following:
1179         - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
1180                                   replication
1181         - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
1182                                 for upsampling and downsampling respectively
1183
1184         It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
1185         looking results it is a slower method. Downsampling will use the box averaging
1186         method which seems to operate very fast. If you are upsampling larger images using
1187         this method you will most likely notice that it is a bit slower and in extreme
1188         cases it will be quite substantially slower as the bicubic algorithm has to process a
1189         lot of data.
1190
1191         It should also be noted that the high quality scaling may not work as expected
1192         when using a single mask colour for transparency, as the scaling will blur the
1193         image and will therefore remove the mask partially. Using the alpha channel
1194         will work.
1195
1196         Example:
1197         @code
1198         // get the bitmap from somewhere
1199         wxBitmap bmp = ...;
1200
1201         // rescale it to have size of 32*32
1202         if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
1203         {
1204             wxImage image = bmp.ConvertToImage();
1205             bmp = wxBitmap(image.Scale(32, 32));
1206
1207             // another possibility:
1208             image.Rescale(32, 32);
1209             bmp = image;
1210         }
1211         @endcode
1212
1213         @see Rescale()
1214     */
1215     wxImage Scale(int width, int height,
1216                   int quality = wxIMAGE_QUALITY_NORMAL) const;
1217
1218     /**
1219        This function is similar to SetData() and has similar restrictions.
1220
1221         The pointer passed to it may however be @NULL in which case the function
1222         will allocate the alpha array internally -- this is useful to add alpha
1223         channel data to an image which doesn't have any.
1224
1225         If the pointer is not @NULL, it must have one byte for each image pixel
1226         and be allocated with malloc().
1227         wxImage takes ownership of the pointer and will free it unless @a static_data
1228         parameter is set to @true -- in this case the caller should do it.
1229     */
1230     void SetAlpha(unsigned char* alpha = NULL,
1231                   bool static_data = false);
1232
1233     /**
1234         Sets the alpha value for the given pixel.
1235         This function should only be called if the image has alpha channel data,
1236         use HasAlpha() to check for this.
1237     */
1238     void SetAlpha(int x, int y, unsigned char alpha);
1239
1240     //@{
1241     /**
1242         Sets the image data without performing checks.
1243
1244         The data given must have the size (width*height*3) or results will be
1245         unexpected. Don't use this method if you aren't sure you know what you
1246         are doing.
1247
1248         The data must have been allocated with @c malloc(), @b NOT with
1249         @c operator new.
1250
1251         After this call the pointer to the data is owned by the wxImage object,
1252         that will be responsible for deleting it.
1253         Do not pass to this function a pointer obtained through GetData().
1254     */
1255     void SetData(unsigned char* data, bool static_data = false);
1256     void SetData(unsigned char* data, int new_width, int new_height,
1257                  bool static_data = false);
1258     //@}
1259
1260     /**
1261         Specifies whether there is a mask or not.
1262
1263         The area of the mask is determined by the current mask colour.
1264     */
1265     void SetMask(bool hasMask = true);
1266
1267     /**
1268         Sets the mask colour for this image (and tells the image to use the mask).
1269     */
1270     void SetMaskColour(unsigned char red, unsigned char green,
1271                        unsigned char blue);
1272
1273     /**
1274         Sets image's mask so that the pixels that have RGB value of mr,mg,mb in
1275         mask will be masked in the image.
1276
1277         This is done by first finding an unused colour in the image, setting
1278         this colour as the mask colour and then using this colour to draw all
1279         pixels in the image who corresponding pixel in mask has given RGB value.
1280
1281         The parameter @a mask is the mask image to extract mask shape from.
1282         It must have the same dimensions as the image.
1283
1284         The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in
1285         mask that will be used to create the mask.
1286
1287         @return Returns @false if mask does not have same dimensions as the image
1288                 or if there is no unused colour left. Returns @true if the mask
1289                 was successfully applied.
1290
1291         @note
1292             Note that this method involves computing the histogram, which is a
1293             computationally intensive operation.
1294     */
1295     bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
1296                           unsigned char mg,
1297                           unsigned char mb);
1298
1299     //@{
1300     /**
1301         Sets a user-defined option. The function is case-insensitive to @a name.
1302
1303         For example, when saving as a JPEG file, the option @b quality is
1304         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1305
1306         @see GetOption(), GetOptionInt(), HasOption()
1307     */
1308     void SetOption(const wxString& name, const wxString& value);
1309     void SetOption(const wxString& name, int value);
1310     //@}
1311
1312     /**
1313         Associates a palette with the image.
1314
1315         The palette may be used when converting wxImage to wxBitmap (MSW only at present)
1316         or in file save operations (none as yet).
1317     */
1318     void SetPalette(const wxPalette& palette);
1319
1320     /**
1321         Sets the colour of the pixels within the given rectangle.
1322
1323         This routine performs bounds-checks for the coordinate so it can be considered
1324         a safe way to manipulate the data.
1325     */
1326     void SetRGB(const wxRect& rect,
1327                 unsigned char red,
1328                 unsigned char green,
1329                 unsigned char blue);
1330
1331     /**
1332         Set the type of image returned by GetType().
1333
1334         This method is mostly used internally by the library but can also be
1335         called from the user code if the image was created from data in the
1336         given bitmap format without using LoadFile() (which would set the type
1337         correctly automatically).
1338
1339         Notice that the image must be created before this function is called.
1340
1341         @since 2.9.0
1342
1343         @param type
1344             One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid
1345             value for it and can be used to reset the bitmap type to default
1346             but @c wxBITMAP_TYPE_MAX is not allowed here.
1347     */
1348     void SetType(wxBitmapType type);
1349
1350     /**
1351         Returns a resized version of this image without scaling it by adding either a
1352         border with the given colour or cropping as necessary.
1353
1354         The image is pasted into a new image with the given @a size and background
1355         colour at the position @a pos relative to the upper left of the new image.
1356
1357         If @a red = green = blue = -1 then the areas of the larger image not covered
1358         by this image are made transparent by filling them with the image mask colour
1359         (which will be allocated automatically if it isn't currently set).
1360
1361         Otherwise, the areas will be filled with the colour with the specified RGB components.
1362
1363         @see Resize()
1364     */
1365     wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
1366                  int green = -1, int blue = -1) const;
1367
1368     /**
1369         Assignment operator, using @ref overview_refcount "reference counting".
1370
1371         @param image
1372             Image to assign.
1373
1374         @return Returns 'this' object.
1375     */
1376     wxImage& operator=(const wxImage& image);
1377 };
1378
1379 // ============================================================================
1380 // Global functions/macros
1381 // ============================================================================
1382
1383 /** @ingroup group_funcmacro_appinitterm */
1384 //@{
1385
1386 /**
1387     Initializes all available image handlers. For a list of available handlers,
1388     see wxImage.
1389
1390     @see wxImage, wxImageHandler
1391
1392     @header{wx/image.h}
1393 */
1394 void wxInitAllImageHandlers();
1395
1396 //@}
1397