X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/df816ad92f556233cc6346e74dbbdb0317f442cd..a4d6005e618d8d6ac3529f0cebe369ab76e5d71b:/docs/latex/wx/image.tex

diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex
index 198750f426..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.
 
 <wx/image.h>
 
+\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}
@@ -431,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}
@@ -732,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}
@@ -844,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.
 
@@ -855,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.
@@ -896,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},
@@ -906,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}
@@ -1050,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:
 
@@ -1091,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}
 
@@ -1228,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}
 
@@ -1241,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}
 
@@ -1296,6 +1341,10 @@ created by IJG.)
 
 <wx/image.h>
 
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
 \wxheading{See also}
 
 \helpref{wxImage}{wximage},
@@ -1321,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.
 
@@ -1358,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.
 
