interface/image.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        image.h
   3 // Purpose:     interface of wxImageHandler
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxImageHandler
  11     @wxheader{image.h}
  12
  13     This is the base class for implementing image file loading/saving, and
  14     image creation from data.
  15     It is used within wxImage and is not normally seen by the application.
  16
  17     If you wish to extend the capabilities of wxImage, derive a class from
  18     wxImageHandler and add the handler using wxImage::AddHandler in your
  19     application initialisation.
  20
  21     @stdobjects
  22     ::wxNullImage
  23
  24     @library{wxcore}
  25     @category{FIXME}
  26
  27     @see wxImage, wxInitAllImageHandlers()
  28
  29     @todo Document all image handler types, indicating their library.
  30 */
  31 class wxImageHandler : public wxObject
  32 {
  33 public:
  34     /**
  35         Default constructor. In your own default constructor, initialise the members
  36         m_name, m_extension and m_type.
  37     */
  38     wxImageHandler();
  39
  40     /**
  41         Destroys the wxImageHandler object.
  42     */
  43     ~wxImageHandler();
  44
  45     /**
  46         Gets the file extension associated with this handler.
  47     */
  48     const wxString GetExtension() const;
  49
  50     /**
  51         If the image file contains more than one image and the image handler is capable
  52         of retrieving these individually, this function will return the number of
  53         available images.
  54
  55         @param stream
  56             Opened input stream for reading image data. Currently, the stream must
  57         support seeking.
  58
  59         @return Number of available images. For most image handlers, this is 1
  60                  (exceptions are TIFF and ICO formats).
  61     */
  62     int GetImageCount(wxInputStream& stream);
  63
  64     /**
  65         Gets the MIME type associated with this handler.
  66     */
  67     const wxString GetMimeType() const;
  68
  69     /**
  70         Gets the name of this handler.
  71     */
  72     const wxString GetName() const;
  73
  74     /**
  75         Gets the image type associated with this handler.
  76     */
  77     long GetType() const;
  78
  79     /**
  80         Loads a image from a stream, putting the resulting data into @e image. If the
  81         image file contains
  82         more than one image and the image handler is capable of retrieving these
  83         individually, @e index
  84         indicates which image to read from the stream.
  85
  86         @param image
  87             The image object which is to be affected by this operation.
  88         @param stream
  89             Opened input stream for reading image data.
  90         @param verbose
  91             If set to @true, errors reported by the image handler will produce
  92         wxLogMessages.
  93         @param index
  94             The index of the image in the file (starting from zero).
  95
  96         @return @true if the operation succeeded, @false otherwise.
  97
  98         @see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
  99     */
 100     bool LoadFile(wxImage* image, wxInputStream& stream,
 101                   bool verbose = true, int index = 0);
 102
 103     /**
 104         Saves a image in the output stream.
 105
 106         @param image
 107             The image object which is to be affected by this operation.
 108         @param stream
 109             Opened output stream for writing the data.
 110
 111         @return @true if the operation succeeded, @false otherwise.
 112
 113         @see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
 114     */
 115     bool SaveFile(wxImage* image, wxOutputStream& stream);
 116
 117     /**
 118         Sets the handler extension.
 119
 120         @param extension
 121             Handler extension.
 122     */
 123     void SetExtension(const wxString& extension);
 124
 125     /**
 126         Sets the handler MIME type.
 127
 128         @param mimename
 129             Handler MIME type.
 130     */
 131     void SetMimeType(const wxString& mimetype);
 132
 133     /**
 134         Sets the handler name.
 135
 136         @param name
 137             Handler name.
 138     */
 139     void SetName(const wxString& name);
 140 };
 141
 142
 143
 144 /**
 145     @class wxImage
 146     @wxheader{image.h}
 147
 148     This class encapsulates a platform-independent image. An image can be
 149     created from data, or using wxBitmap::ConvertToImage. An image can be
 150     loaded from a file in a variety of formats, and is extensible to new
 151     formats via image format handlers. Functions are available to set and
 152     get image bits, so it can be used for basic image manipulation.
 153
 154     A wxImage cannot (currently) be drawn directly to a wxDC. Instead,
 155     a platform-specific wxBitmap object must be created from it using
 156     the wxBitmap::wxBitmap(wxImage,int depth) constructor.
 157     This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
 158
 159     One colour value of the image may be used as a mask colour which will lead to
 160     the automatic creation of a wxMask object associated to the bitmap object.
 161
 162     @library{wxcore}
 163     @category{gdi}
 164
 165     @stdobjects
 166     ::wxNullImage
 167
 168     @see wxBitmap, wxInitAllImageHandlers(), wxPixelData
 169 */
 170 class wxImage : public wxObject
 171 {
 172 public:
 173
 174     /**
 175          Creates an empty wxImage object without an alpha channel.
 176     */
 177     wxImage();
 178
 179     /**
 180          Creates an image with the given size and clears it if requested.
 181          Does not create an alpha channel.
 182
 183         @param width
 184             Specifies the width of the image.
 185         @param height
 186             Specifies the height of the image.
 187         @clear
 188             Clear the image with zeros.
 189     */
 190     wxImage(int width, int height, bool clear = true);
 191
 192     /**
 193         Creates an image from data in memory. If static_data is false
 194         then the wxImage will take ownership of the data and free it
 195         afterwards. For this, it has to be allocated with @e malloc.
 196
 197         @param width
 198             Specifies the width of the image.
 199         @param height
 200             Specifies the height of the image.
 201         @param data
 202             A pointer to RGB data
 203         @param static_data
 204             Indicates if the data should be free'd after use
 205
 206     */
 207     wxImage(int width, int height, unsigned char* data,  bool static_data = false);
 208
 209     /**
 210         Creates an image from data in memory. If static_data is false
 211         then the wxImage will take ownership of the data and free it
 212         afterwards. For this, it has to be allocated with @e malloc.
 213
 214         @param width
 215             Specifies the width of the image.
 216         @param height
 217             Specifies the height of the image.
 218         @param data
 219             A pointer to RGB data
 220         @param alpha
 221             A pointer to alpha-channel data
 222         @param static_data
 223             Indicates if the data should be free'd after use
 224
 225     */
 226     wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
 227
 228     /**
 229         Creates an image from XPM data.
 230
 231         @param xpmData
 232             A pointer to XPM image data.
 233     */
 234     wxImage(const char* const* xpmData);
 235
 236     /**
 237         Creates an image from a file.
 238
 239         @param name
 240             Name of the file from which to load the image.
 241         @param type
 242             May be one of the following:
 243             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 244             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 245             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 246             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 247             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 248             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 249             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 250             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 251             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 252             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 253             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 254             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 255             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 256         @param index
 257             Index of the image to load in the case that the image file contains
 258             multiple images. This is only used by GIF, ICO and TIFF handlers.
 259             The default value (-1) means "choose the default image" and is
 260             interpreted as the first image (index=0) by the GIF and TIFF handler
 261             and as the largest and most colourful one by the ICO handler.
 262
 263         @remarks Depending on how wxWidgets has been configured, not all formats
 264                  may be available.
 265
 266         @see LoadFile()
 267     */
 268     wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1);
 269
 270     /**
 271         Creates an image from a file using MIME-types to specify the type.
 272
 273         @param name
 274             Name of the file from which to load the image.
 275         @param type
 276             See above
 277         @param mimetype
 278             MIME type string (for example 'image/jpeg')
 279         @param index
 280             See above
 281     */
 282     wxImage(const wxString& name, const wxString& mimetype, int index = -1);
 283
 284     /**
 285         Creates an image from a stream.
 286
 287         @param stream
 288             Opened input stream from which to load the image. Currently,
 289             the stream must support seeking.
 290         @param type
 291             See above
 292         @param index
 293             See above.
 294     */
 295     wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);
 296
 297     /**
 298         Creates an image from a stream using MIME-types to specify the type.
 299
 300         @param stream
 301             Opened input stream from which to load the image. Currently,
 302             the stream must support seeking.
 303         @param mimetype
 304             MIME type string (for example 'image/jpeg')
 305         @param index
 306             See above.
 307     */
 308     wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);
 309
 310
 311     /**
 312         Destructor.
 313         See @ref overview_refcountdestruct "reference-counted object destruction" for
 314         more info.
 315     */
 316     ~wxImage();
 317
 318     /**
 319         Register an image handler.
 320     */
 321     static void AddHandler(wxImageHandler* handler);
 322
 323     /**
 324         Blurs the image in both horizontal and vertical directions by the
 325         specified pixel @e blurRadius. This should not be used when using
 326         a single mask colour for transparency.
 327
 328         @see BlurHorizontal(), BlurVertical()
 329     */
 330     wxImage Blur(int blurRadius);
 331
 332     /**
 333         Blurs the image in the horizontal direction only. This should not be used
 334         when using a single mask colour for transparency.
 335
 336         @see Blur(), BlurVertical()
 337     */
 338     wxImage BlurHorizontal(int blurRadius);
 339
 340     /**
 341         Blurs the image in the vertical direction only. This should not be used
 342         when using a single mask colour for transparency.
 343
 344         @see Blur(), BlurHorizontal()
 345     */
 346     wxImage BlurVertical(int blurRadius);
 347
 348     /**
 349         Returns @true if the current image handlers can read this file
 350     */
 351     bool CanRead(const wxString& filename);
 352
 353     /**
 354         Deletes all image handlers.
 355         This function is called by wxWidgets on exit.
 356     */
 357     static void CleanUpHandlers();
 358
 359     /**
 360         Computes the histogram of the image. @a histogram is a reference to
 361         wxImageHistogram object. wxImageHistogram is a specialization of
 362         wxHashMap "template" and is defined as follows:
 363
 364         @return Returns number of colours in the histogram.
 365     */
 366     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 367
 368     /**
 369         If the image has alpha channel, this method converts it to mask. All pixels
 370         with alpha value less than @a threshold are replaced with mask colour
 371         and the alpha channel is removed. Mask colour is chosen automatically using
 372         FindFirstUnusedColour().
 373         If the image image doesn't have alpha channel,
 374         ConvertAlphaToMask does nothing.
 375
 376         @return @false if FindFirstUnusedColour returns @false, @true otherwise.
 377     */
 378     bool ConvertAlphaToMask(unsigned char threshold = 128);
 379
 380     /**
 381         Deprecated, use equivalent @ref wxBitmap::ctor "wxBitmap constructor"
 382         (which takes wxImage and depth as its arguments) instead.
 383     */
 384     wxBitmap ConvertToBitmap() const;
 385
 386     /**
 387         Returns a greyscale version of the image. The returned image uses the luminance
 388         component of the original to calculate the greyscale. Defaults to using
 389         ITU-T BT.601 when converting to YUV, where every pixel equals
 390         (R * @e lr) + (G * @e lg) + (B * @e lb).
 391     */
 392     wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587,
 393                                double lb = 0.114) const;
 394
 395     /**
 396         Returns monochromatic version of the image. The returned image has white
 397         colour where the original has @e (r,g,b) colour and black colour
 398         everywhere else.
 399     */
 400     wxImage ConvertToMono(unsigned char r, unsigned char g,
 401                           unsigned char b) const;
 402
 403     /**
 404         Returns an identical copy of the image.
 405     */
 406     wxImage Copy() const;
 407
 408     /**
 409         Creates a fresh image.  If @a clear is @true, the new image will be initialized
 410         to black.
 411         Otherwise, the image data will be uninitialized.
 412
 413         @param width
 414             The width of the image in pixels.
 415         @param height
 416             The height of the image in pixels.
 417
 418         @return @true if the call succeeded, @false otherwise.
 419     */
 420     bool Create(int width, int height, bool clear = true);
 421
 422     /**
 423         Destroys the image data.
 424     */
 425     void Destroy();
 426
 427     /**
 428         @param r,g,b
 429             Pointers to variables to save the colour.
 430         @param startR,startG,startB
 431             Initial values of the colour. Returned colour
 432             will have RGB values equal to or greater than these.
 433
 434         @return Returns @false if there is no unused colour left, @true on success.
 435     */
 436     bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
 437                                unsigned char* b,
 438                                unsigned char startR = 1,
 439                                unsigned char startG = 0,
 440                                unsigned char startB = 0);
 441
 442     //@{
 443     /**
 444         Finds the handler associated with the given MIME type.
 445
 446         @param name
 447             The handler name.
 448         @param extension
 449             The file extension, such as "bmp".
 450         @param imageType
 451             The image type, such as wxBITMAP_TYPE_BMP.
 452         @param mimetype
 453             MIME type.
 454
 455         @return A pointer to the handler if found, @NULL otherwise.
 456
 457         @see wxImageHandler
 458     */
 459     static wxImageHandler* FindHandler(const wxString& name);
 460     static wxImageHandler* FindHandler(const wxString& extension,
 461                                        long imageType);
 462     static wxImageHandler* FindHandler(long imageType);
 463     static wxImageHandler* FindHandlerMime(const wxString& mimetype);
 464     //@}
 465
 466     /**
 467         Return alpha value at given pixel location.
 468     */
 469     unsigned char GetAlpha(int x, int y) const;
 470
 471     /**
 472         Returns pointer to the array storing the alpha values for this image. This
 473         pointer is @NULL for the images without the alpha channel. If the image
 474         does have it, this pointer may be used to directly manipulate the alpha values
 475         which are stored as the RGB ones.
 476     */
 477     const unsigned char * GetAlpha() const;
 478
 479     /**
 480         Returns the blue intensity at the given coordinate.
 481     */
 482     unsigned char GetBlue(int x, int y) const;
 483
 484     /**
 485         Returns the image data as an array. This is most often used when doing
 486         direct image manipulation. The return value points to an array of
 487         characters in RGBRGBRGB... format in the top-to-bottom, left-to-right
 488         order, that is the first RGB triplet corresponds to the pixel first pixel of
 489         the first row, the second one --- to the second pixel of the first row and so
 490         on until the end of the first row, with second row following after it and so
 491         on.
 492         You should not delete the returned pointer nor pass it to
 493         SetData().
 494     */
 495     unsigned char* GetData() const;
 496
 497     /**
 498         Returns the green intensity at the given coordinate.
 499     */
 500     unsigned char GetGreen(int x, int y) const;
 501
 502     /**
 503         Returns the static list of image format handlers.
 504
 505         @see wxImageHandler
 506     */
 507     static wxList GetHandlers();
 508
 509     /**
 510         Gets the height of the image in pixels.
 511     */
 512     int GetHeight() const;
 513
 514     //@{
 515     /**
 516         If the image file contains more than one image and the image handler is capable
 517         of retrieving these individually, this function will return the number of
 518         available images.
 519
 520         @param name
 521             Name of the file to query.
 522         @param stream
 523             Opened input stream with image data. Currently, the stream must
 524             support seeking.
 525         @param type
 526             May be one of the following:
 527             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 528             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 529             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 530             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 531             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 532             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 533             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 534             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 535             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 536             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 537             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 538             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 539             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 540
 541         @return Number of available images. For most image handlers, this is 1
 542                  (exceptions are TIFF and ICO formats).
 543     */
 544     static int GetImageCount(const wxString& filename,
 545                              long type = wxBITMAP_TYPE_ANY);
 546     static int GetImageCount(wxInputStream& stream,
 547                              long type = wxBITMAP_TYPE_ANY);
 548     //@}
 549
 550     /**
 551         Iterates all registered wxImageHandler objects, and returns a string containing
 552         file extension masks
 553         suitable for passing to file open/save dialog boxes.
 554
 555         @return The format of the returned string is
 556                  "(*.ext1;*.ext2)|*.ext1;*.ext2".
 557
 558         @see wxImageHandler
 559     */
 560     static wxString GetImageExtWildcard();
 561
 562     /**
 563         Gets the blue value of the mask colour.
 564     */
 565     unsigned char GetMaskBlue() const;
 566
 567     /**
 568         Gets the green value of the mask colour.
 569     */
 570     unsigned char GetMaskGreen() const;
 571
 572     /**
 573         Gets the red value of the mask colour.
 574     */
 575     unsigned char GetMaskRed() const;
 576
 577     /**
 578         Gets a user-defined option. The function is case-insensitive to @e name.
 579         For example, when saving as a JPEG file, the option @b quality is
 580         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 581
 582         @see SetOption(), GetOptionInt(), HasOption()
 583     */
 584     wxString GetOption(const wxString& name) const;
 585
 586     /**
 587         Gets a user-defined option as an integer. The function is case-insensitive
 588         to @e name. If the given option is not present, the function returns 0.
 589         Use HasOption() is 0 is a possibly valid value for the option.
 590         Options for wxPNGHandler
 591         @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file.
 592         @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
 593
 594         Supported values for wxIMAGE_OPTION_PNG_FORMAT:
 595         @li wxPNG_TYPE_COLOUR: Stores RGB image.
 596         @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.
 597         @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey.
 598
 599         @see SetOption(), GetOption()
 600     */
 601     int GetOptionInt(const wxString& name) const;
 602
 603     /**
 604         Get the current mask colour or find a suitable unused colour that could be
 605         used as a mask colour. Returns @true if the image currently has a mask.
 606     */
 607     bool GetOrFindMaskColour(unsigned char r, unsigned char g,
 608                              unsigned char b) const;
 609
 610     /**
 611         Returns the palette associated with the image. Currently the palette is only
 612         used when converting to wxBitmap under Windows. Some of the wxImage handlers
 613         have been modified to set the palette if one exists in the image file (usually
 614         256 or less colour images in GIF or PNG format).
 615     */
 616     const wxPalette GetPalette() const;
 617
 618     /**
 619         Returns the red intensity at the given coordinate.
 620     */
 621     unsigned char GetRed(int x, int y) const;
 622
 623     /**
 624         Returns a sub image of the current one as long as the rect belongs entirely to
 625         the image.
 626     */
 627     wxImage GetSubImage(const wxRect& rect) const;
 628
 629     /**
 630         Gets the width of the image in pixels.
 631
 632         @see GetHeight()
 633     */
 634     int GetWidth() const;
 635
 636     /**
 637         Constructor for HSVValue, an object that contains values for hue, saturation
 638         and value which
 639         represent the value of a color. It is used by HSVtoRGB()
 640         and RGBtoHSV(), which
 641         converts between HSV color space and RGB color space.
 642     */
 643     HSVValue(double h = 0.0, double s = 0.0, double v = 0.0);
 644
 645     /**
 646         Converts a color in HSV color space to RGB color space.
 647     */
 648 #define wxImage::RGBValue HSVtoRGB(const HSVValue& hsv)     /* implementation is private */
 649
 650     /**
 651         Returns @true if this image has alpha channel, @false otherwise.
 652
 653         @see GetAlpha(), SetAlpha()
 654     */
 655     bool HasAlpha() const;
 656
 657     /**
 658         Returns @true if there is a mask active, @false otherwise.
 659     */
 660     bool HasMask() const;
 661
 662     /**
 663         Returns @true if the given option is present. The function is case-insensitive
 664         to @e name.
 665
 666         @see SetOption(), GetOption(), GetOptionInt()
 667     */
 668     bool HasOption(const wxString& name) const;
 669
 670     /**
 671         Initializes the image alpha channel data. It is an error to call it
 672         if the image already has alpha data. If it doesn't, alpha data will be
 673         by default initialized to all pixels being fully opaque. But if the image has a
 674         a mask colour, all mask pixels will be completely transparent.
 675     */
 676     void InitAlpha();
 677
 678     /**
 679         Internal use only. Adds standard image format handlers. It only install BMP
 680         for the time being, which is used by wxBitmap.
 681         This function is called by wxWidgets on startup, and shouldn't be called by
 682         the user.
 683
 684         @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
 685     */
 686     static void InitStandardHandlers();
 687
 688     /**
 689         Adds a handler at the start of the static list of format handlers.
 690
 691         @param handler
 692             A new image format handler object. There is usually only one instance
 693             of a given handler class in an application session.
 694
 695         @see wxImageHandler
 696     */
 697     static void InsertHandler(wxImageHandler* handler);
 698
 699     /**
 700         Returns @true if image data is present.
 701     */
 702     bool IsOk() const;
 703
 704     /**
 705         Returns @true if the given pixel is transparent, i.e. either has the mask
 706         colour if this image has a mask or if this image has alpha channel and alpha
 707         value of this pixel is strictly less than @e threshold.
 708     */
 709     bool IsTransparent(int x, int y, unsigned char threshold = 128) const;
 710
 711     //@{
 712     /**
 713         Loads an image from an input stream.
 714
 715         @param name
 716             Name of the file from which to load the image.
 717         @param stream
 718             Opened input stream from which to load the image. Currently, the
 719             stream must support seeking.
 720         @param type
 721             May be one of the following:
 722             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 723             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 724             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 725             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 726             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 727             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 728             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 729             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 730             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 731             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 732             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 733             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 734             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 735         @param mimetype
 736             MIME type string (for example 'image/jpeg')
 737         @param index
 738             Index of the image to load in the case that the image file contains
 739             multiple images. This is only used by GIF, ICO and TIFF handlers.
 740             The default value (-1) means "choose the default image" and is
 741             interpreted as the first image (index=0) by the GIF and TIFF handler
 742             and as the largest and most colourful one by the ICO handler.
 743
 744         @return @true if the operation succeeded, @false otherwise. If the
 745                  optional index parameter is out of range, @false is
 746                  returned and a call to wxLogError() takes place.
 747
 748         @remarks Depending on how wxWidgets has been configured, not all formats
 749                  may be available.
 750
 751         @see SaveFile()
 752     */
 753     bool LoadFile(const wxString& name,
 754                   long type = wxBITMAP_TYPE_ANY,
 755                   int index = -1);
 756     bool LoadFile(const wxString& name, const wxString& mimetype,
 757                   int index = -1);
 758     bool LoadFile(wxInputStream& stream, long type,
 759                   int index = -1);
 760     bool LoadFile(wxInputStream& stream,
 761                   const wxString& mimetype,
 762                   int index = -1);
 763     //@}
 764
 765     /**
 766         Returns a mirrored copy of the image. The parameter @e horizontally
 767         indicates the orientation.
 768     */
 769     wxImage Mirror(bool horizontally = true) const;
 770
 771     /**
 772         Copy the data of the given @a image to the specified position in this image.
 773     */
 774     void Paste(const wxImage& image, int x, int y);
 775
 776     /**
 777         Constructor for RGBValue, an object that contains values for red, green and
 778         blue which
 779         represent the value of a color. It is used by HSVtoRGB()
 780         and RGBtoHSV(), which
 781         converts between HSV color space and RGB color space.
 782     */
 783     RGBValue(unsigned char r = 0, unsigned char g = 0,
 784              unsigned char b = 0);
 785
 786     /**
 787         Converts a color in RGB color space to HSV color space.
 788     */
 789 #define wxImage::HSVValue RGBtoHSV(const RGBValue& rgb)     /* implementation is private */
 790
 791     /**
 792         Finds the handler with the given name, and removes it. The handler
 793         is not deleted.
 794
 795         @param name
 796             The handler name.
 797
 798         @return @true if the handler was found and removed, @false otherwise.
 799
 800         @see wxImageHandler
 801     */
 802     static bool RemoveHandler(const wxString& name);
 803
 804     /**
 805         Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
 806     */
 807     void Replace(unsigned char r1, unsigned char g1,
 808                  unsigned char b1, unsigned char r2,
 809                  unsigned char g2, unsigned char b2);
 810
 811     /**
 812         Changes the size of the image in-place by scaling it: after a call to this
 813         function,
 814         the image will have the given width and height.
 815         For a description of the @a quality parameter, see the Scale() function.
 816         Returns the (modified) image itself.
 817
 818         @see Scale()
 819     */
 820     wxImage Rescale(int width, int height,
 821                     int quality = wxIMAGE_QUALITY_NORMAL);
 822
 823     /**
 824         Changes the size of the image in-place without scaling it by adding either a
 825         border
 826         with the given colour or cropping as necessary. The image is pasted into a new
 827         image with the given @a size and background colour at the position @e pos
 828         relative to the upper left of the new image. If @a red = green = blue = -1
 829         then use either the  current mask colour if set or find, use, and set a
 830         suitable mask colour for any newly exposed areas.
 831         Returns the (modified) image itself.
 832
 833         @see Size()
 834     */
 835     wxImage Resize(const wxSize& size, const wxPoint pos,
 836                    int red = -1, int green = -1,
 837                    int blue = -1);
 838
 839     /**
 840         Rotates the image about the given point, by @a angle radians. Passing @true
 841         to @a interpolating results in better image quality, but is slower. If the
 842         image has a mask, then the mask colour is used for the uncovered pixels in the
 843         rotated image background. Else, black (rgb 0, 0, 0) will be used.
 844         Returns the rotated image, leaving this image intact.
 845     */
 846     wxImage Rotate(double angle, const wxPoint& rotationCentre,
 847                    bool interpolating = true,
 848                    wxPoint* offsetAfterRotation = NULL);
 849
 850     /**
 851         Returns a copy of the image rotated 90 degrees in the direction
 852         indicated by @e clockwise.
 853     */
 854     wxImage Rotate90(bool clockwise = true) const;
 855
 856     /**
 857         Rotates the hue of each pixel in the image by @e angle, which is a double in
 858         the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
 859         corresponds
 860         to +360 degrees.
 861     */
 862     void RotateHue(double angle);
 863
 864     //@{
 865     /**
 866         Saves an image in the given stream.
 867
 868         @param name
 869             Name of the file to save the image to.
 870         @param stream
 871             Opened output stream to save the image to.
 872         @param type
 873             Currently these types can be used:
 874             @li wxBITMAP_TYPE_BMP: Save a BMP image file.
 875             @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
 876             @li wxBITMAP_TYPE_PNG: Save a PNG image file.
 877             @li wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible,
 878                 falls back to 24-bit otherwise).
 879             @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
 880             @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
 881             @li wxBITMAP_TYPE_XPM: Save a XPM image file.
 882             @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may
 883                 be up to 255 wide by 127 high. A single image is saved in 8 colors
 884                 at the size supplied).
 885             @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
 886         @param mimetype
 887             MIME type.
 888
 889         @return @true if the operation succeeded, @false otherwise.
 890
 891         @remarks Depending on how wxWidgets has been configured, not all formats
 892                  may be available.
 893
 894         @see LoadFile()
 895     */
 896     bool SaveFile(const wxString& name, int type) const;
 897     const bool SaveFile(const wxString& name,
 898                         const wxString& mimetype) const;
 899     const bool SaveFile(const wxString& name) const;
 900     const bool SaveFile(wxOutputStream& stream, int type) const;
 901     const bool SaveFile(wxOutputStream& stream,
 902                         const wxString& mimetype) const;
 903     //@}
 904
 905     /**
 906         Returns a scaled version of the image. This is also useful for
 907         scaling bitmaps in general as the only other way to scale bitmaps
 908         is to blit a wxMemoryDC into another wxMemoryDC.
 909         It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer
 910         looking results it is a slower method.  Downsampling will use the box averaging
 911         method
 912         which seems to operate very fast.  If you are upsampling larger images using
 913         this method you will most likely notice that it is a bit slower and in extreme
 914         cases
 915         it will be quite substantially slower as the bicubic algorithm has to process a
 916         lot of
 917         data.
 918         It should also be noted that the high quality scaling may not work as expected
 919         when using a single mask colour for transparency, as the scaling will blur the
 920         image and will therefore remove the mask partially. Using the alpha channel
 921         will work.
 922         Example:
 923
 924         @param quality
 925             Determines what method to use for resampling the image.
 926
 927             Can be one of the following:
 928             @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of
 929                 pixel replication
 930             @li wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling
 931                 methods for upsampling and downsampling respectively
 932
 933         @see Rescale()
 934     */
 935     wxImage Scale(int width, int height,
 936                   int quality = wxIMAGE_QUALITY_NORMAL) const;
 937
 938     /**
 939        Assigns new data as alpha channel to the image.
 940        If @e static_data is false the data will be
 941        free()'d after use.
 942     */
 943     void SetAlpha(unsigned char* alpha = NULL,
 944                   bool static_data = false);
 945
 946     /**
 947         Sets the alpha value for the given pixel. This function should only be
 948         called if the image has alpha channel data, use HasAlpha() to
 949         check for this.
 950     */
 951     void SetAlpha(int x, int y, unsigned char alpha);
 952
 953     /**
 954         Sets the image data without performing checks. The data given must have
 955         the size (width*height*3) or results will be unexpected. Don't use this
 956         method if you aren't sure you know what you are doing.
 957         The data must have been allocated with @c malloc(), @b NOT with
 958         @c operator new.
 959         After this call the pointer to the data is owned by the wxImage object,
 960         that will be responsible for deleting it.
 961         Do not pass to this function a pointer obtained through
 962         GetData().
 963     */
 964     void SetData(unsigned char* data);
 965
 966     /**
 967         Specifies whether there is a mask or not. The area of the mask is determined by
 968         the current mask colour.
 969     */
 970     void SetMask(bool hasMask = true);
 971
 972     /**
 973         Sets the mask colour for this image (and tells the image to use the mask).
 974     */
 975     void SetMaskColour(unsigned char red, unsigned char green,
 976                        unsigned char blue);
 977
 978     /**
 979         @param mask
 980             The mask image to extract mask shape from. Must have same dimensions as the
 981         image.
 982         @param mr,mg,mb
 983             RGB value of pixels in mask that will be used to create the mask.
 984
 985         @return Returns @false if mask does not have same dimensions as the image
 986                  or if there is no unused colour left. Returns @true if
 987                  the mask was successfully applied.
 988     */
 989     bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
 990                           unsigned char mg,
 991                           unsigned char mb);
 992
 993     //@{
 994     /**
 995         Sets a user-defined option. The function is case-insensitive to @e name.
 996         For example, when saving as a JPEG file, the option @b quality is
 997         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 998
 999         @see GetOption(), GetOptionInt(), HasOption()
1000     */
1001     void SetOption(const wxString& name, const wxString& value);
1002     void SetOption(const wxString& name, int value);
1003     //@}
1004
1005     /**
1006         Associates a palette with the image. The palette may be used when converting
1007         wxImage to wxBitmap (MSW only at present) or in file save operations (none as
1008         yet).
1009     */
1010     void SetPalette(const wxPalette& palette);
1011
1012     /**
1013         Sets the colour of the pixels within the given rectangle. This routine performs
1014         bounds-checks for the coordinate so it can be considered a safe way to
1015         manipulate the
1016         data.
1017     */
1018     void SetRGB(wxRect& rect, unsigned char red,
1019                 unsigned char green,
1020                 unsigned char blue);
1021
1022     /**
1023         Returns a resized version of this image without scaling it by adding either a
1024         border
1025         with the given colour or cropping as necessary. The image is pasted into a new
1026         image with the given @a size and background colour at the position @e pos
1027         relative to the upper left of the new image. If @a red = green = blue = -1
1028         then the areas of the larger image not covered by this image are made
1029         transparent by filling them with the image mask colour (which will be allocated
1030         automatically if it isn't currently set). Otherwise, the areas will be filled
1031         with the colour with the specified RGB components.
1032
1033         @see Resize()
1034     */
1035     wxImage Size(const wxSize& size, const wxPoint pos, int red = -1,
1036                  int green = -1, int blue = -1) const;
1037
1038     /**
1039         Assignment operator, using @ref overview_trefcount "reference counting".
1040
1041         @param image
1042             Image to assign.
1043
1044         @return Returns 'this' object.
1045     */
1046     wxImage operator =(const wxImage& image);
1047 };
1048
1049 // ============================================================================
1050 // Global functions/macros
1051 // ============================================================================
1052
1053 /** @ingroup group_funcmacro_appinitterm */
1054 //@{
1055
1056 /**
1057     Initializes all available image handlers. For a list of available handlers,
1058     see wxImage.
1059
1060     @see wxImage, wxImageHandler
1061
1062     @header{wx/image.h}
1063 */
1064 void wxInitAllImageHandlers();
1065
1066 //@}
1067