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          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, wxBitmapType 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, wxBitmapType 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         @return 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         @return @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         @return @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         @return 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         @return 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                                        wxBitmapType imageType);
 460     static wxImageHandler* FindHandler(wxBitmapType 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         @return 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                              wxBitmapType type = wxBITMAP_TYPE_ANY);
 544     static int GetImageCount(wxInputStream& stream,
 545                              wxBitmapType 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         @return 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 type of image found by LoadFile or specified with SaveFile
 629         @since 2.9.0
 630     */
 631     wxBitmapType GetType() const;
 632
 633     /**
 634         Gets the width of the image in pixels.
 635
 636         @see GetHeight()
 637     */
 638     int GetWidth() const;
 639
 640     /**
 641         Constructor for HSVValue, an object that contains values for hue, saturation
 642         and value which
 643         represent the value of a color. It is used by HSVtoRGB()
 644         and RGBtoHSV(), which
 645         converts between HSV color space and RGB color space.
 646     */
 647     HSVValue(double h = 0.0, double s = 0.0, double v = 0.0);
 648
 649     /**
 650         Converts a color in HSV color space to RGB color space.
 651     */
 652 #define wxImage::RGBValue HSVtoRGB(const HSVValue& hsv)     /* implementation is private */
 653
 654     /**
 655         Returns @true if this image has alpha channel, @false otherwise.
 656
 657         @see GetAlpha(), SetAlpha()
 658     */
 659     bool HasAlpha() const;
 660
 661     /**
 662         Returns @true if there is a mask active, @false otherwise.
 663     */
 664     bool HasMask() const;
 665
 666     /**
 667         Returns @true if the given option is present. The function is case-insensitive
 668         to @e name.
 669
 670         @see SetOption(), GetOption(), GetOptionInt()
 671     */
 672     bool HasOption(const wxString& name) const;
 673
 674     /**
 675         Initializes the image alpha channel data. It is an error to call it
 676         if the image already has alpha data. If it doesn't, alpha data will be
 677         by default initialized to all pixels being fully opaque. But if the image has a
 678         a mask colour, all mask pixels will be completely transparent.
 679     */
 680     void InitAlpha();
 681
 682     /**
 683         Internal use only. Adds standard image format handlers. It only install BMP
 684         for the time being, which is used by wxBitmap.
 685         This function is called by wxWidgets on startup, and shouldn't be called by
 686         the user.
 687
 688         @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
 689     */
 690     static void InitStandardHandlers();
 691
 692     /**
 693         Adds a handler at the start of the static list of format handlers.
 694
 695         @param handler
 696             A new image format handler object. There is usually only one instance
 697             of a given handler class in an application session.
 698
 699         @see wxImageHandler
 700     */
 701     static void InsertHandler(wxImageHandler* handler);
 702
 703     /**
 704         Returns @true if image data is present.
 705     */
 706     bool IsOk() const;
 707
 708     /**
 709         Returns @true if the given pixel is transparent, i.e. either has the mask
 710         colour if this image has a mask or if this image has alpha channel and alpha
 711         value of this pixel is strictly less than @e threshold.
 712     */
 713     bool IsTransparent(int x, int y, unsigned char threshold = 128) const;
 714
 715     //@{
 716     /**
 717         Loads an image from an input stream.
 718
 719         @param name
 720             Name of the file from which to load the image.
 721         @param stream
 722             Opened input stream from which to load the image. Currently, the
 723             stream must support seeking.
 724         @param type
 725             May be one of the following:
 726             @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
 727             @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
 728             @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
 729             @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
 730             @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
 731             @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
 732             @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
 733             @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
 734             @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
 735             @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
 736             @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
 737             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
 738             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 739         @param mimetype
 740             MIME type string (for example 'image/jpeg')
 741         @param index
 742             Index of the image to load in the case that the image file contains
 743             multiple images. This is only used by GIF, ICO and TIFF handlers.
 744             The default value (-1) means "choose the default image" and is
 745             interpreted as the first image (index=0) by the GIF and TIFF handler
 746             and as the largest and most colourful one by the ICO handler.
 747
 748         @return @true if the operation succeeded, @false otherwise. If the
 749                  optional index parameter is out of range, @false is
 750                  returned and a call to wxLogError() takes place.
 751
 752         @remarks Depending on how wxWidgets has been configured, not all formats
 753                  may be available.
 754
 755         @see SaveFile()
 756     */
 757     bool LoadFile(const wxString& name,
 758                   wxBitmapType type = wxBITMAP_TYPE_ANY,
 759                   int index = -1);
 760     bool LoadFile(const wxString& name, const wxString& mimetype,
 761                   int index = -1);
 762     bool LoadFile(wxInputStream& stream, wxBitmapType type,
 763                   int index = -1);
 764     bool LoadFile(wxInputStream& stream,
 765                   const wxString& mimetype,
 766                   int index = -1);
 767     //@}
 768
 769     /**
 770         Returns a mirrored copy of the image. The parameter @e horizontally
 771         indicates the orientation.
 772     */
 773     wxImage Mirror(bool horizontally = true) const;
 774
 775     /**
 776         Copy the data of the given @a image to the specified position in this image.
 777     */
 778     void Paste(const wxImage& image, int x, int y);
 779
 780     /**
 781         Constructor for RGBValue, an object that contains values for red, green and
 782         blue which
 783         represent the value of a color. It is used by HSVtoRGB()
 784         and RGBtoHSV(), which
 785         converts between HSV color space and RGB color space.
 786     */
 787     RGBValue(unsigned char r = 0, unsigned char g = 0,
 788              unsigned char b = 0);
 789
 790     /**
 791         Converts a color in RGB color space to HSV color space.
 792     */
 793 #define wxImage::HSVValue RGBtoHSV(const RGBValue& rgb)     /* implementation is private */
 794
 795     /**
 796         Finds the handler with the given name, and removes it. The handler
 797         is not deleted.
 798
 799         @param name
 800             The handler name.
 801
 802         @return @true if the handler was found and removed, @false otherwise.
 803
 804         @see wxImageHandler
 805     */
 806     static bool RemoveHandler(const wxString& name);
 807
 808     /**
 809         Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
 810     */
 811     void Replace(unsigned char r1, unsigned char g1,
 812                  unsigned char b1, unsigned char r2,
 813                  unsigned char g2, unsigned char b2);
 814
 815     /**
 816         Changes the size of the image in-place by scaling it: after a call to this
 817         function,
 818         the image will have the given width and height.
 819         For a description of the @a quality parameter, see the Scale() function.
 820         Returns the (modified) image itself.
 821
 822         @see Scale()
 823     */
 824     wxImage Rescale(int width, int height,
 825                     int quality = wxIMAGE_QUALITY_NORMAL);
 826
 827     /**
 828         Changes the size of the image in-place without scaling it by adding either a
 829         border
 830         with the given colour or cropping as necessary. The image is pasted into a new
 831         image with the given @a size and background colour at the position @e pos
 832         relative to the upper left of the new image. If @a red = green = blue = -1
 833         then use either the  current mask colour if set or find, use, and set a
 834         suitable mask colour for any newly exposed areas.
 835         Returns the (modified) image itself.
 836
 837         @see Size()
 838     */
 839     wxImage Resize(const wxSize& size, const wxPoint pos,
 840                    int red = -1, int green = -1,
 841                    int blue = -1);
 842
 843     /**
 844         Rotates the image about the given point, by @a angle radians. Passing @true
 845         to @a interpolating results in better image quality, but is slower. If the
 846         image has a mask, then the mask colour is used for the uncovered pixels in the
 847         rotated image background. Else, black (rgb 0, 0, 0) will be used.
 848         Returns the rotated image, leaving this image intact.
 849     */
 850     wxImage Rotate(double angle, const wxPoint& rotationCentre,
 851                    bool interpolating = true,
 852                    wxPoint* offsetAfterRotation = NULL);
 853
 854     /**
 855         Returns a copy of the image rotated 90 degrees in the direction
 856         indicated by @e clockwise.
 857     */
 858     wxImage Rotate90(bool clockwise = true) const;
 859
 860     /**
 861         Rotates the hue of each pixel in the image by @e angle, which is a double in
 862         the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
 863         corresponds
 864         to +360 degrees.
 865     */
 866     void RotateHue(double angle);
 867
 868     //@{
 869     /**
 870         Saves an image in the given stream.
 871
 872         @param name
 873             Name of the file to save the image to.
 874         @param stream
 875             Opened output stream to save the image to.
 876         @param type
 877             Currently these types can be used:
 878             @li wxBITMAP_TYPE_BMP: Save a BMP image file.
 879             @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
 880             @li wxBITMAP_TYPE_PNG: Save a PNG image file.
 881             @li wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible,
 882                 falls back to 24-bit otherwise).
 883             @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
 884             @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
 885             @li wxBITMAP_TYPE_XPM: Save a XPM image file.
 886             @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may
 887                 be up to 255 wide by 127 high. A single image is saved in 8 colors
 888                 at the size supplied).
 889             @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
 890         @param mimetype
 891             MIME type.
 892
 893         @return @true if the operation succeeded, @false otherwise.
 894
 895         @remarks Depending on how wxWidgets has been configured, not all formats
 896                  may be available.
 897
 898         @see LoadFile()
 899     */
 900     bool SaveFile(const wxString& name, int type) const;
 901     const bool SaveFile(const wxString& name,
 902                         const wxString& mimetype) const;
 903     const bool SaveFile(const wxString& name) const;
 904     const bool SaveFile(wxOutputStream& stream, int type) const;
 905     const bool SaveFile(wxOutputStream& stream,
 906                         const wxString& mimetype) const;
 907     //@}
 908
 909     /**
 910         Returns a scaled version of the image. This is also useful for
 911         scaling bitmaps in general as the only other way to scale bitmaps
 912         is to blit a wxMemoryDC into another wxMemoryDC.
 913         It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer
 914         looking results it is a slower method.  Downsampling will use the box averaging
 915         method
 916         which seems to operate very fast.  If you are upsampling larger images using
 917         this method you will most likely notice that it is a bit slower and in extreme
 918         cases
 919         it will be quite substantially slower as the bicubic algorithm has to process a
 920         lot of
 921         data.
 922         It should also be noted that the high quality scaling may not work as expected
 923         when using a single mask colour for transparency, as the scaling will blur the
 924         image and will therefore remove the mask partially. Using the alpha channel
 925         will work.
 926         Example:
 927
 928         @param quality
 929             Determines what method to use for resampling the image.
 930
 931             Can be one of the following:
 932             @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of
 933                 pixel replication
 934             @li wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling
 935                 methods for upsampling and downsampling respectively
 936
 937         @see Rescale()
 938     */
 939     wxImage Scale(int width, int height,
 940                   int quality = wxIMAGE_QUALITY_NORMAL) const;
 941
 942     /**
 943        Assigns new data as alpha channel to the image.
 944        If @e static_data is false the data will be
 945        free()'d after use.
 946     */
 947     void SetAlpha(unsigned char* alpha = NULL,
 948                   bool static_data = false);
 949
 950     /**
 951         Sets the alpha value for the given pixel. This function should only be
 952         called if the image has alpha channel data, use HasAlpha() to
 953         check for this.
 954     */
 955     void SetAlpha(int x, int y, unsigned char alpha);
 956
 957     /**
 958         Sets the image data without performing checks. The data given must have
 959         the size (width*height*3) or results will be unexpected. Don't use this
 960         method if you aren't sure you know what you are doing.
 961         The data must have been allocated with @c malloc(), @b NOT with
 962         @c operator new.
 963         After this call the pointer to the data is owned by the wxImage object,
 964         that will be responsible for deleting it.
 965         Do not pass to this function a pointer obtained through
 966         GetData().
 967     */
 968     void SetData(unsigned char* data);
 969
 970     /**
 971         Specifies whether there is a mask or not. The area of the mask is determined by
 972         the current mask colour.
 973     */
 974     void SetMask(bool hasMask = true);
 975
 976     /**
 977         Sets the mask colour for this image (and tells the image to use the mask).
 978     */
 979     void SetMaskColour(unsigned char red, unsigned char green,
 980                        unsigned char blue);
 981
 982     /**
 983         @param mask
 984             The mask image to extract mask shape from. Must have same dimensions as the
 985         image.
 986         @param mr,mg,mb
 987             RGB value of pixels in mask that will be used to create the mask.
 988
 989         @return Returns @false if mask does not have same dimensions as the image
 990                  or if there is no unused colour left. Returns @true if
 991                  the mask was successfully applied.
 992     */
 993     bool SetMaskFromImage(const wxImage& mask, unsigned char mr,
 994                           unsigned char mg,
 995                           unsigned char mb);
 996
 997     //@{
 998     /**
 999         Sets a user-defined option. The function is case-insensitive to @e name.
1000         For example, when saving as a JPEG file, the option @b quality is
1001         used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1002
1003         @see GetOption(), GetOptionInt(), HasOption()
1004     */
1005     void SetOption(const wxString& name, const wxString& value);
1006     void SetOption(const wxString& name, int value);
1007     //@}
1008
1009     /**
1010         Associates a palette with the image. The palette may be used when converting
1011         wxImage to wxBitmap (MSW only at present) or in file save operations (none as
1012         yet).
1013     */
1014     void SetPalette(const wxPalette& palette);
1015
1016     /**
1017         Sets the colour of the pixels within the given rectangle. This routine performs
1018         bounds-checks for the coordinate so it can be considered a safe way to
1019         manipulate the
1020         data.
1021     */
1022     void SetRGB(wxRect& rect, unsigned char red,
1023                 unsigned char green,
1024                 unsigned char blue);
1025
1026     /**
1027         Returns a resized version of this image without scaling it by adding either a
1028         border
1029         with the given colour or cropping as necessary. The image is pasted into a new
1030         image with the given @a size and background colour at the position @e pos
1031         relative to the upper left of the new image. If @a red = green = blue = -1
1032         then the areas of the larger image not covered by this image are made
1033         transparent by filling them with the image mask colour (which will be allocated
1034         automatically if it isn't currently set). Otherwise, the areas will be filled
1035         with the colour with the specified RGB components.
1036
1037         @see Resize()
1038     */
1039     wxImage Size(const wxSize& size, const wxPoint pos, int red = -1,
1040                  int green = -1, int blue = -1) const;
1041
1042     /**
1043         Assignment operator, using @ref overview_trefcount "reference counting".
1044
1045         @param image
1046             Image to assign.
1047
1048         @return Returns 'this' object.
1049     */
1050     wxImage operator =(const wxImage& image);
1051 };
1052
1053 // ============================================================================
1054 // Global functions/macros
1055 // ============================================================================
1056
1057 /** @ingroup group_funcmacro_appinitterm */
1058 //@{
1059
1060 /**
1061     Initializes all available image handlers. For a list of available handlers,
1062     see wxImage.
1063
1064     @see wxImage, wxImageHandler
1065
1066     @header{wx/image.h}
1067 */
1068 void wxInitAllImageHandlers();
1069
1070 //@}
1071