1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxImage class
4 // Author: Robert Roebling
6 // Copyright: (c) Robert Roebling
7 // Licence: wxWindows licence
8 /////////////////////////////////////////////////////////////////////////////
17 #include "wx/object.h"
18 #include "wx/string.h"
19 #include "wx/gdicmn.h"
20 #include "wx/hashmap.h"
23 # include "wx/stream.h"
26 // on some systems (Unixware 7.x) index is defined as a macro in the headers
27 // which breaks the compilation below
30 #define wxIMAGE_OPTION_QUALITY wxString(_T("quality"))
31 #define wxIMAGE_OPTION_FILENAME wxString(_T("FileName"))
33 #define wxIMAGE_OPTION_RESOLUTION wxString(_T("Resolution"))
34 #define wxIMAGE_OPTION_RESOLUTIONX wxString(_T("ResolutionX"))
35 #define wxIMAGE_OPTION_RESOLUTIONY wxString(_T("ResolutionY"))
37 #define wxIMAGE_OPTION_RESOLUTIONUNIT wxString(_T("ResolutionUnit"))
39 // constants used with wxIMAGE_OPTION_RESOLUTIONUNIT
42 wxIMAGE_RESOLUTION_INCHES
= 1,
43 wxIMAGE_RESOLUTION_CM
= 2
46 // Constants for wxImage::Scale() for determining the level of quality
49 wxIMAGE_QUALITY_NORMAL
= 0,
50 wxIMAGE_QUALITY_HIGH
= 1
53 // alpha channel values: fully transparent, default threshold separating
54 // transparent pixels from opaque for a few functions dealing with alpha and
56 const unsigned char wxIMAGE_ALPHA_TRANSPARENT
= 0;
57 const unsigned char wxIMAGE_ALPHA_THRESHOLD
= 0x80;
58 const unsigned char wxIMAGE_ALPHA_OPAQUE
= 0xff;
60 //-----------------------------------------------------------------------------
62 //-----------------------------------------------------------------------------
64 class WXDLLEXPORT wxImageHandler
;
65 class WXDLLEXPORT wxImage
;
66 class WXDLLEXPORT wxPalette
;
68 //-----------------------------------------------------------------------------
70 //-----------------------------------------------------------------------------
73 #include "wx/variant.h"
74 DECLARE_VARIANT_OBJECT_EXPORTED(wxImage
,WXDLLEXPORT
)
77 //-----------------------------------------------------------------------------
79 //-----------------------------------------------------------------------------
81 class WXDLLEXPORT wxImageHandler
: public wxObject
85 : m_name(wxEmptyString
), m_extension(wxEmptyString
), m_mime(), m_type(0)
89 virtual bool LoadFile( wxImage
*image
, wxInputStream
& stream
, bool verbose
=true, int index
=-1 );
90 virtual bool SaveFile( wxImage
*image
, wxOutputStream
& stream
, bool verbose
=true );
92 virtual int GetImageCount( wxInputStream
& stream
);
94 bool CanRead( wxInputStream
& stream
) { return CallDoCanRead(stream
); }
95 bool CanRead( const wxString
& name
);
96 #endif // wxUSE_STREAMS
98 void SetName(const wxString
& name
) { m_name
= name
; }
99 void SetExtension(const wxString
& ext
) { m_extension
= ext
; }
100 void SetType(long type
) { m_type
= type
; }
101 void SetMimeType(const wxString
& type
) { m_mime
= type
; }
102 const wxString
& GetName() const { return m_name
; }
103 const wxString
& GetExtension() const { return m_extension
; }
104 long GetType() const { return m_type
; }
105 const wxString
& GetMimeType() const { return m_mime
; }
109 virtual bool DoCanRead( wxInputStream
& stream
) = 0;
111 // save the stream position, call DoCanRead() and restore the position
112 bool CallDoCanRead(wxInputStream
& stream
);
113 #endif // wxUSE_STREAMS
116 wxString m_extension
;
121 DECLARE_CLASS(wxImageHandler
)
124 //-----------------------------------------------------------------------------
126 //-----------------------------------------------------------------------------
128 class WXDLLEXPORT wxImageHistogramEntry
131 wxImageHistogramEntry() { index
= value
= 0; }
136 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry
,
137 wxIntegerHash
, wxIntegerEqual
,
138 wxImageHistogramBase
);
140 class WXDLLEXPORT wxImageHistogram
: public wxImageHistogramBase
143 wxImageHistogram() : wxImageHistogramBase(256) { }
145 // get the key in the histogram for the given RGB values
146 static unsigned long MakeKey(unsigned char r
,
150 return (r
<< 16) | (g
<< 8) | b
;
153 // find first colour that is not used in the image and has higher
154 // RGB values than RGB(startR, startG, startB)
156 // returns true and puts this colour in r, g, b (each of which may be NULL)
157 // on success or returns false if there are no more free colours
158 bool FindFirstUnusedColour(unsigned char *r
,
161 unsigned char startR
= 1,
162 unsigned char startG
= 0,
163 unsigned char startB
= 0 ) const;
166 //-----------------------------------------------------------------------------
168 //-----------------------------------------------------------------------------
170 class WXDLLEXPORT wxImage
: public wxObject
173 // red, green and blue are 8 bit unsigned integers in the range of 0..255
174 // We use the identifier RGBValue instead of RGB, since RGB is #defined
178 RGBValue(unsigned char r
=0, unsigned char g
=0, unsigned char b
=0)
179 : red(r
), green(g
), blue(b
) {}
185 // hue, saturation and value are doubles in the range 0.0..1.0
189 HSVValue(double h
=0.0, double s
=0.0, double v
=0.0)
190 : hue(h
), saturation(s
), value(v
) {}
197 wxImage( int width
, int height
, bool clear
= true );
198 wxImage( int width
, int height
, unsigned char* data
, bool static_data
= false );
199 wxImage( int width
, int height
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
200 wxImage( const wxString
& name
, long type
= wxBITMAP_TYPE_ANY
, int index
= -1 );
201 wxImage( const wxString
& name
, const wxString
& mimetype
, int index
= -1 );
202 wxImage( const char* const* xpmData
);
205 wxImage( wxInputStream
& stream
, long type
= wxBITMAP_TYPE_ANY
, int index
= -1 );
206 wxImage( wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1 );
207 #endif // wxUSE_STREAMS
209 bool Create( int width
, int height
, bool clear
= true );
210 bool Create( int width
, int height
, unsigned char* data
, bool static_data
= false );
211 bool Create( int width
, int height
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
212 bool Create( const char* const* xpmData
);
214 // needed for Borland 5.5
215 wxImage( char** xpmData
) { Create(wx_const_cast(const char* const*, xpmData
)); }
216 bool Create( char** xpmData
) { return Create(wx_const_cast(const char* const*, xpmData
)); }
220 // creates an identical copy of the image (the = operator
221 // just raises the ref count)
222 wxImage
Copy() const;
224 // return the new image with size width*height
225 wxImage
GetSubImage( const wxRect
& rect
) const;
227 // Paste the image or part of this image into an image of the given size at the pos
228 // any newly exposed areas will be filled with the rgb colour
229 // by default if r = g = b = -1 then fill with this image's mask colour or find and
230 // set a suitable mask colour
231 wxImage
Size( const wxSize
& size
, const wxPoint
& pos
,
232 int r
= -1, int g
= -1, int b
= -1 ) const;
234 // pastes image into this instance and takes care of
235 // the mask colour and out of bounds problems
236 void Paste( const wxImage
&image
, int x
, int y
);
238 // return the new image with size width*height
239 wxImage
Scale( int width
, int height
, int quality
= wxIMAGE_QUALITY_NORMAL
) const;
241 // box averager and bicubic filters for up/down sampling
242 wxImage
ResampleBox(int width
, int height
) const;
243 wxImage
ResampleBicubic(int width
, int height
) const;
245 // blur the image according to the specified pixel radius
246 wxImage
Blur(int radius
);
247 wxImage
BlurHorizontal(int radius
);
248 wxImage
BlurVertical(int radius
);
250 wxImage
ShrinkBy( int xFactor
, int yFactor
) const ;
252 // rescales the image in place
253 wxImage
& Rescale( int width
, int height
, int quality
= wxIMAGE_QUALITY_NORMAL
) { return *this = Scale(width
, height
, quality
); }
255 // resizes the image in place
256 wxImage
& Resize( const wxSize
& size
, const wxPoint
& pos
,
257 int r
= -1, int g
= -1, int b
= -1 ) { return *this = Size(size
, pos
, r
, g
, b
); }
259 // Rotates the image about the given point, 'angle' radians.
260 // Returns the rotated image, leaving this image intact.
261 wxImage
Rotate(double angle
, const wxPoint
& centre_of_rotation
,
262 bool interpolating
= true, wxPoint
* offset_after_rotation
= (wxPoint
*) NULL
) const;
264 wxImage
Rotate90( bool clockwise
= true ) const;
265 wxImage
Mirror( bool horizontally
= true ) const;
267 // replace one colour with another
268 void Replace( unsigned char r1
, unsigned char g1
, unsigned char b1
,
269 unsigned char r2
, unsigned char g2
, unsigned char b2
);
271 // Convert to greyscale image. Uses the luminance component (Y) of the image.
272 // The luma value (YUV) is calculated using (R * lr) + (G * lg) + (B * lb), defaults to ITU-T BT.601
273 wxImage
ConvertToGreyscale( double lr
= 0.299, double lg
= 0.587, double lb
= 0.114 ) const;
275 // convert to monochrome image (<r,g,b> will be replaced by white,
276 // everything else by black)
277 wxImage
ConvertToMono( unsigned char r
, unsigned char g
, unsigned char b
) const;
279 // these routines are slow but safe
280 void SetRGB( int x
, int y
, unsigned char r
, unsigned char g
, unsigned char b
);
281 void SetRGB( const wxRect
& rect
, unsigned char r
, unsigned char g
, unsigned char b
);
282 unsigned char GetRed( int x
, int y
) const;
283 unsigned char GetGreen( int x
, int y
) const;
284 unsigned char GetBlue( int x
, int y
) const;
286 void SetAlpha(int x
, int y
, unsigned char alpha
);
287 unsigned char GetAlpha(int x
, int y
) const;
289 // find first colour that is not used in the image and has higher
290 // RGB values than <startR,startG,startB>
291 bool FindFirstUnusedColour( unsigned char *r
, unsigned char *g
, unsigned char *b
,
292 unsigned char startR
= 1, unsigned char startG
= 0,
293 unsigned char startB
= 0 ) const;
294 // Set image's mask to the area of 'mask' that has <r,g,b> colour
295 bool SetMaskFromImage(const wxImage
& mask
,
296 unsigned char mr
, unsigned char mg
, unsigned char mb
);
298 // converts image's alpha channel to mask, if it has any, does nothing
300 bool ConvertAlphaToMask(unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
302 // This method converts an image where the original alpha
303 // information is only available as a shades of a colour
304 // (actually shades of grey) typically when you draw anti-
305 // aliased text into a bitmap. The DC drawinf routines
306 // draw grey values on the black background although they
307 // actually mean to draw white with differnt alpha values.
308 // This method reverses it, assuming a black (!) background
309 // and white text (actually only the red channel is read).
310 // The method will then fill up the whole image with the
312 bool ConvertColourToAlpha( unsigned char r
, unsigned char g
, unsigned char b
);
314 static bool CanRead( const wxString
& name
);
315 static int GetImageCount( const wxString
& name
, long type
= wxBITMAP_TYPE_ANY
);
316 virtual bool LoadFile( const wxString
& name
, long type
= wxBITMAP_TYPE_ANY
, int index
= -1 );
317 virtual bool LoadFile( const wxString
& name
, const wxString
& mimetype
, int index
= -1 );
320 static bool CanRead( wxInputStream
& stream
);
321 static int GetImageCount( wxInputStream
& stream
, long type
= wxBITMAP_TYPE_ANY
);
322 virtual bool LoadFile( wxInputStream
& stream
, long type
= wxBITMAP_TYPE_ANY
, int index
= -1 );
323 virtual bool LoadFile( wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1 );
326 virtual bool SaveFile( const wxString
& name
) const;
327 virtual bool SaveFile( const wxString
& name
, int type
) const;
328 virtual bool SaveFile( const wxString
& name
, const wxString
& mimetype
) const;
331 virtual bool SaveFile( wxOutputStream
& stream
, int type
) const;
332 virtual bool SaveFile( wxOutputStream
& stream
, const wxString
& mimetype
) const;
335 bool Ok() const { return IsOk(); }
337 int GetWidth() const;
338 int GetHeight() const;
340 // these functions provide fastest access to wxImage data but should be
341 // used carefully as no checks are done
342 unsigned char *GetData() const;
343 void SetData( unsigned char *data
, bool static_data
=false );
344 void SetData( unsigned char *data
, int new_width
, int new_height
, bool static_data
=false );
346 unsigned char *GetAlpha() const; // may return NULL!
347 bool HasAlpha() const { return GetAlpha() != NULL
; }
348 void SetAlpha(unsigned char *alpha
= NULL
, bool static_data
=false);
351 // return true if this pixel is masked or has alpha less than specified
353 bool IsTransparent(int x
, int y
,
354 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
) const;
357 void SetMaskColour( unsigned char r
, unsigned char g
, unsigned char b
);
358 // Get the current mask colour or find a suitable colour
359 // returns true if using current mask colour
360 bool GetOrFindMaskColour( unsigned char *r
, unsigned char *g
, unsigned char *b
) const;
361 unsigned char GetMaskRed() const;
362 unsigned char GetMaskGreen() const;
363 unsigned char GetMaskBlue() const;
364 void SetMask( bool mask
= true );
365 bool HasMask() const;
369 bool HasPalette() const;
370 const wxPalette
& GetPalette() const;
371 void SetPalette(const wxPalette
& palette
);
372 #endif // wxUSE_PALETTE
374 // Option functions (arbitrary name/value mapping)
375 void SetOption(const wxString
& name
, const wxString
& value
);
376 void SetOption(const wxString
& name
, int value
);
377 wxString
GetOption(const wxString
& name
) const;
378 int GetOptionInt(const wxString
& name
) const;
379 bool HasOption(const wxString
& name
) const;
381 unsigned long CountColours( unsigned long stopafter
= (unsigned long) -1 ) const;
383 // Computes the histogram of the image and fills a hash table, indexed
384 // with integer keys built as 0xRRGGBB, containing wxImageHistogramEntry
385 // objects. Each of them contains an 'index' (useful to build a palette
386 // with the image colours) and a 'value', which is the number of pixels
387 // in the image with that colour.
388 // Returned value: # of entries in the histogram
389 unsigned long ComputeHistogram( wxImageHistogram
&h
) const;
391 // Rotates the hue of each pixel of the image. angle is a double in the range
392 // -1.0..1.0 where -1.0 is -360 degrees and 1.0 is 360 degrees
393 void RotateHue(double angle
);
395 static wxList
& GetHandlers() { return sm_handlers
; }
396 static void AddHandler( wxImageHandler
*handler
);
397 static void InsertHandler( wxImageHandler
*handler
);
398 static bool RemoveHandler( const wxString
& name
);
399 static wxImageHandler
*FindHandler( const wxString
& name
);
400 static wxImageHandler
*FindHandler( const wxString
& extension
, long imageType
);
401 static wxImageHandler
*FindHandler( long imageType
);
402 static wxImageHandler
*FindHandlerMime( const wxString
& mimetype
);
404 static wxString
GetImageExtWildcard();
406 static void CleanUpHandlers();
407 static void InitStandardHandlers();
409 static HSVValue
RGBtoHSV(const RGBValue
& rgb
);
410 static RGBValue
HSVtoRGB(const HSVValue
& hsv
);
414 static wxList sm_handlers
;
416 // return the index of the point with the given coordinates or -1 if the
417 // image is invalid of the coordinates are out of range
419 // note that index must be multiplied by 3 when using it with RGB array
420 long XYToIndex(int x
, int y
) const;
422 virtual wxObjectRefData
* CreateRefData() const;
423 virtual wxObjectRefData
* CloneRefData(const wxObjectRefData
* data
) const;
426 friend class WXDLLEXPORT wxImageHandler
;
428 DECLARE_DYNAMIC_CLASS(wxImage
)
432 extern void WXDLLEXPORT
wxInitAllImageHandlers();
434 extern WXDLLEXPORT_DATA(wxImage
) wxNullImage
;
436 //-----------------------------------------------------------------------------
438 //-----------------------------------------------------------------------------
440 #include "wx/imagbmp.h"
441 #include "wx/imagpng.h"
442 #include "wx/imaggif.h"
443 #include "wx/imagpcx.h"
444 #include "wx/imagjpeg.h"
445 #include "wx/imagtga.h"
446 #include "wx/imagtiff.h"
447 #include "wx/imagpnm.h"
448 #include "wx/imagxpm.h"
449 #include "wx/imagiff.h"
451 #endif // wxUSE_IMAGE