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 %newgroup
  24
  25
  26 class wxImageHandler : public wxObject {
  27 public:
  28     // wxImageHandler();    Abstract Base Class
  29     wxString GetName();
  30     wxString GetExtension();
  31     long GetType();
  32     wxString GetMimeType();
  33
  34     //bool LoadFile(wxImage* image, wxInputStream& stream);
  35     //bool SaveFile(wxImage* image, wxOutputStream& stream);
  36     //virtual int GetImageCount( wxInputStream& stream );
  37     //bool CanRead( wxInputStream& stream );
  38
  39     bool CanRead( const wxString& name );
  40
  41     void SetName(const wxString& name);
  42     void SetExtension(const wxString& extension);
  43     void SetType(long type);
  44     void SetMimeType(const wxString& mimetype);
  45 };
  46
  47
  48 //---------------------------------------------------------------------------
  49
  50 class wxImageHistogram /* : public wxImageHistogramBase */
  51 {
  52 public:
  53     wxImageHistogram();
  54
  55     DocStr(MakeKey, "Get the key in the histogram for the given RGB values", "");
  56     static unsigned long MakeKey(unsigned char r,
  57                                  unsigned char g,
  58                                  unsigned char b);
  59
  60     DocDeclAStr(
  61         bool, FindFirstUnusedColour(unsigned char *OUTPUT,
  62                                     unsigned char *OUTPUT,
  63                                     unsigned char *OUTPUT,
  64                                     unsigned char startR = 1,
  65                                     unsigned char startG = 0,
  66                                     unsigned char startB = 0 ) const,
  67         "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
  68         "Find first colour that is not used in the image and has higher RGB
  69 values than startR, startG, startB.  Returns a tuple consisting of a
  70 success flag and rgb values.", "");
  71 };
  72
  73
  74 //---------------------------------------------------------------------------
  75
  76
  77 class wxImage : public wxObject {
  78 public:
  79     DocCtorStr(
  80         wxImage( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
  81         "", "");
  82
  83     ~wxImage();
  84
  85     // Alternate constructors
  86     DocCtorStrName(
  87         wxImage(const wxString& name, const wxString& mimetype, int index = -1),
  88         "", "",
  89         ImageFromMime);
  90
  91     DocCtorStrName(
  92         wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1),
  93         "", "",
  94         ImageFromStream);
  95
  96     DocCtorStrName(
  97         wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1 ),
  98         "", "",
  99         ImageFromStreamMime);
 100
 101     %extend {
 102         %rename(EmptyImage) wxImage(int width=0, int height=0, bool clear = true);
 103         wxImage(int width=0, int height=0, bool clear = true)
 104         {
 105             if (width > 0 && height > 0)
 106                 return new wxImage(width, height, clear);
 107             else
 108                 return new wxImage;
 109         }
 110
 111         MustHaveApp(wxImage(const wxBitmap &bitmap));
 112         %rename(ImageFromBitmap) wxImage(const wxBitmap &bitmap);
 113         wxImage(const wxBitmap &bitmap)
 114         {
 115             return new wxImage(bitmap.ConvertToImage());
 116         }
 117
 118         %rename(ImageFromData) wxImage(int width, int height, unsigned char* data);
 119         wxImage(int width, int height, unsigned char* data)
 120         {
 121             // Copy the source data so the wxImage can clean it up later
 122             unsigned char* copy = (unsigned char*)malloc(width*height*3);
 123             if (copy == NULL) {
 124                 PyErr_NoMemory();
 125                 return NULL;
 126             }
 127             memcpy(copy, data, width*height*3);
 128             return new wxImage(width, height, copy, false);
 129         }
 130
 131
 132         %rename(ImageFromDataWithAlpha) wxImage(int width, int height, unsigned char* data, unsigned char* alpha);
 133         wxImage(int width, int height, unsigned char* data, unsigned char* alpha)
 134         {
 135             // Copy the source data so the wxImage can clean it up later
 136             unsigned char* dcopy = (unsigned char*)malloc(width*height*3);
 137             if (dcopy == NULL) {
 138                 PyErr_NoMemory();
 139                 return NULL;
 140             }
 141             memcpy(dcopy, data, width*height*3);
 142             unsigned char* acopy = (unsigned char*)malloc(width*height);
 143             if (acopy == NULL) {
 144                 PyErr_NoMemory();
 145                 return NULL;
 146             }
 147             memcpy(acopy, alpha, width*height);
 148
 149             return new wxImage(width, height, dcopy, acopy, false);
 150         }
 151     }
 152
 153     void Create( int width, int height );
 154     void Destroy();
 155
 156     wxImage Scale( int width, int height );
 157     wxImage ShrinkBy( int xFactor , int yFactor ) const ;
 158     wxImage& Rescale(int width, int height);
 159
 160     void SetRGB( int x, int y, unsigned char r, unsigned char g, unsigned char b );
 161     unsigned char GetRed( int x, int y );
 162     unsigned char GetGreen( int x, int y );
 163     unsigned char GetBlue( int x, int y );
 164
 165     void SetAlpha(int x, int y, unsigned char alpha);
 166     unsigned char GetAlpha(int x, int y);
 167     bool HasAlpha();
 168
 169     // find first colour that is not used in the image and has higher
 170     // RGB values than <startR,startG,startB>
 171     DocDeclAStr(
 172         bool, FindFirstUnusedColour( byte *OUTPUT, byte *OUTPUT, byte *OUTPUT,
 173                                      byte startR = 0, byte startG = 0, byte startB = 0 ) const,
 174         "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
 175         "Find first colour that is not used in the image and has higher RGB
 176 values than startR, startG, startB.  Returns a tuple consisting of a
 177 success flag and rgb values.", "");
 178
 179
 180     DocDeclStr(
 181         bool , ConvertAlphaToMask(byte threshold = 128),
 182         "If the image has alpha channel, this method converts it to mask. All pixels
 183 with alpha value less than ``threshold`` are replaced with mask colour and the
 184 alpha channel is removed. Mask colour is chosen automatically using
 185 `FindFirstUnusedColour`.
 186
 187 If the image image doesn't have alpha channel, ConvertAlphaToMask does
 188 nothing.", "");
 189
 190
 191     DocDeclStr(
 192         bool , ConvertColourToAlpha( unsigned char r, unsigned char g, unsigned char b ),
 193         "This method converts an image where the original alpha information is
 194 only available as a shades of a colour (actually shades of grey)
 195 typically when you draw anti-aliased text into a bitmap. The DC
 196 drawing routines draw grey values on the black background although
 197 they actually mean to draw white with differnt alpha values.  This
 198 method reverses it, assuming a black (!) background and white text.
 199 The method will then fill up the whole image with the colour given.", "");
 200
 201
 202
 203     // Set image's mask to the area of 'mask' that has <mr,mg,mb> colour
 204     bool SetMaskFromImage(const wxImage & mask,
 205                           byte mr, byte mg, byte mb);
 206
 207 //      void DoFloodFill (wxCoord x, wxCoord y,
 208 //          const wxBrush & fillBrush,
 209 //          const wxColour& testColour,
 210 //          int style = wxFLOOD_SURFACE,
 211 //          int LogicalFunction = wxCOPY /* currently unused */ ) ;
 212
 213     static bool CanRead( const wxString& name );
 214     static int GetImageCount( const wxString& name, long type = wxBITMAP_TYPE_ANY );
 215
 216     bool LoadFile( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 );
 217     %Rename(LoadMimeFile, bool,  LoadFile( const wxString& name, const wxString& mimetype, int index = -1 ));
 218
 219     bool SaveFile( const wxString& name, int type );
 220     %Rename(SaveMimeFile, bool,  SaveFile( const wxString& name, const wxString& mimetype ));
 221
 222     %Rename(CanReadStream, static bool,  CanRead( wxInputStream& stream ));
 223     %Rename(LoadStream, bool,  LoadFile( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1 ));
 224     %Rename(LoadMimeStream, bool,  LoadFile( wxInputStream& stream, const wxString& mimetype, int index = -1 ));
 225
 226     bool Ok();
 227     int GetWidth();
 228     int GetHeight();
 229
 230     %extend {
 231         wxSize GetSize() {
 232             wxSize size(self->GetWidth(), self->GetHeight());
 233             return size;
 234         }
 235     }
 236
 237     wxImage GetSubImage(const wxRect& rect);
 238     wxImage Copy();
 239     void Paste( const wxImage &image, int x, int y );
 240
 241     //unsigned char *GetData();
 242     //void SetData( unsigned char *data );
 243
 244     %extend {
 245         PyObject* GetData() {
 246             unsigned char* data = self->GetData();
 247             int len = self->GetWidth() * self->GetHeight() * 3;
 248             PyObject* rv;
 249             wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len));
 250             return rv;
 251         }
 252         void SetData(PyObject* data) {
 253             unsigned char* dataPtr;
 254
 255             if (! PyString_Check(data)) {
 256                 wxPyBLOCK_THREADS(PyErr_SetString(PyExc_TypeError,
 257                                                   "Expected string object"));
 258                 return /* NULL */ ;
 259             }
 260
 261             size_t len = self->GetWidth() * self->GetHeight() * 3;
 262             dataPtr = (unsigned char*) malloc(len);
 263             wxPyBLOCK_THREADS( memcpy(dataPtr, PyString_AsString(data), len) );
 264             self->SetData(dataPtr);
 265             // wxImage takes ownership of dataPtr...
 266         }
 267
 268
 269
 270         PyObject* GetDataBuffer() {
 271             unsigned char* data = self->GetData();
 272             int len = self->GetWidth() * self->GetHeight() * 3;
 273             PyObject* rv;
 274             wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
 275             return rv;
 276         }
 277         void SetDataBuffer(PyObject* data) {
 278             unsigned char* buffer;
 279             int size;
 280
 281             bool blocked = wxPyBeginBlockThreads();
 282             if (!PyArg_Parse(data, "t#", &buffer, &size))
 283                 goto done;
 284
 285             if (size != self->GetWidth() * self->GetHeight() * 3) {
 286                 PyErr_SetString(PyExc_TypeError, "Incorrect buffer size");
 287                 goto done;
 288             }
 289             self->SetData(buffer);
 290         done:
 291             wxPyEndBlockThreads(blocked);
 292         }
 293
 294
 295
 296         PyObject* GetAlphaData() {
 297             unsigned char* data = self->GetAlpha();
 298             if (! data) {
 299                 RETURN_NONE();
 300             } else {
 301                 int len = self->GetWidth() * self->GetHeight();
 302                 PyObject* rv;
 303                 wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len) );
 304                 return rv;
 305             }
 306         }
 307         void SetAlphaData(PyObject* data) {
 308             unsigned char* dataPtr;
 309
 310             if (! PyString_Check(data)) {
 311                 PyErr_SetString(PyExc_TypeError, "Expected string object");
 312                 return /* NULL */ ;
 313             }
 314
 315             size_t len = self->GetWidth() * self->GetHeight();
 316             dataPtr = (unsigned char*) malloc(len);
 317             wxPyBLOCK_THREADS( memcpy(dataPtr, PyString_AsString(data), len) );
 318             self->SetAlpha(dataPtr);
 319             // wxImage takes ownership of dataPtr...
 320         }
 321
 322
 323
 324         PyObject* GetAlphaBuffer() {
 325             unsigned char* data = self->GetAlpha();
 326             int len = self->GetWidth() * self->GetHeight();
 327             PyObject* rv;
 328             wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
 329             return rv;
 330         }
 331         void SetAlphaBuffer(PyObject* data) {
 332             unsigned char* buffer;
 333             int size;
 334
 335             bool blocked = wxPyBeginBlockThreads();
 336             if (!PyArg_Parse(data, "t#", &buffer, &size))
 337                 goto done;
 338
 339             if (size != self->GetWidth() * self->GetHeight()) {
 340                 PyErr_SetString(PyExc_TypeError, "Incorrect buffer size");
 341                 goto done;
 342             }
 343             self->SetAlpha(buffer);
 344         done:
 345             wxPyEndBlockThreads(blocked);
 346         }
 347     }
 348
 349     void SetMaskColour( unsigned char r, unsigned char g, unsigned char b );
 350     unsigned char GetMaskRed();
 351     unsigned char GetMaskGreen();
 352     unsigned char GetMaskBlue();
 353     void SetMask( bool mask = true );
 354     bool HasMask();
 355
 356     wxImage Rotate(double angle, const wxPoint & centre_of_rotation,
 357                    bool interpolating = true, wxPoint * offset_after_rotation = NULL) const ;
 358     wxImage Rotate90( bool clockwise = true ) ;
 359     wxImage Mirror( bool horizontally = true ) ;
 360
 361     void Replace( unsigned char r1, unsigned char g1, unsigned char b1,
 362                   unsigned char r2, unsigned char g2, unsigned char b2 );
 363
 364     // convert to monochrome image (<r,g,b> will be replaced by white, everything else by black)
 365     wxImage ConvertToMono( unsigned char r, unsigned char g, unsigned char b ) const;
 366
 367     void SetOption(const wxString& name, const wxString& value);
 368     %Rename(SetOptionInt, void,  SetOption(const wxString& name, int value));
 369     wxString GetOption(const wxString& name) const;
 370     int GetOptionInt(const wxString& name) const;
 371     bool HasOption(const wxString& name) const;
 372
 373     unsigned long CountColours( unsigned long stopafter = (unsigned long) -1 );
 374     unsigned long ComputeHistogram( wxImageHistogram& h );
 375
 376     static void AddHandler( wxImageHandler *handler );
 377     static void InsertHandler( wxImageHandler *handler );
 378     static bool RemoveHandler( const wxString& name );
 379     static wxString GetImageExtWildcard();
 380
 381
 382 MustHaveApp(ConvertToBitmap);
 383 MustHaveApp(ConvertToMonoBitmap);
 384
 385     %extend {
 386         wxBitmap ConvertToBitmap(int depth=-1) {
 387             wxBitmap bitmap(*self, depth);
 388             return bitmap;
 389         }
 390
 391         wxBitmap ConvertToMonoBitmap( unsigned char red,
 392                                       unsigned char green,
 393                                       unsigned char blue ) {
 394             wxImage mono = self->ConvertToMono( red, green, blue );
 395             wxBitmap bitmap( mono, 1 );
 396             return bitmap;
 397         }
 398     }
 399
 400     %pythoncode { def __nonzero__(self): return self.Ok() }
 401 };
 402
 403
 404
 405 ///void wxInitAllImageHandlers();
 406
 407 %pythoncode {
 408     def InitAllImageHandlers():
 409         """
 410         The former functionality of InitAllImageHanders is now done internal to
 411         the _core_ extension module and so this function has become a simple NOP.
 412         """
 413         pass
 414 }
 415
 416
 417
 418 // See also wxPy_ReinitStockObjects in helpers.cpp
 419 %immutable;
 420 const wxImage    wxNullImage;
 421 %mutable;
 422
 423 //---------------------------------------------------------------------------
 424
 425
 426 MAKE_CONST_WXSTRING(IMAGE_OPTION_BMP_FORMAT);
 427 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_X);
 428 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_Y);
 429 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTION);
 430 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONUNIT);
 431
 432 enum
 433 {
 434     wxIMAGE_RESOLUTION_INCHES = 1,
 435     wxIMAGE_RESOLUTION_CM = 2
 436 };
 437
 438
 439 enum
 440 {
 441     wxBMP_24BPP        = 24, // default, do not need to set
 442     //wxBMP_16BPP      = 16, // wxQuantize can only do 236 colors?
 443     wxBMP_8BPP         =  8, // 8bpp, quantized colors
 444     wxBMP_8BPP_GREY    =  9, // 8bpp, rgb averaged to greys
 445     wxBMP_8BPP_GRAY    =  wxBMP_8BPP_GREY,
 446     wxBMP_8BPP_RED     = 10, // 8bpp, red used as greyscale
 447     wxBMP_8BPP_PALETTE = 11, // 8bpp, use the wxImage's palette
 448     wxBMP_4BPP         =  4, // 4bpp, quantized colors
 449     wxBMP_1BPP         =  1, // 1bpp, quantized "colors"
 450     wxBMP_1BPP_BW      =  2  // 1bpp, black & white from red
 451 };
 452
 453
 454 class wxBMPHandler : public wxImageHandler {
 455 public:
 456     wxBMPHandler();
 457 };
 458
 459 class wxICOHandler : public wxBMPHandler {
 460 public:
 461     wxICOHandler();
 462 };
 463
 464 class wxCURHandler : public wxICOHandler {
 465 public:
 466     wxCURHandler();
 467 };
 468
 469 class wxANIHandler : public wxCURHandler {
 470 public:
 471     wxANIHandler();
 472 };
 473
 474
 475 //---------------------------------------------------------------------------
 476
 477 class wxPNGHandler : public wxImageHandler {
 478 public:
 479     wxPNGHandler();
 480 };
 481
 482
 483 class wxGIFHandler : public wxImageHandler {
 484 public:
 485     wxGIFHandler();
 486 };
 487
 488
 489 class wxPCXHandler : public wxImageHandler {
 490 public:
 491     wxPCXHandler();
 492 };
 493
 494
 495 class wxJPEGHandler : public wxImageHandler {
 496 public:
 497     wxJPEGHandler();
 498 };
 499
 500
 501 class wxPNMHandler : public wxImageHandler {
 502 public:
 503     wxPNMHandler();
 504 };
 505
 506 class wxXPMHandler : public wxImageHandler {
 507 public:
 508     wxXPMHandler();
 509 };
 510
 511 class wxTIFFHandler : public wxImageHandler {
 512 public:
 513     wxTIFFHandler();
 514 };
 515
 516
 517 #if wxUSE_IFF
 518 class wxIFFHandler : public wxImageHandler {
 519 public:
 520     wxIFFHandler();
 521 };
 522 #endif
 523
 524 //---------------------------------------------------------------------------
 525
 526 %{
 527 #include <wx/quantize.h>
 528 %}
 529
 530 enum {
 531     wxQUANTIZE_INCLUDE_WINDOWS_COLOURS,
 532 //    wxQUANTIZE_RETURN_8BIT_DATA,
 533     wxQUANTIZE_FILL_DESTINATION_IMAGE
 534 };
 535
 536
 537 DocStr(wxQuantize,
 538        "Performs quantization, or colour reduction, on a wxImage.", "");
 539
 540 class wxQuantize /*: public wxObject */
 541 {
 542 public:
 543
 544     %extend {
 545         DocStr(
 546             Quantize,
 547             "Reduce the colours in the source image and put the result into the
 548 destination image, setting the palette in the destination if
 549 needed. Both images may be the same, to overwrite the source image.", "
 550 :todo: Create a version that returns the wx.Palette used.");
 551
 552         static bool Quantize(const wxImage& src, wxImage& dest, int desiredNoColours = 236,
 553                              int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE)
 554         {
 555                 return wxQuantize::Quantize(src, dest,
 556                                             //NULL, // palette
 557                                             desiredNoColours,
 558                                             NULL, // eightBitData
 559                                             flags);
 560         }
 561     }
 562 };
 563
 564
 565 //---------------------------------------------------------------------------