One colour value of the image may be used as a mask colour which will lead to the automatic
creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
+\wxheading{Alpha channel support}
+
+Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is in
+addition to a byte for the red, green and blue colour components for each pixel
+it also stores a byte representing the pixel opacity. The alpha value of $0$
+corresponds to a transparent pixel (null opacity) while the value of $255$
+means that the pixel is 100\% opaque.
+
+Unlike the RGB data, not all images have the alpha channel and before using
+\helpref{GetAlpha}{wximagegetalpha} you should check if this image contains
+alpha value with \helpref{HasAlpha}{wximagehasalpha}. In fact, currently only
+images loaded from PNG files with transparency information will have alpha
+channel but support for it will be added to the other formats as well (as well
+as support for saving images with alpha channel which is not still implemented
+either).
+
\wxheading{Available image handlers}
The following image handlers are available. {\bf wxBMPHandler} is always
\twocolwidtha{5cm}%
\begin{twocollist}
\twocolitem{\indexit{wxBMPHandler}}{For loading and saving, always installed.}
-\twocolitem{\indexit{wxPNGHandler}}{For loading and saving.}
+\twocolitem{\indexit{wxPNGHandler}}{For loading (including alpha support) and saving.}
\twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.}
\twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.}
\twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).}
mask information so that bitmaps and images can be converted back
and forth without loss in that respect.
-\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
+\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{bool}{ clear=true}}
-Creates an image with the given width and height.
+Creates an image with the given width and height. If {\it clear} is true, the new image will be initialized to black.
+Otherwise, the image data will be uninitialized.
-\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data=FALSE}}
+\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data=false}}
Creates an image from given data with the given width and height. If
-{\it static\_data} is TRUE, then wxImage will not delete the actual
+{\it static\_data} is true, then wxImage will not delete the actual
image data in its destructor, otherwise it will free it by calling
{\it free()}.
\wxheading{Remarks}
-Depending on how wxWindows has been configured, not all formats may be available.
+Depending on how wxWidgets has been configured, not all formats may be available.
Note: any handler other than BMP must be previously
initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
\perlnote{Constructors supported by wxPerl are:\par
\begin{itemize}
\item{Wx::Image->new( bitmap )}
+\item{Wx::Image->new( icon )}
\item{Wx::Image->new( width, height )}
-\item{Wx::Image->new( name, type )}
-\item{Wx::Image->new( name, mimetype )}
+\item{Wx::Image->new( width, height, data )}
+\item{Wx::Image->new( file, type, index )}
+\item{Wx::Image->new( file, mimetype, index )}
+\item{Wx::Image->new( stream, type, index )}
+\item{Wx::Image->new( stream, mimetype, index )}
\end{itemize}
}
\func{bool}{CanRead}{\param{const wxString\&}{ filename}}
-returns TRUE if the current image handlers can read this file
+returns true if the current image handlers can read this file
\pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
\membersection{wxImage::CleanUpHandlers}
Deletes all image handlers.
-This function is called by wxWindows on exit.
+This function is called by wxWidgets on exit.
\membersection{wxImage::ComputeHistogram}\label{wximagecomputehistogram}
Returns number of colours in the histogram.
+\membersection{wxImage::ConvertAlphaToMask}\label{wximageconvertalphatomask}
+
+\func{bool}{ConvertAlphaToMask}{\param{unsigned char}{ threshold = 128}}
+
+If the image has alpha channel, this method converts it to mask. All pixels
+with alpha value less than \arg{threshold} are replaced with mask colour
+and the alpha channel is removed. Mask colour is chosen automatically using
+\helpref{FindFirstUnusedColour}{wximagefindfirstunusedcolour}.
+
+If the image image doesn't have alpha channel,
+ConvertAlphaToMask does nothing.
+
+\wxheading{Return value}
+
+\false if FindFirstUnusedColour returns \false, \true otherwise.
+
\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
\constfunc{wxBitmap}{ConvertToBitmap}{\void}
\membersection{wxImage::Create}\label{wximagecreate}
-\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
+\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{bool}{ clear=true}}
-Creates a fresh image.
+Creates a fresh image. If {\it clear} is true, the new image will be initialized to black.
+Otherwise, the image data will be uninitialized.
\wxheading{Parameters}
\wxheading{Return value}
-TRUE if the call succeeded, FALSE otherwise.
+true if the call succeeded, false otherwise.
\membersection{wxImage::Destroy}\label{wximagedestroy}
\wxheading{Return value}
-Returns FALSE if there is no unused colour left, TRUE on success.
+Returns false if there is no unused colour left, true on success.
\wxheading{Notes}
\helpref{wxImageHandler}{wximagehandler}
+\membersection{wxImage::GetImageExtWildcard}
+
+\func{static wxString}{GetImageExtWildcard}{\void}
+
+Iterates all registered wxImageHandler objects, and returns a string containing file extension masks
+suitable for passing to file open/save dialog boxes.
+
+\wxheading{Return value}
+
+The format of the returned string is "(*.ext1;*.ext2)|*.ext1;*.ext2".
+
+It is usually a good idea to prepend a description before passing the result to the dialog.
+
+Example:
+
+\begin{verbatim}
+ wxFileDialog FileDlg( this, "Choose Image", ::wxGetWorkingDirectory(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN );
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxImageHandler}{wximagehandler}
+
+\membersection{wxImage::GetAlpha}\label{wximagegetalpha}
+
+\constfunc{unsigned char}{GetAlpha}{\param{int}{ x}, \param{int}{ y}}
+
+Returns the alpha value for the given pixel. This function may only be called
+for the images with alpha channel, use \helpref{HasAlpha}{wximagehasalpha} to
+check for this.
+
+The returned value is the {\it opacity} of the image, i.e. the value of $0$
+corresponds to the transparent pixels while the value of $255$ -- to the opaque
+ones.
+
+\constfunc{unsigned char *}{GetAlpha}{\void}
+
+Returns pointer to the array storing the alpha values for this image. This
+pointer is {\tt 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 \helpref{RGB}{wximagegetdata} ones.
+
\membersection{wxImage::GetBlue}\label{wximagegetblue}
\constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
Returns the image data as an array. This is most often used when doing
direct image manipulation. The return value points to an array of
-characters in RGBGBRGB... format.
+characters in RGBRGBRGB$\ldots$ format in the top-to-bottom, left-to-right
+order, that is the first RGB triplet corresponds to the pixel first pixel of
+the first row, the second one --- to the second pixel of the first row and so
+on until the end of the first row, with second row following after it and so
+on.
+
+You should not delete the returned pointer nor pass it to
+\helpref{wxImage::SetData}{wximagesetdata}.
\membersection{wxImage::GetGreen}\label{wximagegetgreen}
Number of available images. For most image handlers, this is 1 (exceptions
are TIFF and ICO formats).
-\membersection{wxImage::GetRed}\label{wximagegetred}
-
-\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
-
-Returns the red intensity at the given coordinate.
-
\membersection{wxImage::GetHandlers}
\func{static wxList\&}{GetHandlers}{\void}
Eventually wxImage handlers will set the palette if one exists in the image file.
+\membersection{wxImage::GetRed}\label{wximagegetred}
+
+\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
+
+Returns the red intensity at the given coordinate.
+
\membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
\helpref{wxImage::GetHeight}{wximagegetheight}
+\membersection{wxImage::HasAlpha}\label{wximagehasalpha}
+
+\constfunc{bool}{HasAlpha}{\void}
+
+Returns true if this image has alpha channel, false otherwise.
+
+\wxheading{See also}
+
+\helpref{GetAlpha}{wximagegetalpha}, \helpref{SetAlpha}{wximagesetalpha}
+
\membersection{wxImage::HasMask}\label{wximagehasmask}
\constfunc{bool}{HasMask}{\void}
-Returns TRUE if there is a mask active, FALSE otherwise.
+Returns true if there is a mask active, false otherwise.
\membersection{wxImage::GetOption}\label{wximagegetoption}
\constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
-Returns TRUE if the given option is present. The function is case-insensitive to {\it name}.
+Returns true if the given option is present. The function is case-insensitive to {\it name}.
\wxheading{See also}
Internal use only. Adds standard image format handlers. It only install BMP
for the time being, which is used by wxBitmap.
-This function is called by wxWindows on startup, and shouldn't be called by
+This function is called by wxWidgets on startup, and shouldn't be called by
the user.
\wxheading{See also}
\wxheading{Remarks}
-Depending on how wxWindows has been configured, not all formats may be available.
+Depending on how wxWidgets has been configured, not all formats may be available.
Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
hotspot for loaded cursor file:
\wxheading{Return value}
-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.
+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.
\wxheading{See also}
\constfunc{bool}{Ok}{\void}
-Returns TRUE if image data is present.
+Returns true if image data is present.
\membersection{wxImage::RemoveHandler}
\wxheading{Return value}
-TRUE if the handler was found and removed, FALSE otherwise.
+true if the handler was found and removed, false otherwise.
\wxheading{See also}
\helpref{wxImageHandler}{wximagehandler}
+\membersection{wxImage::Mirror}\label{wximagemirror}
+
+\constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = true}}
+
+Returns a mirrored copy of the image. The parameter {\it horizontally}
+indicates the orientation.
+
+\membersection{wxImage::Replace}\label{wximagereplace}
+
+\func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
+\param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
+
+Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
+
+\membersection{wxImage::Rescale}\label{wximagerescale}
+
+\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
+
+Changes the size of the image in-place: after a call to this function, the
+image will have the given width and height.
+
+Returns the (modified) image itself.
+
+\wxheading{See also}
+
+\helpref{Scale}{wximagescale}
+
+\membersection{wxImage::Rotate}\label{wximagerotate}
+
+\func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
+ \param{bool}{ interpolating = true}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
+
+Rotates the image about the given point, by {\it angle} radians. Passing true
+to {\it interpolating} results in better image quality, but is slower. If the
+image has a mask, then the mask colour is used for the uncovered pixels in the
+rotated image background. Else, black (rgb 0, 0, 0) will be used.
+
+Returns the rotated image, leaving this image intact.
+
+\membersection{wxImage::Rotate90}\label{wximagerotate90}
+
+\constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = true}}
+
+Returns a copy of the image rotated 90 degrees in the direction
+indicated by {\it clockwise}.
+
\membersection{wxImage::SaveFile}\label{wximagesavefile}
\constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
\wxheading{Return value}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{Remarks}
-Depending on how wxWindows has been configured, not all formats may be available.
+Depending on how wxWidgets has been configured, not all formats may be available.
Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
hotspot before saving an image into a cursor file (default hotspot is in
\end{itemize}
}
-\membersection{wxImage::Mirror}\label{wximagemirror}
-
-\constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = TRUE}}
-
-Returns a mirrored copy of the image. The parameter {\it horizontally}
-indicates the orientation.
-
-\membersection{wxImage::Replace}\label{wximagereplace}
-
-\func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
-\param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
-
-Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
-
-\membersection{wxImage::Rescale}\label{wximagerescale}
-
-\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
-
-Changes the size of the image in-place: after a call to this function, the
-image will have the given width and height.
-
-Returns the (modified) image itself.
-
-\wxheading{See also}
-
-\helpref{Scale}{wximagescale}
-
-\membersection{wxImage::Rotate}\label{wximagerotate}
-
-\func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
- \param{bool}{ interpolating = TRUE}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
-
-Rotates the image about the given point, by {\it angle} radians. Passing TRUE
-to {\it interpolating} results in better image quality, but is slower. If the
-image has a mask, then the mask colour is used for the uncovered pixels in the
-rotated image background. Else, black (rgb 0, 0, 0) will be used.
-
-Returns the rotated image, leaving this image intact.
-
-\membersection{wxImage::Rotate90}\label{wximagerotate90}
-
-\constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = TRUE}}
-
-Returns a copy of the image rotated 90 degrees in the direction
-indicated by {\it clockwise}.
-
\membersection{wxImage::Scale}\label{wximagescale}
\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
// rescale it to have size of 32*32
if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
{
- wxImage image(bmp);
+ wxImage image = bmp.ConvertToImage();
bmp = wxBitmap(image.Scale(32, 32));
// another possibility:
\helpref{Rescale}{wximagerescale}
+\membersection{wxImage::SetAlpha}\label{wximagesetalpha}
+
+\func{void}{SetAlpha}{\param{unsigned char *}{alpha = {\tt NULL}}}
+
+This function is similar to \helpref{SetData}{wximagesetdata} and has similar
+restrictions. The pointer passed to it may however be {\tt NULL} in which case
+the function will allocate the alpha array internally -- this is useful to add
+alpha channel data to an image which doesn't have any. If the pointer is not
+{\tt NULL}, it must have one byte for each image pixel and be allocated with
+{\tt malloc()}. wxImage takes ownership of the pointer and will free it.
+
+\func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
+
+Sets the alpha value for the given pixel. This function should only be called
+if the image has alpha channel data, use \helpref{HasAlpha}{wximagehasalpha} to
+check for this.
+
\membersection{wxImage::SetData}\label{wximagesetdata}
\func{void}{SetData}{\param{unsigned char*}{data}}
the size (width*height*3) or results will be unexpected. Don't use this
method if you aren't sure you know what you are doing.
+The data must have been allocated with {\tt malloc()}, {\large {\bf NOT}} with
+{\tt operator new}.
+
+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
+\helpref{wxImage::GetData}{wximagegetdata}.
+
\membersection{wxImage::SetMask}\label{wximagesetmask}
-\func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
+\func{void}{SetMask}{\param{bool}{ hasMask = true}}
Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
\membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
-\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
+\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
Sets the mask colour for this image (and tells the image to use the mask).
\wxheading{Return value}
-Returns FALSE if {\it mask} does not have same dimensions as the image or if
-there is no unused colour left. Returns TRUE if the mask was successfully
+Returns false if {\it 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.
\wxheading{Notes}
\membersection{wxImage::operator $==$}
-\func{bool}{operator $==$}{\param{const wxImage\& }{image}}
+\constfunc{bool}{operator $==$}{\param{const wxImage\& }{image}}
Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).
\wxheading{Return value}
-Returns TRUE if the images were effectively equal, FALSE otherwise.
+Returns true if the images were effectively equal, false otherwise.
\membersection{wxImage::operator $!=$}
-\func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
+\constfunc{bool}{operator $!=$}{\param{const wxImage\& }{image}}
Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).
\wxheading{Return value}
-Returns TRUE if the images were unequal, FALSE otherwise.
+Returns true if the images were unequal, false otherwise.
\section{\class{wxImageHandler}}\label{wximagehandler}
This software is based in part on the work of the Independent JPEG Group.
-(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
+(Applies when wxWidgets is linked with JPEG support. wxJPEGHandler uses libjpeg
created by IJG.)
\wxheading{Derived from}
\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
-\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=TRUE}, \param{int}{ index=0}}
+\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=true}, \param{int}{ index=0}}
Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
more than one image and the image handler is capable of retrieving these individually, {\it index}
\docparam{stream}{Opened input stream for reading image data.}
-\docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
+\docparam{verbose}{If set to true, errors reported by the image handler will produce wxLogMessages.}
\docparam{index}{The index of the image in the file (starting from zero).}
\wxheading{Return value}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{See also}
\wxheading{Return value}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{See also}
projects / wxWidgets.git / blobdiff