Added missing include

[wxWidgets.git] / docs / latex / wx / image.tex

diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex
index 18c099fb71e3f635cbfa09ee22683795b2a83dd4..ccec15b3e852ab76f0cdda44f4d0c7645bb2548c 100644 (file)
--- a/docs/latex/wx/image.tex
+++ b/docs/latex/wx/image.tex
@@ -19,17 +19,16 @@ creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
 
 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
 
 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$
+it also stores a byte representing the pixel opacity. An alpha value of $0$
+corresponds to a transparent pixel (null opacity) while a value of $255$

 means that the pixel is 100\% opaque.
 
 means that the pixel is 100\% opaque.
 

-Unlike the RGB data, not all images have the 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
 \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).
+an alpha channel with \helpref{HasAlpha}{wximagehasalpha}. Note that currently only
+images loaded from PNG files with transparency information will have an alpha
+channel but alpha support will be added to the other formats as well (as well
+as support for saving images with alpha channel which also isn't implemented).

 
 \wxheading{Available image handlers}
 
 
 \wxheading{Available image handlers}
 


@@ -99,7 +98,7 @@ and forth without loss in that respect.
 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.
 
 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
 
 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


@@ -118,6 +117,10 @@ Loads an image from a file.
 
 Loads an image from an input stream.
 
 
 Loads an image from an input stream.
 

+\func{}{wxImage}{\param{const char** }{xpmData}}
+
+Creates an image from XPM data.
+

 \wxheading{Parameters}
 
 \docparam{width}{Specifies the width of the image.}
 \wxheading{Parameters}
 
 \docparam{width}{Specifies the width of the image.}


@@ -153,6 +156,8 @@ 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.}
 
 "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.}
+

 \wxheading{Remarks}
 
 Depending on how wxWidgets has been configured, not all formats may be available.
 \wxheading{Remarks}
 
 Depending on how wxWidgets has been configured, not all formats may be available.


@@ -265,7 +270,7 @@ Returns number of colours in the histogram.
 
 \membersection{wxImage::ConvertAlphaToMask}\label{wximageconvertalphatomask}
 
 
 \membersection{wxImage::ConvertAlphaToMask}\label{wximageconvertalphatomask}
 

-\func{bool}{ConvertAlphaToMask}{\param{unsigned char}{ threshold = 128}}
+\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
 
 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


@@ -540,6 +545,14 @@ Gets the green value of the mask colour.
 Gets the red value of the mask colour.
 
 
 Gets the red value of the mask colour.
 
 

+\membersection{wxImage::GetOrFindMaskColour}\label{wximagegetgetorsetmaskcolour}
+
+\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 
+used as a mask colour. Returns {\tt true} if the image currently has a mask.
+
+

 \membersection{wxImage::GetPalette}\label{wximagegetpalette}
 
 \constfunc{const wxPalette\&}{GetPalette}{\void}
 \membersection{wxImage::GetPalette}\label{wximagegetpalette}
 
 \constfunc{const wxPalette\&}{GetPalette}{\void}


@@ -576,6 +589,26 @@ Gets the width of the image in pixels.
 \helpref{wxImage::GetHeight}{wximagegetheight}
 
 
 \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}
 \membersection{wxImage::HasAlpha}\label{wximagehasalpha}
 
 \constfunc{bool}{HasAlpha}{\void}


@@ -620,6 +653,22 @@ 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.
 
 \helpref{wxImage::HasOption}{wximagehasoption} is $0$ is a possibly valid value
 for the option.
 

+Options for wxPNGHandler
+\twocolwidtha{5cm}%
+\begin{twocollist}
+\twocolitem{wxIMAGE\_OPTION\_PNG\_FORMAT}{Format for saving a PNG file.}
+\twocolitem{wxIMAGE\_OPTION\_PNG\_BITDEPTH}{Bit depth for every channel (R/G/B/A).}
+\end{twocollist}
+
+Supported values for wxIMAGE\_OPTION\_PNG\_FORMAT:
+\twocolwidtha{5cm}%
+\begin{twocollist}
+\twocolitem{wxPNG\_TYPE\_COLOUR}{Stores RGB image.}
+\twocolitem{wxPNG\_TYPE\_GREY}{Stores grey image, converts from RGB.}
+\twocolitem{wxPNG\_TYPE\_GREY\_RED}{Stores grey image, uses red value as grey.}
+\end{twocollist}
+
+

 \wxheading{See also}
 
 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
 \wxheading{See also}
 
 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp


@@ -639,6 +688,16 @@ Returns true if the given option is present. The function is case-insensitive to
 \helpref{wxImage::GetOptionInt}{wximagegetoptionint}
 
 
 \helpref{wxImage::GetOptionInt}{wximagegetoptionint}
 
 

+\membersection{wxImage::InitAlpha}\label{wximageinitalpha}
+
+\func{void}{InitAlpha}{\void}
+
+Initializes the image alpha channel data. It is an error to call it
+if the image already has alpha data. If it doesn't, alpha data will be
+by default initialized to all pixels being fully opaque. But if the image has a
+a mask colour, all mask pixels will be completely transparent.
+
+

 \membersection{wxImage::InitStandardHandlers}\label{wximageinitstandardhandlers}
 
 \func{static void}{InitStandardHandlers}{\void}
 \membersection{wxImage::InitStandardHandlers}\label{wximageinitstandardhandlers}
 
 \func{static void}{InitStandardHandlers}{\void}


@@ -669,6 +728,15 @@ of a given handler class in an application session.}
 \helpref{wxImageHandler}{wximagehandler}
 
 
 \helpref{wxImageHandler}{wximagehandler}
 
 

+\membersection{wxImage::IsTransparent}\label{wximageistransparent}
+
+\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
+value of this pixel is strictly less than \arg{threshold}.
+
+

 \membersection{wxImage::LoadFile}\label{wximageloadfile}
 
 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
 \membersection{wxImage::LoadFile}\label{wximageloadfile}
 
 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}


@@ -762,6 +830,25 @@ mimetype from a file}
 Returns true if image data is present.
 
 
 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 blud 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::RemoveHandler}\label{wximageremovehandler}
 
 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}


@@ -800,8 +887,8 @@ Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
 
 \func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
 
 
 \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.
+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.

 
 Returns the (modified) image itself.
 
 
 Returns the (modified) image itself.
 


@@ -810,6 +897,24 @@ Returns the (modified) image itself.
 \helpref{Scale}{wximagescale}
 
 
 \helpref{Scale}{wximagescale}
 
 

+\membersection{wxImage::Resize}\label{wximageresize}
+
+\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 
+suitable mask colour for any newly exposed areas.
+
+Returns the (modified) image itself.
+
+\wxheading{See also}
+
+\helpref{Size}{wximagesize}
+
+

 \membersection{wxImage::Rotate}\label{wximagerotate}
 
 \func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
 \membersection{wxImage::Rotate}\label{wximagerotate}
 
 \func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},


@@ -823,6 +928,15 @@ rotated image background. Else, black (rgb 0, 0, 0) will be used.
 Returns the rotated image, leaving this image intact.
 
 
 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}}
 \membersection{wxImage::Rotate90}\label{wximagerotate90}
 
 \constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = true}}


@@ -948,16 +1062,34 @@ Example:
 \helpref{Rescale}{wximagerescale}
 
 
 \helpref{Rescale}{wximagerescale}
 
 

+\membersection{wxImage::Size}\label{wximagesize}
+
+\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 
+suitable mask colour for any newly exposed areas.
+
+\wxheading{See also}
+
+\helpref{Resize}{wximageresize}
+
+

 \membersection{wxImage::SetAlpha}\label{wximagesetalpha}
 
 \membersection{wxImage::SetAlpha}\label{wximagesetalpha}
 

-\func{void}{SetAlpha}{\param{unsigned char *}{alpha = {\tt NULL}}}
+\func{void}{SetAlpha}{\param{unsigned char *}{alpha = {\tt NULL}},\param{bool}{ static\_data = \false}}

 
 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 
 
 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.
+{\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
+do it.

 
 \func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
 
 
 \func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
 


@@ -1062,6 +1194,15 @@ be set directly. In that case you will have to get access to the image data
 using the \helpref{GetData}{wximagegetdata} method.
 
 
 using the \helpref{GetData}{wximagegetdata} method.
 
 

+\membersection{wxImage::SetRGB}\label{wximagesetrgbrect}
+
+\func{void}{SetRGB}{\param{wxRect \& }{rect}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
+
+Sets the colour of the pixels within the given rectangle. This routine performs
+bounds-checks for the coordinate so it can be considered a safe way to manipulate the
+data.
+
+

 \membersection{wxImage::operator $=$}\label{wximageassign}
 
 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 \membersection{wxImage::operator $=$}\label{wximageassign}
 
 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}