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