Robert Lang's patch [ 1583183 ] Fixes printing/print preview inconsistencies

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

diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex
index 181a074db6587787c01e5a9127206a32cd4d5325..fa8d2da1e87f1a3cb69fccbe227f68e8e56d8d8a 100644 (file)
--- a/docs/latex/wx/image.tex
+++ b/docs/latex/wx/image.tex
@@ -95,7 +95,7 @@ Default constructor.
 
 \func{}{wxImage}{\param{const wxImage\& }{image}}
 
 
 \func{}{wxImage}{\param{const wxImage\& }{image}}
 

-Copy constructor.
+Copy constructor, uses \helpref{reference counting}{trefcount}.

 
 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
 
 
 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
 


@@ -128,7 +128,7 @@ 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}}
+\func{}{wxImage}{\param{const char* const* }{xpmData}}

 
 Creates an image from XPM data.
 
 
 Creates an image from XPM data.
 


@@ -243,6 +243,46 @@ returns true if the current image handlers can read this file
 
 \pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
 
 
 \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}
 \membersection{wxImage::CleanUpHandlers}\label{wximagecleanuphandlers}
 
 \func{static void}{CleanUpHandlers}{\void}


@@ -304,6 +344,16 @@ Deprecated, use equivalent \helpref{wxBitmap constructor}{wxbitmapctor}
 (which takes wxImage and depth as its arguments) instead.
 
 
 (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}}
 \membersection{wxImage::ConvertToMono}\label{wxbitmapconverttomono}
 
 \constfunc{wxImage}{ConvertToMono}{\param{unsigned char}{ r}, \param{unsigned char}{ g}, \param{unsigned char}{ b}}


@@ -569,9 +619,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
 \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}
 
 
 \membersection{wxImage::GetRed}\label{wximagegetred}


@@ -834,9 +884,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.
 
 
 Returns true if image data is present.
 


@@ -845,7 +895,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}}
 
 
 \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.
 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,11 +946,13 @@ Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
 
 \membersection{wxImage::Rescale}\label{wximagerescale}
 
 
 \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.
 
 
 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}
 Returns the (modified) image itself.
 
 \wxheading{See also}


@@ -1040,14 +1092,31 @@ mimetype to the named file}
 
 \membersection{wxImage::Scale}\label{wximagescale}
 
 
 \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.
 
 
 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:
 
 
 Example:
 


@@ -1099,7 +1168,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
 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}}
 do it.
 
 \func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}


@@ -1218,9 +1287,7 @@ data.
 
 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 
 
 \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{Parameters}
 


@@ -1311,14 +1378,14 @@ Destroys the wxImageHandler object.
 
 \membersection{wxImageHandler::GetName}\label{wximagehandlergetname}
 
 
 \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}
 
 
 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.
 
 
 Gets the file extension associated with this handler.
 


@@ -1348,7 +1415,7 @@ Gets the image type associated with this handler.
 
 \membersection{wxImageHandler::GetMimeType}\label{wximagehandlergetmimetype}
 
 
 \membersection{wxImageHandler::GetMimeType}\label{wximagehandlergetmimetype}
 

-\constfunc{wxString}{GetMimeType}{\void}
+\constfunc{const wxString\&}{GetMimeType}{\void}

 
 Gets the MIME type associated with this handler.
 
 
 Gets the MIME type associated with this handler.