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 #define wxIMAGE_OPTION_MAX_WIDTH wxString(_T("MaxWidth"))
40 #define wxIMAGE_OPTION_MAX_HEIGHT wxString(_T("MaxHeight"))
42 // constants used with wxIMAGE_OPTION_RESOLUTIONUNIT
44 // NB: don't change these values, they correspond to libjpeg constants
45 enum wxImageResolution
47 // Resolution not specified
48 wxIMAGE_RESOLUTION_NONE
= 0,
50 // Resolution specified in inches
51 wxIMAGE_RESOLUTION_INCHES
= 1,
53 // Resolution specified in centimeters
54 wxIMAGE_RESOLUTION_CM
= 2
57 // Constants for wxImage::Scale() for determining the level of quality
60 wxIMAGE_QUALITY_NORMAL
= 0,
61 wxIMAGE_QUALITY_HIGH
= 1
64 // alpha channel values: fully transparent, default threshold separating
65 // transparent pixels from opaque for a few functions dealing with alpha and
67 const unsigned char wxIMAGE_ALPHA_TRANSPARENT
= 0;
68 const unsigned char wxIMAGE_ALPHA_THRESHOLD
= 0x80;
69 const unsigned char wxIMAGE_ALPHA_OPAQUE
= 0xff;
71 //-----------------------------------------------------------------------------
73 //-----------------------------------------------------------------------------
75 class WXDLLIMPEXP_FWD_CORE wxImageHandler
;
76 class WXDLLIMPEXP_FWD_CORE wxImage
;
77 class WXDLLIMPEXP_FWD_CORE wxPalette
;
79 //-----------------------------------------------------------------------------
81 //-----------------------------------------------------------------------------
84 #include "wx/variant.h"
85 DECLARE_VARIANT_OBJECT_EXPORTED(wxImage
,WXDLLIMPEXP_CORE
)
88 //-----------------------------------------------------------------------------
90 //-----------------------------------------------------------------------------
92 class WXDLLIMPEXP_CORE wxImageHandler
: public wxObject
96 : m_name(wxEmptyString
), m_extension(wxEmptyString
), m_mime(), m_type(wxBITMAP_TYPE_INVALID
)
100 // NOTE: LoadFile and SaveFile are not pure virtuals to allow derived classes
101 // to implement only one of the two
102 virtual bool LoadFile( wxImage
*WXUNUSED(image
), wxInputStream
& WXUNUSED(stream
),
103 bool WXUNUSED(verbose
)=true, int WXUNUSED(index
)=-1 )
105 virtual bool SaveFile( wxImage
*WXUNUSED(image
), wxOutputStream
& WXUNUSED(stream
),
106 bool WXUNUSED(verbose
)=true )
109 int GetImageCount( wxInputStream
& stream
);
110 // save the stream position, call DoGetImageCount() and restore the position
112 bool CanRead( wxInputStream
& stream
) { return CallDoCanRead(stream
); }
113 bool CanRead( const wxString
& name
);
114 #endif // wxUSE_STREAMS
116 void SetName(const wxString
& name
) { m_name
= name
; }
117 void SetExtension(const wxString
& ext
) { m_extension
= ext
; }
118 void SetAltExtensions(const wxArrayString
& exts
) { m_altExtensions
= exts
; }
119 void SetType(wxBitmapType type
) { m_type
= type
; }
120 void SetMimeType(const wxString
& type
) { m_mime
= type
; }
121 const wxString
& GetName() const { return m_name
; }
122 const wxString
& GetExtension() const { return m_extension
; }
123 const wxArrayString
& GetAltExtensions() const { return m_altExtensions
; }
124 wxBitmapType
GetType() const { return m_type
; }
125 const wxString
& GetMimeType() const { return m_mime
; }
127 #if WXWIN_COMPATIBILITY_2_8
129 void SetType(long type
) { SetType((wxBitmapType
)type
); }
131 #endif // WXWIN_COMPATIBILITY_2_8
135 // NOTE: this function is allowed to change the current stream position
136 // since GetImageCount() will take care of restoring it later
137 virtual int DoGetImageCount( wxInputStream
& WXUNUSED(stream
) )
138 { return 1; } // default return value is 1 image
140 // NOTE: this function is allowed to change the current stream position
141 // since CallDoCanRead() will take care of restoring it later
142 virtual bool DoCanRead( wxInputStream
& stream
) = 0;
144 // save the stream position, call DoCanRead() and restore the position
145 bool CallDoCanRead(wxInputStream
& stream
);
146 #endif // wxUSE_STREAMS
148 // helper for the derived classes SaveFile() implementations: returns the
149 // values of x- and y-resolution options specified as the image options if
151 static wxImageResolution
152 GetResolutionFromOptions(const wxImage
& image
, int *x
, int *y
);
156 wxString m_extension
;
157 wxArrayString m_altExtensions
;
162 DECLARE_CLASS(wxImageHandler
)
165 //-----------------------------------------------------------------------------
167 //-----------------------------------------------------------------------------
169 class WXDLLIMPEXP_CORE wxImageHistogramEntry
172 wxImageHistogramEntry() { index
= value
= 0; }
177 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry
,
178 wxIntegerHash
, wxIntegerEqual
,
179 wxImageHistogramBase
);
181 class WXDLLIMPEXP_CORE wxImageHistogram
: public wxImageHistogramBase
184 wxImageHistogram() : wxImageHistogramBase(256) { }
186 // get the key in the histogram for the given RGB values
187 static unsigned long MakeKey(unsigned char r
,
191 return (r
<< 16) | (g
<< 8) | b
;
194 // find first colour that is not used in the image and has higher
195 // RGB values than RGB(startR, startG, startB)
197 // returns true and puts this colour in r, g, b (each of which may be NULL)
198 // on success or returns false if there are no more free colours
199 bool FindFirstUnusedColour(unsigned char *r
,
202 unsigned char startR
= 1,
203 unsigned char startG
= 0,
204 unsigned char startB
= 0 ) const;
207 //-----------------------------------------------------------------------------
209 //-----------------------------------------------------------------------------
211 class WXDLLIMPEXP_CORE wxImage
: public wxObject
214 // red, green and blue are 8 bit unsigned integers in the range of 0..255
215 // We use the identifier RGBValue instead of RGB, since RGB is #defined
219 RGBValue(unsigned char r
=0, unsigned char g
=0, unsigned char b
=0)
220 : red(r
), green(g
), blue(b
) {}
226 // hue, saturation and value are doubles in the range 0.0..1.0
230 HSVValue(double h
=0.0, double s
=0.0, double v
=0.0)
231 : hue(h
), saturation(s
), value(v
) {}
238 wxImage( int width
, int height
, bool clear
= true )
239 { Create( width
, height
, clear
); }
240 wxImage( int width
, int height
, unsigned char* data
, bool static_data
= false )
241 { Create( width
, height
, data
, static_data
); }
242 wxImage( int width
, int height
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false )
243 { Create( width
, height
, data
, alpha
, static_data
); }
245 // ctor variants using wxSize:
246 wxImage( const wxSize
& sz
, bool clear
= true )
247 { Create( sz
, clear
); }
248 wxImage( const wxSize
& sz
, unsigned char* data
, bool static_data
= false )
249 { Create( sz
, data
, static_data
); }
250 wxImage( const wxSize
& sz
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false )
251 { Create( sz
, data
, alpha
, static_data
); }
253 wxImage( const wxString
& name
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1 )
254 { LoadFile( name
, type
, index
); }
255 wxImage( const wxString
& name
, const wxString
& mimetype
, int index
= -1 )
256 { LoadFile( name
, mimetype
, index
); }
257 wxImage( const char* const* xpmData
)
261 wxImage( wxInputStream
& stream
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1 )
262 { LoadFile( stream
, type
, index
); }
263 wxImage( wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1 )
264 { LoadFile( stream
, mimetype
, index
); }
265 #endif // wxUSE_STREAMS
267 bool Create( const char* const* xpmData
);
269 // needed for Borland 5.5
270 wxImage( char** xpmData
) { Create(const_cast<const char* const*>(xpmData
)); }
271 bool Create( char** xpmData
) { return Create(const_cast<const char* const*>(xpmData
)); }
274 bool Create( int width
, int height
, bool clear
= true );
275 bool Create( int width
, int height
, unsigned char* data
, bool static_data
= false );
276 bool Create( int width
, int height
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false );
278 // Create() variants using wxSize:
279 bool Create( const wxSize
& sz
, bool clear
= true )
280 { return Create(sz
.GetWidth(), sz
.GetHeight(), clear
); }
281 bool Create( const wxSize
& sz
, unsigned char* data
, bool static_data
= false )
282 { return Create(sz
.GetWidth(), sz
.GetHeight(), data
, static_data
); }
283 bool Create( const wxSize
& sz
, unsigned char* data
, unsigned char* alpha
, bool static_data
= false )
284 { return Create(sz
.GetWidth(), sz
.GetHeight(), data
, alpha
, static_data
); }
288 // initialize the image data with zeroes
289 void Clear(unsigned char value
= 0);
291 // creates an identical copy of the image (the = operator
292 // just raises the ref count)
293 wxImage
Copy() const;
295 // return the new image with size width*height
296 wxImage
GetSubImage( const wxRect
& rect
) const;
298 // Paste the image or part of this image into an image of the given size at the pos
299 // any newly exposed areas will be filled with the rgb colour
300 // by default if r = g = b = -1 then fill with this image's mask colour or find and
301 // set a suitable mask colour
302 wxImage
Size( const wxSize
& size
, const wxPoint
& pos
,
303 int r
= -1, int g
= -1, int b
= -1 ) const;
305 // pastes image into this instance and takes care of
306 // the mask colour and out of bounds problems
307 void Paste( const wxImage
&image
, int x
, int y
);
309 // return the new image with size width*height
310 wxImage
Scale( int width
, int height
, int quality
= wxIMAGE_QUALITY_NORMAL
) const;
312 // box averager and bicubic filters for up/down sampling
313 wxImage
ResampleBox(int width
, int height
) const;
314 wxImage
ResampleBicubic(int width
, int height
) const;
316 // blur the image according to the specified pixel radius
317 wxImage
Blur(int radius
) const;
318 wxImage
BlurHorizontal(int radius
) const;
319 wxImage
BlurVertical(int radius
) const;
321 wxImage
ShrinkBy( int xFactor
, int yFactor
) const ;
323 // rescales the image in place
324 wxImage
& Rescale( int width
, int height
, int quality
= wxIMAGE_QUALITY_NORMAL
) { return *this = Scale(width
, height
, quality
); }
326 // resizes the image in place
327 wxImage
& Resize( const wxSize
& size
, const wxPoint
& pos
,
328 int r
= -1, int g
= -1, int b
= -1 ) { return *this = Size(size
, pos
, r
, g
, b
); }
330 // Rotates the image about the given point, 'angle' radians.
331 // Returns the rotated image, leaving this image intact.
332 wxImage
Rotate(double angle
, const wxPoint
& centre_of_rotation
,
333 bool interpolating
= true, wxPoint
* offset_after_rotation
= NULL
) const;
335 wxImage
Rotate90( bool clockwise
= true ) const;
336 wxImage
Mirror( bool horizontally
= true ) const;
338 // replace one colour with another
339 void Replace( unsigned char r1
, unsigned char g1
, unsigned char b1
,
340 unsigned char r2
, unsigned char g2
, unsigned char b2
);
342 // Convert to greyscale image. Uses the luminance component (Y) of the image.
343 // The luma value (YUV) is calculated using (R * lr) + (G * lg) + (B * lb), defaults to ITU-T BT.601
344 wxImage
ConvertToGreyscale( double lr
= 0.299, double lg
= 0.587, double lb
= 0.114 ) const;
346 // convert to monochrome image (<r,g,b> will be replaced by white,
347 // everything else by black)
348 wxImage
ConvertToMono( unsigned char r
, unsigned char g
, unsigned char b
) const;
350 // these routines are slow but safe
351 void SetRGB( int x
, int y
, unsigned char r
, unsigned char g
, unsigned char b
);
352 void SetRGB( const wxRect
& rect
, unsigned char r
, unsigned char g
, unsigned char b
);
353 unsigned char GetRed( int x
, int y
) const;
354 unsigned char GetGreen( int x
, int y
) const;
355 unsigned char GetBlue( int x
, int y
) const;
357 void SetAlpha(int x
, int y
, unsigned char alpha
);
358 unsigned char GetAlpha(int x
, int y
) const;
360 // find first colour that is not used in the image and has higher
361 // RGB values than <startR,startG,startB>
362 bool FindFirstUnusedColour( unsigned char *r
, unsigned char *g
, unsigned char *b
,
363 unsigned char startR
= 1, unsigned char startG
= 0,
364 unsigned char startB
= 0 ) const;
365 // Set image's mask to the area of 'mask' that has <r,g,b> colour
366 bool SetMaskFromImage(const wxImage
& mask
,
367 unsigned char mr
, unsigned char mg
, unsigned char mb
);
369 // converts image's alpha channel to mask (choosing mask colour
370 // automatically or using the specified colour for the mask), if it has
371 // any, does nothing otherwise:
372 bool ConvertAlphaToMask(unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
373 void ConvertAlphaToMask(unsigned char mr
, unsigned char mg
, unsigned char mb
,
374 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
);
377 // This method converts an image where the original alpha
378 // information is only available as a shades of a colour
379 // (actually shades of grey) typically when you draw anti-
380 // aliased text into a bitmap. The DC drawinf routines
381 // draw grey values on the black background although they
382 // actually mean to draw white with differnt alpha values.
383 // This method reverses it, assuming a black (!) background
384 // and white text (actually only the red channel is read).
385 // The method will then fill up the whole image with the
387 bool ConvertColourToAlpha( unsigned char r
, unsigned char g
, unsigned char b
);
389 static bool CanRead( const wxString
& name
);
390 static int GetImageCount( const wxString
& name
, wxBitmapType type
= wxBITMAP_TYPE_ANY
);
391 virtual bool LoadFile( const wxString
& name
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1 );
392 virtual bool LoadFile( const wxString
& name
, const wxString
& mimetype
, int index
= -1 );
395 static bool CanRead( wxInputStream
& stream
);
396 static int GetImageCount( wxInputStream
& stream
, wxBitmapType type
= wxBITMAP_TYPE_ANY
);
397 virtual bool LoadFile( wxInputStream
& stream
, wxBitmapType type
= wxBITMAP_TYPE_ANY
, int index
= -1 );
398 virtual bool LoadFile( wxInputStream
& stream
, const wxString
& mimetype
, int index
= -1 );
401 virtual bool SaveFile( const wxString
& name
) const;
402 virtual bool SaveFile( const wxString
& name
, wxBitmapType type
) const;
403 virtual bool SaveFile( const wxString
& name
, const wxString
& mimetype
) const;
406 virtual bool SaveFile( wxOutputStream
& stream
, wxBitmapType type
) const;
407 virtual bool SaveFile( wxOutputStream
& stream
, const wxString
& mimetype
) const;
410 bool Ok() const { return IsOk(); }
412 int GetWidth() const;
413 int GetHeight() const;
415 wxSize
GetSize() const
416 { return wxSize(GetWidth(), GetHeight()); }
418 // Gets the type of image found by LoadFile or specified with SaveFile
419 wxBitmapType
GetType() const;
421 // Set the image type, this is normally only called if the image is being
422 // created from data in the given format but not using LoadFile() (e.g.
423 // wxGIFDecoder uses this)
424 void SetType(wxBitmapType type
);
426 // these functions provide fastest access to wxImage data but should be
427 // used carefully as no checks are done
428 unsigned char *GetData() const;
429 void SetData( unsigned char *data
, bool static_data
=false );
430 void SetData( unsigned char *data
, int new_width
, int new_height
, bool static_data
=false );
432 unsigned char *GetAlpha() const; // may return NULL!
433 bool HasAlpha() const { return GetAlpha() != NULL
; }
434 void SetAlpha(unsigned char *alpha
= NULL
, bool static_data
=false);
437 // return true if this pixel is masked or has alpha less than specified
439 bool IsTransparent(int x
, int y
,
440 unsigned char threshold
= wxIMAGE_ALPHA_THRESHOLD
) const;
443 void SetMaskColour( unsigned char r
, unsigned char g
, unsigned char b
);
444 // Get the current mask colour or find a suitable colour
445 // returns true if using current mask colour
446 bool GetOrFindMaskColour( unsigned char *r
, unsigned char *g
, unsigned char *b
) const;
447 unsigned char GetMaskRed() const;
448 unsigned char GetMaskGreen() const;
449 unsigned char GetMaskBlue() const;
450 void SetMask( bool mask
= true );
451 bool HasMask() const;
455 bool HasPalette() const;
456 const wxPalette
& GetPalette() const;
457 void SetPalette(const wxPalette
& palette
);
458 #endif // wxUSE_PALETTE
460 // Option functions (arbitrary name/value mapping)
461 void SetOption(const wxString
& name
, const wxString
& value
);
462 void SetOption(const wxString
& name
, int value
);
463 wxString
GetOption(const wxString
& name
) const;
464 int GetOptionInt(const wxString
& name
) const;
465 bool HasOption(const wxString
& name
) const;
467 unsigned long CountColours( unsigned long stopafter
= (unsigned long) -1 ) const;
469 // Computes the histogram of the image and fills a hash table, indexed
470 // with integer keys built as 0xRRGGBB, containing wxImageHistogramEntry
471 // objects. Each of them contains an 'index' (useful to build a palette
472 // with the image colours) and a 'value', which is the number of pixels
473 // in the image with that colour.
474 // Returned value: # of entries in the histogram
475 unsigned long ComputeHistogram( wxImageHistogram
&h
) const;
477 // Rotates the hue of each pixel of the image. angle is a double in the range
478 // -1.0..1.0 where -1.0 is -360 degrees and 1.0 is 360 degrees
479 void RotateHue(double angle
);
481 static wxList
& GetHandlers() { return sm_handlers
; }
482 static void AddHandler( wxImageHandler
*handler
);
483 static void InsertHandler( wxImageHandler
*handler
);
484 static bool RemoveHandler( const wxString
& name
);
485 static wxImageHandler
*FindHandler( const wxString
& name
);
486 static wxImageHandler
*FindHandler( const wxString
& extension
, wxBitmapType imageType
);
487 static wxImageHandler
*FindHandler( wxBitmapType imageType
);
489 static wxImageHandler
*FindHandlerMime( const wxString
& mimetype
);
491 static wxString
GetImageExtWildcard();
493 static void CleanUpHandlers();
494 static void InitStandardHandlers();
496 static HSVValue
RGBtoHSV(const RGBValue
& rgb
);
497 static RGBValue
HSVtoRGB(const HSVValue
& hsv
);
499 #if WXWIN_COMPATIBILITY_2_8
500 wxDEPRECATED_CONSTRUCTOR(
501 wxImage(const wxString
& name
, long type
, int index
= -1)
503 LoadFile(name
, (wxBitmapType
)type
, index
);
508 wxDEPRECATED_CONSTRUCTOR(
509 wxImage(wxInputStream
& stream
, long type
, int index
= -1)
511 LoadFile(stream
, (wxBitmapType
)type
, index
);
516 bool LoadFile(wxInputStream
& stream
, long type
, int index
= -1)
518 return LoadFile(stream
, (wxBitmapType
)type
, index
);
523 bool SaveFile(wxOutputStream
& stream
, long type
) const
525 return SaveFile(stream
, (wxBitmapType
)type
);
528 #endif // wxUSE_STREAMS
531 bool LoadFile(const wxString
& name
, long type
, int index
= -1)
533 return LoadFile(name
, (wxBitmapType
)type
, index
);
538 bool SaveFile(const wxString
& name
, long type
) const
540 return SaveFile(name
, (wxBitmapType
)type
);
545 static wxImageHandler
*FindHandler(const wxString
& ext
, long type
)
547 return FindHandler(ext
, (wxBitmapType
)type
);
552 static wxImageHandler
*FindHandler(long imageType
)
554 return FindHandler((wxBitmapType
)imageType
);
557 #endif // WXWIN_COMPATIBILITY_2_8
560 static wxList sm_handlers
;
562 // return the index of the point with the given coordinates or -1 if the
563 // image is invalid of the coordinates are out of range
565 // note that index must be multiplied by 3 when using it with RGB array
566 long XYToIndex(int x
, int y
) const;
568 virtual wxObjectRefData
* CreateRefData() const;
569 virtual wxObjectRefData
* CloneRefData(const wxObjectRefData
* data
) const;
572 friend class WXDLLIMPEXP_FWD_CORE wxImageHandler
;
575 // read the image from the specified stream updating image type if
577 bool DoLoad(wxImageHandler
& handler
, wxInputStream
& stream
, int index
);
579 // write the image to the specified stream and also update the image type
581 bool DoSave(wxImageHandler
& handler
, wxOutputStream
& stream
) const;
582 #endif // wxUSE_STREAMS
584 DECLARE_DYNAMIC_CLASS(wxImage
)
588 extern void WXDLLIMPEXP_CORE
wxInitAllImageHandlers();
590 extern WXDLLIMPEXP_DATA_CORE(wxImage
) wxNullImage
;
592 //-----------------------------------------------------------------------------
594 //-----------------------------------------------------------------------------
596 #include "wx/imagbmp.h"
597 #include "wx/imagpng.h"
598 #include "wx/imaggif.h"
599 #include "wx/imagpcx.h"
600 #include "wx/imagjpeg.h"
601 #include "wx/imagtga.h"
602 #include "wx/imagtiff.h"
603 #include "wx/imagpnm.h"
604 #include "wx/imagxpm.h"
605 #include "wx/imagiff.h"
607 #endif // wxUSE_IMAGE