]> git.saurik.com Git - wxWidgets.git/blob - wxPython/src/_image.i
docstring update
[wxWidgets.git] / 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
50 bool CanRead( const wxString& name );
51 %Rename(CanReadStream, bool, CanRead( wxInputStream& stream ));
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 %property(Extension, GetExtension, SetExtension, doc="See `GetExtension` and `SetExtension`");
59 %property(MimeType, GetMimeType, SetMimeType, doc="See `GetMimeType` and `SetMimeType`");
60 %property(Name, GetName, SetName, doc="See `GetName` and `SetName`");
61 %property(Type, GetType, SetType, doc="See `GetType` and `SetType`");
62 };
63
64
65 //---------------------------------------------------------------------------
66
67
68 DocStr(wxPyImageHandler,
69 "This is the base class for implementing image file loading/saving, and
70 image creation from data, all written in Python. To create a custom
71 image handler derive a new class from wx.PyImageHandler and provide
72 the following methods::
73
74 def DoCanRead(self, stream) --> bool
75 '''Check if this handler can read the image on the stream'''
76
77 def LoadFile(self, image, stream, verbose, index) --> bool
78 '''Load image data from the stream and load it into image.'''
79
80 def SaveFile(self, image, stream, verbose) --> bool
81 '''Save the iamge data in image to the stream using
82 this handler's image file format.'''
83
84 def GetImageCount(self, stream) --> int
85 '''If this image format can hold more than one image,
86 how many does the image on the stream have?'''
87
88 To activate your handler create an instance of it and pass it to
89 `wx.Image_AddHandler`. Be sure to call `SetName`, `SetType`, and
90 `SetExtension` from your constructor.
91 ", "");
92
93 class wxPyImageHandler: public wxImageHandler {
94 public:
95 %pythonAppend wxPyImageHandler() "self._SetSelf(self)"
96 wxPyImageHandler();
97 void _SetSelf(PyObject *self);
98 };
99
100
101 //---------------------------------------------------------------------------
102
103
104 class wxImageHistogram /* : public wxImageHistogramBase */
105 {
106 public:
107 wxImageHistogram();
108
109 DocStr(MakeKey, "Get the key in the histogram for the given RGB values", "");
110 static unsigned long MakeKey(byte r,
111 byte g,
112 byte b);
113
114 DocDeclAStr(
115 bool, FindFirstUnusedColour(byte *OUTPUT,
116 byte *OUTPUT,
117 byte *OUTPUT,
118 byte startR = 1,
119 byte startG = 0,
120 byte startB = 0 ) const,
121 "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
122 "Find first colour that is not used in the image and has higher RGB
123 values than startR, startG, startB. Returns a tuple consisting of a
124 success flag and rgb values.", "");
125
126 %extend {
127 DocStr(GetCount,
128 "Returns the pixel count for the given key. Use `MakeKey` to create a
129 key value from a RGB tripple.", "");
130 unsigned long GetCount(unsigned long key) {
131 wxImageHistogramEntry e = (*self)[key];
132 return e.value;
133 }
134
135 DocStr(GetCountRGB,
136 "Returns the pixel count for the given RGB values.", "");
137 unsigned long GetCountRGB(byte r,
138 byte g,
139 byte b) {
140 unsigned long key = wxImageHistogram::MakeKey(r, g, b);
141 wxImageHistogramEntry e = (*self)[key];
142 return e.value;
143 }
144
145 DocStr(GetCountColour,
146 "Returns the pixel count for the given `wx.Colour` value.", "");
147 unsigned long GetCountColour(const wxColour& colour) {
148 unsigned long key = wxImageHistogram::MakeKey(colour.Red(),
149 colour.Green(),
150 colour.Blue());
151 wxImageHistogramEntry e = (*self)[key];
152 return e.value;
153 }
154 }
155
156 };
157
158
159 //---------------------------------------------------------------------------
160
161 DocStr(wxImage,
162 "A platform-independent image class. An image can be created from
163 data, or using `wx.Bitmap.ConvertToImage`, or loaded from a file in a
164 variety of formats. Functions are available to set and get image
165 bits, so it can be used for basic image manipulation.
166
167 A wx.Image cannot be drawn directly to a `wx.DC`. Instead, a
168 platform-specific `wx.Bitmap` object must be created from it using the
169 `wx.BitmapFromImage` constructor. This bitmap can then be drawn in a
170 device context, using `wx.DC.DrawBitmap`.
171
172 One colour value of the image may be used as a mask colour which will
173 lead to the automatic creation of a `wx.Mask` object associated to the
174 bitmap object.
175
176 wx.Image supports alpha channel data, that is in addition to a byte
177 for the red, green and blue colour components for each pixel it also
178 stores a byte representing the pixel opacity. An alpha value of 0
179 corresponds to a transparent pixel (null opacity) while a value of 255
180 means that the pixel is 100% opaque.
181
182 Unlike RGB data, not all images have an alpha channel and before using
183 `GetAlpha` you should check if this image contains an alpha channel
184 with `HasAlpha`. Note that currently only images loaded from PNG files
185 with transparency information will have an alpha channel.", "");
186
187
188 %{
189 // Pull the nested class out to the top level for SWIG's sake
190 #define wxImage_RGBValue wxImage::RGBValue
191 #define wxImage_HSVValue wxImage::HSVValue
192 %}
193
194 DocStr(wxImage_RGBValue,
195 "An object that contains values for red, green and blue which represent
196 the value of a color. It is used by `wx.Image.HSVtoRGB` and
197 `wx.Image.RGBtoHSV`, which converts between HSV color space and RGB
198 color space.", "");
199 class wxImage_RGBValue
200 {
201 public:
202 DocCtorStr(
203 wxImage_RGBValue(byte r=0, byte g=0, byte b=0),
204 "Constructor.", "");
205 byte red;
206 byte green;
207 byte blue;
208 };
209
210
211 DocStr(wxImage_HSVValue,
212 "An object that contains values for hue, saturation and value which
213 represent the value of a color. It is used by `wx.Image.HSVtoRGB` and
214 `wx.Image.RGBtoHSV`, which +converts between HSV color space and RGB
215 color space.", "");
216 class wxImage_HSVValue
217 {
218 public:
219 DocCtorStr(
220 wxImage_HSVValue(double h=0.0, double s=0.0, double v=0.0),
221 "Constructor.", "");
222 double hue;
223 double saturation;
224 double value;
225 };
226
227
228 class wxImage : public wxObject {
229 public:
230 %typemap(out) wxImage*; // turn off this typemap
231
232 DocCtorStr(
233 wxImage( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
234 "Loads an image from a file.",
235 "
236 :param name: Name of the file from which to load the image.
237
238 :param type: May be one of the following:
239
240 ==================== =======================================
241 wx.BITMAP_TYPE_BMP Load a Windows bitmap file.
242 wx.BITMAP_TYPE_GIF Load a GIF bitmap file.
243 wx.BITMAP_TYPE_JPEG Load a JPEG bitmap file.
244 wx.BITMAP_TYPE_PNG Load a PNG bitmap file.
245 wx.BITMAP_TYPE_PCX Load a PCX bitmap file.
246 wx.BITMAP_TYPE_PNM Load a PNM bitmap file.
247 wx.BITMAP_TYPE_TIF Load a TIFF bitmap file.
248 wx.BITMAP_TYPE_XPM Load a XPM bitmap file.
249 wx.BITMAP_TYPE_ICO Load a Windows icon file (ICO).
250 wx.BITMAP_TYPE_CUR Load a Windows cursor file (CUR).
251 wx.BITMAP_TYPE_ANI Load a Windows animated cursor file (ANI).
252 wx.BITMAP_TYPE_ANY Will try to autodetect the format.
253 ==================== =======================================
254
255 :param index: Index of the image to load in the case that the
256 image file contains multiple images. This is only used by GIF,
257 ICO and TIFF handlers. The default value (-1) means to choose
258 the default image and is interpreted as the first image (the
259 one with index=0) by the GIF and TIFF handler and as the
260 largest and most colourful one by the ICO handler.
261
262 :see: `wx.ImageFromMime`, `wx.ImageFromStream`, `wx.ImageFromStreamMime`,
263 `wx.EmptyImage`, `wx.ImageFromBitmap`, `wx.ImageFromBuffer`,
264 `wx.ImageFromData`, `wx.ImageFromDataWithAlpha`
265 ");
266
267 ~wxImage();
268
269 // Alternate constructors
270 DocCtorStrName(
271 wxImage(const wxString& name, const wxString& mimetype, int index = -1),
272 "Loads an image from a file, using a MIME type string (such as
273 'image/jpeg') to specify image type.", "
274
275 :see: `wx.Image`",
276 ImageFromMime);
277
278 DocCtorStrName(
279 wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1),
280 "Loads an image from an input stream, or any readable Python file-like
281 object.", "
282
283 :see: `wx.Image`",
284 ImageFromStream);
285
286 DocCtorStrName(
287 wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1 ),
288 "Loads an image from an input stream, or any readable Python file-like
289 object, specifying the image format with a MIME type string.", "
290
291 :see: `wx.Image`",
292 ImageFromStreamMime);
293
294 %extend {
295 %RenameDocCtor(
296 EmptyImage,
297 "Construct an empty image of a given size, optionally setting all
298 pixels to black.", "
299
300 :see: `wx.Image`",
301 wxImage(int width=0, int height=0, bool clear = true))
302 {
303 if (width > 0 && height > 0)
304 return new wxImage(width, height, clear);
305 else
306 return new wxImage;
307 }
308
309
310 MustHaveApp(wxImage(const wxBitmap &bitmap));
311
312 %RenameDocCtor(
313 ImageFromBitmap,
314 "Construct an Image from a `wx.Bitmap`.", "
315
316 :see: `wx.Image`",
317 wxImage(const wxBitmap &bitmap))
318 {
319 return new wxImage(bitmap.ConvertToImage());
320 }
321
322 %RenameDocCtor(
323 ImageFromData,
324 "Construct an Image from a buffer of RGB bytes. Accepts either a
325 string or a buffer object holding the data and the length of the data
326 must be width*height*3.", "
327
328 :see: `wx.Image`",
329 wxImage(int width, int height, buffer data, int DATASIZE))
330 {
331 if (DATASIZE != width*height*3) {
332 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
333 return NULL;
334 }
335
336 // Copy the source data so the wxImage can clean it up later
337 buffer copy = (buffer)malloc(DATASIZE);
338 if (copy == NULL) {
339 wxPyBLOCK_THREADS(PyErr_NoMemory());
340 return NULL;
341 }
342 memcpy(copy, data, DATASIZE);
343 return new wxImage(width, height, copy, false);
344 }
345
346
347 %RenameDocCtor(
348 ImageFromDataWithAlpha,
349 "Construct an Image from a buffer of RGB bytes with an Alpha channel.
350 Accepts either a string or a buffer object holding the data and the
351 length of the data must be width*height*3 bytes, and the length of the
352 alpha data must be width*height bytes.", "
353
354 :see: `wx.Image`",
355 wxImage(int width, int height, buffer data, int DATASIZE, buffer alpha, int ALPHASIZE))
356 {
357 if (DATASIZE != width*height*3) {
358 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
359 return NULL;
360 }
361 if (ALPHASIZE != width*height) {
362 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
363 return NULL;
364 }
365
366 // Copy the source data so the wxImage can clean it up later
367 buffer dcopy = (buffer)malloc(DATASIZE);
368 if (dcopy == NULL) {
369 wxPyBLOCK_THREADS(PyErr_NoMemory());
370 return NULL;
371 }
372 memcpy(dcopy, data, DATASIZE);
373
374 buffer acopy = (buffer)malloc(ALPHASIZE);
375 if (acopy == NULL) {
376 wxPyBLOCK_THREADS(PyErr_NoMemory());
377 return NULL;
378 }
379 memcpy(acopy, alpha, ALPHASIZE);
380
381 return new wxImage(width, height, dcopy, acopy, false);
382 }
383 }
384
385 // TODO: wxImage( char** xpmData );
386
387 // Turn the typemap back on again
388 %typemap(out) wxImage* { $result = wxPyMake_wxObject($1, $owner); }
389
390
391 DocDeclStr(
392 void , Create( int width, int height, bool clear=true ),
393 "Creates a fresh image. If clear is ``True``, the new image will be
394 initialized to black. Otherwise, the image data will be uninitialized.", "");
395
396 DocDeclStr(
397 void , Destroy(),
398 "Destroys the image data.", "");
399
400
401 DocDeclStr(
402 wxImage , Scale( int width, int height ),
403 "Returns a scaled version of the image. This is also useful for scaling
404 bitmaps in general as the only other way to scale bitmaps is to blit a
405 `wx.MemoryDC` into another `wx.MemoryDC`.", "
406
407 :see: `Rescale`");
408
409 DocDeclStr(
410 wxImage , ShrinkBy( int xFactor , int yFactor ) const ,
411 "Return a version of the image scaled smaller by the given factors.", "");
412
413 DocDeclStr(
414 wxImage& , Rescale(int width, int height),
415 "Changes the size of the image in-place by scaling it: after a call to
416 this function, the image will have the given width and height.
417
418 Returns the (modified) image itself.", "
419
420 :see: `Scale`");
421
422
423 // resizes the image in place
424 DocDeclStr(
425 wxImage& , Resize( const wxSize& size, const wxPoint& pos,
426 int r = -1, int g = -1, int b = -1 ),
427 "Changes the size of the image in-place without scaling it, by adding
428 either a border with the given colour or cropping as necessary. The
429 image is pasted into a new image with the given size and background
430 colour at the position pos relative to the upper left of the new
431 image. If red = green = blue = -1 then use either the current mask
432 colour if set or find, use, and set a suitable mask colour for any
433 newly exposed areas.
434
435 Returns the (modified) image itself.", "
436
437 :see: `Size`");
438
439
440 DocDeclStr(
441 void , SetRGB( int x, int y, byte r, byte g, byte b ),
442 "Sets the pixel at the given coordinate. This routine performs
443 bounds-checks for the coordinate so it can be considered a safe way to
444 manipulate the data, but in some cases this might be too slow so that
445 the data will have to be set directly. In that case you will have to
446 get access to the image data using the `GetData` method.", "");
447
448
449 DocDeclStrName(
450 void, SetRGB( const wxRect& rect,
451 byte r, byte g, byte b ),
452 "Sets the colour of the pixels within the given rectangle. This routine
453 performs bounds-checks for the rectangle so it can be considered a
454 safe way to manipulate the data.", "",
455 SetRGBRect);
456
457 DocDeclStr(
458 byte , GetRed( int x, int y ),
459 "Returns the red intensity at the given coordinate.", "");
460
461 DocDeclStr(
462 byte , GetGreen( int x, int y ),
463 "Returns the green intensity at the given coordinate.", "");
464
465 DocDeclStr(
466 byte , GetBlue( int x, int y ),
467 "Returns the blue intensity at the given coordinate.", "");
468
469
470 DocDeclStr(
471 void , SetAlpha(int x, int y, byte alpha),
472 "Sets the alpha value for the given pixel. This function should only be
473 called if the image has alpha channel data, use `HasAlpha` to check
474 for this.", "");
475
476 DocDeclStr(
477 byte , GetAlpha(int x, int y),
478 "Returns the alpha value for the given pixel. This function may only be
479 called for the images with alpha channel, use `HasAlpha` to check for
480 this.
481
482 The returned value is the *opacity* of the image, i.e. the value of 0
483 corresponds to the fully transparent pixels while the value of 255 to
484 the fully opaque pixels.", "");
485
486 DocDeclStr(
487 bool , HasAlpha(),
488 "Returns true if this image has alpha channel, false otherwise.", "
489
490 :see: `GetAlpha`, `SetAlpha`");
491
492
493 DocDeclStr(
494 void , InitAlpha(),
495 "Initializes the image alpha channel data. It is an error to call it if
496 the image already has alpha data. If it doesn't, alpha data will be by
497 default initialized to all pixels being fully opaque. But if the image
498 has a a mask colour, all mask pixels will be completely transparent.", "");
499
500
501 DocDeclStr(
502 bool , IsTransparent(int x, int y,
503 byte threshold = wxIMAGE_ALPHA_THRESHOLD) const,
504 "Returns ``True`` if this pixel is masked or has an alpha value less
505 than the spcified threshold.", "");
506
507
508 // find first colour that is not used in the image and has higher
509 // RGB values than <startR,startG,startB>
510 DocDeclAStr(
511 bool, FindFirstUnusedColour( byte *OUTPUT, byte *OUTPUT, byte *OUTPUT,
512 byte startR = 0, byte startG = 0, byte startB = 0 ) const,
513 "FindFirstUnusedColour(int startR=1, int startG=0, int startB=0) -> (success, r, g, b)",
514 "Find first colour that is not used in the image and has higher RGB
515 values than startR, startG, startB. Returns a tuple consisting of a
516 success flag and rgb values.", "");
517
518
519 DocDeclStr(
520 bool , ConvertAlphaToMask(byte threshold = wxIMAGE_ALPHA_THRESHOLD),
521 "If the image has alpha channel, this method converts it to mask. All
522 pixels with alpha value less than ``threshold`` are replaced with the
523 mask colour and the alpha channel is removed. The mask colour is
524 chosen automatically using `FindFirstUnusedColour`.
525
526 If the image image doesn't have alpha channel, ConvertAlphaToMask does
527 nothing.", "");
528
529
530 DocDeclStr(
531 bool , ConvertColourToAlpha( byte r, byte g, byte b ),
532 "This method converts an image where the original alpha information is
533 only available as a shades of a colour (actually shades of grey)
534 typically when you draw anti-aliased text into a bitmap. The DC
535 drawing routines draw grey values on the black background although
536 they actually mean to draw white with differnt alpha values. This
537 method reverses it, assuming a black (!) background and white text.
538 The method will then fill up the whole image with the colour given.", "");
539
540
541
542 DocDeclStr(
543 bool , SetMaskFromImage(const wxImage & mask,
544 byte mr, byte mg, byte mb),
545 "Sets the image's mask so that the pixels that have RGB value of
546 ``(mr,mg,mb)`` in ``mask`` will be masked in this image. This is done
547 by first finding an unused colour in the image, setting this colour as
548 the mask colour and then using this colour to draw all pixels in the
549 image who corresponding pixel in mask has given RGB value.
550
551 Returns ``False`` if ``mask`` does not have same dimensions as the
552 image or if there is no unused colour left. Returns ``True`` if the
553 mask was successfully applied.
554
555 Note that this method involves computing the histogram, which is
556 computationally intensive operation.", "");
557
558
559 // void DoFloodFill (wxCoord x, wxCoord y,
560 // const wxBrush & fillBrush,
561 // const wxColour& testColour,
562 // int style = wxFLOOD_SURFACE,
563 // int LogicalFunction = wxCOPY /* currently unused */ ) ;
564
565 DocDeclStr(
566 static bool , CanRead( const wxString& filename ),
567 "Returns True if the image handlers can read this file.", "");
568
569 DocDeclStr(
570 static int , GetImageCount( const wxString& filename, long type = wxBITMAP_TYPE_ANY ),
571 "If the image file contains more than one image and the image handler
572 is capable of retrieving these individually, this function will return
573 the number of available images.", "");
574
575
576 DocDeclStr(
577 bool , LoadFile( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
578 "Loads an image from a file. If no handler type is provided, the
579 library will try to autodetect the format.", "");
580
581 DocDeclStrName(
582 bool , LoadFile( const wxString& name, const wxString& mimetype, int index = -1 ),
583 "Loads an image from a file, specifying the image type with a MIME type
584 string.", "",
585 LoadMimeFile);
586
587
588 DocDeclStr(
589 bool , SaveFile( const wxString& name, int type ),
590 "Saves an image in the named file.", "");
591
592
593 DocDeclStrName(
594 bool , SaveFile( const wxString& name, const wxString& mimetype ),
595 "Saves an image in the named file.", "",
596 SaveMimeFile);
597
598
599 DocDeclStrName(
600 static bool , CanRead( wxInputStream& stream ),
601 "Returns True if the image handlers can read an image file from the
602 data currently on the input stream, or a readable Python file-like
603 object.", "",
604 CanReadStream);
605
606
607 DocDeclStrName(
608 bool , LoadFile( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1 ),
609 "Loads an image from an input stream or a readable Python file-like
610 object. If no handler type is provided, the library will try to
611 autodetect the format.", "",
612 LoadStream);
613
614
615 DocDeclStrName(
616 bool , LoadFile( wxInputStream& stream, const wxString& mimetype, int index = -1 ),
617 "Loads an image from an input stream or a readable Python file-like
618 object, using a MIME type string to specify the image file format.", "",
619 LoadMimeStream);
620
621
622 DocDeclStr(
623 bool , Ok(),
624 "Returns true if image data is present.", "");
625
626 DocDeclStr(
627 int , GetWidth(),
628 "Gets the width of the image in pixels.", "");
629
630 DocDeclStr(
631 int , GetHeight(),
632 "Gets the height of the image in pixels.", "");
633
634
635 %extend {
636 DocStr(GetSize,
637 "Returns the size of the image in pixels.", "");
638 wxSize GetSize() {
639 wxSize size(self->GetWidth(), self->GetHeight());
640 return size;
641 }
642 }
643
644
645 DocDeclStr(
646 wxImage , GetSubImage(const wxRect& rect),
647 "Returns a sub image of the current one as long as the rect belongs
648 entirely to the image.", "");
649
650
651 DocDeclStr(
652 wxImage , Size( const wxSize& size, const wxPoint& pos,
653 int r = -1, int g = -1, int b = -1 ) const,
654 "Returns a resized version of this image without scaling it by adding
655 either a border with the given colour or cropping as necessary. The
656 image is pasted into a new image with the given size and background
657 colour at the position ``pos`` relative to the upper left of the new
658 image. If red = green = blue = -1 then use either the current mask
659 colour if set or find, use, and set a suitable mask colour for any
660 newly exposed areas.", "
661
662 :see: `Resize`");
663
664
665 DocDeclStr(
666 wxImage , Copy(),
667 "Returns an identical copy of the image.", "");
668
669 DocDeclStr(
670 void , Paste( const wxImage &image, int x, int y ),
671 "Pastes ``image`` into this instance and takes care of the mask colour
672 and any out of bounds problems.", "");
673
674
675 //unsigned char *GetData();
676 //void SetData( unsigned char *data );
677
678 %extend {
679 DocStr(GetData,
680 "Returns a string containing a copy of the RGB bytes of the image.", "");
681 PyObject* GetData()
682 {
683 buffer data = self->GetData();
684 int len = self->GetWidth() * self->GetHeight() * 3;
685 PyObject* rv;
686 wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len));
687 return rv;
688 }
689 DocStr(SetData,
690 "Resets the Image's RGB data from a buffer of RGB bytes. Accepts
691 either a string or a buffer object holding the data and the length of
692 the data must be width*height*3.", "");
693 void SetData(buffer data, int DATASIZE)
694 {
695 if (DATASIZE != self->GetWidth() * self->GetHeight() * 3) {
696 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
697 return;
698 }
699 buffer copy = (buffer)malloc(DATASIZE);
700 if (copy == NULL) {
701 wxPyBLOCK_THREADS(PyErr_NoMemory());
702 return;
703 }
704 memcpy(copy, data, DATASIZE);
705 self->SetData(copy, false);
706 // wxImage takes ownership of copy...
707 }
708
709
710 DocStr(GetDataBuffer,
711 "Returns a writable Python buffer object that is pointing at the RGB
712 image data buffer inside the wx.Image. You need to ensure that you do
713 not use this buffer object after the image has been destroyed.", "");
714 PyObject* GetDataBuffer()
715 {
716 buffer data = self->GetData();
717 int len = self->GetWidth() * self->GetHeight() * 3;
718 PyObject* rv;
719 wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
720 return rv;
721 }
722
723 DocStr(SetDataBuffer,
724 "Sets the internal image data pointer to point at a Python buffer
725 object. This can save making an extra copy of the data but you must
726 ensure that the buffer object lives longer than the wx.Image does.", "");
727 void SetDataBuffer(buffer data, int DATASIZE)
728 {
729 if (DATASIZE != self->GetWidth() * self->GetHeight() * 3) {
730 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
731 return;
732 }
733 self->SetData(data, true);
734 }
735
736
737
738 DocStr(GetAlphaData,
739 "Returns a string containing a copy of the alpha bytes of the image.", "");
740 PyObject* GetAlphaData() {
741 buffer data = self->GetAlpha();
742 if (! data) {
743 RETURN_NONE();
744 } else {
745 int len = self->GetWidth() * self->GetHeight();
746 PyObject* rv;
747 wxPyBLOCK_THREADS( rv = PyString_FromStringAndSize((char*)data, len) );
748 return rv;
749 }
750 }
751
752 DocStr(SetAlphaData,
753 "Resets the Image's alpha data from a buffer of bytes. Accepts either
754 a string or a buffer object holding the data and the length of the
755 data must be width*height.", "");
756 void SetAlphaData(buffer alpha, int ALPHASIZE)
757 {
758 if (ALPHASIZE != self->GetWidth() * self->GetHeight()) {
759 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
760 return;
761 }
762 buffer acopy = (buffer)malloc(ALPHASIZE);
763 if (acopy == NULL) {
764 wxPyBLOCK_THREADS(PyErr_NoMemory());
765 return;
766 }
767 memcpy(acopy, alpha, ALPHASIZE);
768 self->SetAlpha(acopy, false);
769 // wxImage takes ownership of acopy...
770 }
771
772
773
774 DocStr(GetAlphaBuffer,
775 "Returns a writable Python buffer object that is pointing at the Alpha
776 data buffer inside the wx.Image. You need to ensure that you do not
777 use this buffer object after the image has been destroyed.", "");
778 PyObject* GetAlphaBuffer()
779 {
780 buffer data = self->GetAlpha();
781 int len = self->GetWidth() * self->GetHeight();
782 PyObject* rv;
783 wxPyBLOCK_THREADS( rv = PyBuffer_FromReadWriteMemory(data, len) );
784 return rv;
785 }
786
787
788 DocStr(SetAlphaBuffer,
789 "Sets the internal image alpha pointer to point at a Python buffer
790 object. This can save making an extra copy of the data but you must
791 ensure that the buffer object lives as long as the wx.Image does.", "");
792 void SetAlphaBuffer(buffer alpha, int ALPHASIZE)
793 {
794 if (ALPHASIZE != self->GetWidth() * self->GetHeight()) {
795 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
796 return;
797 }
798 self->SetAlpha(alpha, true);
799 }
800 }
801
802
803
804 DocDeclStr(
805 void , SetMaskColour( byte r, byte g, byte b ),
806 "Sets the mask colour for this image (and tells the image to use the
807 mask).", "");
808
809
810 DocDeclAStr(
811 /*bool*/ void , GetOrFindMaskColour( byte *OUTPUT,
812 byte *OUTPUT,
813 byte *OUTPUT ) const,
814 "GetOrFindMaskColour() -> (r,g,b)",
815 "Get the current mask colour or find a suitable colour.", "");
816
817
818 DocDeclStr(
819 byte , GetMaskRed(),
820 "Gets the red component of the mask colour.", "");
821
822 DocDeclStr(
823 byte , GetMaskGreen(),
824 "Gets the green component of the mask colour.", "");
825
826 DocDeclStr(
827 byte , GetMaskBlue(),
828 "Gets the blue component of the mask colour.", "");
829
830 DocDeclStr(
831 void , SetMask( bool mask = true ),
832 "Specifies whether there is a mask or not. The area of the mask is
833 determined by the current mask colour.", "");
834
835 DocDeclStr(
836 bool , HasMask(),
837 "Returns ``True`` if there is a mask active, ``False`` otherwise.", "");
838
839
840 DocDeclStr(
841 wxImage , Rotate(double angle, const wxPoint & centre_of_rotation,
842 bool interpolating = true, wxPoint * offset_after_rotation = NULL) const ,
843 "Rotates the image about the given point, by ``angle`` radians. Passing
844 ``True`` to ``interpolating`` results in better image quality, but is
845 slower. If the image has a mask, then the mask colour is used for the
846 uncovered pixels in the rotated image background. Otherwise, black
847 will be used as the fill colour.
848
849 Returns the rotated image, leaving this image intact.", "");
850
851 DocDeclStr(
852 wxImage , Rotate90( bool clockwise = true ) ,
853 "Returns a copy of the image rotated 90 degrees in the direction
854 indicated by ``clockwise``.", "");
855
856 DocDeclStr(
857 wxImage , Mirror( bool horizontally = true ) ,
858 "Returns a mirrored copy of the image. The parameter ``horizontally``
859 indicates the orientation.", "");
860
861
862 DocDeclStr(
863 void , Replace( byte r1, byte g1, byte b1,
864 byte r2, byte g2, byte b2 ),
865 "Replaces the colour specified by ``(r1,g1,b1)`` by the colour
866 ``(r2,g2,b2)``.", "");
867
868 DocDeclStr(
869 wxImage , ConvertToGreyscale( double lr = 0.299,
870 double lg = 0.587,
871 double lb = 0.114 ) const,
872 "Convert to greyscale image. Uses the luminance component (Y) of the
873 image. The luma value (YUV) is calculated using (R * lr) + (G * lg) + (B * lb),
874 defaults to ITU-T BT.601", "");
875
876
877 DocDeclStr(
878 wxImage , ConvertToMono( byte r, byte g, byte b ) const,
879 "Returns monochromatic version of the image. The returned image has
880 white colour where the original has ``(r,g,b)`` colour and black
881 colour everywhere else.", "");
882
883
884 DocDeclStr(
885 void , SetOption(const wxString& name, const wxString& value),
886 "Sets an image handler defined option. For example, when saving as a
887 JPEG file, the option ``wx.IMAGE_OPTION_QUALITY`` is used, which is a
888 number between 0 and 100 (0 is terrible, 100 is very good).", "
889
890 ================================= ===
891 wx.IMAGE_OPTION_BMP_FORMAT
892 wx.IMAGE_OPTION_CUR_HOTSPOT_X
893 wx.IMAGE_OPTION_CUR_HOTSPOT_Y
894 wx.IMAGE_OPTION_RESOLUTION
895 wx.IMAGE_OPTION_RESOLUTIONX
896 wx.IMAGE_OPTION_RESOLUTIONY
897 wx.IMAGE_OPTION_RESOLUTIONUNIT
898 wx.IMAGE_OPTION_QUALITY
899 wx.IMAGE_OPTION_BITSPERSAMPLE
900 wx.IMAGE_OPTION_SAMPLESPERPIXEL
901 wx.IMAGE_OPTION_COMPRESSION
902 wx.IMAGE_OPTION_IMAGEDESCRIPTOR
903 wx.IMAGE_OPTION_PNG_FORMAT
904 wx.IMAGE_OPTION_PNG_BITDEPTH
905 ================================= ===
906
907 :see: `HasOption`, `GetOption`, `GetOptionInt`, `SetOptionInt`");
908
909 DocDeclStrName(
910 void, SetOption(const wxString& name, int value),
911 "Sets an image option as an integer.", "
912
913 :see: `HasOption`, `GetOption`, `GetOptionInt`, `SetOption`",
914 SetOptionInt);
915
916 DocDeclStr(
917 wxString , GetOption(const wxString& name) const,
918 "Gets the value of an image handler option.", "
919
920 :see: `HasOption`, `GetOptionInt`, `SetOption`, `SetOptionInt`");
921
922 DocDeclStr(
923 int , GetOptionInt(const wxString& name) const,
924 "Gets the value of an image handler option as an integer. If the given
925 option is not present, the function returns 0.", "
926
927 :see: `HasOption`, `GetOption`, `SetOptionInt`, `SetOption`");
928
929 DocDeclStr(
930 bool , HasOption(const wxString& name) const,
931 "Returns true if the given option is present.", "
932
933 :see: `GetOption`, `GetOptionInt`, `SetOption`, `SetOptionInt`");
934
935
936 unsigned long CountColours( unsigned long stopafter = (unsigned long) -1 );
937 unsigned long ComputeHistogram( wxImageHistogram& h );
938
939 static void AddHandler( wxImageHandler *handler );
940 static void InsertHandler( wxImageHandler *handler );
941 static bool RemoveHandler( const wxString& name );
942 %extend {
943 static PyObject* GetHandlers() {
944 wxList& list = wxImage::GetHandlers();
945 return wxPy_ConvertList(&list);
946 }
947 }
948
949 DocDeclStr(
950 static wxString , GetImageExtWildcard(),
951 "Iterates all registered wxImageHandler objects, and returns a string
952 containing file extension masks suitable for passing to file open/save
953 dialog boxes.", "");
954
955
956
957 MustHaveApp(ConvertToBitmap);
958 MustHaveApp(ConvertToMonoBitmap);
959
960 %extend {
961 wxBitmap ConvertToBitmap(int depth=-1) {
962 wxBitmap bitmap(*self, depth);
963 return bitmap;
964 }
965
966 wxBitmap ConvertToMonoBitmap( byte red,
967 byte green,
968 byte blue ) {
969 wxImage mono = self->ConvertToMono( red, green, blue );
970 wxBitmap bitmap( mono, 1 );
971 return bitmap;
972 }
973 }
974
975
976 DocDeclStr(
977 void , RotateHue(double angle),
978 "Rotates the hue of each pixel of the image. Hue is a double in the
979 range -1.0..1.0 where -1.0 is -360 degrees and 1.0 is 360 degrees", "");
980
981 DocDeclStr(
982 static wxImage_HSVValue , RGBtoHSV(wxImage_RGBValue rgb),
983 "Converts a color in RGB color space to HSV color space.", "");
984
985 DocDeclStr(
986 static wxImage_RGBValue , HSVtoRGB(wxImage_HSVValue hsv),
987 "Converts a color in HSV color space to RGB color space.", "");
988
989
990 %pythoncode { def __nonzero__(self): return self.Ok() }
991
992 %property(AlphaBuffer, GetAlphaBuffer, SetAlphaBuffer, doc="See `GetAlphaBuffer` and `SetAlphaBuffer`");
993 %property(AlphaData, GetAlphaData, SetAlphaData, doc="See `GetAlphaData` and `SetAlphaData`");
994 %property(Data, GetData, SetData, doc="See `GetData` and `SetData`");
995 %property(DataBuffer, GetDataBuffer, SetDataBuffer, doc="See `GetDataBuffer` and `SetDataBuffer`");
996 %property(Height, GetHeight, doc="See `GetHeight`");
997 %property(MaskBlue, GetMaskBlue, doc="See `GetMaskBlue`");
998 %property(MaskGreen, GetMaskGreen, doc="See `GetMaskGreen`");
999 %property(MaskRed, GetMaskRed, doc="See `GetMaskRed`");
1000 %property(Size, GetSize, doc="See `GetSize`");
1001 %property(Width, GetWidth, doc="See `GetWidth`");
1002 };
1003
1004
1005
1006 // Make an image from buffer objects. Not that this is here instead of in the
1007 // wxImage class (as a constructor) because there is already another one with
1008 // the exact same signature, so there woudl be ambiguities in the generated
1009 // C++. Doing it as an independent factory function like this accomplishes
1010 // the same thing however.
1011 %newobject _ImageFromBuffer;
1012 %inline %{
1013 wxImage* _ImageFromBuffer(int width, int height,
1014 buffer data, int DATASIZE,
1015 buffer alpha=NULL, int ALPHASIZE=0)
1016 {
1017 if (DATASIZE != width*height*3) {
1018 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
1019 return NULL;
1020 }
1021 if (alpha != NULL) {
1022 if (ALPHASIZE != width*height) {
1023 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
1024 return NULL;
1025 }
1026 return new wxImage(width, height, data, alpha, true);
1027 }
1028 return new wxImage(width, height, data, true);
1029 }
1030 %}
1031
1032 %pythoncode {
1033 def ImageFromBuffer(width, height, dataBuffer, alphaBuffer=None):
1034 """
1035 Creates a `wx.Image` from the data in dataBuffer. The dataBuffer
1036 parameter must be a Python object that implements the buffer interface,
1037 such as a string, array, etc. The dataBuffer object is expected to
1038 contain a series of RGB bytes and be width*height*3 bytes long. A buffer
1039 object can optionally be supplied for the image's alpha channel data, and
1040 it is expected to be width*height bytes long.
1041
1042 The wx.Image will be created with its data and alpha pointers initialized
1043 to the memory address pointed to by the buffer objects, thus saving the
1044 time needed to copy the image data from the buffer object to the wx.Image.
1045 While this has advantages, it also has the shoot-yourself-in-the-foot
1046 risks associated with sharing a C pointer between two objects.
1047
1048 To help alleviate the risk a reference to the data and alpha buffer
1049 objects are kept with the wx.Image, so that they won't get deleted until
1050 after the wx.Image is deleted. However please be aware that it is not
1051 guaranteed that an object won't move its memory buffer to a new location
1052 when it needs to resize its contents. If that happens then the wx.Image
1053 will end up referring to an invalid memory location and could cause the
1054 application to crash. Therefore care should be taken to not manipulate
1055 the objects used for the data and alpha buffers in a way that would cause
1056 them to change size.
1057 """
1058 image = _core_._ImageFromBuffer(width, height, dataBuffer, alphaBuffer)
1059 image._buffer = dataBuffer
1060 image._alpha = alphaBuffer
1061 return image
1062 }
1063
1064
1065 ///void wxInitAllImageHandlers();
1066
1067 %pythoncode {
1068 def InitAllImageHandlers():
1069 """
1070 The former functionality of InitAllImageHanders is now done internal to
1071 the _core_ extension module and so this function has become a simple NOP.
1072 """
1073 pass
1074 }
1075
1076
1077
1078 %immutable;
1079 const wxImage wxNullImage;
1080 %mutable;
1081
1082 //---------------------------------------------------------------------------
1083
1084 MAKE_CONST_WXSTRING(IMAGE_OPTION_FILENAME);
1085 MAKE_CONST_WXSTRING(IMAGE_OPTION_BMP_FORMAT);
1086 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_X);
1087 MAKE_CONST_WXSTRING(IMAGE_OPTION_CUR_HOTSPOT_Y);
1088 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTION);
1089 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONX);
1090 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONY);
1091 MAKE_CONST_WXSTRING(IMAGE_OPTION_RESOLUTIONUNIT);
1092 MAKE_CONST_WXSTRING(IMAGE_OPTION_QUALITY);
1093
1094 enum
1095 {
1096 wxIMAGE_RESOLUTION_INCHES = 1,
1097 wxIMAGE_RESOLUTION_CM = 2
1098 };
1099
1100
1101 MAKE_CONST_WXSTRING(IMAGE_OPTION_BITSPERSAMPLE);
1102 MAKE_CONST_WXSTRING(IMAGE_OPTION_SAMPLESPERPIXEL);
1103 MAKE_CONST_WXSTRING(IMAGE_OPTION_COMPRESSION);
1104 MAKE_CONST_WXSTRING(IMAGE_OPTION_IMAGEDESCRIPTOR);
1105
1106 MAKE_CONST_WXSTRING(IMAGE_OPTION_PNG_FORMAT);
1107 MAKE_CONST_WXSTRING(IMAGE_OPTION_PNG_BITDEPTH);
1108
1109 enum
1110 {
1111 wxPNG_TYPE_COLOUR = 0,
1112 wxPNG_TYPE_GREY = 2,
1113 wxPNG_TYPE_GREY_RED = 3
1114 };
1115
1116 enum
1117 {
1118 wxBMP_24BPP = 24, // default, do not need to set
1119 //wxBMP_16BPP = 16, // wxQuantize can only do 236 colors?
1120 wxBMP_8BPP = 8, // 8bpp, quantized colors
1121 wxBMP_8BPP_GREY = 9, // 8bpp, rgb averaged to greys
1122 wxBMP_8BPP_GRAY = wxBMP_8BPP_GREY,
1123 wxBMP_8BPP_RED = 10, // 8bpp, red used as greyscale
1124 wxBMP_8BPP_PALETTE = 11, // 8bpp, use the wxImage's palette
1125 wxBMP_4BPP = 4, // 4bpp, quantized colors
1126 wxBMP_1BPP = 1, // 1bpp, quantized "colors"
1127 wxBMP_1BPP_BW = 2 // 1bpp, black & white from red
1128 };
1129
1130
1131 DocStr(wxBMPHandler,
1132 "A `wx.ImageHandler` for \*.bmp bitmap files.", "");
1133 class wxBMPHandler : public wxImageHandler {
1134 public:
1135 wxBMPHandler();
1136 };
1137
1138 DocStr(wxICOHandler,
1139 "A `wx.ImageHandler` for \*.ico icon files.", "");
1140 class wxICOHandler : public wxBMPHandler {
1141 public:
1142 wxICOHandler();
1143 };
1144
1145 DocStr(wxCURHandler,
1146 "A `wx.ImageHandler` for \*.cur cursor files.", "");
1147 class wxCURHandler : public wxICOHandler {
1148 public:
1149 wxCURHandler();
1150 };
1151
1152 DocStr(wxANIHandler,
1153 "A `wx.ImageHandler` for \*.ani animated cursor files.", "");
1154 class wxANIHandler : public wxCURHandler {
1155 public:
1156 wxANIHandler();
1157 };
1158
1159
1160 //---------------------------------------------------------------------------
1161
1162 DocStr(wxPNGHandler,
1163 "A `wx.ImageHandler` for PNG image files.", "");
1164 class wxPNGHandler : public wxImageHandler {
1165 public:
1166 wxPNGHandler();
1167 };
1168
1169
1170 DocStr(wxGIFHandler,
1171 "A `wx.ImageHandler` for GIF image files.", "");
1172 class wxGIFHandler : public wxImageHandler {
1173 public:
1174 wxGIFHandler();
1175 };
1176
1177
1178 DocStr(wxPCXHandler,
1179 "A `wx.ImageHandler` for PCX imager files.", "");
1180 class wxPCXHandler : public wxImageHandler {
1181 public:
1182 wxPCXHandler();
1183 };
1184
1185
1186 DocStr(wxJPEGHandler,
1187 "A `wx.ImageHandler` for JPEG/JPG image files.", "");
1188 class wxJPEGHandler : public wxImageHandler {
1189 public:
1190 wxJPEGHandler();
1191 };
1192
1193
1194 DocStr(wxPNMHandler,
1195 "A `wx.ImageHandler` for PNM image files.", "");
1196 class wxPNMHandler : public wxImageHandler {
1197 public:
1198 wxPNMHandler();
1199 };
1200
1201 DocStr(wxXPMHandler,
1202 "A `wx.ImageHandler` for XPM image.", "");
1203 class wxXPMHandler : public wxImageHandler {
1204 public:
1205 wxXPMHandler();
1206 };
1207
1208 DocStr(wxTIFFHandler,
1209 "A `wx.ImageHandler` for TIFF image files.", "");
1210 class wxTIFFHandler : public wxImageHandler {
1211 public:
1212 wxTIFFHandler();
1213 };
1214
1215
1216 #if wxUSE_IFF
1217 DocStr(wxIFFHandler,
1218 "A `wx.ImageHandler` for IFF image files.", "");
1219 class wxIFFHandler : public wxImageHandler {
1220 public:
1221 wxIFFHandler();
1222 };
1223 #endif
1224
1225 //---------------------------------------------------------------------------
1226
1227 %{
1228 #include <wx/quantize.h>
1229 %}
1230
1231 enum {
1232 wxQUANTIZE_INCLUDE_WINDOWS_COLOURS,
1233 // wxQUANTIZE_RETURN_8BIT_DATA,
1234 wxQUANTIZE_FILL_DESTINATION_IMAGE
1235 };
1236
1237
1238 DocStr(wxQuantize,
1239 "Performs quantization, or colour reduction, on a wxImage.", "");
1240
1241 class wxQuantize /*: public wxObject */
1242 {
1243 public:
1244
1245 %extend {
1246 DocStr(
1247 Quantize,
1248 "Reduce the colours in the source image and put the result into the
1249 destination image, setting the palette in the destination if
1250 needed. Both images may be the same, to overwrite the source image.", "
1251 :todo: Create a version that returns the wx.Palette used.");
1252
1253 static bool Quantize(const wxImage& src, wxImage& dest, int desiredNoColours = 236,
1254 int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE)
1255 {
1256 return wxQuantize::Quantize(src, dest,
1257 //NULL, // palette
1258 desiredNoColours,
1259 NULL, // eightBitData
1260 flags);
1261 }
1262 }
1263 };
1264
1265
1266 //---------------------------------------------------------------------------