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