// 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,
+
+ /**
+ Use surrounding pixels to calculate an average that will be used for
+ new pixels. This method is typically used when reducing the size of
+ an image.
+ */
+ wxIMAGE_QUALITY_BOX_AVERAGE,
+
+ /**
+ Default image resizing algorithm used by wxImage::Scale(). Currently
+ the same as wxIMAGE_QUALITY_NEAREST.
+ */
+ wxIMAGE_QUALITY_NORMAL,
+
+ /**
+ Best image resizing algorithm. Since version 2.9.2 this results in
+ wxIMAGE_QUALITY_BOX_AVERAGE being used when reducing the size of the
+ image (meaning that both the new width and height will be smaller than
+ the original size). Otherwise wxIMAGE_QUALITY_BICUBIC is used.
+ */
+ wxIMAGE_QUALITY_HIGH
+};
+
/**
Possible values for PNG image type option.
{
wxPNG_TYPE_COLOUR = 0, ///< Colour PNG image.
wxPNG_TYPE_GREY = 2, ///< Greyscale PNG image converted from RGB.
- wxPNG_TYPE_GREY_RED = 3 ///< Greyscale PNG image using red as grey.
+ wxPNG_TYPE_GREY_RED = 3, ///< Greyscale PNG image using red as grey.
+ wxPNG_TYPE_PALETTE = 4 ///< Palette encoding.
};
/**
/**
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 );
+ 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.
Handler name.
*/
void SetName(const wxString& name);
+
+ /**
+ Retrieve the version information about the image library used by this
+ handler.
+
+ This method is not present in wxImageHandler class itself but is
+ present in a few of the classes deriving from it, currently
+ wxJPEGHandler, wxPNGHandler and wxTIFFHandler. It returns the
+ information about the version of the image library being used for the
+ corresponding handler implementation.
+
+ @since 2.9.2
+ */
+ static wxVersionInfo GetLibraryVersionInfo();
};
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.
+ channel with wxImage::HasAlpha. Currently the BMP, PNG, and TIFF format
+ handlers have full alpha channel support for loading so if you want to use
+ alpha you have to use one of these formats. If you initialize the image
+ alpha channel yourself using wxImage::SetAlpha, you should save it in
+ either PNG or TGA format to avoid losing it as these are the only handlers
+ that currently support saving with alpha.
@section image_handlers Available image handlers
To use other image formats, install the appropriate handler with
wxImage::AddHandler or call ::wxInitAllImageHandlers().
- - wxBMPHandler: For loading and saving, always installed.
- - wxPNGHandler: For loading (including alpha support) and saving.
+ - wxBMPHandler: For loading (including alpha support) and saving, always installed.
+ - wxPNGHandler: For loading and saving. Includes alpha support.
- wxJPEGHandler: For loading and saving.
- - wxGIFHandler: Only for loading, due to legal issues.
+ - wxGIFHandler: For loading and saving (see below).
- wxPCXHandler: For loading and saving (see below).
- wxPNMHandler: For loading and saving (see below).
- - wxTIFFHandler: For loading and saving.
- - wxTGAHandler: For loading only.
+ - wxTIFFHandler: For loading (including alpha support) and saving.
+ - wxTGAHandler: For loading and saving. Includes alpha support.
- wxIFFHandler: For loading only.
- wxXPMHandler: For loading and saving.
- wxICOHandler: For loading and saving.
Loading PNMs only works for ASCII or raw RGB images.
When saving in PNM format, wxPNMHandler will always save as raw RGB.
+ Saving GIFs requires images of maximum 8 bpp (see wxQuantize), and the alpha channel converted to a mask (see wxImage::ConvertAlphaToMask).
+ Saving an animated GIF requires images of the same size (see wxGIFHandler::SaveAnimation)
@library{wxcore}
@category{gdi}
{
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
*/
wxImage Rotate90(bool clockwise = true) const;
+ /**
+ Returns a copy of the image rotated by 180 degrees.
+
+ @since 2.9.2
+ */
+ wxImage Rotate180() 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
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 weight_r, double weight_g, double weight_b) const;
+
+ /**
+ Returns a greyscale version of the image.
+ @since 2.9.0
*/
- wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
+ 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.
The function is case-insensitive to @a name.
If the given option is not present, the function returns 0.
- Use HasOption() is 0 is a possibly valid value for the option.
+ Use HasOption() if 0 is a possibly valid value for the option.
Generic options:
@li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
the resulting PNG file. Use this option if your application produces
images with small size variation.
+ Options specific to wxGIFHandler:
+ @li @c wxIMAGE_OPTION_GIF_COMMENT: The comment text that is read from
+ or written to the GIF file. In an animated GIF each frame can have
+ its own comment. If there is only a comment in the first frame of
+ a GIF it will not be repeated in other frames.
+
@param name
The name of the option, case-insensitive.
@return
*/
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.
+
+ Typical example of use:
+ @code
+ wxImage::AddHandler(new wxPNGHandler);
+ @endcode
+
+ See @ref image_handlers for a list of the available handlers. You can
+ also use ::wxInitAllImageHandlers() to add handlers for all the image
+ formats supported by wxWidgets at once.
+
+ @param handler
+ A heap-allocated handler object which will be deleted by wxImage
+ if it is removed later by RemoveHandler() or at program shutdown.
*/
static void AddHandler(wxImageHandler* handler);
This function is called by wxWidgets on exit.
*/
static void CleanUpHandlers();
-
+
/**
Finds the handler with the given name.
/**
Finds the handler with the given name, and removes it.
- The handler is not deleted.
+
+ The handler is also deleted.
@param name
The handler name.
@see wxImageHandler
*/
static bool RemoveHandler(const wxString& name);
-
+
//@}
-
-
+
+
/**
- Returns @true if at least one of the available image handlers can read
+ 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
+ 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);
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:
@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
+ Initializes all available image handlers.
+
+ This function calls wxImage::AddHandler() for all the available image
+ handlers (see @ref image_handlers for the full list). Calling it is the
+ simplest way to initialize wxImage but it creates and registers even the
+ handlers your program may not use. If you want to avoid the overhead of
+ doing this you need to call wxImage::AddHandler() manually just for the
+ handlers that you do want to use.
@see wxImage, wxImageHandler
projects / wxWidgets.git / blobdiff