interface/image.h

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