// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+/**
+ Possible values for the image resolution option.
+
+ @see wxImage::GetOptionInt().
+ */
+enum wxImageResolution
+{
+ /// Resolution not specified.
+ wxIMAGE_RESOLUTION_NONE = 0,
+
+ /// Resolution specified in inches.
+ wxIMAGE_RESOLUTION_INCHES = 1,
+
+ /// Resolution specified in centimetres.
+ wxIMAGE_RESOLUTION_CM = 2
+};
+
+/**
+ Possible values for PNG image type option.
+
+ @see wxImage::GetOptionInt().
+ */
+enum wxImagePNGType
+{
+ 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.
+};
+
/**
@class wxImageHandler
@see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
*/
- bool LoadFile(wxImage* image, wxInputStream& stream,
- bool verbose = true, int index = 0);
+ virtual bool LoadFile(wxImage* image, wxInputStream& stream,
+ bool verbose = true, int index = -1);
/**
Saves a image in the output stream.
The image object which is to be affected by this operation.
@param stream
Opened output stream for writing the data.
+ @param verbose
+ If set to @true, errors reported by the image handler will produce
+ wxLogMessages.
@return @true if the operation succeeded, @false otherwise.
@see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
*/
- bool SaveFile(wxImage* image, wxOutputStream& stream);
+ virtual bool SaveFile(wxImage* image, wxOutputStream& stream,
+ bool verbose = true);
/**
Sets the handler extension.
*/
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 image doesn't have alpha channel, ConvertAlphaToMask() does nothing.
+ 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.
+
+ 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 = 128);
+ bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
/**
- @deprecated
- Use the equivalent @ref wxBitmap::wxBitmap "wxBitmap constructor"
- (which takes wxImage and depth as its arguments) instead.
- */
- wxBitmap ConvertToBitmap() const;
+ 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.
when converting to YUV, where every pixel equals
(R * @a lr) + (G * @a lg) + (B * @a lb).
*/
- wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587,
- double lb = 0.114) const;
+ wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
/**
Returns monochromatic 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.
*/
does have it, this pointer may be used to directly manipulate the alpha values
which are stored as the RGB ones.
*/
- const unsigned char * GetAlpha() const;
+ unsigned char* GetAlpha() const;
/**
Returns the blue intensity at the given coordinate.
@see wxImageHandler
*/
- static wxList GetHandlers();
+ static wxList& GetHandlers();
/**
Gets the height of the image in pixels.
+
+ @see GetWidth(), GetSize()
*/
int GetHeight() const;
unsigned char GetMaskRed() const;
/**
- Gets a user-defined option. The function is case-insensitive to @a name.
+ Gets a user-defined string-valued option.
- 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).
+ Currently the only defined string option is
+ @li @c wxIMAGE_OPTION_FILENAME: The name of the file from which the image
+ was loaded.
+
+ @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;
/**
- Gets a user-defined option as an integer.
+ Gets a user-defined integer-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.
- Options for wxPNGHandler:
- @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file.
- @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
+ Generic options:
+ @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
+ max height given if it is not 0. This is typically used for loading
+ thumbnails and the advantage of using these options compared to
+ calling Rescale() after loading is that some handlers (only JPEG
+ one right now) support rescaling the image during loading which is
+ vastly more efficient than loading the entire huge image and
+ rescaling it later (if these options are not supported by the
+ handler, this is still what happens however). These options must be
+ set before calling LoadFile() to have any effect.
+
+ @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 @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 @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
+ the image resolution (currently BMP, JPEG and TIFF handlers do) and
+ the image provides the resolution information and can be queried
+ after loading the image.
+
+ Options specific to wxPNGHandler:
+ @li @c wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
+ wxImagePNGType for the supported values.
+ @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.
- Supported values for wxIMAGE_OPTION_PNG_FORMAT:
- @li wxPNG_TYPE_COLOUR: Stores RGB image.
- @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.
- @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey.
+ @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.
@see SetOption(), GetOption()
*/
Get the current mask colour or find a suitable unused colour that could be
used as a mask colour. Returns @true if the image currently has a mask.
*/
- bool GetOrFindMaskColour(unsigned char r, unsigned char g,
- unsigned char b) const;
+ bool GetOrFindMaskColour(unsigned char* r, unsigned char* g,
+ unsigned char* b) const;
/**
Returns the palette associated with the image.
*/
wxImage GetSubImage(const wxRect& rect) const;
+ /**
+ Returns the size of the image in pixels.
+
+ @since 2.9.0
+
+ @see GetHeight(), GetWidth()
+ */
+ wxSize GetSize() const;
+
/**
Gets the type of image found by LoadFile() or specified with SaveFile().
/**
Gets the width of the image in pixels.
- @see GetHeight()
+ @see GetHeight(), GetSize()
*/
int GetWidth() const;
/**
Converts a color in HSV color space to RGB color space.
*/
- wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue & hsv);
+ static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv);
/**
Returns @true if this image has alpha channel, @false otherwise.
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;
colour if this image has a mask or if this image has alpha channel and alpha
value of this pixel is strictly less than @a threshold.
*/
- bool IsTransparent(int x, int y, unsigned char threshold = 128) const;
+ bool IsTransparent(int x, int y,
+ unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const;
/**
Loads an image from an input stream.
@see SaveFile()
*/
- bool LoadFile(wxInputStream& stream, wxBitmapType type, int index = -1);
+ virtual bool LoadFile(wxInputStream& stream,
+ wxBitmapType type = wxBITMAP_TYPE_ANY,
+ int index = -1);
/**
Loads an image from a file.
@param index
See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
*/
- bool LoadFile(const wxString& name,
- wxBitmapType type = wxBITMAP_TYPE_ANY,
- int index = -1);
+ virtual bool LoadFile(const wxString& name,
+ wxBitmapType type = wxBITMAP_TYPE_ANY,
+ int index = -1);
/**
Loads an image from a file.
@param index
See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
*/
- bool LoadFile(const wxString& name, const wxString& mimetype,
- int index = -1);
+ virtual bool LoadFile(const wxString& name, const wxString& mimetype,
+ int index = -1);
/**
@param index
See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload.
*/
- bool LoadFile(wxInputStream& stream,
- const wxString& mimetype,
- int index = -1);
+ virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype,
+ int index = -1);
/**
Returns a mirrored copy of the image.
/**
Converts a color in RGB color space to HSV color space.
*/
- wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
+ static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb);
/**
Finds the handler with the given name, and removes it.
@see Scale()
*/
- wxImage Rescale(int width, int height,
+ wxImage& Rescale(int width, int height,
int quality = wxIMAGE_QUALITY_NORMAL);
/**
@see Size()
*/
- wxImage Resize(const wxSize& size, const wxPoint& pos,
- int red = -1, int green = -1,
- int blue = -1);
+ wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1,
+ int green = -1, int blue = -1);
/**
Rotates the image about the given point, by @a angle radians.
@see LoadFile()
*/
- bool SaveFile(wxOutputStream& stream,
- const wxString& mimetype) const;
+ virtual bool SaveFile(wxOutputStream& stream,
+ const wxString& mimetype) const;
/**
Saves an image in the named file.
in 8 colors at the size supplied.
@li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
*/
- bool SaveFile(const wxString& name, wxBitmapType type) const;
+ virtual bool SaveFile(const wxString& name, wxBitmapType type) const;
/**
Saves an image in the named file.
@param mimetype
MIME type.
*/
- bool SaveFile(const wxString& name,
- const wxString& mimetype) const;
+ virtual bool SaveFile(const wxString& name, const wxString& mimetype) const;
/**
Saves an image in the named file.
@param name
Name of the file to save the image to.
*/
- bool SaveFile(const wxString& name) const;
+ virtual bool SaveFile(const wxString& name) const;
/**
Saves an image in the given stream.
@param type
MIME type.
*/
- bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
+ virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const;
/**
Returns a scaled version of the image.
*/
void SetAlpha(int x, int y, unsigned char alpha);
+ //@{
/**
Sets the image data without performing checks.
that will be responsible for deleting it.
Do not pass to this function a pointer obtained through GetData().
*/
- void SetData(unsigned char* data);
+ void SetData(unsigned char* data, bool static_data = false);
+ void SetData(unsigned char* data, int new_width, int new_height,
+ bool static_data = false);
+ //@}
/**
Specifies whether there is a mask or not.
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);
This routine performs bounds-checks for the coordinate so it can be considered
a safe way to manipulate the data.
*/
- void SetRGB(wxRect& rect, unsigned char red,
+ void SetRGB(const wxRect& rect,
+ unsigned char red,
unsigned char green,
unsigned char blue);
@return Returns 'this' object.
*/
- wxImage operator =(const wxImage& image);
+ 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 */
//@{
/**
projects / wxWidgets.git / blobdiff