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