X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2432b92dd7a837db13d3938a56c1959decd03203..5fc0243835d4f6cbe586d85e3a6baa3c9c95fc7c:/docs/latex/wx/image.tex

diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex
index 91e691bafa..a7808cd051 100644
--- a/docs/latex/wx/image.tex
+++ b/docs/latex/wx/image.tex
@@ -7,7 +7,8 @@ via image format handlers. Functions are available to set and get image bits, so
 it can be used for basic image manipulation.
 
 A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific
-wxBitmap object must be created from it, and that bitmap drawn on the wxDC.
+wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using
+wxDC::DrawBitmap.
 
 \wxheading{Derived from}
 
@@ -31,7 +32,9 @@ Copy constructor.
 
 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
 
-Constructs an image from a platform-dependent bitmap.
+Constructs an image from a platform-dependent bitmap. This preserves
+mask information so that bitmaps and images can be converted back
+and forth without loss in that respect.
 
 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
 
@@ -41,6 +44,10 @@ Creates an image with the given width and height.
 
 Loads an image from a file.
 
+\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
+
+Loads an image from an input stream.
+
 \wxheading{Parameters}
 
 \docparam{width}{Specifies the width of the image.}
@@ -49,20 +56,20 @@ Loads an image from a file.
 
 \docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
 
+\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{type}{May be one of the following:
 
-\twocolwidtha{5cm}
+\twocolwidtha{5cm}%
 \begin{twocollist}
 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XBM}}}{Load an X bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XPM}}}{Load an XPM bitmap file.}
 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
 \end{twocollist}
 
 The validity of these flags depends on the platform and wxWindows configuration.
-If all possible wxWindows settings are used, the Windows platform supports BMP, BMP\_RESOURCE,
-XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.}
+If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file
+and a PNG (portable network graphics) file is supported on all platforms that
+implement wxImage.}
 
 \wxheading{See also}
 
@@ -99,7 +106,12 @@ This function is called by wxWindows on exit.
 
 \constfunc{wxBitmap}{ConvertToBitmap}{\void}
 
-Converts the image to a platform-specific bitmap object.
+Converts the image to a platform-specific bitmap object. This has to be done
+to actually display an image as you cannot draw an image directly on a window.
+The resulting bitmap will use the colour depth of the current system which entails
+that a (crude) colour reduction has to take place. When in 8-bit mode, this
+routine will use a color cube created on program start-up to look up colors.
+Still, the image quality won't be perfect for photo images.
 
 \membersection{wxImage::Create}\label{wximagecreate}
 
@@ -161,7 +173,9 @@ Returns the blue intensity at the given coordinate.
 
 \constfunc{unsigned char*}{GetData}{\void}
 
-Returns the image data as an array.
+Returns the image data as an array. This is most often used when doing
+direct image manipulation. The return value points to an array of
+chararcters in RGBGBRGB... format.
 
 \membersection{wxImage::GetGreen}\label{wximagegetgreen}
 
@@ -230,7 +244,8 @@ Returns TRUE if there is a mask active, FALSE otherwise.
 \func{static void}{InitStandardHandlers}{\void}
 
 Adds the standard image format handlers, which, depending on wxWindows
-configuration, can be handlers for Windows image, Windows image resource, and XPM.
+configuration, can be handlers for Windows BMP (loading) and PNG
+(loading and saving) file formats.
 
 This function is called by wxWindows on startup.
 
@@ -257,19 +272,23 @@ of a given handler class in an application session.}
 
 Loads an image from a file.
 
+\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
+
+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{stream}{An input stream.
+The meaning of {\it stream} data is determined by the {\it type} parameter.}
+
 \docparam{type}{One of the following values:
 
-\twocolwidtha{5cm}
+\twocolwidtha{5cm}%
 \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\_XBM}}{Load an X image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
 \end{twocollist}
 
@@ -312,22 +331,25 @@ TRUE if the handler was found and removed, FALSE otherwise.
 
 Saves a image in the named file.
 
+\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
+
+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{type}{One of the following values:
+\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
+
+\docparam{type}{Currently only one type can be used:
 
-\twocolwidtha{5cm}
+\twocolwidtha{5cm}%
 \begin{twocollist}
-\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a Windows image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM image file.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
 \end{twocollist}
 
-The validity of these flags depends on the platform and wxWindows configuration.}
+The validity of these flags depends on the platform and wxWindows configuration
+as well as user-added handlers.}
 
 \wxheading{Return value}
 
@@ -345,13 +367,19 @@ Depending on how wxWindows has been configured, not all formats may be available
 
 \func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
 
-Returns a scaled version of the image.
+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 do blit a wxMemoryDC into another wxMemoryDC. Windows can such scaling
+itself, but on GTK scaling bitmaps is done using this routine 
+internally.
 
 \membersection{wxImage::SetData}\label{wximagesetdata}
 
 \func{void}{SetData}{\param{unsigned char*}{data}}
 
-Sets the image data.
+Sets the image data without performing checks. The data given must have 
+the size (width*height*3) or results will be unexpected. Don't use this
+method if you aren't sure you know what you are doing.
 
 \membersection{wxImage::SetMask}\label{wximagesetmask}
 
@@ -369,7 +397,10 @@ Sets the mask colour for this image.
 
 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
 
-Sets the pixel at the given coordinate.
+Sets the pixel at the given coordinate. This routine performs bounds-checks
+for the coordinate so it can be considered a safe way to manipulate the
+data, but in some cases this might be too slow so that the data will have to
+be set directly. In that case you have to get that data by calling GetData().
 
 \membersection{wxImage::operator $=$}
 
@@ -469,16 +500,16 @@ Gets the image type associated with this handler.
 
 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
 
-\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{const wxString\&}{ name}}
+\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}}
 
-Loads a image from a file or resource, putting the resulting data into {\it image}.
+Loads a image from a stream, putting the resulting data into {\it image}.
 
 \wxheading{Parameters}
 
 \docparam{image}{The image object which is to be affected by this operation.}
 
-\docparam{name}{Either a filename or a Windows resource name.
-The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{stream}{Opened input stream.
+The meaning of {\it stream} is determined by the {\it type} parameter.}
 
 \wxheading{Return value}
 
@@ -492,15 +523,15 @@ TRUE if the operation succeeded, FALSE otherwise.
 
 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
 
-\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{const wxString\& }{name}}
+\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
 
-Saves a image in the named file.
+Saves a image in the output stream.
 
 \wxheading{Parameters}
 
 \docparam{image}{The image object which is to be affected by this operation.}
 
-\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{stream}{A stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
 
 \wxheading{Return value}
 
@@ -542,4 +573,3 @@ Sets the handler type.
 
 \docparam{name}{Handler type.}
 
-