X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7468b994be5579ff57516f07e2d771831e73f65e..0d3a69ec7039f1c77bb3c23d1bfabb13d5df223f:/docs/latex/wx/image.tex

diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex
index 87ead917f6..68e11bd14c 100644
--- a/docs/latex/wx/image.tex
+++ b/docs/latex/wx/image.tex
@@ -14,6 +14,31 @@ be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
 One colour value of the image may be used as a mask colour which will lead to the automatic
 creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
 
+\wxheading{Available image handlers}
+
+The following image handlers are available. {\bf wxBMPHandler} is always
+installed by default. To use other image formats, install the appropiate
+handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
+
+\twocolwidtha{5cm}%
+\begin{twocollist}
+\twocolitem{{\bf \indexit{wxBMPHandler}}}{Only for loading, always installed.}
+\twocolitem{{\bf \indexit{wxPNGHandler}}}{For loading and saving.}
+\twocolitem{{\bf \indexit{wxJPEGHandler}}}{For loading and saving.}
+\twocolitem{{\bf \indexit{wxGIFHandler}}}{Only for loading, due to legal issues.}
+\twocolitem{{\bf \indexit{wxPCXHandler}}}{For loading and saving (see below).}
+\twocolitem{{\bf \indexit{wxPNMHandler}}}{For loading and saving (see below).}
+\twocolitem{{\bf \indexit{wxTIFFHandler}}}{For loading and saving.}
+\end{twocollist}
+
+When saving in PCX format, {\bf wxPCXHandler} will count the number of
+different colours in the image; if there are 256 or less colours, it will
+save as 8 bit, else it will save as 24 bit.
+
+Loading PNMs only works for ASCII or raw RGB images. When saving in
+PNM format, {\bf wxPNMHandler} will always save as raw RGB.
+
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
@@ -24,7 +49,7 @@ creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
 
 \wxheading{See also}
 
-\helpref{wxBitmap}{wxbitmap}
+\helpref{wxBitmap}{wxbitmap}, 
 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
@@ -49,13 +74,13 @@ and forth without loss in that respect.
 
 Creates an image with the given width and height.
 
-\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
+\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
 
 \func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
 
 Loads an image from a file.
 
-\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
+\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
 
 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
 
@@ -67,31 +92,33 @@ Loads an image from an input stream.
 
 \docparam{height}{Specifies the height of the image.}
 
-\docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
+\docparam{name}{Name of the file from which to load the image.}
 
-\docparam{stream}{This refers to an input stream. Its meaning is determined by the {\it type} parameter. It is equal to loading from file except that you provide opened stream (file, HTTP or any other custom class).}
+\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
 
 \docparam{type}{May be one of the following:
 
 \twocolwidtha{5cm}%
 \begin{twocollist}
 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.}
 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PCX}}}{Load a PCX bitmap file.}
 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNM}}}{Load a PNM bitmap file.}
-\end{twocollist}
-
-The validity of these flags depends on the platform and wxWindows configuration.
-If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file,
-a PNG (portable network graphics) file and a JPEG file is supported on all platforms that
-implement wxImage.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_TIF}}}{Load a TIFF bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ANY}}}{Will try to autodetect the format.}
+\end{twocollist}}
 
 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
 
-Note : you must call wxImage::AddHandler(new wxJPEGHandler) during application
-initialization in order to work with JPEGs.
+\wxheading{Remarks}
+
+Depending on how wxWindows has been configured, not all formats may be available.
+
+Note : any handler other than BMP must be previously
+initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
 
 \wxheading{See also}
 
@@ -297,7 +324,7 @@ Returns TRUE if there is a mask active, FALSE otherwise.
 \func{static void}{InitStandardHandlers}{\void}
 
 Internal use only. Adds standard image format handlers. It only install BMP
-for the time being, which is use by wxBitmap.
+for the time being, which is used by wxBitmap.
 
 This function is called by wxWindows on startup, and shouldn't be called by
 the user.
@@ -327,7 +354,7 @@ of a given handler class in an application session.}
 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}}
 
 Loads an image from a file. If no handler type is provided, the library will
-try to use wxBITMAP\_TYPE\_BMP.
+try to autodetect the format.
 
 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
 
@@ -337,11 +364,9 @@ Loads an image from an input stream.
 
 \wxheading{Parameters}
 
-\docparam{name}{A filename.
-The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{name}{Name of the file from which to load the image.}
 
-\docparam{stream}{An input stream.
-The meaning of {\it stream} data is determined by the {\it type} parameter.}
+\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
 
 \docparam{type}{One of the following values:
 
@@ -349,17 +374,20 @@ The meaning of {\it stream} data is determined by the {\it type} parameter.}
 \begin{twocollist}
 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
-\end{twocollist}
-
-The validity of these flags depends on the platform and wxWindows configuration.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
+\end{twocollist}}
 
 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
 
+\wxheading{Remarks}
+
+Depending on how wxWindows has been configured, not all formats may be available.
+
 \wxheading{Return value}
 
 TRUE if the operation succeeded, FALSE otherwise.
@@ -418,21 +446,20 @@ Saves a image in the given stream.
 
 \wxheading{Parameters}
 
-\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{name}{Name of the file to save the image to.}
 
-\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
+\docparam{stream}{Opened output stream to save the image to.}
 
 \docparam{type}{Currently three types can be used:
 
 \twocolwidtha{5cm}%
 \begin{twocollist}
-\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file.}
-\end{twocollist}
-
-The validity of these flags depends on the platform and wxWindows configuration
-as well as user-added handlers.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
+\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
+\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Save a TIFF image file.}
+\end{twocollist}}
 
 \docparam{mimetype}{MIME type.}
 
@@ -478,6 +505,18 @@ Returns the (modified) image itself.
 
 \helpref{Scale}{wximagescale}
 
+\membersection{wxImage::Rotate}\label{wximagerotate}
+
+\func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
+ \param{bool}{ interpolating = TRUE}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
+
+Rotates the image about the given point, by {\it angle} radians. Passing TRUE
+to {\it interpolating} results in better image quality, but is slower. If the
+image has a mask, then the mask colour is used for the uncovered pixels in the
+rotated image background. Else, black (rgb 0, 0, 0) will be used.
+
+Returns the rotated image, leaving this image intact.
+
 \membersection{wxImage::Scale}\label{wximagescale}
 
 \constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
@@ -652,7 +691,7 @@ If the image file contains more than one image and the image handler is capable
 of retrieving these individually, this function will return the number of
 available images.
 
-\docparam{stream}{Opened input stream for reading image file.}
+\docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
 
 \wxheading{Return value}
 
@@ -682,7 +721,7 @@ indicates which image to read from the stream.
 
 \docparam{image}{The image object which is to be affected by this operation.}
 
-\docparam{stream}{Opened input stream for reading images.}
+\docparam{stream}{Opened input stream for reading image data.}
 
 \docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
 
@@ -708,7 +747,7 @@ Saves a image in the output stream.
 
 \docparam{image}{The image object which is to be affected by this operation.}
 
-\docparam{stream}{An opened stream for writing images.}
+\docparam{stream}{Opened output stream for writing the data.}
 
 \wxheading{Return value}