// Purpose: interface of wxImageHandler and wxImage
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
wxIMAGE_RESOLUTION_CM = 2
};
+/**
+ Image resize algorithm.
+
+ This is used with wxImage::Scale() and wxImage::Rescale().
+ */
+enum wxImageResizeQuality
+{
+ /// Simplest and fastest algorithm.
+ wxIMAGE_QUALITY_NEAREST,
+
+ /// Compromise between wxIMAGE_QUALITY_NEAREST and wxIMAGE_QUALITY_BICUBIC.
+ wxIMAGE_QUALITY_BILINEAR,
+
+ /// Highest quality but slowest execution time.
+ wxIMAGE_QUALITY_BICUBIC,
+
+ /// Default image resizing algorithm used by wxImage::Scale().
+ wxIMAGE_QUALITY_NORMAL,
+
+ /// Best image resizing algorithm, currently same as wxIMAGE_QUALITY_BICUBIC.
+ wxIMAGE_QUALITY_HIGH
+};
+
/**
Possible values for PNG image type option.
If you wish to extend the capabilities of wxImage, derive a class from
wxImageHandler and add the handler using wxImage::AddHandler in your
- application initialisation.
+ application initialization.
Note that all wxImageHandlers provided by wxWidgets are part of
the @ref page_libs_wxcore library.
::wxNullImage
@library{wxcore}
- @category{misc}
+ @category{gdi}
@see wxImage, wxInitAllImageHandlers()
*/
virtual ~wxImageHandler();
/**
- Gets the file extension associated with this handler.
+ Returns @true if this handler supports the image format contained in the
+ given stream.
+
+ This function doesn't modify the current stream position (because it
+ restores the original position before returning; this however requires the
+ stream to be seekable; see wxStreamBase::IsSeekable).
+ */
+ bool CanRead( wxInputStream& stream );
+
+ /**
+ Returns @true if this handler supports the image format contained in the
+ file with the given name.
+
+ This function doesn't modify the current stream position (because it
+ restores the original position before returning; this however requires the
+ stream to be seekable; see wxStreamBase::IsSeekable).
+ */
+ bool CanRead( const wxString& filename );
+
+ /**
+ Gets the preferred file extension associated with this handler.
+
+ @see GetAltExtensions()
*/
const wxString& GetExtension() const;
+ /**
+ Returns the other file extensions associated with this handler.
+
+ The preferred extension for this handler is returned by GetExtension().
+
+ @since 2.9.0
+ */
+ const wxArrayString& GetAltExtensions() const;
+
/**
If the image file contains more than one image and the image handler is capable
of retrieving these individually, this function will return the number of
@param stream
Opened input stream for reading image data.
- Currently, the stream must support seeking.
+ This function doesn't modify the current stream position (because it
+ restores the original position before returning; this however requires the
+ stream to be seekable; see wxStreamBase::IsSeekable).
@return Number of available images. For most image handlers, this is 1
- (exceptions are TIFF and ICO formats).
+ (exceptions are TIFF and ICO formats as well as animated GIFs
+ for which this function returns the number of frames in the
+ animation).
*/
virtual int GetImageCount(wxInputStream& stream);
bool verbose = true);
/**
- Sets the handler extension.
+ Sets the preferred file extension associated with this handler.
@param extension
- Handler extension.
+ File extension without leading dot.
+
+ @see SetAltExtensions()
*/
void SetExtension(const wxString& extension);
+ /**
+ Sets the alternative file extensions associated with this handler.
+
+ @param extensions
+ Array of file extensions.
+
+ @see SetExtension()
+
+ @since 2.9.0
+ */
+ void SetAltExtensions(const wxArrayString& extensions);
+
/**
Sets the handler MIME type.
The constants ::wxIMAGE_ALPHA_TRANSPARENT and ::wxIMAGE_ALPHA_OPAQUE can be
used to indicate those values in a more readable form.
- Unlike RGB data, not all images have an alpha channel and before using
- wxImage::GetAlpha you should check if this image contains an alpha channel
- with wxImage::HasAlpha. Note that currently only the PNG format has full
- alpha channel support so only the images loaded from PNG files can have
+ While all images have RGB data, not all images have an alpha channel. Before
+ using wxImage::GetAlpha you should check if this image contains an alpha
+ channel with wxImage::HasAlpha. Note that currently only the PNG format has
+ full alpha channel support so only the images loaded from PNG files can have
alpha and, if you initialize the image alpha channel yourself using
wxImage::SetAlpha, you should save it in PNG format to avoid losing it.
class wxImage : public wxObject
{
public:
+ /**
+ A simple class which stores red, green and blue values as 8 bit unsigned integers
+ in the range of 0-255.
+ */
class RGBValue
{
public:
Constructor for RGBValue, an object that contains values for red, green
and blue which represent the value of a color.
- It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which converts
+ It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV, which convert
between HSV color space and RGB color space.
*/
RGBValue(unsigned char r=0, unsigned char g=0, unsigned char b=0);
};
+ /**
+ A simple class which stores hue, saturation and value as doubles in the range 0.0-1.0.
+ */
class HSVValue
{
public:
Constructor for HSVValue, an object that contains values for hue, saturation
and value which represent the value of a color.
- It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which converts
+ It is used by wxImage::HSVtoRGB() and wxImage::RGBtoHSV(), which convert
between HSV color space and RGB color space.
*/
HSVValue(double h=0.0, double s=0.0, double v=0.0);
*/
wxImage(int width, int height, bool clear = true);
+ /**
+ @overload
+ */
+ wxImage(const wxSize& sz, bool clear = true);
+
/**
Creates an image from data in memory. If @a static_data is @false
then the wxImage will take ownership of the data and free it
Indicates if the data should be free'd after use
*/
- wxImage(int width, int height, unsigned char* data, bool static_data = false);
+ wxImage(int width, int height, unsigned char* data, bool static_data = false);
+
+ /**
+ @overload
+ */
+ wxImage(const wxSize& sz, unsigned char* data, bool static_data = false);
/**
Creates an image from data in memory. If @a static_data is @false
wxImage(int width, int height, unsigned char* data, unsigned char* alpha,
bool static_data = false );
+ /**
+ @overload
+ */
+ wxImage(const wxSize& sz, unsigned char* data, unsigned char* data, unsigned char* alpha,
+ bool static_data = false);
+
/**
Creates an image from XPM data.
@param xpmData
A pointer to XPM image data.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
wxImage(const char* const* xpmData);
*/
wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);
-
/**
Destructor.
*/
virtual ~wxImage();
- /**
- Register an image handler.
- */
- static void AddHandler(wxImageHandler* handler);
-
- /**
- Blurs the image in both horizontal and vertical directions by the
- specified pixel @a blurRadius. This should not be used when using
- a single mask colour for transparency.
- @see BlurHorizontal(), BlurVertical()
- */
- wxImage Blur(int blurRadius) const;
/**
- Blurs the image in the horizontal direction only. This should not be used
- when using a single mask colour for transparency.
-
- @see Blur(), BlurVertical()
+ @name Image creation, initialization and deletion functions
*/
- wxImage BlurHorizontal(int blurRadius) const;
+ //@{
/**
- Blurs the image in the vertical direction only. This should not be used
- when using a single mask colour for transparency.
-
- @see Blur(), BlurHorizontal()
+ Returns an identical copy of this image.
*/
- wxImage BlurVertical(int blurRadius) const;
+ wxImage Copy() const;
/**
- Returns @true if the current image handlers can read this file
- */
- static bool CanRead(const wxString& filename);
+ Creates a fresh image.
+ See wxImage::wxImage(int,int,bool) for more info.
- /**
- Deletes all image handlers.
- This function is called by wxWidgets on exit.
+ @return @true if the call succeeded, @false otherwise.
*/
- static void CleanUpHandlers();
+ bool Create(int width, int height, bool clear = true);
/**
- Computes the histogram of the image. @a histogram is a reference to
- wxImageHistogram object. wxImageHistogram is a specialization of
- wxHashMap "template" and is defined as follows:
-
- @code
- class WXDLLEXPORT wxImageHistogramEntry
- {
- public:
- wxImageHistogramEntry() : index(0), value(0) {}
- unsigned long index;
- unsigned long value;
- };
-
- WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
- wxIntegerHash, wxIntegerEqual,
- wxImageHistogram);
- @endcode
-
- @return Returns number of colours in the histogram.
+ @overload
*/
- unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
+ bool Create( const wxSize& sz, bool clear = true );
/**
- If the image has alpha channel, this method converts it to mask.
-
- All pixels with alpha value less than @a threshold are replaced with mask
- colour and the alpha channel is removed. Mask colour is chosen automatically
- using FindFirstUnusedColour().
-
- If the image image doesn't have alpha channel, ConvertAlphaToMask() does nothing.
+ Creates a fresh image.
+ See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
- @return @false if FindFirstUnusedColour returns @false, @true otherwise.
+ @return @true if the call succeeded, @false otherwise.
*/
- bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
+ bool Create( int width, int height, unsigned char* data, bool static_data = false );
/**
- Returns a greyscale version of the image.
-
- The returned image uses the luminance component of the original to
- calculate the greyscale. Defaults to using the standard ITU-T BT.601
- when converting to YUV, where every pixel equals
- (R * @a lr) + (G * @a lg) + (B * @a lb).
+ @overload
*/
- wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
+ bool Create( const wxSize& sz, unsigned char* data, bool static_data = false );
/**
- Returns monochromatic version of the image.
-
- The returned image has white colour where the original has @e (r,g,b)
- colour and black colour everywhere else.
- */
- wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
+ Creates a fresh image.
+ See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
- /**
- Returns an identical copy of the image.
+ @return @true if the call succeeded, @false otherwise.
*/
- wxImage Copy() const;
+ bool Create( int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
/**
- Creates a fresh image.
-
- If @a clear is @true, the new image will be initialized to black.
- Otherwise, the image data will be uninitialized.
-
- @param width
- The width of the image in pixels.
- @param height
- The height of the image in pixels.
- @param clear
- If @true, initialize the image data with zeroes.
-
- @return @true if the call succeeded, @false otherwise.
+ @overload
*/
- bool Create(int width, int height, bool clear = true);
+ bool Create( const wxSize& sz, unsigned char* data, unsigned char* alpha, bool static_data = false );
/**
Initialize the image data with zeroes (the default) or with the
void Destroy();
/**
- Finds the first colour that is never used in the image.
- The search begins at given initial colour and continues by increasing
- R, G and B components (in this order) by 1 until an unused colour is
- found or the colour space exhausted.
+ Initializes the image alpha channel data.
- The parameters @a r, @a g, @a b are pointers to variables to save the colour.
+ It is an error to call it if the image already has alpha data.
+ If it doesn't, alpha data will be by default initialized to all pixels
+ being fully opaque. But if the image has a mask colour, all mask pixels
+ will be completely transparent.
+ */
+ void InitAlpha();
- The parameters @a startR, @a startG, @a startB define the initial values
- of the colour.
- The returned colour will have RGB values equal to or greater than these.
+ //@}
- @return Returns @false if there is no unused colour left, @true on success.
- @note
- This method involves computing the histogram, which is a
- computationally intensive operation.
+ /**
+ @name Image manipulation functions
*/
- bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
- unsigned char* b, unsigned char startR = 1,
- unsigned char startG = 0,
- unsigned char startB = 0) const;
+ //@{
/**
- Finds the handler with the given name.
+ Blurs the image in both horizontal and vertical directions by the
+ specified pixel @a blurRadius. This should not be used when using
+ a single mask colour for transparency.
- @param name
- The handler name.
+ @see BlurHorizontal(), BlurVertical()
+ */
+ wxImage Blur(int blurRadius) const;
- @return A pointer to the handler if found, @NULL otherwise.
+ /**
+ Blurs the image in the horizontal direction only. This should not be used
+ when using a single mask colour for transparency.
- @see wxImageHandler
+ @see Blur(), BlurVertical()
*/
- static wxImageHandler* FindHandler(const wxString& name);
+ wxImage BlurHorizontal(int blurRadius) const;
/**
- Finds the handler associated with the given extension and type.
+ Blurs the image in the vertical direction only. This should not be used
+ when using a single mask colour for transparency.
- @param extension
- The file extension, such as "bmp".
- @param imageType
- The image type; one of the ::wxBitmapType values.
+ @see Blur(), BlurHorizontal()
+ */
+ wxImage BlurVertical(int blurRadius) const;
- @return A pointer to the handler if found, @NULL otherwise.
+ /**
+ Returns a mirrored copy of the image.
+ The parameter @a horizontally indicates the orientation.
+ */
+ wxImage Mirror(bool horizontally = true) const;
- @see wxImageHandler
+ /**
+ Copy the data of the given @a image to the specified position in this image.
*/
- static wxImageHandler* FindHandler(const wxString& extension,
- wxBitmapType imageType);
+ void Paste(const wxImage& image, int x, int y);
/**
- Finds the handler associated with the given image type.
+ Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
+ */
+ void Replace(unsigned char r1, unsigned char g1,
+ unsigned char b1, unsigned char r2,
+ unsigned char g2, unsigned char b2);
- @param imageType
- The image type; one of the ::wxBitmapType values.
+ /**
+ Changes the size of the image in-place by scaling it: after a call to this
+ function,the image will have the given width and height.
- @return A pointer to the handler if found, @NULL otherwise.
+ For a description of the @a quality parameter, see the Scale() function.
+ Returns the (modified) image itself.
- @see wxImageHandler
+ @see Scale()
*/
- static wxImageHandler* FindHandler(wxBitmapType imageType);
+ wxImage& Rescale(int width, int height,
+ wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL);
/**
- Finds the handler associated with the given MIME type.
+ Changes the size of the image in-place without scaling it by adding either a
+ border with the given colour or cropping as necessary.
- @param mimetype
- MIME type.
+ The image is pasted into a new image with the given @a size and background
+ colour at the position @a pos relative to the upper left of the new image.
- @return A pointer to the handler if found, @NULL otherwise.
+ If @a red = green = blue = -1 then use either the current mask colour
+ if set or find, use, and set a suitable mask colour for any newly exposed
+ areas.
- @see wxImageHandler
- */
- static wxImageHandler* FindHandlerMime(const wxString& mimetype);
+ @return The (modified) image itself.
- /**
- Return alpha value at given pixel location.
+ @see Size()
*/
- unsigned char GetAlpha(int x, int y) const;
+ wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1,
+ int green = -1, int blue = -1);
/**
- Returns pointer to the array storing the alpha values for this image.
+ Rotates the image about the given point, by @a angle radians.
- This pointer is @NULL for the images without the alpha channel. If the image
- does have it, this pointer may be used to directly manipulate the alpha values
- which are stored as the RGB ones.
- */
- unsigned char* GetAlpha() const;
+ Passing @true to @a interpolating results in better image quality, but is slower.
- /**
- Returns the blue intensity at the given coordinate.
+ If the image has a mask, then the mask colour is used for the uncovered
+ pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
+
+ Returns the rotated image, leaving this image intact.
*/
- unsigned char GetBlue(int x, int y) const;
+ wxImage Rotate(double angle, const wxPoint& rotationCentre,
+ bool interpolating = true,
+ wxPoint* offsetAfterRotation = NULL) const;
+
+ /**
+ Returns a copy of the image rotated 90 degrees in the direction
+ indicated by @a clockwise.
+ */
+ wxImage Rotate90(bool clockwise = true) const;
+
+ /**
+ Rotates the hue of each pixel in the image by @e angle, which is a double in
+ the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
+ corresponds to +360 degrees.
+ */
+ void RotateHue(double angle);
+
+ /**
+ Returns a scaled version of the image.
+
+ This is also useful for scaling bitmaps in general as the only other way
+ to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
+
+ The parameter @a quality determines what method to use for resampling
+ the image, see wxImageResizeQuality documentation.
+
+ It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
+ looking results it is a slower method. Downsampling will use the box averaging
+ method which seems to operate very fast. If you are upsampling larger images using
+ this method you will most likely notice that it is a bit slower and in extreme
+ cases it will be quite substantially slower as the bicubic algorithm has to process a
+ lot of data.
+
+ It should also be noted that the high quality scaling may not work as expected
+ when using a single mask colour for transparency, as the scaling will blur the
+ image and will therefore remove the mask partially. Using the alpha channel
+ will work.
+
+ Example:
+ @code
+ // get the bitmap from somewhere
+ wxBitmap bmp = ...;
+
+ // rescale it to have size of 32*32
+ if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
+ {
+ wxImage image = bmp.ConvertToImage();
+ bmp = wxBitmap(image.Scale(32, 32));
+
+ // another possibility:
+ image.Rescale(32, 32);
+ bmp = image;
+ }
+ @endcode
+
+ @see Rescale()
+ */
+ wxImage Scale(int width, int height,
+ wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL) const;
+
+ /**
+ Returns a resized version of this image without scaling it by adding either a
+ border with the given colour or cropping as necessary.
+
+ The image is pasted into a new image with the given @a size and background
+ colour at the position @a pos relative to the upper left of the new image.
+
+ If @a red = green = blue = -1 then the areas of the larger image not covered
+ by this image are made transparent by filling them with the image mask colour
+ (which will be allocated automatically if it isn't currently set).
+
+ Otherwise, the areas will be filled with the colour with the specified RGB components.
+
+ @see Resize()
+ */
+ wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
+ int green = -1, int blue = -1) const;
+
+ //@}
+
+
+ /**
+ @name Conversion functions
+ */
+ //@{
+
+ /**
+ If the image has alpha channel, this method converts it to mask.
+
+ If the image has an alpha channel, all pixels with alpha value less
+ than @a threshold are replaced with the mask colour and the alpha
+ channel is removed. Otherwise nothing is done.
+
+ The mask colour is chosen automatically using
+ FindFirstUnusedColour() by this function, see the overload below if you
+ this is not appropriate.
+
+ @return @false if FindFirstUnusedColour returns @false, @true otherwise.
+ */
+ bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
+
+ /**
+ If the image has alpha channel, this method converts it to mask using
+ the specified colour as the mask colour.
+
+ If the image has an alpha channel, all pixels with alpha value less
+ than @a threshold are replaced with the mask colour and the alpha
+ channel is removed. Otherwise nothing is done.
+
+ @since 2.9.0
+
+ @param mr
+ The red component of the mask colour.
+ @param mg
+ The green component of the mask colour.
+ @param mb
+ The blue component of the mask colour.
+ @param threshold
+ Pixels with alpha channel values below the given threshold are
+ considered to be transparent, i.e. the corresponding mask pixels
+ are set. Pixels with the alpha values above the threshold are
+ considered to be opaque.
+
+ */
+ void ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
+ unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
+
+ /**
+ Returns a greyscale version of the image.
+
+ The returned image uses the luminance component of the original to
+ calculate the greyscale. Defaults to using the standard ITU-T BT.601
+ when converting to YUV, where every pixel equals
+ (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
+ */
+ wxImage ConvertToGreyscale(double weight_r, double weight_g, double weight_b) const;
+
+ /**
+ Returns a greyscale version of the image.
+ @since 2.9.0
+ */
+ wxImage ConvertToGreyscale() const;
+
+ /**
+ Returns monochromatic version of the image.
+
+ The returned image has white colour where the original has @e (r,g,b)
+ colour and black colour everywhere else.
+ */
+ wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
+
+ /**
+ Returns disabled (dimmed) version of the image.
+ @since 2.9.0
+ */
+ wxImage ConvertToDisabled(unsigned char brightness = 255) const;
+
+ //@}
+
+
+ /**
+ @name Miscellaneous functions
+ */
+ //@{
+
+ /**
+ Computes the histogram of the image. @a histogram is a reference to
+ wxImageHistogram object. wxImageHistogram is a specialization of
+ wxHashMap "template" and is defined as follows:
+
+ @code
+ class WXDLLEXPORT wxImageHistogramEntry
+ {
+ public:
+ wxImageHistogramEntry() : index(0), value(0) {}
+ unsigned long index;
+ unsigned long value;
+ };
+
+ WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
+ wxIntegerHash, wxIntegerEqual,
+ wxImageHistogram);
+ @endcode
+
+ @return Returns number of colours in the histogram.
+ */
+ unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
+
+ /**
+ Finds the first colour that is never used in the image.
+ The search begins at given initial colour and continues by increasing
+ R, G and B components (in this order) by 1 until an unused colour is
+ found or the colour space exhausted.
+
+ The parameters @a r, @a g, @a b are pointers to variables to save the colour.
+
+ The parameters @a startR, @a startG, @a startB define the initial values
+ of the colour.
+ The returned colour will have RGB values equal to or greater than these.
+
+ @return Returns @false if there is no unused colour left, @true on success.
+
+ @note
+ This method involves computing the histogram, which is a
+ computationally intensive operation.
+ */
+ bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
+ unsigned char* b, unsigned char startR = 1,
+ unsigned char startG = 0,
+ unsigned char startB = 0) const;
+
+ /**
+ Assignment operator, using @ref overview_refcount "reference counting".
+
+ @param image
+ Image to assign.
+
+ @return Returns 'this' object.
+ */
+ wxImage& operator=(const wxImage& image);
+
+ //@}
+
+
+ /**
+ @name Getters
+ */
+ //@{
+
+ /**
+ Returns pointer to the array storing the alpha values for this image.
+
+ This pointer is @NULL for the images without the alpha channel. If the image
+ does have it, this pointer may be used to directly manipulate the alpha values
+ which are stored as the RGB ones.
+ */
+ unsigned char* GetAlpha() const;
/**
Returns the image data as an array.
unsigned char* GetData() const;
/**
- Returns the green intensity at the given coordinate.
+ Return alpha value at given pixel location.
*/
- unsigned char GetGreen(int x, int y) const;
+ unsigned char GetAlpha(int x, int y) const;
/**
- Returns the static list of image format handlers.
-
- @see wxImageHandler
+ Returns the red intensity at the given coordinate.
*/
- static wxList& GetHandlers();
+ unsigned char GetRed(int x, int y) const;
/**
- Gets the height of the image in pixels.
-
- @see GetWidth(), GetSize()
+ Returns the green intensity at the given coordinate.
*/
- int GetHeight() const;
+ unsigned char GetGreen(int x, int y) const;
- //@{
/**
- If the image file contains more than one image and the image handler is
- capable of retrieving these individually, this function will return the
- number of available images.
-
- For the overload taking the parameter @a filename, that's the name
- of the file to query.
- For the overload taking the parameter @a stream, that's the ppened input
- stream with image data. Currently, the stream must support seeking.
-
- The parameter @a type may be one of the following values:
- @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
- @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
- @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
- @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
- @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
- @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
- @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
- @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
- @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
- @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
- @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
- @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
- @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
-
- @return Number of available images. For most image handlers, this is 1
- (exceptions are TIFF and ICO formats).
+ Returns the blue intensity at the given coordinate.
*/
- static int GetImageCount(const wxString& filename,
- wxBitmapType type = wxBITMAP_TYPE_ANY);
- static int GetImageCount(wxInputStream& stream,
- wxBitmapType type = wxBITMAP_TYPE_ANY);
- //@}
+ unsigned char GetBlue(int x, int y) const;
/**
- Iterates all registered wxImageHandler objects, and returns a string containing
- file extension masks suitable for passing to file open/save dialog boxes.
-
- @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
- It is usually a good idea to prepend a description before passing
- the result to the dialog.
- Example:
- @code
- wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
- _("Image Files ") + wxImage::GetImageExtWildcard(),
- wxFD_OPEN );
- @endcode
+ Gets the red value of the mask colour.
+ */
+ unsigned char GetMaskRed() const;
- @see wxImageHandler
+ /**
+ Gets the green value of the mask colour.
*/
- static wxString GetImageExtWildcard();
+ unsigned char GetMaskGreen() const;
/**
Gets the blue value of the mask colour.
unsigned char GetMaskBlue() const;
/**
- Gets the green value of the mask colour.
+ Gets the width of the image in pixels.
+
+ @see GetHeight(), GetSize()
*/
- unsigned char GetMaskGreen() const;
+ int GetWidth() const;
/**
- Gets the red value of the mask colour.
+ Gets the height of the image in pixels.
+
+ @see GetWidth(), GetSize()
*/
- unsigned char GetMaskRed() const;
+ int GetHeight() const;
+
+ /**
+ Returns the size of the image in pixels.
+
+ @since 2.9.0
+
+ @see GetHeight(), GetWidth()
+ */
+ wxSize GetSize() const;
/**
Gets a user-defined string-valued option.
*/
const wxPalette& GetPalette() const;
- /**
- Returns the red intensity at the given coordinate.
- */
- unsigned char GetRed(int x, int y) const;
-
/**
Returns a sub image of the current one as long as the rect belongs entirely
to the image.
*/
wxImage GetSubImage(const wxRect& rect) const;
- /**
- Returns the size of the image in pixels.
-
- @since 2.9.0
-
- @see GetHeight(), GetWidth()
- */
- wxSize GetSize() const;
-
/**
Gets the type of image found by LoadFile() or specified with SaveFile().
*/
wxBitmapType GetType() const;
- /**
- Gets the width of the image in pixels.
-
- @see GetHeight(), GetSize()
- */
- int GetWidth() const;
-
- /**
- Converts a color in HSV color space to RGB color space.
- */
- static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv);
-
/**
Returns @true if this image has alpha channel, @false otherwise.
*/
bool HasOption(const wxString& name) const;
- /**
- Initializes the image alpha channel data.
-
- It is an error to call it if the image already has alpha data.
- If it doesn't, alpha data will be by default initialized to all pixels
- being fully opaque. But if the image has a mask colour, all mask pixels
- will be completely transparent.
- */
- void InitAlpha();
-
- /**
- Internal use only. Adds standard image format handlers.
- It only install wxBMPHandler for the time being, which is used by wxBitmap.
-
- This function is called by wxWidgets on startup, and shouldn't be called by
- the user.
-
- @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
- */
- static void InitStandardHandlers();
-
- /**
- Adds a handler at the start of the static list of format handlers.
-
- @param handler
- A new image format handler object. There is usually only one instance
- of a given handler class in an application session.
-
- @see wxImageHandler
- */
- static void InsertHandler(wxImageHandler* handler);
-
/**
Returns @true if image data is present.
*/
bool IsTransparent(int x, int y,
unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
+ //@}
+
+
+ /**
+ @name Loading and saving functions
+ */
+ //@{
+
/**
Loads an image from an input stream.
virtual bool LoadFile(const wxString& name, const wxString& mimetype,
int index = -1);
-
/**
- Loads an image from an input stream.
-
- @param stream
- Opened input stream from which to load the image.
- Currently, the stream must support seeking.
- @param mimetype
- MIME type string (for example 'image/jpeg')
- @param index
- See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
- */
- virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
- int index = -1);
-
- /**
- Returns a mirrored copy of the image.
- The parameter @a horizontally indicates the orientation.
- */
- wxImage Mirror(bool horizontally = true) const;
-
- /**
- Copy the data of the given @a image to the specified position in this image.
- */
- void Paste(const wxImage& image, int x, int y);
-
- /**
- Converts a color in RGB color space to HSV color space.
- */
- static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
-
- /**
- Finds the handler with the given name, and removes it.
- The handler is not deleted.
-
- @param name
- The handler name.
-
- @return @true if the handler was found and removed, @false otherwise.
-
- @see wxImageHandler
- */
- static bool RemoveHandler(const wxString& name);
-
- /**
- Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2.
- */
- void Replace(unsigned char r1, unsigned char g1,
- unsigned char b1, unsigned char r2,
- unsigned char g2, unsigned char b2);
-
- /**
- Changes the size of the image in-place by scaling it: after a call to this
- function,the image will have the given width and height.
-
- For a description of the @a quality parameter, see the Scale() function.
- Returns the (modified) image itself.
-
- @see Scale()
- */
- wxImage& Rescale(int width, int height,
- int quality = wxIMAGE_QUALITY_NORMAL);
-
- /**
- Changes the size of the image in-place without scaling it by adding either a
- border with the given colour or cropping as necessary.
-
- The image is pasted into a new image with the given @a size and background
- colour at the position @a pos relative to the upper left of the new image.
-
- If @a red = green = blue = -1 then use either the current mask colour
- if set or find, use, and set a suitable mask colour for any newly exposed
- areas.
-
- @return The (modified) image itself.
-
- @see Size()
- */
- wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1,
- int green = -1, int blue = -1);
-
- /**
- Rotates the image about the given point, by @a angle radians.
-
- Passing @true to @a interpolating results in better image quality, but is slower.
-
- If the image has a mask, then the mask colour is used for the uncovered
- pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used.
-
- Returns the rotated image, leaving this image intact.
- */
- wxImage Rotate(double angle, const wxPoint& rotationCentre,
- bool interpolating = true,
- wxPoint* offsetAfterRotation = NULL) const;
-
- /**
- Returns a copy of the image rotated 90 degrees in the direction
- indicated by @a clockwise.
- */
- wxImage Rotate90(bool clockwise = true) const;
-
- /**
- Rotates the hue of each pixel in the image by @e angle, which is a double in
- the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0
- corresponds to +360 degrees.
+ Loads an image from an input stream.
+
+ @param stream
+ Opened input stream from which to load the image.
+ Currently, the stream must support seeking.
+ @param mimetype
+ MIME type string (for example 'image/jpeg')
+ @param index
+ See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
*/
- void RotateHue(double angle);
+ virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
+ int index = -1);
/**
Saves an image in the given stream.
*/
virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
- /**
- Returns a scaled version of the image.
-
- This is also useful for scaling bitmaps in general as the only other way
- to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
-
- The parameter @a quality determines what method to use for resampling the image.
- Can be one of the following:
- - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
- replication
- - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
- for upsampling and downsampling respectively
-
- It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
- looking results it is a slower method. Downsampling will use the box averaging
- method which seems to operate very fast. If you are upsampling larger images using
- this method you will most likely notice that it is a bit slower and in extreme
- cases it will be quite substantially slower as the bicubic algorithm has to process a
- lot of data.
-
- It should also be noted that the high quality scaling may not work as expected
- when using a single mask colour for transparency, as the scaling will blur the
- image and will therefore remove the mask partially. Using the alpha channel
- will work.
-
- Example:
- @code
- // get the bitmap from somewhere
- wxBitmap bmp = ...;
+ //@}
- // rescale it to have size of 32*32
- if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
- {
- wxImage image = bmp.ConvertToImage();
- bmp = wxBitmap(image.Scale(32, 32));
- // another possibility:
- image.Rescale(32, 32);
- bmp = image;
- }
- @endcode
- @see Rescale()
+ /**
+ @name Setters
*/
- wxImage Scale(int width, int height,
- int quality = wxIMAGE_QUALITY_NORMAL) const;
+ //@{
/**
This function is similar to SetData() and has similar restrictions.
*/
void SetAlpha(int x, int y, unsigned char alpha);
- //@{
+ /**
+ Removes the alpha channel from the image.
+
+ This function should only be called if the image has alpha channel data,
+ use HasAlpha() to check for this.
+
+ @since 2.9.1
+ */
+ void ClearAlpha();
+
/**
Sets the image data without performing checks.
The data must have been allocated with @c malloc(), @b NOT with
@c operator new.
- After this call the pointer to the data is owned by the wxImage object,
- that will be responsible for deleting it.
+ If @a static_data is @false, after this call the pointer to the data is
+ owned by the wxImage object, that will be responsible for deleting it.
Do not pass to this function a pointer obtained through GetData().
*/
void SetData(unsigned char* data, bool static_data = false);
+
+ /**
+ @overload
+ */
void SetData(unsigned char* data, int new_width, int new_height,
bool static_data = false);
- //@}
/**
Specifies whether there is a mask or not.
unsigned char mg,
unsigned char mb);
- //@{
/**
Sets a user-defined option. The function is case-insensitive to @a name.
@see GetOption(), GetOptionInt(), HasOption()
*/
void SetOption(const wxString& name, const wxString& value);
+
+ /**
+ @overload
+ */
void SetOption(const wxString& name, int value);
- //@}
/**
Associates a palette with the image.
*/
void SetType(wxBitmapType type);
+ //@}
+
+
+
/**
- Returns a resized version of this image without scaling it by adding either a
- border with the given colour or cropping as necessary.
+ @name Handler management functions
+ */
+ //@{
- The image is pasted into a new image with the given @a size and background
- colour at the position @a pos relative to the upper left of the new image.
+ /**
+ Register an image handler.
+ See @ref image_handlers for a list of the available handlers.
+ */
+ static void AddHandler(wxImageHandler* handler);
- If @a red = green = blue = -1 then the areas of the larger image not covered
- by this image are made transparent by filling them with the image mask colour
- (which will be allocated automatically if it isn't currently set).
+ /**
+ Deletes all image handlers.
+ This function is called by wxWidgets on exit.
+ */
+ static void CleanUpHandlers();
- Otherwise, the areas will be filled with the colour with the specified RGB components.
+ /**
+ Finds the handler with the given name.
- @see Resize()
+ @param name
+ The handler name.
+
+ @return A pointer to the handler if found, @NULL otherwise.
+
+ @see wxImageHandler
*/
- wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
- int green = -1, int blue = -1) const;
+ static wxImageHandler* FindHandler(const wxString& name);
/**
- Assignment operator, using @ref overview_refcount "reference counting".
+ Finds the handler associated with the given extension and type.
- @param image
- Image to assign.
+ @param extension
+ The file extension, such as "bmp".
+ @param imageType
+ The image type; one of the ::wxBitmapType values.
- @return Returns 'this' object.
+ @return A pointer to the handler if found, @NULL otherwise.
+
+ @see wxImageHandler
*/
- wxImage& operator=(const wxImage& image);
+ static wxImageHandler* FindHandler(const wxString& extension,
+ wxBitmapType imageType);
+
+ /**
+ Finds the handler associated with the given image type.
+
+ @param imageType
+ The image type; one of the ::wxBitmapType values.
+
+ @return A pointer to the handler if found, @NULL otherwise.
+
+ @see wxImageHandler
+ */
+ static wxImageHandler* FindHandler(wxBitmapType imageType);
+
+ /**
+ Finds the handler associated with the given MIME type.
+
+ @param mimetype
+ MIME type.
+
+ @return A pointer to the handler if found, @NULL otherwise.
+
+ @see wxImageHandler
+ */
+ static wxImageHandler* FindHandlerMime(const wxString& mimetype);
+
+ /**
+ Returns the static list of image format handlers.
+
+ @see wxImageHandler
+ */
+ static wxList& GetHandlers();
+
+ /**
+ Internal use only. Adds standard image format handlers.
+ It only install wxBMPHandler for the time being, which is used by wxBitmap.
+
+ This function is called by wxWidgets on startup, and shouldn't be called by
+ the user.
+
+ @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
+ */
+ static void InitStandardHandlers();
+
+ /**
+ Adds a handler at the start of the static list of format handlers.
+
+ @param handler
+ A new image format handler object. There is usually only one instance
+ of a given handler class in an application session.
+
+ @see wxImageHandler
+ */
+ static void InsertHandler(wxImageHandler* handler);
+
+ /**
+ Finds the handler with the given name, and removes it.
+ The handler is not deleted.
+
+ @param name
+ The handler name.
+
+ @return @true if the handler was found and removed, @false otherwise.
+
+ @see wxImageHandler
+ */
+ static bool RemoveHandler(const wxString& name);
+
+ //@}
+
+
+ /**
+ Returns @true if at least one of the available image handlers can read
+ the file with the given name.
+
+ See wxImageHandler::CanRead for more info.
+ */
+ static bool CanRead(const wxString& filename);
+
+ /**
+ Returns @true if at least one of the available image handlers can read
+ the data in the given stream.
+
+ See wxImageHandler::CanRead for more info.
+ */
+ static bool CanRead(wxInputStream& stream);
+
+ //@{
+ /**
+ If the image file contains more than one image and the image handler is
+ capable of retrieving these individually, this function will return the
+ number of available images.
+
+ For the overload taking the parameter @a filename, that's the name
+ of the file to query.
+ For the overload taking the parameter @a stream, that's the opened input
+ stream with image data.
+
+ See wxImageHandler::GetImageCount() for more info.
+
+ The parameter @a type may be one of the following values:
+ @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
+ @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
+ @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
+ @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
+ @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
+ @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
+ @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
+ @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
+ @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
+ @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
+ @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
+ @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
+ @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
+
+ @return Number of available images. For most image handlers, this is 1
+ (exceptions are TIFF and ICO formats as well as animated GIFs
+ for which this function returns the number of frames in the
+ animation).
+ */
+ static int GetImageCount(const wxString& filename,
+ wxBitmapType type = wxBITMAP_TYPE_ANY);
+ static int GetImageCount(wxInputStream& stream,
+ wxBitmapType type = wxBITMAP_TYPE_ANY);
+ //@}
+
+ /**
+ Iterates all registered wxImageHandler objects, and returns a string containing
+ file extension masks suitable for passing to file open/save dialog boxes.
+
+ @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2".
+ It is usually a good idea to prepend a description before passing
+ the result to the dialog.
+ Example:
+ @code
+ wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "",
+ _("Image Files ") + wxImage::GetImageExtWildcard(),
+ wxFD_OPEN );
+ @endcode
+
+ @see wxImageHandler
+ */
+ static wxString GetImageExtWildcard();
+
+ /**
+ Converts a color in RGB color space to HSV color space.
+ */
+ static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
+
+ /**
+ Converts a color in HSV color space to RGB color space.
+ */
+ static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv);
};
/**
/**
Initializes all available image handlers. For a list of available handlers,
see wxImage.
+ If you don't need/want all image handlers loaded
@see wxImage, wxImageHandler
projects / wxWidgets.git / blobdiff