wxPython/src/_image.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _image.i
   3 // Purpose:     SWIG definitions for wxImage and such
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     25-Sept-2000
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17
  18 %{
  19 #include "wx/wxPython/pyistream.h"
  20 %}
  21
  22 //---------------------------------------------------------------------------
  23
  24 enum {
  25     wxIMAGE_ALPHA_TRANSPARENT,
  26     wxIMAGE_ALPHA_THRESHOLD,
  27     wxIMAGE_ALPHA_OPAQUE
  28 };
  29
  30
  31 //---------------------------------------------------------------------------
  32 %newgroup
  33
  34 DocStr(wxImageHandler,
  35 "This is the base class for implementing image file loading/saving, and
  36 image creation from data. It is used within `wx.Image` and is not
  37 normally seen by the application.", "");
  38 class wxImageHandler : public wxObject {
  39 public:
  40     // wxImageHandler();    Abstract Base Class
  41     wxString GetName();
  42     wxString GetExtension();
  43     long GetType();
  44     wxString GetMimeType();
  45
  46     //bool LoadFile(wxImage* image, wxInputStream& stream);
  47     //bool SaveFile(wxImage* image, wxOutputStream& stream);
  48     //virtual int GetImageCount( wxInputStream& stream );
  49     //bool CanRead( wxInputStream& stream );
  50
  51     bool CanRead( const wxString& name );
  52
  53     void SetName(const wxString& name);
  54     void SetExtension(const wxString& extension);
  55     void SetType(long type);
  56     void SetMimeType(const wxString& mimetype);
  57 };
  58
  59
  60 //---------------------------------------------------------------------------
  61
  62 class wxImageHistogram /* : public wxImageHistogramBase */
  63 {
  64 public:
  65     wxImageHistogram();
  66
  67     DocStr(MakeKey, "Get the key in the histogram for the given RGB values", "");
  68     static unsigned long MakeKey(byte r,
  69                                  byte g,
  70                                  byte b);
  71
  72     DocDeclAStr(
  73         bool, FindFirstUnusedColour(byte *OUTPUT,
  74                                     byte *OUTPUT,
  75                                     byte *OUTPUT,
  76                                     byte startR = 1,
  77                                     byte startG = 0,
  78                                     byte startB = 0 ) const,
  79         "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
  80         "Find first colour that is not used in the image and has higher RGB
  81 values than startR, startG, startB.  Returns a tuple consisting of a
  82 success flag and rgb values.", "");
  83
  84     %extend {
  85         DocStr(GetCount,
  86                "Returns the pixel count for the given key.  Use `MakeKey` to create a
  87 key value from a RGB tripple.", "");
  88         unsigned long GetCount(unsigned long key) {
  89             wxImageHistogramEntry e = (*self)[key];
  90             return e.value;
  91         }
  92
  93         DocStr(GetCountRGB,
  94                "Returns the pixel count for the given RGB values.", "");
  95         unsigned long GetCountRGB(byte r,
  96                                   byte g,
  97                                   byte b) {
  98             unsigned long key = wxImageHistogram::MakeKey(r, g, b);
  99             wxImageHistogramEntry e = (*self)[key];
 100             return e.value;
 101         }
 102
 103         DocStr(GetCountColour,
 104                "Returns the pixel count for the given `wx.Colour` value.", "");
 105         unsigned long GetCountColour(const wxColour& colour) {
 106             unsigned long key = wxImageHistogram::MakeKey(colour.Red(),
 107                                                           colour.Green(),
 108                                                           colour.Blue());
 109             wxImageHistogramEntry e = (*self)[key];
 110             return e.value;
 111         }
 112     }
 113
 114 };
 115
 116
 117 //---------------------------------------------------------------------------
 118
 119 %{
 120     typedef unsigned char* buffer;
 121 %}
 122
 123 %typemap(in) (buffer data, int DATASIZE)
 124     { if (!PyArg_Parse($input, "t#", &$1, &$2)) SWIG_fail; }
 125
 126 %typemap(in) (buffer alpha, int ALPHASIZE)
 127     { if (!PyArg_Parse($input, "t#", &$1, &$2)) SWIG_fail; }
 128
 129 //---------------------------------------------------------------------------
 130
 131
 132 DocStr(wxImage,
 133 "A platform-independent image class.  An image can be created from
 134 data, or using `wx.Bitmap.ConvertToImage`, or loaded from a file in a
 135 variety of formats.  Functions are available to set and get image
 136 bits, so it can be used for basic image manipulation.
 137
 138 A wx.Image cannot be drawn directly to a `wx.DC`.  Instead, a
 139 platform-specific `wx.Bitmap` object must be created from it using the
 140 `wx.BitmapFromImage` constructor. This bitmap can then be drawn in a
 141 device context, using `wx.DC.DrawBitmap`.
 142
 143 One colour value of the image may be used as a mask colour which will
 144 lead to the automatic creation of a `wx.Mask` object associated to the
 145 bitmap object.
 146
 147 wx.Image supports alpha channel data, that is in addition to a byte
 148 for the red, green and blue colour components for each pixel it also
 149 stores a byte representing the pixel opacity. An alpha value of 0
 150 corresponds to a transparent pixel (null opacity) while a value of 255
 151 means that the pixel is 100% opaque.
 152
 153 Unlike RGB data, not all images have an alpha channel and before using
 154 `GetAlpha` you should check if this image contains an alpha channel
 155 with `HasAlpha`. Note that currently only images loaded from PNG files
 156 with transparency information will have an alpha channel.", "");
 157
 158 %{
 159 // Pull the nested class out to the top level for SWIG's sake
 160 #define wxImage_RGBValue wxImage::RGBValue
 161 #define wxImage_HSVValue wxImage::HSVValue
 162 %}
 163
 164 class wxImage_RGBValue
 165 {
 166 public:
 167     wxImage_RGBValue(byte r=0, byte g=0, byte b=0);
 168     byte red;
 169     byte green;
 170     byte blue;
 171 };
 172
 173 class wxImage_HSVValue
 174 {
 175 public:
 176     wxImage_HSVValue(double h=0.0, double s=0.0, double v=0.0);
 177     double hue;
 178     double saturation;
 179     double value;
 180 };
 181
 182
 183 class wxImage : public wxObject {
 184 public:
 185     %typemap(out) wxImage*;    // turn off this typemap
 186
 187     DocCtorStr(
 188         wxImage( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
 189         "Loads an image from a file.",
 190         "
 191     :param name:  Name of the file from which to load the image.
 192
 193     :param type: May be one of the following:
 194
 195         ====================    =======================================
 196         wx.BITMAP_TYPE_BMP      Load a Windows bitmap file.
 197         wx.BITMAP_TYPE_GIF      Load a GIF bitmap file.
 198         wx.BITMAP_TYPE_JPEG     Load a JPEG bitmap file.
 199         wx.BITMAP_TYPE_PNG      Load a PNG bitmap file.
 200         wx.BITMAP_TYPE_PCX      Load a PCX bitmap file.
 201         wx.BITMAP_TYPE_PNM      Load a PNM bitmap file.
 202         wx.BITMAP_TYPE_TIF      Load a TIFF bitmap file.
 203         wx.BITMAP_TYPE_XPM      Load a XPM bitmap file.
 204         wx.BITMAP_TYPE_ICO      Load a Windows icon file (ICO).
 205         wx.BITMAP_TYPE_CUR      Load a Windows cursor file (CUR).
 206         wx.BITMAP_TYPE_ANI      Load a Windows animated cursor file (ANI).
 207         wx.BITMAP_TYPE_ANY      Will try to autodetect the format.
 208         ====================    =======================================
 209
 210     :param index: Index of the image to load in the case that the
 211         image file contains multiple images. This is only used by GIF,
 212         ICO and TIFF handlers. The default value (-1) means to choose
 213         the default image and is interpreted as the first image (the
 214         one with index=0) by the GIF and TIFF handler and as the
 215         largest and most colourful one by the ICO handler.
 216
 217 :see: `wx.ImageFromMime`, `wx.ImageFromStream`, `wx.ImageFromStreamMime`,
 218       `wx.EmptyImage`, `wx.ImageFromBitmap`, `wx.ImageFromData`,
 219       `wx.ImageFromDataWithAlpha`
 220 ");
 221
 222     ~wxImage();
 223
 224     // Alternate constructors
 225     DocCtorStrName(
 226         wxImage(const wxString& name, const wxString& mimetype, int index = -1),
 227         "Loads an image from a file, using a MIME type string (such as
 228 'image/jpeg') to specify image type.", "
 229
 230 :see: `wx.Image`",
 231         ImageFromMime);
 232
 233     DocCtorStrName(
 234         wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1),
 235         "Loads an image from an input stream, or any readable Python file-like
 236 object.", "
 237
 238 :see: `wx.Image`",
 239         ImageFromStream);
 240
 241     DocCtorStrName(
 242         wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1 ),
 243         "Loads an image from an input stream, or any readable Python file-like
 244 object, specifying the image format with a MIME type string.", "
 245
 246 :see: `wx.Image`",
 247         ImageFromStreamMime);
 248
 249     %extend {
 250         %RenameDocCtor(
 251             EmptyImage,
 252             "Construct an empty image of a given size, optionally setting all
 253 pixels to black.", "
 254
 255 :see: `wx.Image`",
 256             wxImage(int width=0, int height=0, bool clear = true))
 257             {
 258                 if (width > 0 && height > 0)
 259                     return new wxImage(width, height, clear);
 260                 else
 261                     return new wxImage;
 262             }
 263
 264
 265        MustHaveApp(wxImage(const wxBitmap &bitmap));
 266
 267         %RenameDocCtor(
 268             ImageFromBitmap,
 269             "Construct an Image from a `wx.Bitmap`.", "
 270
 271 :see: `wx.Image`",
 272             wxImage(const wxBitmap &bitmap))
 273             {
 274                 return new wxImage(bitmap.ConvertToImage());
 275             }
 276
 277         %RenameDocCtor(
 278             ImageFromData,
 279             "Construct an Image from a buffer of RGB bytes.  Accepts either a
 280 string or a buffer object holding the data and the length of the data
 281 must be width*height*3.", "
 282
 283 :see: `wx.Image`",
 284             wxImage(int width, int height, buffer data, int DATASIZE))
 285             {
 286                 if (DATASIZE != width*height*3) {
 287                     wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
 288                     return NULL;
 289                 }
 290
 291                 // Copy the source data so the wxImage can clean it up later
 292                 buffer copy = (buffer)malloc(DATASIZE);
 293                 if (copy == NULL) {
 294                     wxPyBLOCK_THREADS(PyErr_NoMemory());
 295                     return NULL;
 296                 }
 297                 memcpy(copy, data, DATASIZE);
 298                 return new wxImage(width, height, copy, false);
 299             }
 300
 301
 302         %RenameDocCtor(
 303             ImageFromDataWithAlpha,
 304             "Construct an Image from a buffer of RGB bytes with an Alpha channel.
 305 Accepts either a string or a buffer object holding the data and the
 306 length of the data must be width*height*3 bytes, and the length of the
 307 alpha data must be width*height bytes.", "
 308
 309 :see: `wx.Image`",
 310             wxImage(int width, int height, buffer data, int DATASIZE, buffer alpha, int ALPHASIZE))
 311             {
 312                 if (DATASIZE != width*height*3) {
 313                     wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
 314                     return NULL;
 315                 }
 316                 if (ALPHASIZE != width*height) {
 317                     wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
 318                     return NULL;
 319                 }
 320
 321                 // Copy the source data so the wxImage can clean it up later
 322                 buffer dcopy = (buffer)malloc(DATASIZE);
 323                 if (dcopy == NULL) {
 324                     wxPyBLOCK_THREADS(PyErr_NoMemory());
 325                     return NULL;
 326                 }
 327                 memcpy(dcopy, data, DATASIZE);
 328
 329                 buffer acopy = (buffer)malloc(ALPHASIZE);
 330                 if (acopy == NULL) {
 331                     wxPyBLOCK_THREADS(PyErr_NoMemory());
 332                     return NULL;
 333                 }
 334                 memcpy(acopy, alpha, ALPHASIZE);
 335
 336                 return new wxImage(width, height, dcopy, acopy, false);
 337             }
 338     }
 339
 340     // TODO: wxImage( char** xpmData );
 341
 342     // Turn it back on again
 343     %typemap(out) wxImage* { $result = wxPyMake_wxObject($1, $owner); }
 344
 345
 346     DocDeclStr(
 347         void , Create( int width, int height, bool clear=true ),
 348         "Creates a fresh image.  If clear is ``True``, the new image will be
 349 initialized to black. Otherwise, the image data will be uninitialized.", "");
 350
 351     DocDeclStr(
 352         void , Destroy(),
 353         "Destroys the image data.", "");
 354
 355
 356     DocDeclStr(
 357         wxImage , Scale( int width, int height ),
 358         "Returns a scaled version of the image. This is also useful for scaling
 359 bitmaps in general as the only other way to scale bitmaps is to blit a
 360 `wx.MemoryDC` into another `wx.MemoryDC`.", "
 361
 362 :see: `Rescale`");
 363
 364     DocDeclStr(
 365         wxImage , ShrinkBy( int xFactor , int yFactor ) const ,
 366         "Return a version of the image scaled smaller by the given factors.", "");
 367
 368     DocDeclStr(
 369         wxImage& , Rescale(int width, int height),
 370         "Changes the size of the image in-place by scaling it: after a call to
 371 this function, the image will have the given width and height.
 372
 373 Returns the (modified) image itself.", "
 374
 375 :see: `Scale`");
 376
 377
 378     // resizes the image in place
 379     DocDeclStr(
 380         wxImage& , Resize( const wxSize& size, const wxPoint& pos,
 381                            int r = -1, int g = -1, int b = -1 ),
 382         "Changes the size of the image in-place without scaling it, by adding
 383 either a border with the given colour or cropping as necessary. The
 384 image is pasted into a new image with the given size and background
 385 colour at the position pos relative to the upper left of the new
 386 image. If red = green = blue = -1 then use either the current mask
 387 colour if set or find, use, and set a suitable mask colour for any
 388 newly exposed areas.
 389
 390 Returns the (modified) image itself.", "
 391
 392 :see: `Size`");
 393
 394
 395     DocDeclStr(
 396         void , SetRGB( int x, int y, byte r, byte g, byte b ),
 397         "Sets the pixel at the given coordinate. This routine performs
 398 bounds-checks for the coordinate so it can be considered a safe way to
 399 manipulate the data, but in some cases this might be too slow so that
 400 the data will have to be set directly. In that case you will have to
 401 get access to the image data using the `GetData` method.", "");
 402
 403
 404     DocDeclStrName(
 405             void, SetRGB( const wxRect& rect,
 406                           byte r, byte g, byte b ),
 407             "Sets the colour of the pixels within the given rectangle. This routine
 408 performs bounds-checks for the rectangle so it can be considered a
 409 safe way to manipulate the data.", "",
 410             SetRGBRect);
 411
 412     DocDeclStr(
 413         byte , GetRed( int x, int y ),
 414         "Returns the red intensity at the given coordinate.", "");
 415
 416     DocDeclStr(
 417         byte , GetGreen( int x, int y ),
 418         "Returns the green intensity at the given coordinate.", "");
 419
 420     DocDeclStr(
 421         byte , GetBlue( int x, int y ),
 422         "Returns the blue intensity at the given coordinate.", "");
 423
 424
 425     DocDeclStr(
 426         void , SetAlpha(int x, int y, byte alpha),
 427         "Sets the alpha value for the given pixel. This function should only be
 428 called if the image has alpha channel data, use `HasAlpha` to check
 429 for this.", "");
 430
 431     DocDeclStr(
 432         byte , GetAlpha(int x, int y),
 433         "Returns the alpha value for the given pixel. This function may only be
 434 called for the images with alpha channel, use `HasAlpha` to check for
 435 this.
 436
 437 The returned value is the *opacity* of the image, i.e. the value of 0
 438 corresponds to the fully transparent pixels while the value of 255 to
 439 the fully opaque pixels.", "");
 440
 441     DocDeclStr(
 442         bool , HasAlpha(),
 443         "Returns true if this image has alpha channel, false otherwise.", "
 444
 445 :see: `GetAlpha`, `SetAlpha`");
 446
 447
 448     DocDeclStr(
 449         void , InitAlpha(),
 450         "Initializes the image alpha channel data. It is an error to call it if
 451 the image already has alpha data. If it doesn't, alpha data will be by
 452 default initialized to all pixels being fully opaque. But if the image
 453 has a a mask colour, all mask pixels will be completely transparent.", "");
 454
 455
 456     DocDeclStr(
 457         bool , IsTransparent(int x, int y,
 458                              byte threshold = wxIMAGE_ALPHA_THRESHOLD) const,
 459         "Returns ``True`` if this pixel is masked or has an alpha value less
 460 than the spcified threshold.", "");
 461
 462
 463     // find first colour that is not used in the image and has higher
 464     // RGB values than <startR,startG,startB>
 465     DocDeclAStr(
 466         bool, FindFirstUnusedColour( byte *OUTPUT, byte *OUTPUT, byte *OUTPUT,
 467                                      byte startR = 0, byte startG = 0, byte startB = 0 ) const,
 468         "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
 469         "Find first colour that is not used in the image and has higher RGB
 470 values than startR, startG, startB.  Returns a tuple consisting of a
 471 success flag and rgb values.", "");
 472
 473
 474     DocDeclStr(
 475         bool , ConvertAlphaToMask(byte threshold = wxIMAGE_ALPHA_THRESHOLD),
 476         "If the image has alpha channel, this method converts it to mask. All
 477 pixels with alpha value less than ``threshold`` are replaced with the
 478 mask colour and the alpha channel is removed. The mask colour is
 479 chosen automatically using `FindFirstUnusedColour`.
 480
 481 If the image image doesn't have alpha channel, ConvertAlphaToMask does
 482 nothing.", "");
 483
 484
 485     DocDeclStr(
 486         bool , ConvertColourToAlpha( byte r, byte g, byte b ),
 487         "This method converts an image where the original alpha information is
 488 only available as a shades of a colour (actually shades of grey)
 489 typically when you draw anti-aliased text into a bitmap. The DC
 490 drawing routines draw grey values on the black background although
 491 they actually mean to draw white with differnt alpha values.  This
 492 method reverses it, assuming a black (!) background and white text.
 493 The method will then fill up the whole image with the colour given.", "");
 494
 495
 496
 497     DocDeclStr(
 498         bool , SetMaskFromImage(const wxImage & mask,
 499                                 byte mr, byte mg, byte mb),
 500         "Sets the image's mask so that the pixels that have RGB value of
 501 ``(mr,mg,mb)`` in ``mask`` will be masked in this image. This is done
 502 by first finding an unused colour in the image, setting this colour as
 503 the mask colour and then using this colour to draw all pixels in the
 504 image who corresponding pixel in mask has given RGB value.
 505
 506 Returns ``False`` if ``mask`` does not have same dimensions as the
 507 image or if there is no unused colour left. Returns ``True`` if the
 508 mask was successfully applied.
 509
 510 Note that this method involves computing the histogram, which is
 511 computationally intensive operation.", "");
 512
 513
 514 //      void DoFloodFill (wxCoord x, wxCoord y,
 515 //          const wxBrush & fillBrush,
 516 //          const wxColour& testColour,
 517 //          int style = wxFLOOD_SURFACE,
 518 //          int LogicalFunction = wxCOPY /* currently unused */ ) ;
 519
 520     DocDeclStr(
 521         static bool , CanRead( const wxString& filename ),
 522         "Returns True if the image handlers can read this file.", "");
 523
 524     DocDeclStr(
 525         static int , GetImageCount( const wxString& filename, long type = wxBITMAP_TYPE_ANY ),
 526         "If the image file contains more than one image and the image handler
 527 is capable of retrieving these individually, this function will return
 528 the number of available images.", "");
 529
 530
 531     DocDeclStr(
 532         bool , LoadFile( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
 533         "Loads an image from a file. If no handler type is provided, the
 534 library will try to autodetect the format.", "");
 535
 536     DocDeclStrName(
 537         bool , LoadFile( const wxString& name, const wxString& mimetype, int index = -1 ),
 538         "Loads an image from a file, specifying the image type with a MIME type
 539 string.", "",
 540         LoadMimeFile);
 541
 542
 543     DocDeclStr(
 544         bool , SaveFile( const wxString& name, int type ),
 545         "Saves an image in the named file.", "");
 546
 547
 548     DocDeclStrName(
 549         bool , SaveFile( const wxString& name, const wxString& mimetype ),
 550         "Saves an image in the named file.", "",
 551         SaveMimeFile);
 552
 553
 554     DocDeclStrName(
 555         static bool , CanRead( wxInputStream& stream ),
 556         "Returns True if the image handlers can read an image file from the
 557 data currently on the input stream, or a readable Python file-like
 558 object.", "",
 559         CanReadStream);
 560
 561
 562     DocDeclStrName(
 563         bool , LoadFile( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
 564         "Loads an image from an input stream or a readable Python file-like
 565 object. If no handler type is provided, the library will try to
 566 autodetect the format.", "",
 567         LoadStream);
 568
 569
 570     DocDeclStrName(
 571         bool , LoadFile( wxInputStream& stream, const wxString& mimetype, int index = -1 ),
 572         "Loads an image from an input stream or a readable Python file-like
 573 object, using a MIME type string to specify the image file format.", "",
 574         LoadMimeStream);
 575
 576
 577     DocDeclStr(
 578         bool , Ok(),
 579         "Returns true if image data is present.", "");
 580
 581     DocDeclStr(
 582         int , GetWidth(),
 583         "Gets the width of the image in pixels.", "");
 584
 585     DocDeclStr(
 586         int , GetHeight(),
 587         "Gets the height of the image in pixels.", "");
 588
 589
 590     %extend {
 591         DocStr(GetSize,
 592                "Returns the size of the image in pixels.", "");
 593         wxSize GetSize() {
 594             wxSize size(self->GetWidth(), self->GetHeight());
 595             return size;
 596         }
 597     }
 598
 599
 600     DocDeclStr(
 601         wxImage , GetSubImage(const wxRect& rect),
 602         "Returns a sub image of the current one as long as the rect belongs
 603 entirely to the image.", "");
 604
 605
 606     DocDeclStr(
 607         wxImage , Size( const wxSize& size, const wxPoint& pos,
 608                         int r = -1, int g = -1, int b = -1 ) const,
 609         "Returns a resized version of this image without scaling it by adding
 610 either a border with the given colour or cropping as necessary. The
 611 image is pasted into a new image with the given size and background
 612 colour at the position ``pos`` relative to the upper left of the new
 613 image. If red = green = blue = -1 then use either the current mask
 614 colour if set or find, use, and set a suitable mask colour for any
 615 newly exposed areas.", "
 616
 617 :see: `Resize`");
 618
 619
 620     DocDeclStr(
 621         wxImage , Copy(),
 622         "Returns an identical copy of the image.", "");
 623
 624     DocDeclStr(
 625         void , Paste( const wxImage &image, int x, int y ),
 626         "Pastes ``image`` into this instance and takes care of the mask colour
 627 and any out of bounds problems.", "");
 628
 629
 630     //unsigned char *GetData();
 631     //void SetData( unsigned char *data );
 632
 633     %extend {
 634         DocStr(GetData,
 635                "Returns a string containing a copy of the RGB bytes of the image.", "");
 636         PyObject* GetData()
 637         {
 638             buffer data = self->GetData();
 639             int len = self->GetWidth() * self->GetHeight() * 3;
 640             PyObject* rv;
 641             wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len));
 642             return rv;
 643         }
 644         DocStr(SetData,
 645                "Resets the Image's RGB data from a buffer of RGB bytes.  Accepts
 646 either a string or a buffer object holding the data and the length of
 647 the data must be width*height*3.", "");
 648         void SetData(buffer data, int DATASIZE)
 649         {
 650             if (DATASIZE != self->GetWidth() * self->GetHeight() * 3) {
 651                 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
 652                 return;
 653             }
 654             buffer copy = (buffer)malloc(DATASIZE);
 655             if (copy == NULL) {
 656                 wxPyBLOCK_THREADS(PyErr_NoMemory());
 657                 return;
 658             }
 659             memcpy(copy, data, DATASIZE);
 660             self->SetData(copy, false);
 661             // wxImage takes ownership of copy...
 662         }
 663
 664
 665         DocStr(GetDataBuffer,
 666                "Returns a writable Python buffer object that is pointing at the RGB
 667 image data buffer inside the wx.Image. You need to ensure that you do
 668 not use this buffer object after the image has been destroyed.", "");
 669         PyObject* GetDataBuffer()
 670         {
 671             buffer data = self->GetData();
 672             int len = self->GetWidth() * self->GetHeight() * 3;
 673             PyObject* rv;
 674             wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
 675             return rv;
 676         }
 677
 678         DocStr(SetDataBuffer,
 679                "Sets the internal image data pointer to point at a Python buffer
 680 object.  This can save making an extra copy of the data but you must
 681 ensure that the buffer object lives longer than the wx.Image does.", "");
 682         void SetDataBuffer(buffer data, int DATASIZE)
 683         {
 684             if (DATASIZE != self->GetWidth() * self->GetHeight() * 3) {
 685                 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
 686                 return;
 687             }
 688             self->SetData(data, true);
 689         }
 690
 691
 692
 693         DocStr(GetAlphaData,
 694                "Returns a string containing a copy of the alpha bytes of the image.", "");
 695         PyObject* GetAlphaData() {
 696             buffer data = self->GetAlpha();
 697             if (! data) {
 698                 RETURN_NONE();
 699             } else {
 700                 int len = self->GetWidth() * self->GetHeight();
 701                 PyObject* rv;
 702                 wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len) );
 703                 return rv;
 704             }
 705         }
 706
 707         DocStr(SetAlphaData,
 708                "Resets the Image's alpha data from a buffer of bytes.  Accepts either
 709 a string or a buffer object holding the data and the length of the
 710 data must be width*height.", "");
 711         void SetAlphaData(buffer alpha, int ALPHASIZE)
 712         {
 713             if (ALPHASIZE != self->GetWidth() * self->GetHeight()) {
 714                 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
 715                 return;
 716             }
 717             buffer acopy = (buffer)malloc(ALPHASIZE);
 718             if (acopy == NULL) {
 719                 wxPyBLOCK_THREADS(PyErr_NoMemory());
 720                 return;
 721             }
 722             memcpy(acopy, alpha, ALPHASIZE);
 723             self->SetAlpha(acopy, false);
 724             // wxImage takes ownership of acopy...
 725         }
 726
 727
 728
 729         DocStr(GetDataBuffer,
 730                "Returns a writable Python buffer object that is pointing at the Alpha
 731 data buffer inside the wx.Image. You need to ensure that you do not
 732 use this buffer object after the image has been destroyed.", "");
 733         PyObject* GetAlphaBuffer()
 734         {
 735             buffer data = self->GetAlpha();
 736             int len = self->GetWidth() * self->GetHeight();
 737             PyObject* rv;
 738             wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
 739             return rv;
 740         }
 741
 742
 743         DocStr(SetDataBuffer,
 744                "Sets the internal image alpha pointer to point at a Python buffer
 745 object.  This can save making an extra copy of the data but you must
 746 ensure that the buffer object lives as long as the wx.Image does.", "");
 747         void SetAlphaBuffer(buffer alpha, int ALPHASIZE)
 748         {
 749             if (ALPHASIZE != self->GetWidth() * self->GetHeight()) {
 750                 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
 751                 return;
 752             }
 753             self->SetAlpha(alpha, true);
 754         }
 755     }
 756
 757
 758
 759     DocDeclStr(
 760         void , SetMaskColour( byte r, byte g, byte b ),
 761         "Sets the mask colour for this image (and tells the image to use the
 762 mask).", "");
 763
 764
 765     DocDeclAStr(
 766         /*bool*/ void , GetOrFindMaskColour( byte *OUTPUT,
 767                                              byte *OUTPUT,
 768                                              byte *OUTPUT ) const,
 769         "GetOrFindMaskColour() -> (r,g,b)",
 770         "Get the current mask colour or find a suitable colour.", "");
 771
 772
 773     DocDeclStr(
 774         byte , GetMaskRed(),
 775         "Gets the red component of the mask colour.", "");
 776
 777     DocDeclStr(
 778         byte , GetMaskGreen(),
 779         "Gets the green component of the mask colour.", "");
 780
 781     DocDeclStr(
 782         byte , GetMaskBlue(),
 783         "Gets the blue component of the mask colour.", "");
 784
 785     DocDeclStr(
 786         void , SetMask( bool mask = true ),
 787         "Specifies whether there is a mask or not. The area of the mask is
 788 determined by the current mask colour.", "");
 789
 790     DocDeclStr(
 791         bool , HasMask(),
 792         "Returns ``True`` if there is a mask active, ``False`` otherwise.", "");
 793
 794
 795     DocDeclStr(
 796         wxImage , Rotate(double angle, const wxPoint & centre_of_rotation,
 797                          bool interpolating = true, wxPoint * offset_after_rotation = NULL) const ,
 798         "Rotates the image about the given point, by ``angle`` radians. Passing
 799 ``True`` to ``interpolating`` results in better image quality, but is
 800 slower. If the image has a mask, then the mask colour is used for the
 801 uncovered pixels in the rotated image background. Otherwise, black
 802 will be used as the fill colour.
 803
 804 Returns the rotated image, leaving this image intact.", "");
 805
 806     DocDeclStr(
 807         wxImage , Rotate90( bool clockwise = true ) ,
 808         "Returns a copy of the image rotated 90 degrees in the direction
 809 indicated by ``clockwise``.", "");
 810
 811     DocDeclStr(
 812         wxImage , Mirror( bool horizontally = true ) ,
 813         "Returns a mirrored copy of the image. The parameter ``horizontally``
 814 indicates the orientation.", "");
 815
 816
 817     DocDeclStr(
 818         void , Replace( byte r1, byte g1, byte b1,
 819                         byte r2, byte g2, byte b2 ),
 820         "Replaces the colour specified by ``(r1,g1,b1)`` by the colour
 821 ``(r2,g2,b2)``.", "");
 822
 823
 824     DocDeclStr(
 825         wxImage , ConvertToMono( byte r, byte g, byte b ) const,
 826         "Returns monochromatic version of the image. The returned image has
 827 white colour where the original has ``(r,g,b)`` colour and black
 828 colour everywhere else.", "");
 829
 830
 831     DocDeclStr(
 832         void , SetOption(const wxString& name, const wxString& value),
 833         "Sets an image handler defined option.  For example, when saving as a
 834 JPEG file, the option ``wx.IMAGE_OPTION_QUALITY`` is used, which is a
 835 number between 0 and 100 (0 is terrible, 100 is very good).", "
 836
 837     ================================= ===
 838     wx.IMAGE_OPTION_BMP_FORMAT
 839     wx.IMAGE_OPTION_CUR_HOTSPOT_X
 840     wx.IMAGE_OPTION_CUR_HOTSPOT_Y
 841     wx.IMAGE_OPTION_RESOLUTION
 842     wx.IMAGE_OPTION_RESOLUTIONX
 843     wx.IMAGE_OPTION_RESOLUTIONY
 844     wx.IMAGE_OPTION_RESOLUTIONUNIT
 845     wx.IMAGE_OPTION_QUALITY
 846     wx.IMAGE_OPTION_BITSPERSAMPLE
 847     wx.IMAGE_OPTION_SAMPLESPERPIXEL
 848     wx.IMAGE_OPTION_COMPRESSION
 849     wx.IMAGE_OPTION_IMAGEDESCRIPTOR
 850     wx.IMAGE_OPTION_PNG_FORMAT
 851     wx.IMAGE_OPTION_PNG_BITDEPTH
 852     ================================= ===
 853
 854 :see: `HasOption`, `GetOption`, `GetOptionInt`, `SetOptionInt`");
 855
 856     DocDeclStrName(
 857         void,  SetOption(const wxString& name, int value),
 858         "Sets an image option as an integer.", "
 859
 860 :see: `HasOption`, `GetOption`, `GetOptionInt`, `SetOption`",
 861         SetOptionInt);
 862
 863     DocDeclStr(
 864         wxString , GetOption(const wxString& name) const,
 865         "Gets the value of an image handler option.", "
 866
 867 :see: `HasOption`, `GetOptionInt`, `SetOption`, `SetOptionInt`");
 868
 869     DocDeclStr(
 870         int , GetOptionInt(const wxString& name) const,
 871         "Gets the value of an image handler option as an integer.  If the given
 872 option is not present, the function returns 0.", "
 873
 874 :see: `HasOption`, `GetOption`, `SetOptionInt`, `SetOption`");
 875
 876     DocDeclStr(
 877         bool , HasOption(const wxString& name) const,
 878         "Returns true if the given option is present.", "
 879
 880 :see: `GetOption`, `GetOptionInt`, `SetOption`, `SetOptionInt`");
 881
 882
 883     unsigned long CountColours( unsigned long stopafter = (unsigned long) -1 );
 884     unsigned long ComputeHistogram( wxImageHistogram& h );
 885
 886     static void AddHandler( wxImageHandler *handler );
 887     static void InsertHandler( wxImageHandler *handler );
 888     static bool RemoveHandler( const wxString& name );
 889
 890     DocDeclStr(
 891         static wxString , GetImageExtWildcard(),
 892         "Iterates all registered wxImageHandler objects, and returns a string
 893 containing file extension masks suitable for passing to file open/save
 894 dialog boxes.", "");
 895
 896
 897
 898 MustHaveApp(ConvertToBitmap);
 899 MustHaveApp(ConvertToMonoBitmap);
 900
 901     %extend {
 902         wxBitmap ConvertToBitmap(int depth=-1) {
 903             wxBitmap bitmap(*self, depth);
 904             return bitmap;
 905         }
 906
 907         wxBitmap ConvertToMonoBitmap( byte red,
 908                                       byte green,
 909                                       byte blue ) {
 910             wxImage mono = self->ConvertToMono( red, green, blue );
 911             wxBitmap bitmap( mono, 1 );
 912             return bitmap;
 913         }
 914     }
 915
 916
 917     DocDeclStr(
 918         void , RotateHue(double angle),
 919         "Rotates the hue of each pixel of the image. Hue is a double in the
 920 range -1.0..1.0 where -1.0 is -360 degrees and 1.0 is 360 degrees", "");
 921
 922     static wxImage_HSVValue RGBtoHSV(wxImage_RGBValue rgb);
 923     static wxImage_RGBValue HSVtoRGB(wxImage_HSVValue hsv);
 924
 925     %pythoncode { def __nonzero__(self): return self.Ok() }
 926 };
 927
 928
 929
 930 ///void wxInitAllImageHandlers();
 931
 932 %pythoncode {
 933     def InitAllImageHandlers():
 934         """
 935         The former functionality of InitAllImageHanders is now done internal to
 936         the _core_ extension module and so this function has become a simple NOP.
 937         """
 938         pass
 939 }
 940
 941
 942
 943 // See also wxPy_ReinitStockObjects in helpers.cpp
 944 %immutable;
 945 const wxImage    wxNullImage;
 946 %mutable;
 947
 948 //---------------------------------------------------------------------------
 949
 950 MAKE_CONST_WXSTRING(IMAGE_OPTION_FILENAME);
 951 MAKE_CONST_WXSTRING(IMAGE_OPTION_BMP_FORMAT);
 952 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_X);
 953 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_Y);
 954 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTION);
 955 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONX);
 956 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONY);
 957 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONUNIT);
 958 MAKE_CONST_WXSTRING(IMAGE_OPTION_QUALITY);
 959
 960 enum
 961 {
 962     wxIMAGE_RESOLUTION_INCHES = 1,
 963     wxIMAGE_RESOLUTION_CM = 2
 964 };
 965
 966
 967 MAKE_CONST_WXSTRING(IMAGE_OPTION_BITSPERSAMPLE);
 968 MAKE_CONST_WXSTRING(IMAGE_OPTION_SAMPLESPERPIXEL);
 969 MAKE_CONST_WXSTRING(IMAGE_OPTION_COMPRESSION);
 970 MAKE_CONST_WXSTRING(IMAGE_OPTION_IMAGEDESCRIPTOR);
 971
 972 MAKE_CONST_WXSTRING(IMAGE_OPTION_PNG_FORMAT);
 973 MAKE_CONST_WXSTRING(IMAGE_OPTION_PNG_BITDEPTH);
 974
 975 enum
 976 {
 977     wxPNG_TYPE_COLOUR = 0,
 978     wxPNG_TYPE_GREY = 2,
 979     wxPNG_TYPE_GREY_RED = 3
 980 };
 981
 982 enum
 983 {
 984     wxBMP_24BPP        = 24, // default, do not need to set
 985     //wxBMP_16BPP      = 16, // wxQuantize can only do 236 colors?
 986     wxBMP_8BPP         =  8, // 8bpp, quantized colors
 987     wxBMP_8BPP_GREY    =  9, // 8bpp, rgb averaged to greys
 988     wxBMP_8BPP_GRAY    =  wxBMP_8BPP_GREY,
 989     wxBMP_8BPP_RED     = 10, // 8bpp, red used as greyscale
 990     wxBMP_8BPP_PALETTE = 11, // 8bpp, use the wxImage's palette
 991     wxBMP_4BPP         =  4, // 4bpp, quantized colors
 992     wxBMP_1BPP         =  1, // 1bpp, quantized "colors"
 993     wxBMP_1BPP_BW      =  2  // 1bpp, black & white from red
 994 };
 995
 996
 997 DocStr(wxBMPHandler,
 998 "A `wx.ImageHandler` for \*.bmp bitmap files.", "");
 999 class wxBMPHandler : public wxImageHandler {
1000 public:
1001     wxBMPHandler();
1002 };
1003
1004 DocStr(wxICOHandler,
1005 "A `wx.ImageHandler` for \*.ico icon files.", "");
1006 class wxICOHandler : public wxBMPHandler {
1007 public:
1008     wxICOHandler();
1009 };
1010
1011 DocStr(wxCURHandler,
1012 "A `wx.ImageHandler` for \*.cur cursor files.", "");
1013 class wxCURHandler : public wxICOHandler {
1014 public:
1015     wxCURHandler();
1016 };
1017
1018 DocStr(wxANIHandler,
1019 "A `wx.ImageHandler` for \*.ani animated cursor files.", "");
1020 class wxANIHandler : public wxCURHandler {
1021 public:
1022     wxANIHandler();
1023 };
1024
1025
1026 //---------------------------------------------------------------------------
1027
1028 DocStr(wxPNGHandler,
1029 "A `wx.ImageHandler` for PNG image files.", "");
1030 class wxPNGHandler : public wxImageHandler {
1031 public:
1032     wxPNGHandler();
1033 };
1034
1035
1036 DocStr(wxGIFHandler,
1037 "A `wx.ImageHandler` for GIF image files.", "");
1038 class wxGIFHandler : public wxImageHandler {
1039 public:
1040     wxGIFHandler();
1041 };
1042
1043
1044 DocStr(wxPCXHandler,
1045 "A `wx.ImageHandler` for PCX imager files.", "");
1046 class wxPCXHandler : public wxImageHandler {
1047 public:
1048     wxPCXHandler();
1049 };
1050
1051
1052 DocStr(wxJPEGHandler,
1053 "A `wx.ImageHandler` for JPEG/JPG image files.", "");
1054 class wxJPEGHandler : public wxImageHandler {
1055 public:
1056     wxJPEGHandler();
1057 };
1058
1059
1060 DocStr(wxPNMHandler,
1061 "A `wx.ImageHandler` for PNM image files.", "");
1062 class wxPNMHandler : public wxImageHandler {
1063 public:
1064     wxPNMHandler();
1065 };
1066
1067 DocStr(wxXPMHandler,
1068 "A `wx.ImageHandler` for XPM image.", "");
1069 class wxXPMHandler : public wxImageHandler {
1070 public:
1071     wxXPMHandler();
1072 };
1073
1074 DocStr(wxTIFFHandler,
1075 "A `wx.ImageHandler` for TIFF image files.", "");
1076 class wxTIFFHandler : public wxImageHandler {
1077 public:
1078     wxTIFFHandler();
1079 };
1080
1081
1082 #if wxUSE_IFF
1083 DocStr(wxIFFHandler,
1084 "A `wx.ImageHandler` for IFF image files.", "");
1085 class wxIFFHandler : public wxImageHandler {
1086 public:
1087     wxIFFHandler();
1088 };
1089 #endif
1090
1091 //---------------------------------------------------------------------------
1092
1093 %{
1094 #include <wx/quantize.h>
1095 %}
1096
1097 enum {
1098     wxQUANTIZE_INCLUDE_WINDOWS_COLOURS,
1099 //    wxQUANTIZE_RETURN_8BIT_DATA,
1100     wxQUANTIZE_FILL_DESTINATION_IMAGE
1101 };
1102
1103
1104 DocStr(wxQuantize,
1105        "Performs quantization, or colour reduction, on a wxImage.", "");
1106
1107 class wxQuantize /*: public wxObject */
1108 {
1109 public:
1110
1111     %extend {
1112         DocStr(
1113             Quantize,
1114             "Reduce the colours in the source image and put the result into the
1115 destination image, setting the palette in the destination if
1116 needed. Both images may be the same, to overwrite the source image.", "
1117 :todo: Create a version that returns the wx.Palette used.");
1118
1119         static bool Quantize(const wxImage& src, wxImage& dest, int desiredNoColours = 236,
1120                              int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE)
1121         {
1122                 return wxQuantize::Quantize(src, dest,
1123                                             //NULL, // palette
1124                                             desiredNoColours,
1125                                             NULL, // eightBitData
1126                                             flags);
1127         }
1128     }
1129 };
1130
1131
1132 //---------------------------------------------------------------------------