// Purpose: interface of wxImageHandler and wxImage
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
/// Highest quality but slowest execution time.
wxIMAGE_QUALITY_BICUBIC,
- /// Default image resizing algorithm used by wxImage::Scale().
+ /**
+ 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, currently same as wxIMAGE_QUALITY_BICUBIC.
+ /**
+ 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
};
{
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.
};
+
+/**
+ Image option names.
+*/
+#define wxIMAGE_OPTION_QUALITY wxString(wxT("quality"))
+#define wxIMAGE_OPTION_FILENAME wxString(wxT("FileName"))
+#define wxIMAGE_OPTION_RESOLUTION wxString(wxT("Resolution"))
+#define wxIMAGE_OPTION_RESOLUTIONX wxString(wxT("ResolutionX"))
+#define wxIMAGE_OPTION_RESOLUTIONY wxString(wxT("ResolutionY"))
+#define wxIMAGE_OPTION_RESOLUTIONUNIT wxString(wxT("ResolutionUnit"))
+#define wxIMAGE_OPTION_MAX_WIDTH wxString(wxT("MaxWidth"))
+#define wxIMAGE_OPTION_MAX_HEIGHT wxString(wxT("MaxHeight"))
+
+#define wxIMAGE_OPTION_BMP_FORMAT wxString(wxT("wxBMP_FORMAT"))
+#define wxIMAGE_OPTION_CUR_HOTSPOT_X wxString(wxT("HotSpotX"))
+#define wxIMAGE_OPTION_CUR_HOTSPOT_Y wxString(wxT("HotSpotY"))
+
+#define wxIMAGE_OPTION_GIF_COMMENT wxString(wxT("GifComment"))
+
+#define wxIMAGE_OPTION_PNG_FORMAT wxString(wxT("PngFormat"))
+#define wxIMAGE_OPTION_PNG_BITDEPTH wxString(wxT("PngBitDepth"))
+#define wxIMAGE_OPTION_PNG_FILTER wxString(wxT("PngF"))
+#define wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL wxString(wxT("PngZL"))
+#define wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL wxString(wxT("PngZM"))
+#define wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY wxString(wxT("PngZS"))
+#define wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE wxString(wxT("PngZB"))
+
+#define wxIMAGE_OPTION_TIFF_BITSPERSAMPLE wxString(wxT("BitsPerSample"))
+#define wxIMAGE_OPTION_TIFF_SAMPLESPERPIXEL wxString(wxT("SamplesPerPixel"))
+#define wxIMAGE_OPTION_TIFF_COMPRESSION wxString(wxT("Compression"))
+#define wxIMAGE_OPTION_TIFF_PHOTOMETRIC wxString(wxT("Photometric"))
+#define wxIMAGE_OPTION_TIFF_IMAGEDESCRIPTOR wxString(wxT("ImageDescriptor"))
+
+
+enum
+{
+ wxBMP_24BPP = 24, // default, do not need to set
+ //wxBMP_16BPP = 16, // wxQuantize can only do 236 colors?
+ wxBMP_8BPP = 8, // 8bpp, quantized colors
+ wxBMP_8BPP_GREY = 9, // 8bpp, rgb averaged to greys
+ wxBMP_8BPP_GRAY = wxBMP_8BPP_GREY,
+ wxBMP_8BPP_RED = 10, // 8bpp, red used as greyscale
+ wxBMP_8BPP_PALETTE = 11, // 8bpp, use the wxImage's palette
+ wxBMP_4BPP = 4, // 4bpp, quantized colors
+ wxBMP_1BPP = 1, // 1bpp, quantized "colors"
+ wxBMP_1BPP_BW = 2 // 1bpp, black & white from red
+};
+
+
/**
@class wxImageHandler
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.
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, 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}
/**
@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);
/**
@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).
*/
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
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);
/**
/**
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).
/**
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);
/**
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.
@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).
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