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