+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: image.tex
+%% Purpose: wxImage documentation
+%% Author: wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets Team
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{\class{wxImage}}\label{wximage}
This class encapsulates a platform-independent image. An image can be created
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 \helpref{wxDC}{wxdc}. Instead,
+A wxImage cannot (currently) be drawn directly to a \helpref{wxDC}{wxdc}. Instead,
a platform-specific \helpref{wxBitmap}{wxbitmap} object must be created from it using
-the \helpref{wxBitmap::wxBitmap(wxImage,int depth)}{wxbitmapctor} constructor.
+the \helpref{wxBitmap::wxBitmap(wxImage,int depth)}{wxbitmapctor} constructor.
This bitmap can then
be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
corresponds to a transparent pixel (null opacity) while a value of $255$
means that the pixel is 100\% opaque.
-Unlike RGB data, not all images have an alpha channel and before using
+Unlike RGB data, not all images have an alpha channel and before using
\helpref{GetAlpha}{wximagegetalpha} you should check if this image contains
an alpha channel with \helpref{HasAlpha}{wximagehasalpha}. Note that currently only
images loaded from PNG files with transparency information will have an alpha
The following image handlers are available. {\bf wxBMPHandler} is always
installed by default. To use other image formats, install the appropriate
-handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
+handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
\twocolwidtha{5cm}%
\wxheading{See also}
-\helpref{wxBitmap}{wxbitmap},
+\helpref{wxBitmap}{wxbitmap},
\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
\latexignore{\rtfignore{\wxheading{Members}}}
\func{}{wxImage}{\param{const wxImage\& }{image}}
-Copy constructor.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
\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
+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
image data in its destructor, otherwise it will free it by calling
{\it free()}.
Loads an image from an input stream.
-\func{}{wxImage}{\param{const char** }{xpmData}}
+\func{}{wxImage}{\param{const char* const* }{xpmData}}
Creates an image from XPM data.
\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
\docparam{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. The default value (-1) means
-"choose the default image" and is interpreted as the first image (index=0) by
+This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
+"choose the default image" and is 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.}
\docparam{xpmData}{A pointer to XPM image data.}
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
+initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
-Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
+Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
hotspot for loaded cursor file:
\begin{verbatim}
int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
\pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
+
+\membersection{wxImage::Blur}\label{wximageblur}
+
+\func{wxImage}{Blur}{\param{int}{ blurRadius}}
+
+Blurs the image in both horizontal and vertical directions by the specified pixel
+{\it blurRadius}. This should not be used when using a single mask colour
+for transparency.
+
+\wxheading{See also}
+
+\helpref{BlurHorizontal}{wximagehorzblur}
+\helpref{BlurVertical}{wximagevertblur}
+
+
+\membersection{wxImage::BlurHorizontal}\label{wximagehorzblur}
+
+\func{wxImage}{BlurHorizontal}{\param{int}{ blurRadius}}
+
+Blurs the image in the horizontal direction only. This should not be used
+when using a single mask colour for transparency.
+\wxheading{See also}
+
+\helpref{Blur}{wximageblur}
+\helpref{BlurVertical}{wximagevertblur}
+
+
+\membersection{wxImage::BlurVertical}\label{wximagevertblur}
+
+\func{wxImage}{BlurVertical}{\param{int}{ blurRadius}}
+
+Blurs the image in the vertical direction only. This should not be used
+when using a single mask colour for transparency.
+
+\wxheading{See also}
+
+\helpref{Blur}{wximageblur}
+\helpref{BlurHorizontal}{wximagehorzblur}
+
+
\membersection{wxImage::CleanUpHandlers}\label{wximagecleanuphandlers}
\func{static void}{CleanUpHandlers}{\void}
\constfunc{unsigned long}{ComputeHistogram}{\param{wxImageHistogram\& }{histogram}}
-Computes the histogram of the image. {\it histogram} is a reference to
-wxImageHistogram object. wxImageHistogram is a specialization of
+Computes the histogram of the image. {\it histogram} is a reference to
+wxImageHistogram object. wxImageHistogram is a specialization of
\helpref{wxHashMap}{wxhashmap} "template" and is defined as follows:
\begin{verbatim}
\wxheading{Return value}
-\false if FindFirstUnusedColour returns \false, \true otherwise.
+\false if FindFirstUnusedColour returns \false, \true otherwise.
\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
(which takes wxImage and depth as its arguments) instead.
+\membersection{wxImage::ConvertToGreyscale}\label{wximageconverttogreyscale}
+
+\constfunc{wxImage}{ConvertToGreyscale}{\param{double}{ lr = 0.299}, \param{double}{ lg = 0.587}, \param{double}{ lb = 0.114}}
+
+Returns a greyscale version of the image. The returned image uses the luminance
+component of the original to calculate the greyscale. Defaults to using
+ITU-T BT.601 when converting to YUV, where every pixel equals
+(R * {\it lr}) + (G * {\it lg}) + (B * {\it lb}).
+
+
\membersection{wxImage::ConvertToMono}\label{wxbitmapconverttomono}
\constfunc{wxImage}{ConvertToMono}{\param{unsigned char}{ r}, \param{unsigned char}{ g}, \param{unsigned char}{ b}}
Returns monochromatic version of the image. The returned image has white
-colour where the original has {\it (r,g,b)} colour and black colour
+colour where the original has {\it (r,g,b)} colour and black colour
everywhere else.
Example:
\begin{verbatim}
- wxFileDialog FileDlg( this, "Choose Image", ::wxGetWorkingDirectory(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN );
+ wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN );
\end{verbatim}
\wxheading{See also}
\func{static int}{GetImageCount}{\param{wxInputStream\&}{ stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
-If the image file contains more than one image and the image handler is capable
+If the image file contains more than one image and the image handler is capable
of retrieving these individually, this function will return the number of
available images.
\constfunc{bool}{GetOrFindMaskColour}{\param{unsigned char}{ *r}, \param{unsigned char}{ *g}, \param{unsigned char}{ *b}}
-Get the current mask colour or find a suitable unused colour that could be
+Get the current mask colour or find a suitable unused colour that could be
used as a mask colour. Returns {\tt true} if the image currently has a mask.
\constfunc{const wxPalette\&}{GetPalette}{\void}
Returns the palette associated with the image. Currently the palette is only
-used when converting to wxBitmap under Windows.
-
-Eventually wxImage handlers will set the palette if one exists in the image file.
+used when converting to wxBitmap under Windows. Some of the wxImage handlers
+have been modified to set the palette if one exists in the image file (usually
+256 or less colour images in GIF or PNG format).
\membersection{wxImage::GetRed}\label{wximagegetred}
\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
-Returns a sub image of the current one as long as the rect belongs entirely to
+Returns a sub image of the current one as long as the rect belongs entirely to
the image.
\helpref{wxImage::GetHeight}{wximagegetheight}
+\membersection{HSVValue::HSVValue}\label{hsvvaluehsvvalue}
+
+\func{}{HSVValue}{\param{double }{h = 0.0}, \param{double }{s = 0.0}, \param{double }{v = 0.0}}
+
+Constructor for HSVValue, an object that contains values for hue, saturation and value which
+represent the value of a color. It is used by \helpref{wxImage::HSVtoRGB}{wximagehsvtorgb}
+and \helpref{wxImage::RGBtoHSV}{wximagergbtohsv}, which
+converts between HSV color space and RGB color space.
+
+\pythonnote{use wxImage\_HSVValue in wxPython}
+
+
+
+\membersection{wxImage::HSVtoRGB}\label{wximagehsvtorgb}
+
+\func{wxImage::RGBValue}{HSVtoRGB}{\param{const HSVValue \& }{hsv}}
+
+Converts a color in HSV color space to RGB color space.
+
+
\membersection{wxImage::HasAlpha}\label{wximagehasalpha}
\constfunc{bool}{HasAlpha}{\void}
Gets a user-defined option as an integer. The function is case-insensitive to {\it name}.
-If the given option is not present, the function returns $0$. Use
+If the given option is not present, the function returns $0$. Use
\helpref{wxImage::HasOption}{wximagehasoption} is $0$ is a possibly valid value
for the option.
\wxheading{See also}
-\helpref{wxImageHandler}{wximagehandler},
+\helpref{wxImageHandler}{wximagehandler},
\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
\membersection{wxImage::IsTransparent}\label{wximageistransparent}
-\constfunc{IsTransparent}{\param{int }{x}, \param{int }{y}, \param{unsigned char threshold = $128$}}
+\constfunc{bool}{IsTransparent}{\param{int }{x}, \param{int }{y}, \param{unsigned char}{ threshold = $128$}}
Returns \true if the given pixel is transparent, i.e. either has the mask
colour if this image has a mask or if this image has alpha channel and alpha
\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
\docparam{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. The default value (-1) means
-"choose the default image" and is interpreted as the first image (index=0) by
+This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
+"choose the default image" and is 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.}
\wxheading{Remarks}
Depending on how wxWidgets has been configured, not all formats may be available.
-Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
+Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
hotspot for loaded cursor file:
\begin{verbatim}
int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
-\membersection{wxImage::Ok}\label{wximageok}
+\membersection{wxImage::IsOk}\label{wximageisok}
-\constfunc{bool}{Ok}{\void}
+\constfunc{bool}{IsOk}{\void}
Returns true if image data is present.
+\membersection{RGBValue::RGBValue}\label{rgbvaluergbvalue}
+
+\func{}{RGBValue}{\param{unsigned char }{r = 0}, \param{unsigned char }{g = 0}, \param{unsigned char }{b = 0}}
+
+Constructor for RGBValue, an object that contains values for red, green and blue which
+represent the value of a color. It is used by \helpref{wxImage::HSVtoRGB}{wximagehsvtorgb}
+and \helpref{wxImage::RGBtoHSV}{wximagergbtohsv}, which
+converts between HSV color space and RGB color space.
+
+\pythonnote{use wxImage\_RGBValue in wxPython}
+
+
+\membersection{wxImage::RGBtoHSV}\label{wximagergbtohsv}
+
+\func{wxImage::HSVValue}{RGBtoHSV}{\param{const RGBValue\& }{rgb}}
+
+Converts a color in RGB color space to HSV color space.
+
+
\membersection{wxImage::RemoveHandler}\label{wximageremovehandler}
\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
\membersection{wxImage::Rescale}\label{wximagerescale}
-\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
+\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}, \param{int}{ quality = wxIMAGE\_QUALITY\_NORMAL}}
-Changes the size of the image in-place by scaling it: after a call to this function,
+Changes the size of the image in-place by scaling it: after a call to this function,
the image will have the given width and height.
+For a description of the {\it quality} parameter, see the \helpref{Scale}{wximagescale} function.
+
Returns the (modified) image itself.
\wxheading{See also}
\func{wxImage \&}{Resize}{\param{const wxSize\&}{ size}, \param{const wxPoint&}{ pos}, \param{int}{ red = -1}, \param{int}{ green = -1}, \param{int}{ blue = -1}}
-Changes the size of the image in-place without scaling it by adding either a border
-with the given colour or cropping as necessary. The image is pasted into a new
-image with the given {\it size} and background colour at the position {\it pos}
-relative to the upper left of the new image. If {\it red = green = blue = -1}
-then use either the current mask colour if set or find, use, and set a
+Changes the size of the image in-place without scaling it by adding either a border
+with the given colour or cropping as necessary. The image is pasted into a new
+image with the given {\it size} and background colour at the position {\it pos}
+relative to the upper left of the new image. If {\it red = green = blue = -1}
+then use either the current mask colour if set or find, use, and set a
suitable mask colour for any newly exposed areas.
Returns the (modified) image itself.
Returns the rotated image, leaving this image intact.
+\membersection{wxImage::RotateHue}\label{wximagerotatehue}
+
+\func{void}{RotateHue}{\param{double}{ angle}}
+
+Rotates the hue of each pixel in the image by {\it angle}, which is a double in
+the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 corresponds
+to +360 degrees.
+
+
\membersection{wxImage::Rotate90}\label{wximagerotate90}
\constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = true}}
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
+Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
+hotspot before saving an image into a cursor file (default hotspot is in
the centre of the image):
\begin{verbatim}
image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
\membersection{wxImage::Scale}\label{wximagescale}
-\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
+\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}, \param{int}{ quality = wxIMAGE\_QUALITY\_NORMAL}}
Returns a scaled version of the image. This is also useful for
scaling bitmaps in general as the only other way to scale bitmaps
is to blit a wxMemoryDC into another wxMemoryDC.
-It may be mentioned that the GTK port uses this function internally
-to scale bitmaps when using mapping modes in wxDC.
+\docparam{quality}{Determines what method to use for resampling the image. Can be one of the following:
+
+\twocolwidtha{5cm}%
+\begin{twocollist}
+\twocolitem{{\bf wxIMAGE\_QUALITY\_NORMAL}}{Uses the normal default scaling method of pixel replication}
+\twocolitem{{\bf wxIMAGE\_QUALITY\_HIGH}}{Uses bicubic and box averaging resampling methods for upsampling and downsampling respectively}
+\end{twocollist}}
+
+It should be noted that although using wxIMAGE\_QUALITY\_HIGH produces much nicer
+looking results it is a slower method. Downsampling will use the box averaging method
+which seems to operate very fast. If you are upsampling larger images using
+this method you will most likely notice that it is a bit slower and in extreme cases
+it will be quite substantially slower as the bicubic algorithm has to process a lot of
+data.
+
+It should also be noted that the high quality scaling may not work as expected
+when using a single mask colour for transparency, as the scaling will blur the
+image and will therefore remove the mask partially. Using the alpha channel
+will work.
Example:
\constfunc{wxImage}{Size}{\param{const wxSize\&}{ size}, \param{const wxPoint&}{ pos}, \param{int}{ red = -1}, \param{int}{ green = -1}, \param{int}{ blue = -1}}
-Returns a resized version of this image without scaling it by adding either a border
-with the given colour or cropping as necessary. The image is pasted into a new
-image with the given {\it size} and background colour at the position {\it pos}
-relative to the upper left of the new image. If {\it red = green = blue = -1}
-then use either the current mask colour if set or find, use, and set a
+Returns a resized version of this image without scaling it by adding either a border
+with the given colour or cropping as necessary. The image is pasted into a new
+image with the given {\it size} and background colour at the position {\it pos}
+relative to the upper left of the new image. If {\it red = green = blue = -1}
+then use either the current mask colour if set or find, use, and set a
suitable mask colour for any newly exposed areas.
\wxheading{See also}
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
+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 unless
-\arg{static\_data} parameter is set.to \true -- in this case the caller should
+\arg{static\_data} parameter is set to \true -- in this case the caller should
do it.
\func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb}
in {\it mask} will be masked in the image. This is done by first finding an
unused colour in the image, setting this colour as the mask colour and then
-using this colour to draw all pixels in the image who corresponding pixel
+using this colour to draw all pixels in the image who corresponding pixel
in {\it mask} has given RGB value.
\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
+there is no unused colour left. Returns true if the mask was successfully
applied.
\wxheading{Notes}
Sets the pixel at the given coordinate. This routine performs bounds-checks
for the coordinate so it can be considered a safe way to manipulate the
data, but in some cases this might be too slow so that the data will have to
-be set directly. In that case you will have to get access to the image data
+be set directly. In that case you will have to get access to the image data
using the \helpref{GetData}{wximagegetdata} method.
\func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
-Assignment operator. This operator does not copy any data, but instead
-passes a pointer to the data in {\it image} and increments a reference
-counter. It is a fast operation.
+Assignment operator, using \helpref{reference counting}{trefcount}.
\wxheading{Parameters}
\wxheading{See also}
-\helpref{wxImage}{wximage},
+\helpref{wxImage}{wximage},
\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
\latexignore{\rtfignore{\wxheading{Members}}}
\membersection{wxImageHandler::GetName}\label{wximagehandlergetname}
-\constfunc{wxString}{GetName}{\void}
+\constfunc{const wxString\&}{GetName}{\void}
Gets the name of this handler.
\membersection{wxImageHandler::GetExtension}\label{wximagehandlergetextension}
-\constfunc{wxString}{GetExtension}{\void}
+\constfunc{const wxString\&}{GetExtension}{\void}
Gets the file extension associated with this handler.
\func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
-If the image file contains more than one image and the image handler is capable
+If the image file contains more than one image and the image handler is capable
of retrieving these individually, this function will return the number of
available images.
\membersection{wxImageHandler::GetMimeType}\label{wximagehandlergetmimetype}
-\constfunc{wxString}{GetMimeType}{\void}
+\constfunc{const wxString\&}{GetMimeType}{\void}
Gets the MIME type associated with this handler.
\wxheading{See also}
-\helpref{wxImage::LoadFile}{wximageloadfile},
-\helpref{wxImage::SaveFile}{wximagesavefile},
+\helpref{wxImage::LoadFile}{wximageloadfile},
+\helpref{wxImage::SaveFile}{wximagesavefile},
\helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
\wxheading{See also}
-\helpref{wxImage::LoadFile}{wximageloadfile},
-\helpref{wxImage::SaveFile}{wximagesavefile},
+\helpref{wxImage::LoadFile}{wximageloadfile},
+\helpref{wxImage::SaveFile}{wximagesavefile},
\helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
\wxheading{Parameters}
\docparam{name}{Handler type.}
-
projects / wxWidgets.git / blobdiff