]> git.saurik.com Git - wxWidgets.git/blob - include/wx/image.h
cleanup
[wxWidgets.git] / include / wx / image.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/image.h
3 // Purpose: wxImage class
4 // Author: Robert Roebling
5 // RCS-ID: $Id$
6 // Copyright: (c) Robert Roebling
7 // Licence: wxWindows licence
8 /////////////////////////////////////////////////////////////////////////////
9
10 #ifndef _WX_IMAGE_H_
11 #define _WX_IMAGE_H_
12
13 #include "wx/defs.h"
14
15 #if wxUSE_IMAGE
16
17 #include "wx/object.h"
18 #include "wx/string.h"
19 #include "wx/gdicmn.h"
20 #include "wx/hashmap.h"
21
22 #if wxUSE_STREAMS
23 # include "wx/stream.h"
24 #endif
25
26 // on some systems (Unixware 7.x) index is defined as a macro in the headers
27 // which breaks the compilation below
28 #undef index
29
30 #define wxIMAGE_OPTION_QUALITY wxString(_T("quality"))
31 #define wxIMAGE_OPTION_FILENAME wxString(_T("FileName"))
32
33 #define wxIMAGE_OPTION_RESOLUTION wxString(_T("Resolution"))
34 #define wxIMAGE_OPTION_RESOLUTIONX wxString(_T("ResolutionX"))
35 #define wxIMAGE_OPTION_RESOLUTIONY wxString(_T("ResolutionY"))
36
37 #define wxIMAGE_OPTION_RESOLUTIONUNIT wxString(_T("ResolutionUnit"))
38
39 // constants used with wxIMAGE_OPTION_RESOLUTIONUNIT
40 //
41 // NB: don't change these values, they correspond to libjpeg constants
42 enum wxImageResolution
43 {
44 // Resolution not specified
45 wxIMAGE_RESOLUTION_NONE = 0,
46
47 // Resolution specified in inches
48 wxIMAGE_RESOLUTION_INCHES = 1,
49
50 // Resolution specified in centimeters
51 wxIMAGE_RESOLUTION_CM = 2
52 };
53
54 // Constants for wxImage::Scale() for determining the level of quality
55 enum
56 {
57 wxIMAGE_QUALITY_NORMAL = 0,
58 wxIMAGE_QUALITY_HIGH = 1
59 };
60
61 // alpha channel values: fully transparent, default threshold separating
62 // transparent pixels from opaque for a few functions dealing with alpha and
63 // fully opaque
64 const unsigned char wxIMAGE_ALPHA_TRANSPARENT = 0;
65 const unsigned char wxIMAGE_ALPHA_THRESHOLD = 0x80;
66 const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff;
67
68 //-----------------------------------------------------------------------------
69 // classes
70 //-----------------------------------------------------------------------------
71
72 class WXDLLIMPEXP_FWD_CORE wxImageHandler;
73 class WXDLLIMPEXP_FWD_CORE wxImage;
74 class WXDLLIMPEXP_FWD_CORE wxPalette;
75
76 //-----------------------------------------------------------------------------
77 // wxVariant support
78 //-----------------------------------------------------------------------------
79
80 #if wxUSE_VARIANT
81 #include "wx/variant.h"
82 DECLARE_VARIANT_OBJECT_EXPORTED(wxImage,WXDLLEXPORT)
83 #endif
84
85 //-----------------------------------------------------------------------------
86 // wxImageHandler
87 //-----------------------------------------------------------------------------
88
89 class WXDLLEXPORT wxImageHandler: public wxObject
90 {
91 public:
92 wxImageHandler()
93 : m_name(wxEmptyString), m_extension(wxEmptyString), m_mime(), m_type(0)
94 { }
95
96 #if wxUSE_STREAMS
97 virtual bool LoadFile( wxImage *image, wxInputStream& stream, bool verbose=true, int index=-1 );
98 virtual bool SaveFile( wxImage *image, wxOutputStream& stream, bool verbose=true );
99
100 virtual int GetImageCount( wxInputStream& stream );
101
102 bool CanRead( wxInputStream& stream ) { return CallDoCanRead(stream); }
103 bool CanRead( const wxString& name );
104 #endif // wxUSE_STREAMS
105
106 void SetName(const wxString& name) { m_name = name; }
107 void SetExtension(const wxString& ext) { m_extension = ext; }
108 void SetType(long type) { m_type = type; }
109 void SetMimeType(const wxString& type) { m_mime = type; }
110 const wxString& GetName() const { return m_name; }
111 const wxString& GetExtension() const { return m_extension; }
112 long GetType() const { return m_type; }
113 const wxString& GetMimeType() const { return m_mime; }
114
115 protected:
116 #if wxUSE_STREAMS
117 virtual bool DoCanRead( wxInputStream& stream ) = 0;
118
119 // save the stream position, call DoCanRead() and restore the position
120 bool CallDoCanRead(wxInputStream& stream);
121 #endif // wxUSE_STREAMS
122
123 // helper for the derived classes SaveFile() implementations: returns the
124 // values of x- and y-resolution options specified as the image options if
125 // any
126 static wxImageResolution
127 GetResolutionFromOptions(const wxImage& image, int *x, int *y);
128
129
130 wxString m_name;
131 wxString m_extension;
132 wxString m_mime;
133 long m_type;
134
135 private:
136 DECLARE_CLASS(wxImageHandler)
137 };
138
139 //-----------------------------------------------------------------------------
140 // wxImageHistogram
141 //-----------------------------------------------------------------------------
142
143 class WXDLLEXPORT wxImageHistogramEntry
144 {
145 public:
146 wxImageHistogramEntry() { index = value = 0; }
147 unsigned long index;
148 unsigned long value;
149 };
150
151 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
152 wxIntegerHash, wxIntegerEqual,
153 wxImageHistogramBase);
154
155 class WXDLLEXPORT wxImageHistogram : public wxImageHistogramBase
156 {
157 public:
158 wxImageHistogram() : wxImageHistogramBase(256) { }
159
160 // get the key in the histogram for the given RGB values
161 static unsigned long MakeKey(unsigned char r,
162 unsigned char g,
163 unsigned char b)
164 {
165 return (r << 16) | (g << 8) | b;
166 }
167
168 // find first colour that is not used in the image and has higher
169 // RGB values than RGB(startR, startG, startB)
170 //
171 // returns true and puts this colour in r, g, b (each of which may be NULL)
172 // on success or returns false if there are no more free colours
173 bool FindFirstUnusedColour(unsigned char *r,
174 unsigned char *g,
175 unsigned char *b,
176 unsigned char startR = 1,
177 unsigned char startG = 0,
178 unsigned char startB = 0 ) const;
179 };
180
181 //-----------------------------------------------------------------------------
182 // wxImage
183 //-----------------------------------------------------------------------------
184
185 class WXDLLEXPORT wxImage: public wxObject
186 {
187 public:
188 // red, green and blue are 8 bit unsigned integers in the range of 0..255
189 // We use the identifier RGBValue instead of RGB, since RGB is #defined
190 class RGBValue
191 {
192 public:
193 RGBValue(unsigned char r=0, unsigned char g=0, unsigned char b=0)
194 : red(r), green(g), blue(b) {}
195 unsigned char red;
196 unsigned char green;
197 unsigned char blue;
198 };
199
200 // hue, saturation and value are doubles in the range 0.0..1.0
201 class HSVValue
202 {
203 public:
204 HSVValue(double h=0.0, double s=0.0, double v=0.0)
205 : hue(h), saturation(s), value(v) {}
206 double hue;
207 double saturation;
208 double value;
209 };
210
211 wxImage(){}
212 wxImage( int width, int height, bool clear = true );
213 wxImage( int width, int height, unsigned char* data, bool static_data = false );
214 wxImage( int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
215 wxImage( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 );
216 wxImage( const wxString& name, const wxString& mimetype, int index = -1 );
217 wxImage( const char* const* xpmData );
218
219 #if wxUSE_STREAMS
220 wxImage( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1 );
221 wxImage( wxInputStream& stream, const wxString& mimetype, int index = -1 );
222 #endif // wxUSE_STREAMS
223
224 bool Create( int width, int height, bool clear = true );
225 bool Create( int width, int height, unsigned char* data, bool static_data = false );
226 bool Create( int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
227 bool Create( const char* const* xpmData );
228 #ifdef __BORLANDC__
229 // needed for Borland 5.5
230 wxImage( char** xpmData ) { Create(wx_const_cast(const char* const*, xpmData)); }
231 bool Create( char** xpmData ) { return Create(wx_const_cast(const char* const*, xpmData)); }
232 #endif
233 void Destroy();
234
235 // creates an identical copy of the image (the = operator
236 // just raises the ref count)
237 wxImage Copy() const;
238
239 // return the new image with size width*height
240 wxImage GetSubImage( const wxRect& rect) const;
241
242 // Paste the image or part of this image into an image of the given size at the pos
243 // any newly exposed areas will be filled with the rgb colour
244 // by default if r = g = b = -1 then fill with this image's mask colour or find and
245 // set a suitable mask colour
246 wxImage Size( const wxSize& size, const wxPoint& pos,
247 int r = -1, int g = -1, int b = -1 ) const;
248
249 // pastes image into this instance and takes care of
250 // the mask colour and out of bounds problems
251 void Paste( const wxImage &image, int x, int y );
252
253 // return the new image with size width*height
254 wxImage Scale( int width, int height, int quality = wxIMAGE_QUALITY_NORMAL ) const;
255
256 // box averager and bicubic filters for up/down sampling
257 wxImage ResampleBox(int width, int height) const;
258 wxImage ResampleBicubic(int width, int height) const;
259
260 // blur the image according to the specified pixel radius
261 wxImage Blur(int radius) const;
262 wxImage BlurHorizontal(int radius) const;
263 wxImage BlurVertical(int radius) const;
264
265 wxImage ShrinkBy( int xFactor , int yFactor ) const ;
266
267 // rescales the image in place
268 wxImage& Rescale( int width, int height, int quality = wxIMAGE_QUALITY_NORMAL ) { return *this = Scale(width, height, quality); }
269
270 // resizes the image in place
271 wxImage& Resize( const wxSize& size, const wxPoint& pos,
272 int r = -1, int g = -1, int b = -1 ) { return *this = Size(size, pos, r, g, b); }
273
274 // Rotates the image about the given point, 'angle' radians.
275 // Returns the rotated image, leaving this image intact.
276 wxImage Rotate(double angle, const wxPoint & centre_of_rotation,
277 bool interpolating = true, wxPoint * offset_after_rotation = (wxPoint*) NULL) const;
278
279 wxImage Rotate90( bool clockwise = true ) const;
280 wxImage Mirror( bool horizontally = true ) const;
281
282 // replace one colour with another
283 void Replace( unsigned char r1, unsigned char g1, unsigned char b1,
284 unsigned char r2, unsigned char g2, unsigned char b2 );
285
286 // Convert to greyscale image. Uses the luminance component (Y) of the image.
287 // The luma value (YUV) is calculated using (R * lr) + (G * lg) + (B * lb), defaults to ITU-T BT.601
288 wxImage ConvertToGreyscale( double lr = 0.299, double lg = 0.587, double lb = 0.114 ) const;
289
290 // convert to monochrome image (<r,g,b> will be replaced by white,
291 // everything else by black)
292 wxImage ConvertToMono( unsigned char r, unsigned char g, unsigned char b ) const;
293
294 // these routines are slow but safe
295 void SetRGB( int x, int y, unsigned char r, unsigned char g, unsigned char b );
296 void SetRGB( const wxRect& rect, unsigned char r, unsigned char g, unsigned char b );
297 unsigned char GetRed( int x, int y ) const;
298 unsigned char GetGreen( int x, int y ) const;
299 unsigned char GetBlue( int x, int y ) const;
300
301 void SetAlpha(int x, int y, unsigned char alpha);
302 unsigned char GetAlpha(int x, int y) const;
303
304 // find first colour that is not used in the image and has higher
305 // RGB values than <startR,startG,startB>
306 bool FindFirstUnusedColour( unsigned char *r, unsigned char *g, unsigned char *b,
307 unsigned char startR = 1, unsigned char startG = 0,
308 unsigned char startB = 0 ) const;
309 // Set image's mask to the area of 'mask' that has <r,g,b> colour
310 bool SetMaskFromImage(const wxImage & mask,
311 unsigned char mr, unsigned char mg, unsigned char mb);
312
313 // converts image's alpha channel to mask, if it has any, does nothing
314 // otherwise:
315 bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
316
317 // This method converts an image where the original alpha
318 // information is only available as a shades of a colour
319 // (actually shades of grey) typically when you draw anti-
320 // aliased text into a bitmap. The DC drawinf routines
321 // draw grey values on the black background although they
322 // actually mean to draw white with differnt alpha values.
323 // This method reverses it, assuming a black (!) background
324 // and white text (actually only the red channel is read).
325 // The method will then fill up the whole image with the
326 // colour given.
327 bool ConvertColourToAlpha( unsigned char r, unsigned char g, unsigned char b );
328
329 static bool CanRead( const wxString& name );
330 static int GetImageCount( const wxString& name, long type = wxBITMAP_TYPE_ANY );
331 virtual bool LoadFile( const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1 );
332 virtual bool LoadFile( const wxString& name, const wxString& mimetype, int index = -1 );
333
334 #if wxUSE_STREAMS
335 static bool CanRead( wxInputStream& stream );
336 static int GetImageCount( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY );
337 virtual bool LoadFile( wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1 );
338 virtual bool LoadFile( wxInputStream& stream, const wxString& mimetype, int index = -1 );
339 #endif
340
341 virtual bool SaveFile( const wxString& name ) const;
342 virtual bool SaveFile( const wxString& name, int type ) const;
343 virtual bool SaveFile( const wxString& name, const wxString& mimetype ) const;
344
345 #if wxUSE_STREAMS
346 virtual bool SaveFile( wxOutputStream& stream, int type ) const;
347 virtual bool SaveFile( wxOutputStream& stream, const wxString& mimetype ) const;
348 #endif
349
350 bool Ok() const { return IsOk(); }
351 bool IsOk() const;
352 int GetWidth() const;
353 int GetHeight() const;
354
355 // these functions provide fastest access to wxImage data but should be
356 // used carefully as no checks are done
357 unsigned char *GetData() const;
358 void SetData( unsigned char *data, bool static_data=false );
359 void SetData( unsigned char *data, int new_width, int new_height, bool static_data=false );
360
361 unsigned char *GetAlpha() const; // may return NULL!
362 bool HasAlpha() const { return GetAlpha() != NULL; }
363 void SetAlpha(unsigned char *alpha = NULL, bool static_data=false);
364 void InitAlpha();
365
366 // return true if this pixel is masked or has alpha less than specified
367 // threshold
368 bool IsTransparent(int x, int y,
369 unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
370
371 // Mask functions
372 void SetMaskColour( unsigned char r, unsigned char g, unsigned char b );
373 // Get the current mask colour or find a suitable colour
374 // returns true if using current mask colour
375 bool GetOrFindMaskColour( unsigned char *r, unsigned char *g, unsigned char *b ) const;
376 unsigned char GetMaskRed() const;
377 unsigned char GetMaskGreen() const;
378 unsigned char GetMaskBlue() const;
379 void SetMask( bool mask = true );
380 bool HasMask() const;
381
382 #if wxUSE_PALETTE
383 // Palette functions
384 bool HasPalette() const;
385 const wxPalette& GetPalette() const;
386 void SetPalette(const wxPalette& palette);
387 #endif // wxUSE_PALETTE
388
389 // Option functions (arbitrary name/value mapping)
390 void SetOption(const wxString& name, const wxString& value);
391 void SetOption(const wxString& name, int value);
392 wxString GetOption(const wxString& name) const;
393 int GetOptionInt(const wxString& name) const;
394 bool HasOption(const wxString& name) const;
395
396 unsigned long CountColours( unsigned long stopafter = (unsigned long) -1 ) const;
397
398 // Computes the histogram of the image and fills a hash table, indexed
399 // with integer keys built as 0xRRGGBB, containing wxImageHistogramEntry
400 // objects. Each of them contains an 'index' (useful to build a palette
401 // with the image colours) and a 'value', which is the number of pixels
402 // in the image with that colour.
403 // Returned value: # of entries in the histogram
404 unsigned long ComputeHistogram( wxImageHistogram &h ) const;
405
406 // Rotates the hue of each pixel of the image. angle is a double in the range
407 // -1.0..1.0 where -1.0 is -360 degrees and 1.0 is 360 degrees
408 void RotateHue(double angle);
409
410 static wxList& GetHandlers() { return sm_handlers; }
411 static void AddHandler( wxImageHandler *handler );
412 static void InsertHandler( wxImageHandler *handler );
413 static bool RemoveHandler( const wxString& name );
414 static wxImageHandler *FindHandler( const wxString& name );
415 static wxImageHandler *FindHandler( const wxString& extension, long imageType );
416 static wxImageHandler *FindHandler( long imageType );
417 static wxImageHandler *FindHandlerMime( const wxString& mimetype );
418
419 static wxString GetImageExtWildcard();
420
421 static void CleanUpHandlers();
422 static void InitStandardHandlers();
423
424 static HSVValue RGBtoHSV(const RGBValue& rgb);
425 static RGBValue HSVtoRGB(const HSVValue& hsv);
426
427
428 protected:
429 static wxList sm_handlers;
430
431 // return the index of the point with the given coordinates or -1 if the
432 // image is invalid of the coordinates are out of range
433 //
434 // note that index must be multiplied by 3 when using it with RGB array
435 long XYToIndex(int x, int y) const;
436
437 virtual wxObjectRefData* CreateRefData() const;
438 virtual wxObjectRefData* CloneRefData(const wxObjectRefData* data) const;
439
440 private:
441 friend class WXDLLIMPEXP_FWD_CORE wxImageHandler;
442
443 DECLARE_DYNAMIC_CLASS(wxImage)
444 };
445
446
447 extern void WXDLLEXPORT wxInitAllImageHandlers();
448
449 extern WXDLLEXPORT_DATA(wxImage) wxNullImage;
450
451 //-----------------------------------------------------------------------------
452 // wxImage handlers
453 //-----------------------------------------------------------------------------
454
455 #include "wx/imagbmp.h"
456 #include "wx/imagpng.h"
457 #include "wx/imaggif.h"
458 #include "wx/imagpcx.h"
459 #include "wx/imagjpeg.h"
460 #include "wx/imagtga.h"
461 #include "wx/imagtiff.h"
462 #include "wx/imagpnm.h"
463 #include "wx/imagxpm.h"
464 #include "wx/imagiff.h"
465
466 #endif // wxUSE_IMAGE
467
468 #endif
469 // _WX_IMAGE_H_