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