X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/07d0abae96558ccb1c0a2bb3d0991e47b6dea549..11ef729d54ee338a1d569b5a238c2feb84d488ff:/docs/latex/wx/image.tex diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index 18c099fb71..ccec15b3e8 100644 --- 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 -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. -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 -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} @@ -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. -\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 @@ -118,6 +117,10 @@ Loads an image from a file. 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.} @@ -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.} +\docparam{xpmData}{A pointer to XPM image data.} + \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} -\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 @@ -540,6 +545,14 @@ Gets the green 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} @@ -576,6 +589,26 @@ Gets the width of the image in pixels. \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} @@ -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. +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 @@ -639,6 +688,16 @@ Returns true if the given option is present. The function is case-insensitive to \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} @@ -669,6 +728,15 @@ of a given handler class in an application session.} \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}} @@ -762,6 +830,25 @@ mimetype from a file} 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}} @@ -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}} -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. @@ -810,6 +897,24 @@ Returns the (modified) image itself. \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}, @@ -823,6 +928,15 @@ rotated image background. Else, black (rgb 0, 0, 0) will be used. 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}} @@ -948,16 +1062,34 @@ Example: \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} -\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 -{\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}} @@ -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. +\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}}