@class wxImageHandler
@wxheader{image.h}
- This is the base class for implementing image file loading/saving, and image
- creation from data.
+ This is the base class for implementing image file loading/saving, and
+ image creation from data.
It is used within wxImage and is not normally seen by the application.
If you wish to extend the capabilities of wxImage, derive a class from
- wxImageHandler
- and add the handler using wxImage::AddHandler in your
+ wxImageHandler and add the handler using wxImage::AddHandler in your
application initialisation.
+ @stdobjects
+ ::wxNullImage
+
@library{wxcore}
@category{FIXME}
@see wxImage, wxInitAllImageHandlers()
+
+ @todo Document all image handler types, indicating their library.
*/
class wxImageHandler : public wxObject
{
Opened input stream for reading image data. Currently, the stream must
support seeking.
- @returns Number of available images. For most image handlers, this is 1
+ @return Number of available images. For most image handlers, this is 1
(exceptions are TIFF and ICO formats).
*/
int GetImageCount(wxInputStream& stream);
/**
Gets the image type associated with this handler.
*/
- long GetType() const;
+ wxBitmapType GetType() const;
/**
Loads a image from a stream, putting the resulting data into @e image. If the
@param index
The index of the image in the file (starting from zero).
- @returns @true if the operation succeeded, @false otherwise.
+ @return @true if the operation succeeded, @false otherwise.
@see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
*/
@param stream
Opened output stream for writing the data.
- @returns @true if the operation succeeded, @false otherwise.
+ @return @true if the operation succeeded, @false otherwise.
@see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
*/
@class wxImage
@wxheader{image.h}
- This class encapsulates a platform-independent image. An image can be created
- from data, or using wxBitmap::ConvertToImage. An image
- can be loaded from a file in a variety of formats, and is extensible to new
- formats
- via image format handlers. Functions are available to set and get image bits, so
- it can be used for basic image manipulation.
+ This class encapsulates a platform-independent image. An image can be
+ created from data, or using wxBitmap::ConvertToImage. An image can be
+ loaded from a file in a variety of formats, and is extensible to new
+ formats via image format handlers. Functions are available to set and
+ get image bits, so it can be used for basic image manipulation.
A wxImage cannot (currently) be drawn directly to a wxDC. Instead,
a platform-specific wxBitmap object must be created from it using
the wxBitmap::wxBitmap(wxImage,int depth) constructor.
- This bitmap can then
- be drawn in a device context, using wxDC::DrawBitmap.
+ This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.
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.
class wxImage : public wxObject
{
public:
- //@{
+
+ /**
+ Creates an empty wxImage object without an alpha channel.
+ */
+ wxImage();
+
+ /**
+ Creates an image with the given size and clears it if requested.
+ Does not create an alpha channel.
+
+ @param width
+ Specifies the width of the image.
+ @param height
+ Specifies the height of the image.
+ @clear
+ Clear the image with zeros.
+ */
+ wxImage(int width, int height, bool clear = true);
+
/**
Creates an image from data in memory. If static_data is false
then the wxImage will take ownership of the data and free it
afterwards. For this, it has to be allocated with @e malloc.
-
+
@param width
Specifies the width of the image.
@param height
Specifies the height of the image.
@param data
A pointer to RGB data
- @param alpha
- A pointer to alpha-channel data
@param static_data
Indicates if the data should be free'd after use
-
+
*/
- wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
wxImage(int width, int height, unsigned char* data, bool static_data = false);
- //@}
-
+
/**
- Creates an image with the given size and clears it if requested.
- Does not create an alpha channel.
-
+ Creates an image from data in memory. If static_data is false
+ then the wxImage will take ownership of the data and free it
+ afterwards. For this, it has to be allocated with @e malloc.
+
@param width
Specifies the width of the image.
@param height
Specifies the height of the image.
- @clear
- Clear the image with zeros.
- */
- wxImage(int width, int height, bool clear = true);
-
- /**
- Creates an empty wxImage object. Does not create
- an alpha channel.
+ @param data
+ A pointer to RGB data
+ @param alpha
+ A pointer to alpha-channel data
+ @param static_data
+ Indicates if the data should be free'd after use
+
*/
- wxImage();
-
+ wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
+
/**
Creates an image from XPM data.
-
+
@param xpmData
A pointer to XPM image data.
*/
wxImage(const char* const* xpmData);
- //@{
+
/**
+ Creates an image from a file.
+
@param name
Name of the file from which to load the image.
- @param stream
- Opened input stream from which to load the image. Currently,
- the stream must support seeking.
@param type
May be one of the following:
@li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
@li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
@li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
@li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
-
- @param mimetype
- MIME type string (for example 'image/jpeg')
@param index
Index of the image to load in the case that the image file contains
multiple images. This is only used by GIF, ICO and TIFF handlers.
@see LoadFile()
*/
- wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1);
+ wxImage(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
+
+ /**
+ Creates an image from a file using MIME-types to specify the type.
+
+ @param name
+ Name of the file from which to load the image.
+ @param type
+ See above
+ @param mimetype
+ MIME type string (for example 'image/jpeg')
+ @param index
+ See above
+ */
wxImage(const wxString& name, const wxString& mimetype, int index = -1);
- wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);
+
+ /**
+ Creates an image from a stream.
+
+ @param stream
+ Opened input stream from which to load the image. Currently,
+ the stream must support seeking.
+ @param type
+ See above
+ @param index
+ See above.
+ */
+ wxImage(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
+
+ /**
+ Creates an image from a stream using MIME-types to specify the type.
+
+ @param stream
+ Opened input stream from which to load the image. Currently,
+ the stream must support seeking.
+ @param mimetype
+ MIME type string (for example 'image/jpeg')
+ @param index
+ See above.
+ */
wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);
- //@}
-
+
/**
Destructor.
*/
~wxImage();
- //@{
/**
- returns @true if the current image handlers can read this file
+ Register an image handler.
*/
static void AddHandler(wxImageHandler* handler);
- See also bool CanRead(const wxString& filename);
- //@}
/**
- Blurs the image in both horizontal and vertical directions by the specified
- pixel
- @e blurRadius. This should not be used when using a single mask colour
- for transparency.
+ Blurs the image in both horizontal and vertical directions by the
+ specified pixel @e blurRadius. This should not be used when using
+ a single mask colour for transparency.
- @see @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical
+ @see BlurHorizontal(), BlurVertical()
*/
wxImage Blur(int blurRadius);
Blurs the image in the horizontal direction only. This should not be used
when using a single mask colour for transparency.
- @see Blur(), @ref vertblur() BlurVertical
+ @see Blur(), BlurVertical()
*/
wxImage BlurHorizontal(int blurRadius);
Blurs the image in the vertical direction only. This should not be used
when using a single mask colour for transparency.
- @see Blur(), @ref horzblur() BlurHorizontal
+ @see Blur(), BlurHorizontal()
*/
wxImage BlurVertical(int blurRadius);
+ /**
+ Returns @true if the current image handlers can read this file
+ */
+ bool CanRead(const wxString& filename);
+
/**
Deletes all image handlers.
This function is called by wxWidgets on exit.
wxImageHistogram object. wxImageHistogram is a specialization of
wxHashMap "template" and is defined as follows:
- @returns Returns number of colours in the histogram.
+ @return Returns number of colours in the histogram.
*/
unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
If the image image doesn't have alpha channel,
ConvertAlphaToMask does nothing.
- @returns @false if FindFirstUnusedColour returns @false, @true otherwise.
+ @return @false if FindFirstUnusedColour returns @false, @true otherwise.
*/
bool ConvertAlphaToMask(unsigned char threshold = 128);
@param height
The height of the image in pixels.
- @returns @true if the call succeeded, @false otherwise.
+ @return @true if the call succeeded, @false otherwise.
*/
bool Create(int width, int height, bool clear = true);
Initial values of the colour. Returned colour
will have RGB values equal to or greater than these.
- @returns Returns @false if there is no unused colour left, @true on success.
+ @return Returns @false if there is no unused colour left, @true on success.
*/
bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
unsigned char* b,
@param mimetype
MIME type.
- @returns A pointer to the handler if found, @NULL otherwise.
+ @return A pointer to the handler if found, @NULL otherwise.
@see wxImageHandler
*/
static wxImageHandler* FindHandler(const wxString& name);
static wxImageHandler* FindHandler(const wxString& extension,
- long imageType);
- static wxImageHandler* FindHandler(long imageType);
+ wxBitmapType imageType);
+ static wxImageHandler* FindHandler(wxBitmapType imageType);
static wxImageHandler* FindHandlerMime(const wxString& mimetype);
//@}
- //@{
+ /**
+ Return alpha value at given pixel location.
+ */
+ unsigned char GetAlpha(int x, int y) const;
+
/**
Returns pointer to the array storing the alpha values for this image. This
pointer is @NULL for the images without the alpha channel. If the image
does have it, this pointer may be used to directly manipulate the alpha values
- which are stored as the @ref getdata() RGB ones.
+ which are stored as the RGB ones.
*/
- unsigned char GetAlpha(int x, int y) const;
const unsigned char * GetAlpha() const;
- //@}
/**
Returns the blue intensity at the given coordinate.
@li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
@li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
- @returns Number of available images. For most image handlers, this is 1
+ @return Number of available images. For most image handlers, this is 1
(exceptions are TIFF and ICO formats).
*/
static int GetImageCount(const wxString& filename,
- long type = wxBITMAP_TYPE_ANY);
+ wxBitmapType type = wxBITMAP_TYPE_ANY);
static int GetImageCount(wxInputStream& stream,
- long type = wxBITMAP_TYPE_ANY);
+ wxBitmapType type = wxBITMAP_TYPE_ANY);
//@}
/**
file extension masks
suitable for passing to file open/save dialog boxes.
- @returns The format of the returned string is
+ @return The format of the returned string is
"(*.ext1;*.ext2)|*.ext1;*.ext2".
@see wxImageHandler
/**
Gets a user-defined option as an integer. The function is case-insensitive
- to @e name. If the given option is not present, the function returns 0.
+ to @e 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).
-
+
Supported values for wxIMAGE_OPTION_PNG_FORMAT:
@li wxPNG_TYPE_COLOUR: Stores RGB image.
@li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.
*/
wxImage GetSubImage(const wxRect& rect) const;
+ /**
+ Gets the type of image found by LoadFile or specified with SaveFile
+ @since 2.9.0
+ */
+ wxBitmapType GetType() const;
+
/**
Gets the width of the image in pixels.
interpreted as the first image (index=0) by the GIF and TIFF handler
and as the largest and most colourful one by the ICO handler.
- @returns @true if the operation succeeded, @false otherwise. If the
+ @return @true if the operation succeeded, @false otherwise. If the
optional index parameter is out of range, @false is
returned and a call to wxLogError() takes place.
@see SaveFile()
*/
bool LoadFile(const wxString& name,
- long type = wxBITMAP_TYPE_ANY,
+ wxBitmapType type = wxBITMAP_TYPE_ANY,
int index = -1);
bool LoadFile(const wxString& name, const wxString& mimetype,
int index = -1);
- bool LoadFile(wxInputStream& stream, long type,
+ bool LoadFile(wxInputStream& stream, wxBitmapType type,
int index = -1);
bool LoadFile(wxInputStream& stream,
const wxString& mimetype,
@param name
The handler name.
- @returns @true if the handler was found and removed, @false otherwise.
+ @return @true if the handler was found and removed, @false otherwise.
@see wxImageHandler
*/
@param mimetype
MIME type.
- @returns @true if the operation succeeded, @false otherwise.
+ @return @true if the operation succeeded, @false otherwise.
@remarks Depending on how wxWidgets has been configured, not all formats
may be available.
Example:
@param quality
- Determines what method to use for resampling the image.
-
+ Determines what method to use for resampling the image.
+
Can be one of the following:
@li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of
pixel replication
wxImage Scale(int width, int height,
int quality = wxIMAGE_QUALITY_NORMAL) const;
- //@{
/**
- Sets the alpha value for the given pixel. This function should only be called
- if the image has alpha channel data, use HasAlpha() to
- check for this.
+ Assigns new data as alpha channel to the image.
+ If @e static_data is false the data will be
+ free()'d after use.
*/
void SetAlpha(unsigned char* alpha = NULL,
bool static_data = false);
+
+ /**
+ Sets the alpha value for the given pixel. This function should only be
+ called if the image has alpha channel data, use HasAlpha() to
+ check for this.
+ */
void SetAlpha(int x, int y, unsigned char alpha);
- //@}
/**
Sets the image data without performing checks. The data given must have
@param mr,mg,mb
RGB value of pixels in mask that will be used to create the mask.
- @returns Returns @false if mask does not have same dimensions as the image
+ @return Returns @false if mask does not have same dimensions as the image
or if there is no unused colour left. Returns @true if
the mask was successfully applied.
*/
@param image
Image to assign.
- @returns Returns 'this' object.
+ @return Returns 'this' object.
*/
wxImage operator =(const wxImage& image);
};
-/**
- An empty wxImage.
-*/
-wxImage wxNullImage;
-
-
// ============================================================================
// Global functions/macros
// ============================================================================
projects / wxWidgets.git / blobdiff