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