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, using
-wxDC::DrawBitmap.
+A wxImage cannot (currently) be drawn directly to a \helpref{wxDC}{wxdc}. Instead,
+a platform-specific \helpref{wxBitmap}{wxbitmap} object must be created from it using
+the \helpref{ConvertToBitmap}{wximageconverttobitmap} function. This bitmap can then
+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).}
+\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}
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}}
\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PCX}}}{Load a PCX bitmap file.}
\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNM}}}{Load a PNM bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ANY}}}{Will try to autodetect the format.}
\end{twocollist}
The validity of these flags depends on the platform and wxWindows configuration.
\pythonnote{Constructors supported by wxPython are:\par
\indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{wxImage(name, flag)}}{Loads an image from a file}
-\twocolitem{\bf{wxNullImage()}}{Create a null image (has no size or
+\twocolitem{{\bf wxImage(name, flag)}}{Loads an image from a file}
+\twocolitem{{\bf wxNullImage()}}{Create a null image (has no size or
image data)}
-\twocolitem{\bf{wxEmptyImage(width, height)}}{Creates an empty image
+\twocolitem{{\bf wxEmptyImage(width, height)}}{Creates an empty image
of the given size}
-\twocolitem{\bf{wxImageFromMime(name, mimetype}}{Creates an image from
+\twocolitem{{\bf wxImageFromMime(name, mimetype}}{Creates an image from
the given file of the given mimetype}
-\twocolitem{\bf{wxImageFromBitmap(bitmap)}}{Creates an image from a
+\twocolitem{{\bf wxImageFromBitmap(bitmap)}}{Creates an image from a
platform-dependent bitmap}
\end{twocollist}}
}
\helpref{wxImageHandler}{wximagehandler}
-\pythonnote{In wxPython this static method is named \tt{wxImage_AddHandler}.}
+\pythonnote{In wxPython this static method is named {\tt wxImage_AddHandler}.}
\membersection{wxImage::CleanUpHandlers}
\func{static void}{CleanUpHandlers}{\void}
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.
+that a colour reduction has to take place.
+
+When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created
+on program start-up to look up colors. This ensures a very fast conversion, but
+the image quality won't be perfect (and could be better for photo images using more
+sophisticated dithering algorithms).
\membersection{wxImage::Create}\label{wximagecreate}
\membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
-\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{rect}}
+\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
Returns a sub image of the current one as long as the rect belongs entirely to
the image.
\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.}
\pythonnote{In place of a single overloaded method name, wxPython
implements the following methods:\par
\indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{LoadFile(filename, type)}}{Loads an image of the given
+\twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
type from a file}
-\twocolitem{\bf{LoadMimeFile(filename, mimetype)}}{Loads an image of the given
+\twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
mimetype from a file}
\end{twocollist}}
}
\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
-\docparam{type}{Currently two types can be used:
+\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
\pythonnote{In place of a single overloaded method name, wxPython
implements the following methods:\par
\indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{SaveFile(filename, type)}}{Saves the image using the given
+\twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
type to the named file}
-\twocolitem{\bf{SaveMimeFile(filename, mimetype)}}{Saves the image using the given
+\twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
mimetype to the named file}
\end{twocollist}}
}
+\membersection{wxImage::Replace}\label{wximagereplace}
+
+\func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
+\param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
+
+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}}
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 post uses this function internally
+It may be mentioned that the GTK port uses this function internally
to scale bitmaps when using mapping mode in wxDC.
Example:
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().
+be set directly. In that case you will have to get access to the image data
+using the \helpref{GetData}{wximagegetdata} method.
\membersection{wxImage::operator $=$}
projects / wxWidgets.git / blobdiff