X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ce045aed585af0f00b72f1cdba893b47ac2e0e55..78cb09ec439962b53ba75fef814b9a3871412287:/docs/latex/wx/image.tex?ds=sidebyside diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index 181a074db6..8a7721ff5d 100644 --- a/docs/latex/wx/image.tex +++ b/docs/latex/wx/image.tex @@ -36,16 +36,18 @@ means that the pixel is 100\% opaque. 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 -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). +an alpha channel with \helpref{HasAlpha}{wximagehasalpha}. Note that currently +only the PNG format has full alpha channel support so only the images loaded +from PNG files can have alpha and, if you initialize the image alpha channel +yourself using \helpref{SetAlpha}{wximagesetalpha}, you should save it in PNG +format to avoid losing it. + \wxheading{Available image handlers} 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 call \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}. \twocolwidtha{5cm}% @@ -57,6 +59,7 @@ handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or \twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).} \twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).} \twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.} +\twocolitem{\indexit{wxTGAHandler}}{For loading only.} \twocolitem{\indexit{wxIFFHandler}}{For loading only.} \twocolitem{\indexit{wxXPMHandler}}{For loading and saving.} \twocolitem{\indexit{wxICOHandler}}{For loading and saving.} @@ -79,6 +82,10 @@ PNM format, {\bf wxPNMHandler} will always save as raw RGB. +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{See also} \helpref{wxBitmap}{wxbitmap}, @@ -95,7 +102,7 @@ Default constructor. \func{}{wxImage}{\param{const wxImage\& }{image}} -Copy constructor. +Copy constructor, uses \helpref{reference counting}{trefcount}. \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}} @@ -128,7 +135,7 @@ Loads an image from a file. 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. @@ -153,6 +160,7 @@ Creates an image from XPM data. \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.} \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.} \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_TGA}}{Load a TGA bitmap file.} \twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.} \twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).} \twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).} @@ -222,6 +230,7 @@ platform-dependent bitmap} \func{}{\destruct{wxImage}}{\void} Destructor. +See \helpref{reference-counted object destruction}{refcountdestruct} for more info. \membersection{wxImage::AddHandler}\label{wximageaddhandler} @@ -243,6 +252,46 @@ returns true if the current image handlers can read this file \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} @@ -304,6 +353,16 @@ Deprecated, use equivalent \helpref{wxBitmap constructor}{wxbitmapctor} (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}} @@ -421,7 +480,7 @@ It is usually a good idea to prepend a description before passing the result to Example: \begin{verbatim} - wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN ); + wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxFD_OPEN ); \end{verbatim} \wxheading{See also} @@ -569,9 +628,9 @@ 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} @@ -722,7 +781,8 @@ the user. \wxheading{See also} \helpref{wxImageHandler}{wximagehandler}, -\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} +\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}, +\helpref{wxQuantize}{wxquantize} \membersection{wxImage::InsertHandler}\label{wximageinserthandler} @@ -834,9 +894,9 @@ mimetype from a file} -\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. @@ -845,7 +905,7 @@ Returns true if image data is present. \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 +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. @@ -886,6 +946,12 @@ Returns a mirrored copy of the image. The parameter {\it horizontally} indicates the orientation. +\membersection{wxImage::Paste}\label{wximagepaste} + +\func{void}{Paste}{\param{const wxImage\& }{image}, \param{int }{x}, \param{int }{y}} + +Copy the data of the given \arg{image} to the specified position in this image. + \membersection{wxImage::Replace}\label{wximagereplace} \func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1}, @@ -896,11 +962,13 @@ 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}} +\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, 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} @@ -1040,14 +1108,31 @@ mimetype to the named file} \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: @@ -1081,8 +1166,10 @@ Returns a resized version of this image without scaling it by adding either a bo 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. +then the areas of the larger image not covered by this image are made +transparent by filling them with the image mask colour (which will be allocated +automatically if it isn't currently set). Otherwise, the areas will be filled +with the colour with the specified RGB components. \wxheading{See also} @@ -1099,7 +1186,7 @@ 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 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}} @@ -1218,9 +1305,7 @@ data. \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} @@ -1231,36 +1316,6 @@ counter. It is a fast operation. Returns 'this' object. -\membersection{wxImage::operator $==$}\label{wximageequal} - -\constfunc{bool}{operator $==$}{\param{const wxImage\& }{image}} - -Equality operator. This operator tests whether the internal data pointers are -equal (a fast test). - -\wxheading{Parameters} - -\docparam{image}{Image to compare with 'this'} - -\wxheading{Return value} - -Returns true if the images were effectively equal, false otherwise. - - -\membersection{wxImage::operator $!=$}\label{wximagenotequal} - -\constfunc{bool}{operator $!=$}{\param{const wxImage\& }{image}} - -Inequality operator. This operator tests whether the internal data pointers are -unequal (a fast test). - -\wxheading{Parameters} - -\docparam{image}{Image to compare with 'this'} - -\wxheading{Return value} - -Returns true if the images were unequal, false otherwise. \section{\class{wxImageHandler}}\label{wximagehandler} @@ -1286,6 +1341,10 @@ created by IJG.) +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{See also} \helpref{wxImage}{wximage}, @@ -1311,14 +1370,14 @@ Destroys the wxImageHandler object. \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. @@ -1348,7 +1407,7 @@ Gets the image type associated with this handler. \membersection{wxImageHandler::GetMimeType}\label{wximagehandlergetmimetype} -\constfunc{wxString}{GetMimeType}{\void} +\constfunc{const wxString\&}{GetMimeType}{\void} Gets the MIME type associated with this handler.