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