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