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