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