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