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     // TODO: wxImage( char** xpmData );
 154
 155
 156     void Create( int width, int height );
 157     void Destroy();
 158
 159     wxImage Scale( int width, int height );
 160     wxImage ShrinkBy( int xFactor , int yFactor ) const ;
 161     wxImage& Rescale(int width, int height);
 162
 163     // resizes the image in place
 164     wxImage& Resize( const wxSize& size, const wxPoint& pos,
 165                      int r = -1, int g = -1, int b = -1 );
 166
 167     void SetRGB( int x, int y, unsigned char r, unsigned char g, unsigned char b );
 168
 169     %Rename(SetRGBRect,
 170             void, SetRGB( const wxRect& rect,
 171                           unsigned char r, unsigned char g, unsigned char b ));
 172
 173     unsigned char GetRed( int x, int y );
 174     unsigned char GetGreen( int x, int y );
 175     unsigned char GetBlue( int x, int y );
 176
 177     void SetAlpha(int x, int y, unsigned char alpha);
 178     unsigned char GetAlpha(int x, int y);
 179     bool HasAlpha();
 180
 181     DocDeclStr(
 182         void , InitAlpha(),
 183         "Initializes the image alpha channel data. It is an error to call it if
 184 the image already has alpha data. If it doesn't, alpha data will be by
 185 default initialized to all pixels being fully opaque. But if the image
 186 has a a mask colour, all mask pixels will be completely transparent.", "");
 187
 188
 189     // find first colour that is not used in the image and has higher
 190     // RGB values than <startR,startG,startB>
 191     DocDeclAStr(
 192         bool, FindFirstUnusedColour( byte *OUTPUT, byte *OUTPUT, byte *OUTPUT,
 193                                      byte startR = 0, byte startG = 0, byte startB = 0 ) const,
 194         "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
 195         "Find first colour that is not used in the image and has higher RGB
 196 values than startR, startG, startB.  Returns a tuple consisting of a
 197 success flag and rgb values.", "");
 198
 199
 200     DocDeclStr(
 201         bool , ConvertAlphaToMask(byte threshold = 128),
 202         "If the image has alpha channel, this method converts it to mask. All pixels
 203 with alpha value less than ``threshold`` are replaced with mask colour and the
 204 alpha channel is removed. Mask colour is chosen automatically using
 205 `FindFirstUnusedColour`.
 206
 207 If the image image doesn't have alpha channel, ConvertAlphaToMask does
 208 nothing.", "");
 209
 210
 211     DocDeclStr(
 212         bool , ConvertColourToAlpha( unsigned char r, unsigned char g, unsigned char b ),
 213         "This method converts an image where the original alpha information is
 214 only available as a shades of a colour (actually shades of grey)
 215 typically when you draw anti-aliased text into a bitmap. The DC
 216 drawing routines draw grey values on the black background although
 217 they actually mean to draw white with differnt alpha values.  This
 218 method reverses it, assuming a black (!) background and white text.
 219 The method will then fill up the whole image with the colour given.", "");
 220
 221
 222
 223     // Set image's mask to the area of 'mask' that has <mr,mg,mb> colour
 224     bool SetMaskFromImage(const wxImage & mask,
 225                           byte mr, byte mg, byte mb);
 226
 227 //      void DoFloodFill (wxCoord x, wxCoord y,
 228 //          const wxBrush & fillBrush,
 229 //          const wxColour& testColour,
 230 //          int style = wxFLOOD_SURFACE,
 231 //          int LogicalFunction = wxCOPY /* currently unused */ ) ;
 232
 233     static bool CanRead( const wxString& name );
 234     static int GetImageCount( const wxString& name, long type = wxBITMAP_TYPE_ANY );
 235
 236     bool LoadFile( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 );
 237     %Rename(LoadMimeFile, bool,  LoadFile( const wxString& name, const wxString& mimetype, int index = -1 ));
 238
 239     bool SaveFile( const wxString& name, int type );
 240     %Rename(SaveMimeFile, bool,  SaveFile( const wxString& name, const wxString& mimetype ));
 241
 242     %Rename(CanReadStream, static bool,  CanRead( wxInputStream& stream ));
 243     %Rename(LoadStream, bool,  LoadFile( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1 ));
 244     %Rename(LoadMimeStream, bool,  LoadFile( wxInputStream& stream, const wxString& mimetype, int index = -1 ));
 245
 246     bool Ok();
 247     int GetWidth();
 248     int GetHeight();
 249
 250     %extend {
 251         wxSize GetSize() {
 252             wxSize size(self->GetWidth(), self->GetHeight());
 253             return size;
 254         }
 255     }
 256
 257     wxImage GetSubImage(const wxRect& rect);
 258
 259     // Paste the image or part of this image into an image of the given size at the pos
 260     //  any newly exposed areas will be filled with the rgb colour
 261     //  by default if r = g = b = -1 then fill with this image's mask colour or find and
 262     //  set a suitable mask colour
 263     wxImage Size( const wxSize& size, const wxPoint& pos,
 264                   int r = -1, int g = -1, int b = -1 ) const;
 265
 266     wxImage Copy();
 267     void Paste( const wxImage &image, int x, int y );
 268
 269     //unsigned char *GetData();
 270     //void SetData( unsigned char *data );
 271
 272     %extend {
 273         PyObject* GetData() {
 274             unsigned char* data = self->GetData();
 275             int len = self->GetWidth() * self->GetHeight() * 3;
 276             PyObject* rv;
 277             wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len));
 278             return rv;
 279         }
 280         void SetData(PyObject* data) {
 281             unsigned char* dataPtr;
 282
 283             if (! PyString_Check(data)) {
 284                 wxPyBLOCK_THREADS(PyErr_SetString(PyExc_TypeError,
 285                                                   "Expected string object"));
 286                 return /* NULL */ ;
 287             }
 288
 289             size_t len = self->GetWidth() * self->GetHeight() * 3;
 290             dataPtr = (unsigned char*) malloc(len);
 291             wxPyBLOCK_THREADS( memcpy(dataPtr, PyString_AsString(data), len) );
 292             self->SetData(dataPtr);
 293             // wxImage takes ownership of dataPtr...
 294         }
 295
 296
 297
 298         PyObject* GetDataBuffer() {
 299             unsigned char* data = self->GetData();
 300             int len = self->GetWidth() * self->GetHeight() * 3;
 301             PyObject* rv;
 302             wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
 303             return rv;
 304         }
 305         void SetDataBuffer(PyObject* data) {
 306             unsigned char* buffer;
 307             int size;
 308
 309             wxPyBlock_t blocked = wxPyBeginBlockThreads();
 310             if (!PyArg_Parse(data, "t#", &buffer, &size))
 311                 goto done;
 312
 313             if (size != self->GetWidth() * self->GetHeight() * 3) {
 314                 PyErr_SetString(PyExc_TypeError, "Incorrect buffer size");
 315                 goto done;
 316             }
 317             self->SetData(buffer);
 318         done:
 319             wxPyEndBlockThreads(blocked);
 320         }
 321
 322
 323
 324         PyObject* GetAlphaData() {
 325             unsigned char* data = self->GetAlpha();
 326             if (! data) {
 327                 RETURN_NONE();
 328             } else {
 329                 int len = self->GetWidth() * self->GetHeight();
 330                 PyObject* rv;
 331                 wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len) );
 332                 return rv;
 333             }
 334         }
 335         void SetAlphaData(PyObject* data) {
 336             unsigned char* dataPtr;
 337
 338             if (! PyString_Check(data)) {
 339                 PyErr_SetString(PyExc_TypeError, "Expected string object");
 340                 return /* NULL */ ;
 341             }
 342
 343             size_t len = self->GetWidth() * self->GetHeight();
 344             dataPtr = (unsigned char*) malloc(len);
 345             wxPyBLOCK_THREADS( memcpy(dataPtr, PyString_AsString(data), len) );
 346             self->SetAlpha(dataPtr);
 347             // wxImage takes ownership of dataPtr...
 348         }
 349
 350
 351
 352         PyObject* GetAlphaBuffer() {
 353             unsigned char* data = self->GetAlpha();
 354             int len = self->GetWidth() * self->GetHeight();
 355             PyObject* rv;
 356             wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
 357             return rv;
 358         }
 359         void SetAlphaBuffer(PyObject* data) {
 360             unsigned char* buffer;
 361             int size;
 362
 363             wxPyBlock_t blocked = wxPyBeginBlockThreads();
 364             if (!PyArg_Parse(data, "t#", &buffer, &size))
 365                 goto done;
 366
 367             if (size != self->GetWidth() * self->GetHeight()) {
 368                 PyErr_SetString(PyExc_TypeError, "Incorrect buffer size");
 369                 goto done;
 370             }
 371             self->SetAlpha(buffer);
 372         done:
 373             wxPyEndBlockThreads(blocked);
 374         }
 375     }
 376
 377     void SetMaskColour( unsigned char r, unsigned char g, unsigned char b );
 378
 379     DocDeclAStr(
 380         /*bool*/ void , GetOrFindMaskColour( unsigned char *OUTPUT,
 381                                              unsigned char *OUTPUT,
 382                                              unsigned char *OUTPUT ) const,
 383         "GetOrFindMaskColour() -> (r,g,b)",
 384         "Get the current mask colour or find a suitable colour.", "");
 385
 386
 387     unsigned char GetMaskRed();
 388     unsigned char GetMaskGreen();
 389     unsigned char GetMaskBlue();
 390     void SetMask( bool mask = true );
 391     bool HasMask();
 392
 393     wxImage Rotate(double angle, const wxPoint & centre_of_rotation,
 394                    bool interpolating = true, wxPoint * offset_after_rotation = NULL) const ;
 395     wxImage Rotate90( bool clockwise = true ) ;
 396     wxImage Mirror( bool horizontally = true ) ;
 397
 398     void Replace( unsigned char r1, unsigned char g1, unsigned char b1,
 399                   unsigned char r2, unsigned char g2, unsigned char b2 );
 400
 401     // convert to monochrome image (<r,g,b> will be replaced by white, everything else by black)
 402     wxImage ConvertToMono( unsigned char r, unsigned char g, unsigned char b ) const;
 403
 404     void SetOption(const wxString& name, const wxString& value);
 405     %Rename(SetOptionInt, void,  SetOption(const wxString& name, int value));
 406     wxString GetOption(const wxString& name) const;
 407     int GetOptionInt(const wxString& name) const;
 408     bool HasOption(const wxString& name) const;
 409
 410     unsigned long CountColours( unsigned long stopafter = (unsigned long) -1 );
 411     unsigned long ComputeHistogram( wxImageHistogram& h );
 412
 413     static void AddHandler( wxImageHandler *handler );
 414     static void InsertHandler( wxImageHandler *handler );
 415     static bool RemoveHandler( const wxString& name );
 416     static wxString GetImageExtWildcard();
 417
 418
 419 MustHaveApp(ConvertToBitmap);
 420 MustHaveApp(ConvertToMonoBitmap);
 421
 422     %extend {
 423         wxBitmap ConvertToBitmap(int depth=-1) {
 424             wxBitmap bitmap(*self, depth);
 425             return bitmap;
 426         }
 427
 428         wxBitmap ConvertToMonoBitmap( unsigned char red,
 429                                       unsigned char green,
 430                                       unsigned char blue ) {
 431             wxImage mono = self->ConvertToMono( red, green, blue );
 432             wxBitmap bitmap( mono, 1 );
 433             return bitmap;
 434         }
 435     }
 436
 437     %pythoncode { def __nonzero__(self): return self.Ok() }
 438 };
 439
 440
 441
 442 ///void wxInitAllImageHandlers();
 443
 444 %pythoncode {
 445     def InitAllImageHandlers():
 446         """
 447         The former functionality of InitAllImageHanders is now done internal to
 448         the _core_ extension module and so this function has become a simple NOP.
 449         """
 450         pass
 451 }
 452
 453
 454
 455 // See also wxPy_ReinitStockObjects in helpers.cpp
 456 %immutable;
 457 const wxImage    wxNullImage;
 458 %mutable;
 459
 460 //---------------------------------------------------------------------------
 461
 462 MAKE_CONST_WXSTRING(IMAGE_OPTION_FILENAME);
 463 MAKE_CONST_WXSTRING(IMAGE_OPTION_BMP_FORMAT);
 464 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_X);
 465 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_Y);
 466 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTION);
 467 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONX);
 468 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONY);
 469 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONUNIT);
 470 MAKE_CONST_WXSTRING(IMAGE_OPTION_QUALITY);
 471
 472 enum
 473 {
 474     wxIMAGE_RESOLUTION_INCHES = 1,
 475     wxIMAGE_RESOLUTION_CM = 2
 476 };
 477
 478
 479 MAKE_CONST_WXSTRING(IMAGE_OPTION_BITSPERSAMPLE);
 480 MAKE_CONST_WXSTRING(IMAGE_OPTION_SAMPLESPERPIXEL);
 481 MAKE_CONST_WXSTRING(IMAGE_OPTION_COMPRESSION);
 482 MAKE_CONST_WXSTRING(IMAGE_OPTION_IMAGEDESCRIPTOR);
 483
 484 MAKE_CONST_WXSTRING(IMAGE_OPTION_PNG_FORMAT);
 485 MAKE_CONST_WXSTRING(IMAGE_OPTION_PNG_BITDEPTH);
 486
 487 enum
 488 {
 489     wxPNG_TYPE_COLOUR = 0,
 490     wxPNG_TYPE_GREY = 2,
 491     wxPNG_TYPE_GREY_RED = 3
 492 };
 493
 494 enum
 495 {
 496     wxBMP_24BPP        = 24, // default, do not need to set
 497     //wxBMP_16BPP      = 16, // wxQuantize can only do 236 colors?
 498     wxBMP_8BPP         =  8, // 8bpp, quantized colors
 499     wxBMP_8BPP_GREY    =  9, // 8bpp, rgb averaged to greys
 500     wxBMP_8BPP_GRAY    =  wxBMP_8BPP_GREY,
 501     wxBMP_8BPP_RED     = 10, // 8bpp, red used as greyscale
 502     wxBMP_8BPP_PALETTE = 11, // 8bpp, use the wxImage's palette
 503     wxBMP_4BPP         =  4, // 4bpp, quantized colors
 504     wxBMP_1BPP         =  1, // 1bpp, quantized "colors"
 505     wxBMP_1BPP_BW      =  2  // 1bpp, black & white from red
 506 };
 507
 508
 509 class wxBMPHandler : public wxImageHandler {
 510 public:
 511     wxBMPHandler();
 512 };
 513
 514 class wxICOHandler : public wxBMPHandler {
 515 public:
 516     wxICOHandler();
 517 };
 518
 519 class wxCURHandler : public wxICOHandler {
 520 public:
 521     wxCURHandler();
 522 };
 523
 524 class wxANIHandler : public wxCURHandler {
 525 public:
 526     wxANIHandler();
 527 };
 528
 529
 530 //---------------------------------------------------------------------------
 531
 532 class wxPNGHandler : public wxImageHandler {
 533 public:
 534     wxPNGHandler();
 535 };
 536
 537
 538 class wxGIFHandler : public wxImageHandler {
 539 public:
 540     wxGIFHandler();
 541 };
 542
 543
 544 class wxPCXHandler : public wxImageHandler {
 545 public:
 546     wxPCXHandler();
 547 };
 548
 549
 550 class wxJPEGHandler : public wxImageHandler {
 551 public:
 552     wxJPEGHandler();
 553 };
 554
 555
 556 class wxPNMHandler : public wxImageHandler {
 557 public:
 558     wxPNMHandler();
 559 };
 560
 561 class wxXPMHandler : public wxImageHandler {
 562 public:
 563     wxXPMHandler();
 564 };
 565
 566 class wxTIFFHandler : public wxImageHandler {
 567 public:
 568     wxTIFFHandler();
 569 };
 570
 571
 572 #if wxUSE_IFF
 573 class wxIFFHandler : public wxImageHandler {
 574 public:
 575     wxIFFHandler();
 576 };
 577 #endif
 578
 579 //---------------------------------------------------------------------------
 580
 581 %{
 582 #include <wx/quantize.h>
 583 %}
 584
 585 enum {
 586     wxQUANTIZE_INCLUDE_WINDOWS_COLOURS,
 587 //    wxQUANTIZE_RETURN_8BIT_DATA,
 588     wxQUANTIZE_FILL_DESTINATION_IMAGE
 589 };
 590
 591
 592 DocStr(wxQuantize,
 593        "Performs quantization, or colour reduction, on a wxImage.", "");
 594
 595 class wxQuantize /*: public wxObject */
 596 {
 597 public:
 598
 599     %extend {
 600         DocStr(
 601             Quantize,
 602             "Reduce the colours in the source image and put the result into the
 603 destination image, setting the palette in the destination if
 604 needed. Both images may be the same, to overwrite the source image.", "
 605 :todo: Create a version that returns the wx.Palette used.");
 606
 607         static bool Quantize(const wxImage& src, wxImage& dest, int desiredNoColours = 236,
 608                              int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE)
 609         {
 610                 return wxQuantize::Quantize(src, dest,
 611                                             //NULL, // palette
 612                                             desiredNoColours,
 613                                             NULL, // eightBitData
 614                                             flags);
 615         }
 616     }
 617 };
 618
 619
 620 //---------------------------------------------------------------------------