// 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();
};
the wxBitmap::wxBitmap(wxImage,int depth) constructor.
This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
+ More on the difference between wxImage and wxBitmap: wxImage is just a
+ buffer of RGB bytes with an optional buffer for the alpha bytes. It is all
+ generic, platform independent and image file format independent code. It
+ includes generic code for scaling, resizing, clipping, and other manipulations
+ of the image data. OTOH, wxBitmap is intended to be a wrapper of whatever is
+ the native image format that is quickest/easiest to draw to a DC or to be the
+ target of the drawing operations performed on a wxMemoryDC. By splitting the
+ responsibilities between wxImage/wxBitmap like this then it's easier to use
+ generic code shared by all platforms and image types for generic operations and
+ platform specific code where performance or compatibility is needed.
+
One colour value of the image may be used as a mask colour which will lead to
the automatic creation of a wxMask object associated to the bitmap object.
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
- alpha and, if you initialize the image alpha channel yourself using
- wxImage::SetAlpha, you should save it in PNG format to avoid losing it.
+ 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. Currently the BMP, PNG, TGA, 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, TGA, or TIFF 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 and saving. Includes alpha support.
+ - 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
/**
@overload
*/
- wxImage(const wxSize& sz, unsigned char* data, unsigned char* data, unsigned char* alpha,
+ wxImage(const wxSize& sz, 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);
@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_TIFF: 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).
*/
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 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.
- Currently the only defined string option is
+ Generic options:
@li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
was loaded.
+ 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
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 wxTIFFHandler:
+ @li @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE: Number of bits per
+ sample (channel). Currently values of 1 and 8 are supported. A
+ value of 1 results in a black and white image. A value of 8 (the
+ default) can mean greyscale or RGB, depending on the value of
+ @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL.
+ @li @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL: Number of samples
+ (channels) per pixel. Currently values of 1 and 3 are supported.
+ A value of 1 results in either a greyscale (by default) or black and
+ white image, depending on the value of
+ @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE. A value of 3 (the default)
+ will result in an RGB image.
+ @li @c wxIMAGE_OPTION_TIFF_COMPRESSION: Compression type. By default
+ it is set to 1 (COMPRESSION_NONE). Typical other values are
+ 5 (COMPRESSION_LZW) and 7 (COMPRESSION_JPEG). See tiff.h for more
+ options.
+ @li @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC: Specifies the photometric
+ interpretation. By default it is set to 2 (PHOTOMETRIC_RGB) for RGB
+ images and 0 (PHOTOMETRIC_MINISWHITE) for greyscale or black and
+ white images. It can also be set to 1 (PHOTOMETRIC_MINISBLACK) to
+ treat the lowest value as black and highest as white.
+ If you want a greyscale image it is also sufficient to only specify
+ @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC and set it to either
+ PHOTOMETRIC_MINISWHITE or PHOTOMETRIC_MINISBLACK. The other values
+ are taken care of.
+
+ @note
+ Be careful when combining the options @c wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL,
+ @c wxIMAGE_OPTION_TIFF_BITSPERSAMPLE, and @c wxIMAGE_OPTION_TIFF_PHOTOMETRIC.
+ While some measures are taken to prevent illegal combinations and/or
+ values, it is still easy to abuse them and come up with invalid
+ results in the form of either corrupted images or crashes.
+
@param name
The name of the option, case-insensitive.
@return
@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_TIFF: 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).
*/
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:
@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_TIFF: 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).
@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);
};
+
+class wxImageHistogram : public wxImageHistogramBase
+{
+public:
+ wxImageHistogram();
+
+ // get the key in the histogram for the given RGB values
+ static unsigned long MakeKey(unsigned char r,
+ unsigned char g,
+ unsigned char b);
+
+ // find first colour that is not used in the image and has higher
+ // RGB values than RGB(startR, startG, startB)
+ //
+ // returns true and puts this colour in r, g, b (each of which may be NULL)
+ // on success or returns false if there are no more free colours
+ bool FindFirstUnusedColour(unsigned char *r,
+ unsigned char *g,
+ unsigned char *b,
+ unsigned char startR = 1,
+ unsigned char startG = 0,
+ unsigned char startB = 0 ) const;
+};
+
/**
An instance of an empty image without an alpha channel.
*/
//@{
/**
- 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