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()
*/
/**
Register an image handler.
+ See @ref image_handlers for a list of the available handlers.
*/
static void AddHandler(wxImageHandler* handler);
*/
unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
+ //@{
/**
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 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.
- If the image image doesn't have alpha channel, ConvertAlphaToMask() does nothing.
+ 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.
@param height
The height of the image in pixels.
@param clear
- If @true, initialize the image data with zeros.
+ If @true, initialize the image data with zeroes.
@return @true if the call succeeded, @false otherwise.
*/
bool Create(int width, int height, bool clear = true);
+ /**
+ Initialize the image data with zeroes (the default) or with the
+ byte value given as @a value.
+
+ @since 2.9.0
+ */
+ void Clear(unsigned char value = 0);
+
/**
Destroys the image data.
*/
@see wxImageHandler
*/
- static wxList GetHandlers();
+ static wxList& GetHandlers();
/**
Gets the height of the image in pixels.
Gets a user-defined string-valued option.
Currently the only defined string option is
- @li wxIMAGE_OPTION_FILENAME: The name of the file from which the image
+ @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
was loaded.
- @see SetOption(), GetOptionInt(), HasOption()
-
@param name
The name of the option, case-insensitive.
@return
The value of the option or an empty string if not found. Use
HasOption() if an empty string can be a valid option value.
+
+ @see SetOption(), GetOptionInt(), HasOption()
*/
wxString GetOption(const wxString& name) const;
Use HasOption() is 0 is a possibly valid value for the option.
Generic options:
- @li wxIMAGE_OPTION_MAX_WIDTH and wxIMAGE_OPTION_MAX_HEIGHT: If either
+ @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either
of these options is specified, the loaded image will be scaled down
(preserving its aspect ratio) so that its width is less than the
max width given if it is not 0 @em and its height is less than the
handler, this is still what happens however). These options must be
set before calling LoadFile() to have any effect.
- @li wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
+ @li @c wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
integer in 0..100 range with 0 meaning very poor and 100 excellent
(but very badly compressed). This option is currently ignored for
the other formats.
- @li wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
+ @li @c wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
whether the resolution of the image is specified in centimetres or
inches, see wxImageResolution enum elements.
- @li wxIMAGE_OPTION_RESOLUTION, wxIMAGE_OPTION_RESOLUTIONX and
- wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
- the image in the units corresponding to wxIMAGE_OPTION_RESOLUTIONUNIT
+ @li @c wxIMAGE_OPTION_RESOLUTION, @c wxIMAGE_OPTION_RESOLUTIONX and
+ @c wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
+ the image in the units corresponding to @c wxIMAGE_OPTION_RESOLUTIONUNIT
options value. The first option can be set before saving the image
to set both horizontal and vertical resolution to the same value.
The X and Y options are set by the image handlers if they support
after loading the image.
Options specific to wxPNGHandler:
- @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
+ @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
wxImagePNGType for the supported values.
- @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
-
- @see SetOption(), GetOption()
+ @li @c wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
+ @li @c wxIMAGE_OPTION_PNG_FILTER: Filter for saving a PNG file, see libpng
+ (http://www.libpng.org/pub/png/libpng-1.2.5-manual.html) for possible values
+ (e.g. PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FILTER_UP, etc).
+ @li @c wxIMAGE_OPTION_PNG_COMPRESSION_LEVEL: Compression level (0..9) for
+ saving a PNG file. An high value creates smaller-but-slower PNG file.
+ Note that unlike other formats (e.g. JPEG) the PNG format is always
+ lossless and thus this compression level doesn't tradeoff the image
+ quality.
+ @li @c wxIMAGE_OPTION_PNG_COMPRESSION_MEM_LEVEL: Compression memory usage
+ level (1..9) for saving a PNG file. An high value means the saving
+ process consumes more memory, but may create smaller PNG file.
+ @li @c wxIMAGE_OPTION_PNG_COMPRESSION_STRATEGY: Possible values are 0 for
+ default strategy, 1 for filter, and 2 for Huffman-only.
+ You can use OptiPNG (http://optipng.sourceforge.net/) to get a suitable
+ value for your application.
+ @li @c wxIMAGE_OPTION_PNG_COMPRESSION_BUFFER_SIZE: Internal buffer size
+ (in bytes) for saving a PNG file. Ideally this should be as big as
+ the resulting PNG file. Use this option if your application produces
+ images with small size variation.
@param name
The name of the option, case-insensitive.
@return
- The value of the option or 0 if not found. Use HasOption() if 0
- can be a valid option value.
+ The value of the option or 0 if not found.
+ Use HasOption() if 0 can be a valid option value.
+
+ @see SetOption(), GetOption()
*/
int GetOptionInt(const wxString& name) const;
Returns @true if the given option is present.
The function is case-insensitive to @a name.
+ The lists of the currently supported options are in GetOption() and
+ GetOptionInt() function docs.
+
@see SetOption(), GetOption(), GetOptionInt()
*/
bool HasOption(const wxString& name) const;
For example, when saving as a JPEG file, the option @b quality is
used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
+ The lists of the currently supported options are in GetOption() and
+ GetOptionInt() function docs.
+
@see GetOption(), GetOptionInt(), HasOption()
*/
void SetOption(const wxString& name, const wxString& value);
wxImage& operator=(const wxImage& image);
};
+/**
+ An instance of an empty image without an alpha channel.
+*/
+wxImage wxNullImage;
+
+
// ============================================================================
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */
//@{
/**
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