// 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.
*/
virtual ~wxImageHandler();
+ /**
+ 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.
@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 as well as animated GIFs
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.
{
public:
/**
- A simple class which stores red, green and blue values as 8 bit unsigned integers
+ A simple class which stores red, green and blue values as 8 bit unsigned integers
in the range of 0-255.
*/
class RGBValue
If @true, initialize the image to black.
*/
wxImage(int width, int height, bool clear = true);
-
+
/**
@overload
*/
@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
then the wxImage will take ownership of the data and free it
*/
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);
*/
virtual ~wxImage();
-
-
+
+
/**
@name Image creation, initialization and deletion functions
*/
//@{
-
+
/**
Returns an identical copy of this image.
*/
/**
Creates a fresh image.
See wxImage::wxImage(int,int,unsigned char*,bool) for more info.
-
+
@return @true if the call succeeded, @false otherwise.
*/
bool Create( int width, int height, unsigned char* data, bool static_data = false );
/**
Creates a fresh image.
See wxImage::wxImage(int,int,unsigned char*,unsigned char*,bool) for more info.
-
+
@return @true if the call succeeded, @false otherwise.
*/
bool Create( int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
-
+
/**
@overload
*/
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
byte value given as @a value.
Destroys the image data.
*/
void Destroy();
-
+
/**
Initializes the image alpha channel data.
@see Scale()
*/
wxImage& Rescale(int width, int height,
- int quality = wxIMAGE_QUALITY_NORMAL);
+ wxImageResizeQuality quality = wxIMAGE_QUALITY_NORMAL);
/**
Changes the size of the image in-place without scaling it by adding either a
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
+ 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
@see Rescale()
*/
wxImage Scale(int width, int height,
- int quality = wxIMAGE_QUALITY_NORMAL) const;
-
+ 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.
FindFirstUnusedColour() by this function, see the overload below if you
this is not appropriate.
- @return @false if FindFirstUnusedColour returns @false, @true otherwise.
+ @return Returns @true on success, @false on error.
*/
bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
are set. Pixels with the alpha values above the threshold are
considered to be opaque.
+ @return Returns @true on success, @false on error.
*/
- void ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
+ bool ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
/**
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).
+ (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
*/
- wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
+ 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.
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
@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
@return Returns 'this' object.
*/
wxImage& operator=(const wxImage& image);
-
+
//@}
-
-
+
+
/**
@name Getters
*/
@see GetHeight(), GetWidth()
*/
wxSize GetSize() const;
-
+
/**
Gets a user-defined string-valued option.
*/
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.
- If @a static_data is @false, after this call the pointer to the data is
+ 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
*/
@see GetOption(), GetOptionInt(), HasOption()
*/
void SetOption(const wxString& name, const wxString& value);
-
- /**
+
+ /**
@overload
*/
void SetOption(const wxString& name, int value);
void SetType(wxBitmapType type);
//@}
-
-
-
+
+
+
/**
@name Handler management functions
*/
//@{
-
+
/**
Register an image handler.
See @ref image_handlers for a list of the available handlers.
This function is called by wxWidgets on exit.
*/
static void CleanUpHandlers();
-
+
/**
Finds the handler with the given name.
@see wxImageHandler
*/
static bool RemoveHandler(const wxString& name);
-
+
//@}
-
-
+
+
/**
- Returns @true if the current image handlers can read this file
+ 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
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.
+ 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.
@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.
*/
/**
Initializes all available image handlers. For a list of available handlers,
see wxImage.
- If you don't need/want all image handlers loaded
+ If you don't need/want all image handlers loaded
@see wxImage, wxImageHandler
projects / wxWidgets.git / blobdiff